Spec: Compile Context Once and Project It Truthfully

User Input

in @linear project https://linear.app/devpunks/project/harness-intelligence-23aceec78aca/issues we have new modules M7 M8 M9 for the refactor and re architecture around effect v4. so now please start a $delivery-phase FOR EACH SINGLE ONE of the EPICS. complete all epics and their inner stories with a delivery phase per epic

DO NOT MISS ON ANY OF THE STORIES

do this in full parallel. dont merge on main the subsequent pr

This specification covers Linear epic IP-317 and every child story beneath it: IP-325 and IP-326.

Context

Repository context is currently at risk of being reinterpreted by planning, scaffold, update, and harness-specific paths. CLI operators, agents, and maintainers need one deterministic semantic account of selected project context, followed by truthful harness projections whose omissions and failures remain visible. The capability must preserve established pack-to-scope behavior while making contribution identity, provenance, compatibility, and harness support observable.

Non-Goals

• Adding a new pack applicability language or pack-authored selector model.
• Putting target paths, filenames, links, hashes, package mutations, or write actions in the context plan.
• Encoding harness-specific schemas or filesystem strategies in the canonical context model.
• Treating capability groups as project packs or moving skill workflow meaning out of each skill.
• Treating a known unsupported contribution as failure of the entire scaffold.

Acceptance Criteria

Neutral context plan (IP-325)

• One deterministic plan identifies every repository scope, selected pack, resolved skill, scoped prompt, lifecycle hook, tool contribution, and subagent contribution for the same semantic inputs.
• Every resolved contribution carries its identity, source and provenance, compatibility, required reference closure, and meaningful ordering.
• Existing pack-to-scope placement is preserved through semantic equality of repository scopes, packs, contributions, provenance, and meaningful ordering.
• Project packs select repository context, while capability groups compose subagent templates; a subagent template does not consume project packs directly.
• Skill workflow meaning remains owned by each SKILL.md and is neither duplicated nor interpreted as pack policy.
• The context plan ends at repository scope identifiers and resolved contribution intent, with no target paths, links, hashes, package mutations, or write actions.

Truthful harness projection (IP-326)

• Harness capability contracts describe neutral support for skills, scoped prompts, subagent templates, lifecycle hooks, and tool configuration.
• Every harness adapter publishes a versioned capability matrix that distinguishes supported, degraded, and unsupported behavior.
• Supported projections continue when another contribution is known to be unsupported.
• A known unsupported contribution produces a typed warning scoped to the affected harness and contribution, an explicit degraded or partial outcome, and a recorded omission.
• Invalid projections, adapter defects, and failed applications remain errors for their affected actions rather than being reported as ordinary degradation.
• Every harness-specific file, link, mirror, or configuration entry is reproducible and traceable to canonical contribution identity and never becomes an independent source of truth.
• Shared projection contract evidence proves the same supported, degraded, and unsupported semantics across adapters.
• Capability changes are explicit compatibility changes rather than incidental adapter behavior.

Constraints

• Context planning remains neutral and contains no filesystem or write decisions.
• Neutral authored contributions remain canonical; harness outputs are managed projections.
• Byte-level generated-output compatibility belongs to downstream scaffold and harness evidence. The context-plan contract uses semantic equality.
• Known capability gaps degrade explicitly; defects, invalid projections, and failed writes remain typed failures.
• IP-317 is delivered on its own child branch and pull request based on the unmerged parent architecture branch. Parent and child remain unmerged and undeployed; neither targets main.

Branch/Base Intent

• Parent pull request: draft PR #76.
• Parent branch: team/stefan/refactor-cli-architecture.
• Child branch: team/stefan/ip-317-context-plan.
• Child pull-request base: team/stefan/refactor-cli-architecture, never main.
• State: parent and child remain unmerged and undeployed.
• Dependency evidence: PR #76 and apps/wiki/content/docs/project/specs/cli/IP-319-establish-one-comprehensive-behavior-contract/IMPLEMENTATION-NOTES.md record completed, accepted IP-330 characterization evidence. IP-325 precedes IP-326 inside the child branch.

Decision Log

Review Status

• State: Approved
• Requirements authority: completed Q1-Q58 grill artifacts and Linear IP-317/IP-325/IP-326, read in full on 2026-07-14
• Completeness check: parent outcome, constraints, relations, and every child-story acceptance signal and non-goal are represented
• Quality check: problem-space and binary-criteria self-review passed
• Independent review: complete; spec-reviewer found no blocking issue after the IP-330 evidence and dependency status were corrected
• Human approval: complete; delivery is authorized to continue to planning on the coordinated draft PR

Delivery Phase Handoff

• Phase: spec
• Status: complete
• Scope: IP-317 with IP-325 and IP-326
• Artifacts: this SPEC.md
• Validation: frontmatter, story coverage, dependency ordering, and spec-quality self-check complete
• Review/debug/docs state: independently reviewed and human-approved; no implementation, runtime debugging, or docs ingest performed for IP-317
• UI Evidence: not applicable to this spec phase
• Next suggested route: create-plan on child branch team/stefan/ip-317-context-plan, preserving IP-325 before IP-326 and targeting parent branch team/stefan/refactor-cli-architecture
• Blockers: none at the spec gate