Plan: Finder Provider Projection and Intent Control

Plan State

• Status: in progress; W1 and the A1 checkpoint are complete, W2 is ready
• Architecture applicability: architecture-bearing
• Architecture evidence: the change crosses Finder state and routing, requirements supersession, provider-neutral mutation planning, the Linear adapter, generated handoffs, executable contracts, and Harness distribution.
• Task identity mode: planning-only
• Spec authority: https://github.com/wearedevpunks/harness-intelligence/blob/896b21024c240e5cee3c5e5b2d92cb6ba88c187b/apps/wiki/content/docs/project/specs/cli/issue-178-180-finder-provider-intent-control/SPEC.md
• Harness branch: team/stefan/finder-control-envelope
• Harness base: origin/main@694420ca
• Shared skill source: /Users/stefan/Desktop/repos/wearedevpunks-skills on checked-out main
• Provider policy: Collective Intelligence Linear is read-only for this work
• Backlog sync: skipped because no provider Task graph exists for this Harness-internal fix and Linear mutation is explicitly out of scope

Initial Situation

Finder, requirements-grill, and write-backlog each preserve a useful part of the workflow, but their outputs are not bound into one executable authority. The current provider-neutral backlog model also fixes one physical hierarchy. The Linear adapter therefore rejects an accepted project topology when the workspace cannot or does not use nested Initiatives.

The supplied Collective Intelligence handoff preserves important correction history, but its Dataset Platform route is older than the live provider state. This is normal temporal drift. The unsafe part is that a narrative handoff has no typed epoch, correction lineage, profile fingerprint, or mutation binding that mechanically prevents stale work.

The shared source repository is on the required main branch at 2c7473179569d237acd3d01a2df055cb76d2e174. It contains two unrelated, user-owned modifications:

• skills/phases/finder-phase/AUTHORING-HANDOFF.md
• skills/phases/finder-phase/references/state-graph.md

Those files are excluded from every implementation write scope and commit. The Harness sync command fetches the pushed public source into its own cache, so it can project committed bytes without copying those working-tree modifications.

Issue

An agent cannot answer these questions from one durable contract:

1. Which human intent revision is current?
2. Which unresolved work set is legal now?
3. Which semantic graph is accepted?
4. How does this project map that graph into this provider?
5. Which provider snapshot and topology did the human approve?
6. Which exact cleanup operation was authorized?
7. What did the provider actually contain after the write?

The resulting gaps produced issue #178's unsupported Linear hierarchy and issue #180's cross-cutting Fog, premature projections, incorrect stage change, ticket fragmentation, missing Project placement, cleanup substitution, and repeated correction loss.

Proposed Solution Shape

Establish one control envelope with a small validation interface. Finder owns intent, coherent work sets, stage state, and route eligibility. Requirements grilling contributes append-only corrections and downstream invalidations. write-backlog compiles the semantic graph into a versioned mutation plan. Provider adapters apply an explicitly approved projection profile and return exact readback plus residual delta. The Markdown handoff is generated from the validated state and never authorizes a mutation.

Two interface shapes were considered:

1. Extend every prose artifact independently with overlapping epoch, profile, snapshot, and approval fields. This minimizes new files but leaves every caller responsible for reconstructing validity.
2. Define one deep control-envelope validator and let prose skills consume its small eligible-or-rejected result. This centralizes cross-field invariants while stage and provider behavior remain with their existing owners.

Choose option 2. It yields the highest leverage, concentrates validation and fixtures, and keeps provider mapping behind the writer seam.

Locked Decision Ledger

Parked Decisions

• Generic Linear Free default profile. Owner: future provider-capability requirements grill. Resume when a project without an approved profile needs initialization.
• Automatic detection versus operator confirmation for each Linear capability. Owner: future Linear adapter requirements grill. Resume when the connected API can prove additional capabilities or a new profile is required.
• Migration from the former nested-Initiative projection. Owner: dedicated migration requirements grill. Resume on an explicit project migration request.
• Provider-wide cleanup defaults. Owner: future provider-specific recoverable-actions requirements grill. Resume when a provider workflow needs a default beyond one explicitly authorized operation.

Dependency Readiness

• Status: Ready
• Agent-ready spec: retained at Harness commit 896b21024c240e5cee3c5e5b2d92cb6ba88c187b
• Research report: retained at Harness commit 5a4acbfc
• Shared-source base: pushed main commit 2c7473179569d237acd3d01a2df055cb76d2e174
• External provider fact: Linear sub-Initiatives are Enterprise-only according to https://linear.app/docs/sub-initiatives
• Runtime provider precondition: workspace identity and topology still require fresh project-specific readback
• Stack dependency: No Stack Required

Branch and Base Constraints

• Shared reusable-skill edits occur only in the checked-out shared-source main, then commit and push there before any Harness sync.
• Harness changes remain on team/stefan/finder-control-envelope based on origin/main@694420ca.
• The shared-source commit must exclude the two pre-existing user-owned edits.
• Harness synchronization must fetch the pushed source through the CLI cache and verify the exact receipt SHA.
• Harness self-projection must start from a committed bundled baseline. If the update proposes unrelated managed drift, stop and inspect rather than retaining it silently.

Research and Codebase Findings

• Finder already centralizes routing and delegates all provider writes to write-backlog; the new contract deepens this existing seam.
• The runtime handoff carries stable identities and provider snapshots but no typed correction lineage or topology approval binding.
• The router already treats fresh evidence as stronger than suggested routes, but its stage inputs are not bound to an intent epoch.
• Functional Finder permits several accepted Functional outcomes, while the current contract does not bound concurrent unresolved shells across one Fog.
• Requirements grilling preserves stable question IDs and explicit supersession history, but does not invalidate downstream provider intents.
• The Linear adapter currently hardcodes Root Initiative to Product Area Initiative to nested Initiative to Epic Project.
• write-backlog previews structural changes and reads them back exactly, but the approval is not bound to a versioned semantic graph, projection profile, provider snapshot, or topology fingerprint.
• The shared test suite already uses Node contract tests and JSON fixtures. The new regression corpus can extend that public seam without adding a runner.
• bun run sync:skills fetches remote source into an isolated CLI cache before replacing apps/cli/skills; it does not read the dirty shared-source working tree.
• Harness pins the canonical shared-source commit in the sync script and a focused test. Operator docs repeat the same pin and need the same update.

Target Ownership Topology

Human intent and accepted corrections
  requirements-grill
    owns decision and supersession evidence
    emits correction and invalidation facts
      ↓
  Finder control envelope
    owns intent epoch, coherent work sets, stage state, evidence bindings
    exposes eligible route | typed zero-write rejection
      ↓ semantic intent
  write-backlog mutation planner
    owns semantic graph, mutation plan, approval binding, cleanup semantics
      ↓ selected projection profile
  provider adapter
    owns native mapping, provider execution, exact readback, residual delta
      ↓
  control envelope + generated Markdown handoff

Shared source main
  → pushed immutable commit
  → Harness sync cache and receipt
  → apps/cli skill bundle
  → committed bundled baseline
  → scaffolded .agents mirror and operator docs

Declared Dependency Graph

Allowed dependency edges:

requirements-grill correction facts
  → Finder control-envelope validator

Finder router
  → control-envelope validator
  → write-backlog semantic mutation seam

write-backlog mutation planner
  → selected provider projection profile
  → provider adapter
  → exact readback and residual delta
  → control envelope

control envelope
  → generated human-readable handoff

pushed shared-source commit
  → Harness sync cache
  → distributed skill mirrors

Forbidden edges:

• Finder or requirements grilling directly mutates a provider.
• A provider adapter renames or redefines semantic backlog roles.
• A Markdown handoff selects a route or authorizes a mutation.
• A stale route, preview, approval, or plan bypasses epoch or snapshot checks.
• A provider response is treated as successful readback without observed state.
• Duplicate satisfies delete, cancel, archive, close, detach, or supersede.
• Harness generated mirrors become an authoring source.
• The shared-source dirty AUTHORING-HANDOFF.md or state-graph.md enters this change's commit or Harness projection.

Public Seam Contract

Responsibility Acceptance Criteria

Architecture Waves

Migration Ledger

No temporary seam is planned. The control envelope is introduced as a required validation boundary before existing stage and provider contracts consume it. Final closure requires this ledger to remain empty.

Task Dependency Graph

T1
├── T2 ──┐
├── T3 ──┼── T5 ── T6 ── T7 ── T8
└── T4 ──┘

Parallel Execution Waves

Tasks

T1: Establish the control-envelope validation boundary

• depends_on: []
• location: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/finder-phase/references/control-envelope.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/finder-phase/references/runtime-handoff.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/finder-phase/scripts/finder-control-envelope.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/finder-control-envelope.contract.test.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/fixtures/finder-control-envelope.json
• owned_paths: the five exact T1 paths above; explicitly excludes skills/phases/finder-phase/AUTHORING-HANDOFF.md and skills/phases/finder-phase/references/state-graph.md
• wave_boundary: W1
• description: Define the versioned machine-readable envelope, deterministic canonical hashing and eligibility result, monotonic epoch and correction rules, stage working-set cardinality, mutation bindings, exact readback/residual fields, and generated handoff projection. Freeze the correction-record input contract consumed independently by Finder routing and requirements supersession so T3 and T4 remain parallel after A1. Keep one small public validator/renderer interface and independent valid/invalid fixtures. Do not implement Finder route or provider mapping in this module.
• validation: Contract tests accept a complete current envelope and independently reject every missing or stale authority binding with write_eligible: false; handoff output identifies schema version, epoch, snapshot, route, correction summary, and residual delta.
• status: Complete
• log: 2026-09-01 — Added the versioned control-envelope validator, generated runtime-handoff projection, frozen correction-record contract, and deterministic issue regression fixture. Parent review added missing mutation-plan coverage and accepted the A1 checkpoint with no temporary seam.
• files edited/created: skills/phases/finder-phase/references/control-envelope.md; skills/phases/finder-phase/references/runtime-handoff.md; skills/phases/finder-phase/scripts/finder-control-envelope.mjs; tests/finder-control-envelope.contract.test.mjs; tests/fixtures/finder-control-envelope.json
• task_identity_mode: planning-only
• backlog_item_id: not_applicable
• backlog_item_url: not_applicable
• relation_mode: unprojected
• backlog_sync_skip_reason: No provider Task graph exists for this Harness-internal fix; Linear is explicitly read-only, so the plan uses unprojected Tn identities.
• assigned_skills: [codebase-design, swarm-planner, tdd]
• implementation_skill_guidance:
  • skill: codebase-design applicable_behavior: Expose one deep eligible-or-rejected interface; keep canonicalization, cross-field invariants, and handoff projection internal and test through the same seam callers use.
  • skill: tdd applicable_behavior: Write and run one public-result rejection fixture before validator code, record real RED, then implement only enough to reach GREEN before the next invariant.
• tdd_status: required
• tdd_target: A stale intent epoch or provider snapshot currently has no public validator result that prevents write eligibility and explains the rejection.
• red_command: node --test tests/finder-control-envelope.contract.test.mjs
• expected_red_failure: The control-envelope module or its stale-binding rejection result does not exist.
• green_command: node --test tests/finder-control-envelope.contract.test.mjs
• reason_not_testable:
• red_evidence: node --test tests/finder-control-envelope.contract.test.mjs failed before production code with ERR_MODULE_NOT_FOUND for skills/phases/finder-phase/scripts/finder-control-envelope.mjs.
• green_evidence: Parent rerun of node --check skills/phases/finder-phase/scripts/finder-control-envelope.mjs && node --test tests/finder-control-envelope.contract.test.mjs && bunx biome check skills/phases/finder-phase/scripts/finder-control-envelope.mjs tests/finder-control-envelope.contract.test.mjs tests/fixtures/finder-control-envelope.json && git diff --check passed; 10 tests passed and every invalid fixture returned both writeEligible: false and write_eligible: false with providerWrites: 0 without throwing.
• codebase_design_notes: validateControlEnvelope(state, options) is the deep authority module and renderRuntimeHandoff(validated) is its only presentation projection. Canonical hashing, cross-field bindings, correction monotonicity, working-set cardinality, readback/residual checks, and stale-provider invalidation remain internal. Finder, writer, and handoff callers consume one eligible-or-rejected vocabulary; provider mapping and routing remain outside this module. JSON fixtures protect Harness-owned behavior, not Linear response shapes.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A1
• behavior_owner: Finder control-envelope validator
• integration_surface: Finder router, write-backlog mutation planner, runtime handoff projection
• public_seam: validate/compile current control state -> eligible result or typed zero-write rejection; render validated state -> Markdown handoff
• topology_delta: Adds one authority boundary between conversational artifacts and every route or mutation consumer.
• forbidden_ownership: No Finder gate or provider adapter may duplicate canonical hashing, epoch comparison, or mutation-binding validity.
• temporary_seams: none
• responsibility_acceptance_criteria: [RAC-001, RAC-006]

T2: Make provider projection and mutation intent explicit

• depends_on: [T1]
• location: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog, /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/write-backlog-provider-planning.contract.test.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/write-backlog-linear.contract.test.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/write-backlog-lifecycle.contract.test.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/write-backlog-operating-model.contract.test.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/fixtures/write-backlog-provider-planning.json
• owned_paths: the complete skills/agnostic/requirements/write-backlog/** tree and the five exact writer test/fixture paths above
• wave_boundary: W2
• description: Replace the universal physical hierarchy assumption with an explicit projection profile contract. Compile a versioned mutation plan bound to the T1 envelope, semantic graph hash, profile identity/hash, provider snapshot, topology fingerprint, and approval. Add exact delete/cancel/archive/close/detach/supersede/duplicate semantics. Update Linear guidance and fixtures for both explicitly accepted nested-Initiative profiles and the current Collective root-plus-business-area-Projects profile.
• validation: Writer tests reject missing, incompatible, or stale profiles and approvals before mutation; accept the Collective profile with zero sub-Initiatives; preview exact Project placement; distinguish cleanup operations; and return observed plus residual delta after readback. No supported local Linear provider runtime exists and Collective Intelligence Linear remains read-only, so runtime confidence comes from the retained current provider snapshot plus deterministic Harness-owned mapping, rejection, mutation-plan, cleanup-verb, and readback-residual fixtures.
• status: Planned
• log:
• files edited/created:
• task_identity_mode: planning-only
• backlog_item_id: not_applicable
• backlog_item_url: not_applicable
• relation_mode: unprojected
• backlog_sync_skip_reason: No provider Task graph exists for this Harness-internal fix; Linear is explicitly read-only, so the plan uses unprojected Tn identities.
• assigned_skills: [codebase-design, swarm-planner, tdd]
• implementation_skill_guidance:
  • skill: codebase-design applicable_behavior: Keep semantic mutation planning in write-backlog; isolate native mapping and readback behind provider profiles so adapters cannot redefine product meaning.
  • skill: tdd applicable_behavior: Capture one failing public writer result per tracer bullet: unsupported profile, Collective profile acceptance, stale binding, exact cleanup verb, then readback residual.
• tdd_status: required
• tdd_target: The current Linear contract rejects the accepted Collective topology and cannot distinguish a stale approval or Duplicate from an authorized removal.
• red_command: node --test tests/write-backlog-provider-planning.contract.test.mjs tests/write-backlog-linear.contract.test.mjs tests/write-backlog-lifecycle.contract.test.mjs tests/write-backlog-operating-model.contract.test.mjs
• expected_red_failure: The first new projection-profile or cleanup-semantic assertion fails against the fixed hierarchy and unversioned mutation contract.
• green_command: node --test tests/write-backlog-provider-planning.contract.test.mjs tests/write-backlog-linear.contract.test.mjs tests/write-backlog-lifecycle.contract.test.mjs tests/write-backlog-operating-model.contract.test.mjs
• reason_not_testable:
• red_evidence:
• green_evidence:
• codebase_design_notes: write-backlog remains the deep mutation owner. The projection profile is an adapter contract, while the semantic graph and mutation eligibility remain provider-neutral. The same plan result drives preview, approval, execution, and readback.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A2
• behavior_owner: write-backlog mutation planner and Linear adapter
• integration_surface: Finder semantic intents, control-envelope validator, Linear provider operations
• public_seam: compile semantic intent + approved profile + fresh snapshot -> versioned mutation plan or zero-write rejection
• topology_delta: Separates semantic hierarchy from physical provider projection and adds exact retraction intent.
• forbidden_ownership: Provider adapters cannot select the human's semantic topology, infer cleanup verbs, or approve structural change.
• temporary_seams: none
• responsibility_acceptance_criteria: [RAC-004, RAC-005]

T3: Bind Finder decomposition and stage routing to current intent

• depends_on: [T1]
• location: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/finder-phase/SKILL.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/finder-phase/references/entrypoint-contract.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/finder-phase/phases/router.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/finder-phase/phases/ensure-fog.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/finder-phase/phases/functional-grilling.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/finder-phase/phases/reconcile.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/finder-phase/phases/handback.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/finder-phase/phases/decompose-request.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/finder-phase/scripts/finder-contract.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/finder-phase-graph.contract.test.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/functional-finder.contract.test.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/wayfinder-lifecycle.contract.test.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/fixtures/finder-phase-routes.json
• owned_paths: the fourteen exact T3 paths above; explicitly excludes skills/phases/finder-phase/AUTHORING-HANDOFF.md, skills/phases/finder-phase/references/state-graph.md, and T1's runtime-handoff/control-envelope paths
• wave_boundary: W2
• description: Add a pre-Fog coherent-work-set gate, bind every route and projection intent to the current envelope epoch, enforce at most one unresolved working set at the selected stage, preserve many accepted Functional results, keep questions inside one grilling child, reject stage relabeling in favor of explicit supersession, and require accepted Functional evidence plus Story placement readback before Technical routing.
• validation: Route fixtures produce split-preview/no-write for unrelated concerns, hand back on concurrent unresolved shells or stale epoch, retain several accepted Functional children, reject stage relabel, reject premature Story and Technical projection, and prefer newer provider facts while preserving correction history.
• status: Planned
• log:
• files edited/created:
• task_identity_mode: planning-only
• backlog_item_id: not_applicable
• backlog_item_url: not_applicable
• relation_mode: unprojected
• backlog_sync_skip_reason: No provider Task graph exists for this Harness-internal fix; Linear is explicitly read-only, so the plan uses unprojected Tn identities.
• assigned_skills: [codebase-design, swarm-planner, tdd]
• implementation_skill_guidance:
  • skill: codebase-design applicable_behavior: Keep route policy in Finder gates and consume the shared envelope result; do not leak provider mechanics or duplicate mutation planning.
  • skill: tdd applicable_behavior: Add one failing route fixture before each gate change and prove the public selected outcome or typed zero-write handback.
• tdd_status: required
• tdd_target: A cross-area request can reach Fog creation and multiple unresolved Functional shells can remain routable without one typed rejection.
• red_command: node --test tests/finder-phase-graph.contract.test.mjs tests/functional-finder.contract.test.mjs tests/wayfinder-lifecycle.contract.test.mjs
• expected_red_failure: The first new decomposition, cardinality, stage-immutability, or stale-epoch fixture has no matching route result.
• green_command: node --test tests/finder-phase-graph.contract.test.mjs tests/functional-finder.contract.test.mjs tests/wayfinder-lifecycle.contract.test.mjs
• reason_not_testable:
• red_evidence:
• green_evidence:
• codebase_design_notes: The router remains one public state-transition seam. Decomposition is a bounded gate before identity allocation; control-envelope validity precedes stage selection. Provider mapping remains behind write-backlog.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A2
• behavior_owner: Finder router and stage gates
• integration_surface: Human request, control-envelope result, semantic mutation intent
• public_seam: route current Fog state -> exactly one gate, split preview, checkpoint, or typed zero-write handback
• topology_delta: Adds coherent decomposition and epoch/cardinality guards before existing lifecycle transitions.
• forbidden_ownership: Finder cannot execute provider writes, reinterpret cleanup intent, or use Markdown handoff freshness as authority.
• temporary_seams: none
• responsibility_acceptance_criteria: [RAC-002]

T4: Propagate supersession into downstream invalidation

• depends_on: [T1]
• location: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/requirements-grill/SKILL.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/requirements-grill/references/artifact-output.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/requirements-grill/references/grilling-flow.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/requirements-grill-composition.contract.test.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/fixtures/requirements-correction-supersession.json
• owned_paths: the five exact T4 paths above
• wave_boundary: W2
• description: Extend accepted supersession output with one correction entry, exactly one next intent epoch, affected semantic identities, invalidated projection or provider intents, requested cleanup, and a reconcile-or-handback requirement. Preserve stable question IDs and append-only history; never rewrite prior decisions.
• validation: Requirements contract fixtures prove a correction advances one epoch, retains old and new values, names all invalidated downstream identities, and leaves operational provider facts to Finder readback.
• status: Planned
• log:
• files edited/created:
• task_identity_mode: planning-only
• backlog_item_id: not_applicable
• backlog_item_url: not_applicable
• relation_mode: unprojected
• backlog_sync_skip_reason: No provider Task graph exists for this Harness-internal fix; Linear is explicitly read-only, so the plan uses unprojected Tn identities.
• assigned_skills: [codebase-design, swarm-planner, tdd]
• implementation_skill_guidance:
  • skill: codebase-design applicable_behavior: Keep requirements artifacts as decision evidence that emit correction facts; leave route selection and provider mutation with their existing owners.
  • skill: tdd applicable_behavior: First prove a superseded decision currently lacks downstream invalidation and epoch evidence, then add the minimum artifact contract to pass.
• tdd_status: required
• tdd_target: A superseded accepted decision preserves prose history but does not expose the invalidated Story/Task or provider intent to downstream control.
• red_command: node --test tests/requirements-grill-composition.contract.test.mjs
• expected_red_failure: The new supersession fixture lacks intent epoch, correction lineage, or downstream invalidation fields.
• green_command: node --test tests/requirements-grill-composition.contract.test.mjs
• reason_not_testable:
• red_evidence:
• green_evidence:
• codebase_design_notes: Requirements grilling owns why intent changed. Finder owns what route is legal now. The correction record is the small seam between them.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A2
• behavior_owner: Requirements grilling decision artifacts
• integration_surface: Finder control envelope and reconciliation route
• public_seam: accepted supersession -> append-only correction and downstream invalidation facts
• topology_delta: Connects stable requirements history to mechanical invalidation without giving requirements artifacts runtime provider authority.
• forbidden_ownership: Requirements grilling cannot infer current provider state, select a Finder gate, or execute cleanup.
• temporary_seams: none
• responsibility_acceptance_criteria: [RAC-003]

T5: Integrate, validate, and publish the shared source

• depends_on: [T2, T3, T4]
• location: /Users/stefan/Desktop/repos/wearedevpunks-skills Git index and remote main
• owned_paths: read-only validation over all shared-source files; exclusive commit/push authority over this exact staged-path allowlist only: skills/phases/finder-phase/references/control-envelope.md, skills/phases/finder-phase/references/runtime-handoff.md, skills/phases/finder-phase/scripts/finder-control-envelope.mjs, skills/agnostic/requirements/write-backlog/**, skills/phases/finder-phase/SKILL.md, skills/phases/finder-phase/references/entrypoint-contract.md, skills/phases/finder-phase/phases/router.md, skills/phases/finder-phase/phases/ensure-fog.md, skills/phases/finder-phase/phases/functional-grilling.md, skills/phases/finder-phase/phases/reconcile.md, skills/phases/finder-phase/phases/handback.md, skills/phases/finder-phase/phases/decompose-request.md, skills/phases/finder-phase/scripts/finder-contract.mjs, skills/agnostic/requirements/requirements-grill/SKILL.md, skills/agnostic/requirements/requirements-grill/references/artifact-output.md, skills/agnostic/requirements/requirements-grill/references/grilling-flow.md, tests/finder-control-envelope.contract.test.mjs, tests/fixtures/finder-control-envelope.json, tests/finder-phase-graph.contract.test.mjs, tests/functional-finder.contract.test.mjs, tests/wayfinder-lifecycle.contract.test.mjs, tests/fixtures/finder-phase-routes.json, tests/requirements-grill-composition.contract.test.mjs, tests/fixtures/requirements-correction-supersession.json, tests/write-backlog-provider-planning.contract.test.mjs, tests/write-backlog-linear.contract.test.mjs, tests/write-backlog-lifecycle.contract.test.mjs, tests/write-backlog-operating-model.contract.test.mjs, and tests/fixtures/write-backlog-provider-planning.json; never stage the two pre-existing user-owned dirty files
• wave_boundary: W3
• description: Run focused and full shared contract suites, inspect cumulative ownership and forbidden edges, verify the user-owned diff is byte-unchanged, stage only the explicit allowlist, create one conventional commit, push checked-out shared-source main, and read back the exact remote SHA. The T5 worker alone has authority to stage, commit, and push the shared repository after parent validation; T1-T4 workers must not retain or publish commits. Route any code finding back to its owning task before commit.
• validation: Focused suites and node --test tests/*.test.mjs pass; git diff --check passes; staged paths contain no user-owned file; post-push origin/main equals the exact local commit; user-owned working-tree edits remain present and unchanged.
• status: Planned
• log:
• files edited/created:
• task_identity_mode: planning-only
• backlog_item_id: not_applicable
• backlog_item_url: not_applicable
• relation_mode: unprojected
• backlog_sync_skip_reason: No provider Task graph exists for this Harness-internal fix; Linear is explicitly read-only, so the plan uses unprojected Tn identities.
• assigned_skills: [codebase-design, swarm-planner]
• implementation_skill_guidance:
  • skill: codebase-design applicable_behavior: Check cumulative owner boundaries, public seams, and forbidden dependencies before retaining the shared-source commit; send behavior fixes back through their public RED/GREEN suite.
• tdd_status: not_applicable
• tdd_target: Shared-source integration, exact staging, and remote retention do not add behavior.
• red_command: not_applicable
• expected_red_failure: not_applicable
• green_command: node --test tests/finder-control-envelope.contract.test.mjs tests/finder-phase-graph.contract.test.mjs tests/functional-finder.contract.test.mjs tests/wayfinder-lifecycle.contract.test.mjs tests/requirements-grill-composition.contract.test.mjs tests/write-backlog-provider-planning.contract.test.mjs tests/write-backlog-linear.contract.test.mjs tests/write-backlog-lifecycle.contract.test.mjs tests/write-backlog-operating-model.contract.test.mjs && node --test tests/*.test.mjs && git diff --check
• reason_not_testable: Integration and publication consume the behavior evidence produced by T1-T4.
• red_evidence:
• green_evidence:
• codebase_design_notes: This task owns convergence and source retention, not a new module. It verifies the target ownership topology before distribution.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A3
• behavior_owner: Shared-skill source retention boundary
• integration_surface: T1-T4 source changes, git commit, public wearedevpunks/skills main
• public_seam: exact pushed shared-source commit SHA
• topology_delta: Retains the converged architecture as one immutable upstream authority.
• forbidden_ownership: Integration may not absorb user-owned dirty files or repair behavior outside the owning task's test seam.
• temporary_seams: none
• responsibility_acceptance_criteria: [RAC-001, RAC-002, RAC-003, RAC-004, RAC-005, RAC-006]

T6: Pin and synchronize the shared source into the CLI bundle

• depends_on: [T5]
• location: apps/cli/scripts/sync-skills-repo.mjs, apps/cli/src/scripts/sync-skills-repo.test.ts, apps/cli/skills/**, BASELINE_CHANGELOG.md
• owned_paths: the four exact T6 scopes above; generated apps/cli/skills/** must come only from bun run sync:skills
• wave_boundary: W4
• description: Update the canonical source pin test first, observe RED against the old pin, update the sync script to T5's exact pushed SHA, run the default sync, verify its cache receipt, and retain the generated CLI skill bundle plus a non-empty Unreleased baseline note with compatibility >=4.0.0 <5. Keep CHANGELOG.md byte-unchanged so changed changelog paths classify this as baseline-only. Do not hand-edit generated skill bytes or publish the baseline without explicit user instruction.
• validation: Pin test passes; default bun run sync:skills fetches the exact T5 SHA; cache receipt reports the same commit and main; diff -rq between cache source and apps/cli/skills is empty; BASELINE_CHANGELOG.md has reviewed non-empty Unreleased notes and compatibility >=4.0.0 <5; CHANGELOG.md is unchanged; focused CLI checks and git diff --check pass.
• status: Planned
• log:
• files edited/created:
• task_identity_mode: planning-only
• backlog_item_id: not_applicable
• backlog_item_url: not_applicable
• relation_mode: unprojected
• backlog_sync_skip_reason: No provider Task graph exists for this Harness-internal fix; Linear is explicitly read-only, so the plan uses unprojected Tn identities.
• assigned_skills: [codebase-design, swarm-planner, tdd]
• implementation_skill_guidance:
  • skill: codebase-design applicable_behavior: Keep the immutable pin and generated cache-copy mechanism as the only distribution seam; do not introduce a local-working-tree source path.
  • skill: tdd applicable_behavior: Change the public expected canonical commit in the test, capture failure against the old script pin, then update the implementation and run the real sync/readback.
• tdd_status: required
• tdd_target: The CLI default selection still expects the pre-fix shared-source commit after T5 publishes a new canonical main.
• red_command: bun run --cwd apps/cli test -- src/scripts/sync-skills-repo.test.ts
• expected_red_failure: Expected canonical commit equals T5's new SHA while the sync script still returns 2c7473179569d237acd3d01a2df055cb76d2e174.
• green_command: bun run --cwd apps/cli test -- src/scripts/sync-skills-repo.test.ts && bun run sync:skills
• reason_not_testable:
• red_evidence:
• green_evidence:
• codebase_design_notes: The pinned remote fetch is the deep distribution seam. The ignored cache receipt is runtime evidence; tracked pin, test, generated bundle, and changelog are release-bearing authority.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A4
• behavior_owner: CLI shared-skill distribution
• integration_surface: pushed shared-source commit, isolated cache, bundled apps/cli/skills
• public_seam: resolve canonical selection -> exact pinned commit; sync -> receipt and byte-identical bundle
• topology_delta: Advances the immutable shared-source authority and distributes its exact bytes.
• forbidden_ownership: Generated bundle files cannot be authored directly or sourced from the dirty shared working tree.
• temporary_seams: none
• responsibility_acceptance_criteria: [RAC-007]

T7: Regenerate the self-hosted mirror and align durable docs

• depends_on: [T6]
• location: .agents/skills/finder-phase/**, .agents/skills/write-backlog/**, .agents/skills/requirements-grill/**, .devpunks/scaffold-manifest.json, .devpunks/harness-projection-receipt.json, docs/README.md, docs/runbooks/hi-cli-scaffolding.md, apps/wiki/content/docs/project/runbooks/hi-cli-scaffolding.md, relevant Finder and backlog-model wiki pages discovered from existing links
• owned_paths: the exact generated mirror/receipt and durable docs scopes above; additional self-update output requires explicit parent inspection before retention
• wave_boundary: W5
• description: Build the bundled baseline from committed T6 bytes, run the repository-local bundled update with update checks disabled, retain only authority-derived self-projection changes, and align root/operator/wiki docs with projection profiles, intent epochs, working-set cardinality, mutation binding, exact cleanup semantics, generated handoffs, and the new source pin. Preserve DECIDED/RECOMMENDED/OPEN distinctions and do not copy the shared dirty files.
• validation: Selected .agents skill directories are byte-identical to the exact CLI cache source; repository-local hi check --json reports no unaccounted managed drift; root and mirrored runbook pins equal T5; docs describe current implemented behavior; focused formatting and git diff --check pass.
• status: Planned
• log:
• files edited/created:
• task_identity_mode: planning-only
• backlog_item_id: not_applicable
• backlog_item_url: not_applicable
• relation_mode: unprojected
• backlog_sync_skip_reason: No provider Task graph exists for this Harness-internal fix; Linear is explicitly read-only, so the plan uses unprojected Tn identities.
• assigned_skills: [codebase-design, swarm-planner]
• implementation_skill_guidance:
  • skill: codebase-design applicable_behavior: Document the implemented owner boundaries and public seams; keep generated mirrors as projections and avoid duplicating provider or control logic in narrative docs.
• tdd_status: not_applicable
• tdd_target: Generated projection and documentation align already-tested source behavior.
• red_command: not_applicable
• expected_red_failure: not_applicable
• green_command: bun run baseline:build && HI_NO_UPDATE_CHECK=1 HI_NO_SKILL_UPDATE_CHECK=1 bun run ./apps/cli/src/index.ts update --input . --baseline bundled --write --json && HI_NO_UPDATE_CHECK=1 HI_NO_SKILL_UPDATE_CHECK=1 bun run ./apps/cli/src/index.ts check --input . --baseline bundled --json && git diff --check
• reason_not_testable: This task regenerates managed artifacts from committed source and documents behavior already protected by T1-T6 contracts.
• red_evidence:
• green_evidence:
• codebase_design_notes: The self-hosted mirror demonstrates that consumer agents receive the same small control seams as the canonical source. Docs explain responsibility and operation without becoming runtime authority.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A4
• behavior_owner: Harness self-scaffold projection and operator documentation
• integration_surface: committed CLI baseline, generated .agents skills, managed receipts, human operator docs
• public_seam: committed bundled baseline -> exact self-hosted projection; source-first runbook contract
• topology_delta: Makes the new control architecture available to this repository and future scaffold consumers.
• forbidden_ownership: Docs and generated .agents mirrors cannot supersede shared source or authorize provider mutations.
• temporary_seams: none
• responsibility_acceptance_criteria: [RAC-007]

T8: Review conformance and close implementation evidence

• depends_on: [T7]
• location: both repositories' changed paths, apps/wiki/content/docs/project/specs/cli/issue-178-180-finder-provider-intent-control/{SPEC.md,PLAN.md,IMPLEMENTATION-NOTES.md}
• owned_paths: read-only review over all changed paths; write only spec-folder evidence and corrections returned to the owning implementation task
• wave_boundary: W6
• description: Run an independent findings-first architecture and simplification review, rerun all shared/Harness focused suites, verify exact source receipts and mirror parity, require release classification result baseline without publication, record RED/GREEN and convergence evidence, and update the spec state only after every acceptance criterion is proven. Leave GitHub issues open unless the fix is merged or the user explicitly requests issue mutation.
• validation: Review has no blocking finding; RAC-001 through RAC-007 remain green; exact shared remote, cache receipt, CLI pin, generated bundle, .agents mirrors, and docs agree; release classifier returns baseline, BASELINE_CHANGELOG.md declares compatibility >=4.0.0 <5, and CHANGELOG.md remains unchanged; no publication or Linear mutation occurred; user-owned shared-source edits remain byte-unchanged and uncommitted.
• status: Planned
• log:
• files edited/created:
• task_identity_mode: planning-only
• backlog_item_id: not_applicable
• backlog_item_url: not_applicable
• relation_mode: unprojected
• backlog_sync_skip_reason: No provider Task graph exists for this Harness-internal fix; Linear is explicitly read-only, so the plan uses unprojected Tn identities.
• assigned_skills: [codebase-design, swarm-planner]
• implementation_skill_guidance:
  • skill: codebase-design applicable_behavior: Review the cumulative system against declared owners, dependency edges, public seams, responsibility criteria, and empty migration ledger; route behavior fixes back through their public tests.
• tdd_status: not_applicable
• tdd_target: Review and evidence closeout consume task-level RED/GREEN proof.
• red_command: not_applicable
• expected_red_failure: not_applicable
• green_command: node --test /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/*.test.mjs && bun run --cwd apps/cli test -- src/scripts/sync-skills-repo.test.ts && bun run --cwd apps/cli check-types && bun run release:classify -- --base origin/main --head HEAD && git diff --check
• reason_not_testable: Closeout adds no production behavior; any review correction must return to the owning task's RED/GREEN seam.
• red_evidence:
• green_evidence:
• codebase_design_notes: Final review compares the implemented system, not file placement alone, with every architecture criterion and forbidden edge.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A5
• behavior_owner: Architecture conformance and durable evidence
• integration_surface: Shared source, Harness distribution, docs, retained implementation artifacts
• public_seam: findings-first review result and exact immutable evidence set
• topology_delta: Confirms the target system is complete and records no new runtime seam.
• forbidden_ownership: Closeout cannot weaken a gate, silently accept drift, publish a baseline, mutate Linear, or close unmerged issues.
• temporary_seams: none
• responsibility_acceptance_criteria: [RAC-001, RAC-002, RAC-003, RAC-004, RAC-005, RAC-006, RAC-007]

Testing Strategy

• Use vertical RED-to-GREEN tracer bullets through the same public contract seam that agents consume.
• Keep provider fixtures focused on Harness-owned mapping and rejection behavior; do not recreate or assert Linear's third-party implementation.
• Assert typed zero-write results and the exact stale or unsupported binding.
• Verify both accepted and rejected projection profiles, routes, correction epochs, mutation bindings, cleanup verbs, readback residuals, and cold resume.
• Run focused suites during each task and the entire shared Node contract suite before source publication.
• Update the Harness sync pin test before the production pin to capture honest RED.
• Compare exact remote-cache bytes to both generated mirrors; never compare the dirty shared-source working tree as distribution authority.
• Treat provider runtime validation as not required because there is no supported local provider runtime and Collective Intelligence Linear is read-only. Validate against the retained current provider snapshot plus deterministic Harness-owned mapping, rejection, mutation, and readback fixtures.

Validation Gates

1. T1 proves the control-envelope interface and completes A1.
2. T2-T4 run in parallel only after A1; their owned paths are disjoint and every behavior starts with observed RED.
3. The A2 convergence checkpoint reruns T1-T4 and verifies no stage or adapter bypasses the envelope.
4. T5 passes the full shared suite, stages exact paths, preserves user-owned changes, pushes main, and reads back the remote commit.
5. T6 captures pin RED/GREEN, runs the default remote sync, verifies the receipt, records compatibility >=4.0.0 <5 in BASELINE_CHANGELOG.md, and leaves CHANGELOG.md unchanged.
6. T7 starts from committed T6 bytes, regenerates the self-hosted mirror, and verifies managed state plus durable docs.
7. T8 independently reviews architecture and simplification, reruns all focused suites, requires classifier result baseline, and records final evidence without publishing or mutating Linear.

Risks and Mitigations

• User-owned shared-source changes leak into generated mirrors. Use only the pushed remote cache as sync authority; exclude both dirty paths from staging; compare their pre/post hashes.
• A second prose schema increases cognitive load. Keep one executable envelope reference and one validator result; route stage and provider prose through it.
• The Collective profile becomes another hardcoded universal hierarchy. Require explicit profile selection and approval; fixtures prove context, not a default.
• One-open-working-set accidentally forbids legitimate decomposition. Limit it to unresolved work at the router-selected stage and retain multiple accepted Functional outcomes.
• Fresh provider state erases correction history. Keep operational snapshot and correction ledger as separate fields with different precedence roles.
• Cleanup semantics become destructive by default. Require the exact human verb, stable targets, provider support, approval, and final readback.
• Self-update introduces unrelated managed drift. Start from committed bundled bytes, inspect its JSON summary and changed paths, and stop on an unaccounted category.
• Fixture-heavy changes test wording instead of behavior. Assert public eligible/rejected route and mutation outcomes; keep exact strings only for stable result codes and documented operation names.
• Release work expands beyond the request. Add reviewed baseline notes and run classification, but do not publish without explicit instruction.

Unresolved Questions

None block this implementation. Every remaining product decision is explicitly parked with an owner and resume trigger.

Planned Review and Documentation

• plan-reviewer performs an independent read-only review before implementation.
• Each architecture wave ends with the documented continuous convergence checkpoint.
• A final findings-first code review checks architecture, simplification, regression coverage, and source/mirror provenance.
• Implementation notes record actual files, RED/GREEN evidence, deviations, exact shared-source SHA, Harness receipt, validation, and release classification.
• Durable root and wiki runbooks are updated in the same task as the generated workflow change.