Plan: Finder Intake and Requirements Boundary

Plan State

• Status: Complete. The user authorized a local canonical shared-skill checkout at /home/stefan/repos/harness-intelligence/.tmp/wearedevpunks-skills; gate G0 verified its clean checked-out main branch at 96273ded64bafe844dd9300ef7c0295653febb0d before W1 dispatch.
• Authorized path substitution: every retained task path beginning /Users/stefan/Desktop/repos/wearedevpunks-skills resolves to the local canonical checkout above for this run. Only location changed; scope, identity, dependencies, and validation did not.
• Task identity mode: provider-task for every task.
• Architecture applicability: architecture-bearing because six public workflow seams and their cumulative ownership change across the Finder, requirements compiler, provider writer, and delivery-state boundaries.
• Planning branch: team/stefan/finder-control-envelope at planning input 753563612fe6e39d5ec8665e294283b9628b7021.
• Open pull request: none observed by gh pr view during planning.
• Research: Finder Intake and Requirements Boundary Planning Research.
• Current graph step: W3 active with T6 after T1 through T5 completed, canonical main pushed at cedba700b240e5529e3589eee592b05b8bbb14c0, and both native blockers read back Done.

Initial Situation

The compiled specification and Linear hierarchy are retained and requirements are closed. The active implementation still exposes Technical Finder, treats Finder as a staged ladder, stops Requirements Phase before backlog projection, uses US-### as specification identity, and carries the superseded Linear Free mapping. Delivery-status guidance already distinguishes merge, staging, and production, but Fog intake and provider topology still contain staged fields.

The supported scaffold update has advanced the current repository to baseline 2026.09.02-e430f9a0. Fresh bun run hi check --json proves CLI 4.0.2 and no baseline drift. These accepted .devpunks/** changes are starting state and must not be reverted.

The user explicitly authorized the local canonical reusable-skill checkout /home/stefan/repos/harness-intelligence/.tmp/wearedevpunks-skills on this Linux host. It was freshly cloned from wearedevpunks/skills, verified clean, and verified on exact branch main before implementation dispatch.

Issue

Harness has two competing operating models. The accepted model has two explicit nontechnical Finder wrappers, optional Finder context for Requirements Phase, neutral specification outcomes, derived delivery identities, one provider writer, and production-evidence Fog completion. Current canonical and distributed instructions still encode the superseded three-stage model. The repair must converge every public seam and generated consumer without changing historical IP-380 through IP-388 or creating a second execution graph.

Proposed Solution Shape

Repair the canonical shared skills through the six existing provider Tasks, using public contract tests as RED/GREEN tracer bullets. Keep wrappers thin, make finder-phase the only Finder lifecycle engine, make Requirements Phase the only delivery-depth orchestrator, keep Create Spec provider-neutral, keep write-backlog the only provider mutation authority, preserve the standalone delivery-status seam, and retain provider mechanics in adapters plus the provider-neutral blocker validator.

After canonical tests pass, commit and push the shared source on main, update the exact Harness source pin, run bun run sync:skills, verify the receipt SHA, update Harness-owned catalog and prompt consumers, build and validate the bundled baseline, project it through the supported update path, run cumulative verification, classify release impact, and perform fresh repository/provider readback. Publication is not inferred: run bun run baseline:publish only if a reviewed changelog selects baseline and the user has requested publication.

Locked Decision Ledger

$grilling outcome

The canonical grill frontier is empty and shared understanding is confirmed. No planning decision is deferred. CI/CD event automation remains parked and is not part of this plan.

Dependency Readiness

No Stack Required. The specification requires no parent implementation or provider mutation before planning. The missing canonical checkout is an implementation environment precondition, not a changed dependency decision.

Branch/Base Intent

Not applicable. Keep the recorded Harness branch checked out for Harness implementation, validation, commits, push, and closeout. The canonical shared skills source separately follows its repository rule: checked-out main only.

Provider Identity Readback

Fresh readback resolved Devpunks workspace 1081916c-55b9-46bb-b923-a80db9ffca35, CLI Project ad21ca0b-b4b0-48e1-91ee-291a111335c4, and milestone 628692ba-d348-44eb-a7d9-185f504955fb (V4.2 Finder Intake and Requirements Boundary). All six Tasks are Backlog and carry their expected Story parent.

Every Task carries this exact immutable provider attachment: https://github.com/wearedevpunks/harness-intelligence/blob/aaa1aeeed984c0d2e6a2bb83132169bcb0f04142/apps/wiki/content/docs/project/specs/cli/issue-180-finder-intake-requirements-boundary/SPEC.md

The attached aaa1aeee… URL and current 75356361… immutable URL resolve to the same Git blob 5f945ed57caa3d5144cd768528981a4fdaa9a43b. No Task carries a Fog provenance link because this hierarchy was projected from direct Requirements authority; AC-014 permits that route and requires no implicit Fog. The connector alias observed in this session differs from the earlier handoff. Every provider operation must verify the stable workspace identity before use.

Codebase Findings

• Canonical skill sources currently pinned by Harness are synchronized under apps/cli/skills/**; .agents/skills/** is a scaffolded consumer.
• apps/cli/scripts/sync-skills-repo.mjs owns the canonical URL, exact commit pin, full skill-tree replacement, and receipt.
• Finder catalog and root prompt exposure are Harness-owned TypeScript in apps/cli/src/data/catalog/** and apps/cli/src/content/**.
• apps/cli/scripts/build-baseline.mjs and build-dist.mjs bind synchronized skills, catalogs, prompts, subagents, and generated hashes into release artifacts.
• Create Spec has five named repair surfaces. Keep their vocabulary and readiness rules aligned instead of scattering additional identities.
• validateTaskBlockerGraph(...) is already a deep provider-neutral module: keep milestone ordering, missing-target, self-edge, future-edge, and cycle policy behind this interface.
• Delivery status is already a separate deep seam. Preserve it rather than teaching Finder or provider adapters to infer production completion.
• Root docs still describe the superseded Finder model and contain an old shared-source pin. Docs updates are mandatory after implementation proof.

External Research

No external library or framework API changes are planned. Current repository source, immutable shared-source content, the accepted spec, and live provider readback are sufficient. Context7/web dependency research is therefore not applicable.

Architecture Contract

Target Ownership Topology

public intake
├── business-finder       # business language; ceiling Initiative
├── functional-finder     # business + functional language; ceiling Epic
└── finder-phase          # sole Fog/support-work lifecycle and resume owner

delivery-depth orchestration
└── requirements-phase
    ├── requirements-grill
    ├── create-spec       # compiles accepted decisions as OUT-###
    └── write-backlog     # derives hierarchy, Stories, Tasks, blockers

provider mutation
└── write-backlog
    ├── provider-neutral identity + blocker validation
    ├── Linear adapter    # linear-free-v1
    ├── GitHub adapter    # Projects V2 + recursive Issues
    └── exact readback + residual delta

delivery truth
└── delivery-status       # observed start/block/review/PR/merge/stage/prod

• Finder wrappers own audience, intake language, ceiling, and return shape. They must not absorb Fog routing, requirements closure, or provider writes.
• finder-phase owns one Fog, immutable intake lens, generic Grilling, Research, Prototype, reuse/create/ambiguity, and bounded return.
• Requirements Phase owns conditional Finder-context loading and the only route through full requirements closure to delivery projection. It must not absorb provider mechanics.
• Create Spec owns provider-neutral compilation and immutable readiness. It must not assign provider Story identity.
• Write Backlog owns semantic hierarchy, mutation validation, adapters, preview/approval, write, readback, and residual delta. Adapters must not own product hierarchy policy independently.
• Delivery status owns evidence transitions and Fog completion. Finder return and merge must not infer production.

Declared Dependency Graph

business-finder ──public wrapper contract──┐
functional-finder ─public wrapper contract─┴─> finder-phase

direct requirements ───────────────────────┐
optional exact Finder context ─────────────┴─> requirements-phase
  ──> requirements-grill ──> create-spec ──stable SPEC──> write-backlog
  ──> validateTaskBlockerGraph ──> selected provider adapter ──> readback

delivery observations ──> delivery-status ──production coverage──> Fog completion

Allowed cross-owner edges use the named public contracts. Forbidden edges are: Finder to Create Spec or delivery projection; Create Spec to provider Story selection; provider adapters to requirements decisions; Design Phase directly to former Technical projection; and merge/staging to Fog completion.

Responsibility Acceptance Criteria

Architecture Waves

A1 boundary establishment
  T1 Finder ownership
  T2 Requirements ownership
  checkpoint RAC-1, RAC-2

A2 identity and truth
  T3 outcome identity
  T4 Fog/delivery truth
  checkpoint RAC-1..RAC-4

A3 provider convergence
  T5 hierarchy/adapters/blockers/readback
  checkpoint RAC-1..RAC-5

A4 final distribution closure
  T6 sync, generated consumers, docs, full verification, live readback
  checkpoint RAC-1..RAC-6; migration ledger empty

Architecture waves describe cumulative topology. Worker wave boundaries below also honor the single canonical-source worktree lock.

Public Seam Contract

Any implementation that changes one of these consumer contracts must first amend this plan and re-run plan review. It may not silently widen ownership.

Migration Ledger

No temporary seam is planned or permitted. Canonical edits may be uncommitted while their RED/GREEN loop runs, but distributed mirrors are synchronized only after canonical convergence. Final closure requires no Technical compatibility route, Stage gate, US-### specification identity, exact-Story bridge, or parallel provider writer.

Task Dependency Graph

T1 IP-432 ───────────────────────────────┐
T2 IP-433 ───────────────────────────────┤
T3 IP-434 ──> T5 IP-436 ──┐             ├─ cumulative validation in T6
T4 IP-435 ────────────────┴─> T6 IP-437 ┘

Only the T3 -> T5, T4 -> T6, and T5 -> T6 arrows are provider-native blockers. T1 and T2 have no invented blocker edge to T6; their acceptance is a cumulative T6 gate.

Worker wave boundaries

The four initially unblocked Tasks own disjoint content and new test files, so they run together. Workers edit only their declared files. They never stage, commit, push, switch, or create branches. The parent alone owns the canonical Git index, HEAD, and push after W2 validation; this shared integration step is outside worker write scope and does not add provider blockers.

Tasks

T1 / IP-432: Simplify Finder to Business and Functional entrypoints

• depends_on: []
• location: canonical shared-skill Finder surfaces and their contract tests
• owned_paths:
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/business-finder/**
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/functional-finder/**
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/finder-phase/**
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/technical-finder/** (remove)
• /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/finder-intake-boundary.contract.test.mjs (new)
• /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/fixtures/finder-phase-routes.json
• /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/finder-phase-graph.contract.test.mjs (existing declared GREEN seam; evidence-only ownership clarification)
• /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/functional-finder.contract.test.mjs (existing declared GREEN seam; evidence-only ownership clarification)
• wave_boundary: W1
• description: Replace staged Finder with two explicit nontechnical wrappers over one graph engine; preserve one Fog, immutable intake lens, generic Grilling/Research/Prototype children, evidence-based reuse/create/ambiguity, Business Initiative ceiling, Functional Epic ceiling, and bounded return without Fog completion. Remove Technical Finder and its route/depth.
• validation: RAC-1; AC-001 through AC-013 and AC-021; no canonical public route, catalog input, or contract exposes Technical Finder.
• status: Complete
• log: RED proved active Technical Finder/staged graph; worker and parent integration produced the two-wrapper generic-child engine; focused and cross-contract checks passed; Linear exact readback is Done.
• files edited/created: Finder wrappers/engine, removed Technical Finder, Finder/show-me/review contracts and route fixture.
• task_identity_mode: provider-task
• backlog_item_id: 3e3ee922-a289-46f8-a955-47826025c0cd
• backlog_item_url: https://linear.app/devpunks/issue/IP-432/simplify-finder-to-business-and-functional-entrypoints
• relation_mode: native
• backlog_sync_skip_reason:
• assigned_skills: [writing-for-agents, write-graph-based-skills, tdd, codebase-design, simplify]
• implementation_skill_guidance:
  • skill: writing-for-agents applicable_behavior: Keep wrapper pointers thin, co-locate each owner's rules, remove stale staged sediment, and preserve explicit invocation mechanics.
  • skill: write-graph-based-skills applicable_behavior: Repair the existing durable router graph with explicit guards, resume evidence, one selected phase, and bounded return; keep sibling phases isolated.
  • skill: tdd applicable_behavior: Rewrite one public Finder contract first, capture real RED against the three-stage implementation, then make the smallest coherent graph change to GREEN.
  • skill: codebase-design applicable_behavior: Keep audience/ceiling in wrappers and lifecycle complexity behind the shared Finder interface; test the same seam callers use.
  • skill: simplify applicable_behavior: After GREEN, remove Technical/Stage/cardinality branches and redundant wording without widening the accepted contract.
• tdd_status: required
• tdd_target: Public skill contracts expose exactly two explicit-only wrappers, generic support-child routing, accepted ceilings, ambiguity handback, and bounded non-completing return.
• red_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test tests/finder-intake-boundary.contract.test.mjs
• expected_red_failure: Current Technical Finder/depth, staged cardinality, Business Epic output, or Functional Story output violates the new public assertions.
• green_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test tests/finder-intake-boundary.contract.test.mjs tests/finder-phase-graph.contract.test.mjs tests/functional-finder.contract.test.mjs
• reason_not_testable:
• red_evidence: Finder intake failed 0/1 because Technical Finder existed; graph slices exposed staged gates, lens maturity, and above-ceiling routing.
• green_evidence: Finder gate 12/12; review/show-me 47/47; cumulative A1/A2 checkpoint passed.
• codebase_design_notes: Deepen the shared Finder module: wrappers expose a small presentation/ceiling interface while the engine owns routing, resume, support work, and durable return.
• 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 wrappers and finder-phase
• integration_surface: public skill invocation and durable Finder handoff
• public_seam: Business/Functional bounded result plus Finder router/handoff
• topology_delta: Remove Technical wrapper/depth and move all shared lifecycle behavior behind one engine.
• forbidden_ownership: Requirements closure, Story/Task projection, provider mechanics, Fog completion inference
• temporary_seams: none
• responsibility_acceptance_criteria: [RAC-1]

T2 / IP-433: Make Requirements Phase the sole delivery-depth route

• depends_on: []
• location: canonical Requirements Phase and route handback contracts
• owned_paths:
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/requirements-phase/**
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase/phases/backlog.md
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/delivery-phase/phases/router.md
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/requirements-delivery-depth.contract.test.mjs (new)
• wave_boundary: W1
• description: Accept direct bounded requirements input, conditionally load an exact supplied Finder graph, compose Requirements Grill, Create Spec, and Write Backlog, derive missing placement from accepted authority, and return scope-changing design evidence to Requirements Phase.
• validation: RAC-2; AC-014 through AC-020 and AC-035; direct invocation creates no Finder artifact and no other route authorizes Story/Task blockers.
• status: Complete
• log: RED proved missing direct/optional-context composition; Requirements Phase now owns Requirements Grill, Create Spec, and Write Backlog; Linear readback is Done.
• files edited/created: Requirements Phase, Design/Delivery handback routes, delivery-depth/composition contracts.
• task_identity_mode: provider-task
• backlog_item_id: fc798d2c-8bb5-4ee0-83fb-74b9534db027
• backlog_item_url: https://linear.app/devpunks/issue/IP-433/make-requirements-phase-the-sole-delivery-depth-route
• relation_mode: native
• backlog_sync_skip_reason:
• assigned_skills: [writing-for-agents, tdd, codebase-design, simplify]
• implementation_skill_guidance:
  • skill: writing-for-agents applicable_behavior: Make the conditional Finder-context pointer precise and keep direct and context routes easy to distinguish.
  • skill: tdd applicable_behavior: Capture RED first for direct no-Finder input and one exact supplied-context route through the public Requirements result.
  • skill: codebase-design applicable_behavior: Keep orchestration behind the Requirements Phase interface and provider mechanics behind Write Backlog.
  • skill: simplify applicable_behavior: Remove prior-Finder, Technical, exact-Story, fixed-count, and direct-design projection routes after GREEN.
• tdd_status: required
• tdd_target: Direct and optional-context callers reach one stable spec and Write Backlog result without implicit Finder ownership.
• red_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test tests/requirements-delivery-depth.contract.test.mjs
• expected_red_failure: Current Requirements Phase stops after Create Spec and rejects or omits the accepted post-spec projection route.
• green_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test tests/requirements-delivery-depth.contract.test.mjs tests/requirements-grill-composition.contract.test.mjs
• reason_not_testable:
• red_evidence: New delivery-depth contract failed 4/4 on direct invocation, exact optional context, backlog projection, and design return.
• green_evidence: Mandated Requirements suite 10/10; cumulative A1/A2 checkpoint passed.
• codebase_design_notes: Requirements Phase is the deep orchestration seam; optional Finder loading is an input adapter, not a second workflow.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A1
• behavior_owner: Requirements Phase
• integration_surface: direct bounded input, optional Finder handles, Design/Delivery routing
• public_seam: stable Requirements result naming retained spec and Write Backlog result
• topology_delta: Extend the existing phase from compilation to the sole delivery-depth orchestration boundary.
• forbidden_ownership: Finder lifecycle, provider adapter mechanics, provider identity inference in Create Spec
• temporary_seams: none
• responsibility_acceptance_criteria: [RAC-2]

T3 / IP-434: Separate specification outcomes from backlog identities

• depends_on: []
• location: canonical Create Spec compiler and technical projection contract
• owned_paths:
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/create-spec/SKILL.md
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/create-spec/assets/SPEC-TEMPLATE.md
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/create-spec/references/readiness.md
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/create-spec/references/spec-quality-bar.md
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/references/technical-projection.md
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/finder-outcome-identity.contract.test.mjs (new)
• wave_boundary: W1
• description: Use OUT-### for neutral outcomes, require complete one-way AC coverage, remove Technical/exact-Story prerequisites, and derive or reuse Epic/Story/Task identities only after immutable compilation.
• validation: RAC-3; AC-017 through AC-019, AC-036, and AC-037; all five repair surfaces agree and a fixture has unequal outcome/Story counts.
• status: Complete
• log: RED proved US/User Stories identity; five surfaces now use neutral OUT identities; shared lifecycle reconciled; Linear readback is Done.
• files edited/created: Create Spec skill/template/readiness/quality bar, delivery projection, outcome/lifecycle contracts.
• task_identity_mode: provider-task
• backlog_item_id: b8e10f6c-6808-43bc-a1a7-ebf00ff635fb
• backlog_item_url: https://linear.app/devpunks/issue/IP-434/separate-specification-outcomes-from-backlog-identities
• relation_mode: native
• backlog_sync_skip_reason:
• assigned_skills: [writing-for-agents, tdd, codebase-design, simplify]
• implementation_skill_guidance:
  • skill: writing-for-agents applicable_behavior: Keep outcome identity defined once, disclose readiness details behind precise pointers, and remove stale exact-Story caches.
  • skill: tdd applicable_behavior: Make the five-surface consistency and unequal-cardinality fixture RED before changing compiler/projection prose.
  • skill: codebase-design applicable_behavior: Preserve Create Spec as a provider-neutral compiler interface and Write Backlog as the adapter from outcomes to delivery identities.
  • skill: simplify applicable_behavior: Remove duplicate US-###, User Stories, Technical Finder, and one-outcome/one-Story assumptions after GREEN.
• tdd_status: required
• tdd_target: Immutable readiness proves complete OUT-### coverage while Write Backlog independently derives provider Stories and Tasks.
• red_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test tests/finder-outcome-identity.contract.test.mjs
• expected_red_failure: All five current surfaces expose US-###, User Stories, Technical Finder, exact Story, or false cardinality.
• green_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test tests/finder-outcome-identity.contract.test.mjs tests/write-backlog-lifecycle.contract.test.mjs
• reason_not_testable:
• red_evidence: Outcome contract failed because template lacked Requirements and Outcomes and retained US-001/User Stories coverage.
• green_evidence: Outcome 4/4; combined lifecycle 14/14; cumulative A1/A2 checkpoint passed.
• codebase_design_notes: Create Spec hides compilation/readiness behind one stable artifact; Write Backlog is the sole identity-derivation adapter.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A2
• behavior_owner: Create Spec and Write Backlog projection boundary
• integration_surface: compiled SPEC.md consumed by delivery projection
• public_seam: OUT-###/AC readiness and immutable spec reference
• topology_delta: Remove provider Story identity from the compiler and move derivation wholly behind Write Backlog.
• forbidden_ownership: provider item selection/count inside Create Spec; mutable/local-only authority
• temporary_seams: none
• responsibility_acceptance_criteria: [RAC-3]

T4 / IP-435: Preserve Fog provenance and production-evidence completion

• depends_on: []
• location: canonical Fog provenance and delivery-status contracts
• owned_paths:
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/references/fog-intake.md
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/references/delivery-status.md
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/references/normalization.md
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/finder-fog-delivery-truth.contract.test.mjs (new)
• wave_boundary: W1
• description: Preserve immutable intake lens and lateral provider links, treat historical Stage as compatibility evidence only, keep delivery facts distinct, deny completion credit to Cancelled/Superseded Fogs, and complete only from exact production coverage of accepted resulting scope.
• validation: RAC-4; AC-012, AC-013, AC-021, AC-022, and AC-033; provider snapshots for IP-380 through IP-388 remain unchanged.
• status: Complete
• log: Three RED slices proved missing immutable lens, historical compatibility, and distinct delivery evidence; production-only completion is green; Linear readback is Done.
• files edited/created: Fog intake, delivery status, normalization, Fog delivery-truth/normalization contracts.
• task_identity_mode: provider-task
• backlog_item_id: 9feb4c38-7029-48ba-938d-3d5e2237e4ca
• backlog_item_url: https://linear.app/devpunks/issue/IP-435/preserve-fog-provenance-and-production-evidence-completion
• relation_mode: native
• backlog_sync_skip_reason:
• assigned_skills: [writing-for-agents, tdd, codebase-design, simplify]
• implementation_skill_guidance:
  • skill: writing-for-agents applicable_behavior: Co-locate provenance authority, observed state, completion coverage, and historical compatibility rules at their owning seams.
  • skill: tdd applicable_behavior: Add only missing historical/no-credit/accepted-scope assertions, preserving the already-green merge/stage/production distinctions.
  • skill: codebase-design applicable_behavior: Keep delivery truth behind the delivery-status interface; Finder and adapters supply evidence but do not infer completion.
  • skill: simplify applicable_behavior: Remove current Stage/cardinality gates while retaining narrow production-evidence language and exact readback.
• tdd_status: required
• tdd_target: Fog provenance remains lateral and immutable; only complete production coverage grants completion credit.
• red_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test tests/finder-fog-delivery-truth.contract.test.mjs
• expected_red_failure: Current Fog intake requires Stage/cardinality and lacks immutable lens plus historical compatibility/no-credit assertions.
• green_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test tests/finder-fog-delivery-truth.contract.test.mjs tests/delivery-backlog-state.contract.test.mjs tests/delivery-backlog-state-integration.contract.test.mjs
• reason_not_testable:
• red_evidence: Initial 0/1 immutable-lens failure, then historical-stage and review/distinct-fact failures.
• green_evidence: Assigned delivery/Fog 12/12; normalization 3/3; cumulative A1/A2 checkpoint passed.
• codebase_design_notes: Delivery status is a deep evidence-to-result module; provenance and completion coverage remain local to it.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A2
• behavior_owner: Fog provenance and delivery-status branch
• integration_surface: Finder return, Write Backlog links, Implement Spec lifecycle, Fog closeout
• public_seam: delivery transition/readback result and production coverage decision
• topology_delta: Replace staged Fog fields with immutable lens/provenance while preserving the existing production-only completion seam.
• forbidden_ownership: provider hierarchy policy; implicit completion from Finder, merge, or staging
• temporary_seams: none
• responsibility_acceptance_criteria: [RAC-4]

T5 / IP-436: Derive and validate provider hierarchy from retained specifications

• depends_on: [T3]
• location: canonical Write Backlog hierarchy, adapters, validator, and focused fixtures
• owned_paths:
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/SKILL.md
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/REFERENCE.md
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/assets/concepts/backlog-model.md
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/references/project-context.md
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/references/providers/linear.md
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/references/providers/github.md
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/scripts/validate-task-blocker-graph.mjs
  • /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/finder-provider-hierarchy.contract.test.mjs (new)
• wave_boundary: W2
• description: Consume immutable OUT-### specs; derive/reuse placement; implement linear-free-v1 and accepted GitHub Projects V2 mapping; validate full blocker graph, workspace, identity, labels, parents, milestone, approval, preview, write, exact readback, partial failure, and residual delta.
• validation: RAC-5; AC-022 through AC-032, AC-034, and AC-035; both provider branches fail closed and Linear creates neither nested semantic Initiatives nor a Project per semantic Initiative.
• status: Complete
• log: Focused provider checkpoint passed 41/41 after correcting the stale Source stories assertion to Source outcomes; the full canonical suite passed 218/225 with only seven pre-existing unrelated parallel-research durable-report failures. git diff --check passed. Linear IP-436 read back Done in Devpunks workspace 1081916c-55b9-46bb-b923-a80db9ffca35. Parent committed the main hierarchy repair at 0fe4c88, then removed the remaining provider-payload US-### identity under a focused RED/GREEN at 750ab36, then removed tracked platform metadata at 394da118c9f619c394e1485b9cb38b0121287c7c, and made bounded Finder returns fail closed on incomplete support evidence at cedba700b240e5529e3589eee592b05b8bbb14c0; all four commits are pushed on canonical main.
• files edited/created: canonical Write Backlog policy, Linear/GitHub adapters, hierarchy concepts, blocker validator, compatibility examples, and focused provider contract suites under the authorized local checkout.
• task_identity_mode: provider-task
• backlog_item_id: 3e01c90c-e486-4844-977c-4f7262badcd8
• backlog_item_url: https://linear.app/devpunks/issue/IP-436/derive-and-validate-provider-hierarchy-from-retained-specifications
• relation_mode: native
• backlog_sync_skip_reason:
• assigned_skills: [writing-for-agents, tdd, codebase-design, simplify]
• implementation_skill_guidance:
  • skill: writing-for-agents applicable_behavior: Keep semantic hierarchy and validation in provider-neutral authority; disclose only adapter-specific representation in provider branches.
  • skill: tdd applicable_behavior: Turn the current nested-Initiative Linear fixture RED first, then proceed one mapping/rejection/readback behavior at a time.
  • skill: codebase-design applicable_behavior: Preserve the small mutation envelope and blocker-validator interfaces; adapters translate representation and cannot redefine policy.
  • skill: simplify applicable_behavior: Remove old nested-Initiative/Epic-Project/Stage mechanics and duplicated validation after all provider contracts are GREEN.
• tdd_status: required
• tdd_target: One retained spec deterministically maps to validated Linear Free or GitHub hierarchy and returns exact readback/residual delta.
• red_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test tests/finder-provider-hierarchy.contract.test.mjs
• expected_red_failure: Current Linear mapping uses nested Initiatives and Epic Projects and does not satisfy the accepted full hierarchy/readback contract.
• green_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test tests/finder-provider-hierarchy.contract.test.mjs tests/write-backlog-operating-model.contract.test.mjs tests/write-backlog-lifecycle.contract.test.mjs tests/write-backlog-linear.contract.test.mjs tests/write-backlog-github.contract.test.mjs tests/write-backlog-provider-planning.contract.test.mjs
• reason_not_testable:
• red_evidence: Initial focused hierarchy contract failed on nested native Linear Initiative / Epic Project assumptions and incomplete provider-neutral readback rules, as recorded by the W2 worker handoff.
• green_evidence: node --test tests/finder-provider-hierarchy.contract.test.mjs tests/write-backlog-operating-model.contract.test.mjs tests/write-backlog-lifecycle.contract.test.mjs tests/write-backlog-linear.contract.test.mjs tests/write-backlog-github.contract.test.mjs tests/write-backlog-provider-planning.contract.test.mjs passed 41/41 in the local canonical checkout; git diff --check passed.
• codebase_design_notes: Provider-neutral hierarchy and blocker validation form the deep module; Linear/GitHub are true-external adapters behind that seam.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A3
• behavior_owner: Write Backlog mutation envelope, validator, and provider adapters
• integration_surface: Requirements Phase output and provider APIs
• public_seam: preview/approval/write/readback result with residual delta
• topology_delta: Replace legacy provider topology while preserving one provider-neutral policy owner and two representation adapters.
• forbidden_ownership: requirements closure, Create Spec identity, provider writes outside Write Backlog, historical-ticket normalization
• temporary_seams: none
• responsibility_acceptance_criteria: [RAC-5]

T6 / IP-437: Prove compatibility, delivery transitions, and exact readback

• status: Complete
• depends_on: [T4, T5]
• location: canonical commit/receipt, Harness synchronized consumers, catalog/prompt code, docs, release and live readback evidence
• owned_paths:
  • apps/cli/scripts/sync-skills-repo.mjs
  • apps/cli/src/scripts/sync-skills-repo.test.ts
  • apps/cli/.devpunks-cache/skills-sync.json
  • apps/cli/skills/** (generated by sync only)
  • apps/cli/src/data/catalog/skills.ts
  • apps/cli/src/data/catalog/packs.ts
  • apps/cli/src/content/prompts.ts
  • apps/cli/src/content/scaffold-copy.ts
  • apps/cli/src/content/finder-entrypoints-catalog-prompts.test.ts
  • apps/cli/src/data/bundled-baseline-identity.generated.ts (generated)
  • .agents/skills/** (supported baseline projection only; never hand edit)
  • .devpunks/scaffold-manifest.json
  • .devpunks/settings.json
  • docs/README.md
  • docs/runbooks/hi-cli-scaffolding.md
  • BASELINE_CHANGELOG.md and/or CHANGELOG.md only when release classification requires reviewed notes
  • apps/wiki/content/docs/project/specs/cli/issue-180-finder-intake-requirements-boundary/IMPLEMENTATION-NOTES.md
• wave_boundary: W3
• description: Verify the parent's pushed canonical main SHA, pin and synchronize that exact SHA, update Harness-owned Finder exposure, verify byte parity and generated hashes, update operator docs, build/project the bundled baseline through supported commands, run full source and Harness checks, prove compatibility and delivery transitions, classify release, and perform exact provider/repository/CI/published-state readbacks without changing IP-380 through IP-388.
• validation: RAC-1 through RAC-6; all accepted testing decisions and verification seams; source SHA=pin=test=receipt; clean scaffold check; exact Devpunks hierarchy/milestone/blocker readback; publication state reported separately and never inferred.
• status: In Progress
• log:
• files edited/created:
• task_identity_mode: provider-task
• backlog_item_id: d9c61507-5123-414a-8eee-2cee8f82e416
• backlog_item_url: https://linear.app/devpunks/issue/IP-437/prove-compatibility-delivery-transitions-and-exact-readback
• relation_mode: native
• backlog_sync_skip_reason:
• assigned_skills: [writing-for-agents, quality-types, tdd, codebase-design, simplify]
• implementation_skill_guidance:
  • skill: writing-for-agents applicable_behavior: Keep root prompts, scaffold guidance, docs, pin evidence, and skill pointers aligned with the accepted ubiquitous language.
  • skill: quality-types applicable_behavior: Keep TypeScript catalog/prompt identities literal and closed so Technical Finder cannot remain through a loose string surface.
  • skill: tdd applicable_behavior: Change the Harness public catalog expectation first, capture RED against stale generated/TypeScript exposure, then synchronize and update to GREEN.
  • skill: codebase-design applicable_behavior: Treat canonical source, sync adapter, catalog consumer, baseline projection, and provider readback as explicit seams; do not duplicate skill policy in TypeScript.
  • skill: simplify applicable_behavior: After cumulative GREEN, remove stale Technical/pin/docs references and redundant compatibility text while preserving historical evidence.
• tdd_status: required
• tdd_target: Canonical source, distributed skill trees, Finder catalog/prompt surface, docs, baseline, and live readback express one compatible contract.
• red_command: bun run --cwd apps/cli test -- src/content/finder-entrypoints-catalog-prompts.test.ts src/scripts/sync-skills-repo.test.ts
• expected_red_failure: Updated expectations reject the current three-wrapper catalog and old source pin/receipt.
• green_command: bun run --cwd apps/cli test -- src/content/finder-entrypoints-catalog-prompts.test.ts src/scripts/sync-skills-repo.test.ts && bun run --cwd apps/cli check-types && bun run --cwd apps/cli check && bun run baseline:build && bun run validate:packaged-product && bun run validate:consumer-repositories && bun run hi check --json
• canonical_full_suite_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test tests/*.test.mjs
• sync_command: cd /home/stefan/repos/harness-intelligence && bun run sync:skills
• receipt_command: cd /home/stefan/repos/harness-intelligence && jq -r '.requestedRef, .commit' apps/cli/.devpunks-cache/skills-sync.json
• receipt_expected_result: requestedRef and commit equal the exact pushed canonical source SHA recorded by the parent, and that same SHA appears in apps/cli/scripts/sync-skills-repo.mjs plus its pin test.
• baseline_build_command: cd /home/stefan/repos/harness-intelligence && bun run --cwd apps/cli build && bun run baseline:build
• bundled_projection_command: cd /home/stefan/repos/harness-intelligence && node apps/cli/dist/index.js update --json --baseline bundled --input /home/stefan/repos/harness-intelligence --check
• bundled_projection_expected_result: The locally built CLI reports only the reviewed corrected managed delta. Apply it to the Harness worktree only when the selected release flow can retain a compatible exact baseline pin; otherwise validate the bundled product in run-owned fixtures and do not make the stable checkout drift.
• stable_scaffold_readback_command: cd /home/stefan/repos/harness-intelligence && bun run hi check --json
• stable_scaffold_expected_result: failed:false, CLI 4.0.2 current, baselineVersionDrift:false, empty changedFiles, no stale files, and operation success.
• release_classification_command: cd /home/stefan/repos/harness-intelligence && bun run release:classify -- --base e430f9a070865a1a784555baa6e9011c58561114 --head HEAD
• release_classification_expected_result: Classification follows only the changed changelog paths. Record baseline/npm/mixed/none and every unmet release precondition. Publish no artifact unless baseline is selected, reviewed notes and compatibility pass, and the user explicitly requested it.
• provider_readback_checkpoint: Call get_workspace({}) on the selected Linear connector and require Devpunks workspace 1081916c-55b9-46bb-b923-a80db9ffca35; then call get_issue({id: <Task UUID>, includeRelations: true}) for all six UUIDs in the Provider Identity Readback table. Require exact Task identifier, parent Story, V4.2 milestone, Backlog/delivery state, immutable spec attachment, native blocker edges, and no Fog link for this direct-Requirements projection. Separately read IP-380 through IP-388 and compare their retained identity/state snapshot byte-for-byte. This checkpoint is read-only.
• provider_readback_expected_result: The live hierarchy matches the table, T3 blocks T5, T4 and T5 block T6, no other execution blockers are invented, and historical staged items are unchanged.
• reason_not_testable:
• red_evidence:
• green_evidence:
• codebase_design_notes: Synchronization is an adapter from canonical policy to generated consumers; exact receipt and bundled identity make the seam observable without copying policy into callers.
• review_mode: cli
• runtime_validation: required
• runtime_target: supported Harness CLI bundled-baseline projection plus read-only Devpunks Linear and GitHub provider surfaces
• runtime_evidence: Local bundled CLI projects the corrected contract with no drift; fresh provider reads prove workspace, Root/Product Area/Story/Task parents, V4.2 membership, blockers, immutable spec links, unchanged IP-380 through IP-388, and exact residual state. If a live GitHub Story-to-Task write is explicitly authorized, retain its exact recursive readback separately; otherwise report that runtime coverage as not exercised.
• runtime_cleanup: Use no provider mutation for ordinary verification. Any separately authorized disposable provider write must carry a unique run identifier and remove only run-owned resources after exact readback.
• architecture_wave: A4
• behavior_owner: canonical/distributed contract integration and closeout evidence
• integration_surface: shared source Git, Harness sync/build/update, CLI checks, docs, Linear/GitHub readback, release authority
• public_seam: exact source receipt, catalog output, bundled baseline identity, scaffold check, provider readback
• topology_delta: Converge every consumer on the target ownership graph and remove all stale compatibility routes.
• forbidden_ownership: new product requirements, implicit provider mutation, unrequested publication, historical ticket edits, manual generated-skill edits
• temporary_seams: none; final migration ledger must be empty
• responsibility_acceptance_criteria: [RAC-1, RAC-2, RAC-3, RAC-4, RAC-5, RAC-6]

Testing Strategy

1. Each behavior-changing provider Task starts with one focused public-contract RED in the canonical source and advances one tracer bullet at a time.
2. Each canonical task runs its focused GREEN suite before the source lock moves. Previously satisfied architecture criteria are regression-checked at every architecture checkpoint.
3. The parent integration checkpoint runs the complete canonical suite before commit/push. T6 verifies checked-out main equals the pushed SHA, reruns the complete suite at that fixed point, then compares the SHA with the Harness pin, pin test, and sync receipt.
4. Harness runs focused catalog/sync tests, typecheck, lint/format check, baseline build, packaged-product validation, and consumer-repository validation.
5. A locally built CLI projects the bundled baseline through the supported update interface; bun run hi check --json must then report failed:false, no drift, no stale or changed files, and a successful operation.
6. Static compatibility searches reject active Technical Finder, Stage gates, US-### specification identity, exact selected Story, and fixed-count assumptions while excluding retained historical evidence paths.
7. Live readback verifies provider state separately from fixtures. Provider, repository, CI, and published-baseline states each receive their own verdict.

Validation Gates

• Gate G0 — environment (blocking before worker dispatch): run test -d /Users/stefan/Desktop/repos/wearedevpunks-skills/.git, git -C /Users/stefan/Desktop/repos/wearedevpunks-skills branch --show-current, git -C /Users/stefan/Desktop/repos/wearedevpunks-skills status --short, git -C /Users/stefan/Desktop/repos/wearedevpunks-skills diff --name-status, and git -C /Users/stefan/Desktop/repos/wearedevpunks-skills log -1 --format=%H. The directory must exist and branch output must be exactly main. Persist the dirty-file inventory, reconcile user-owned changes without reset or overwrite, verify Harness remains on team/stefan/finder-control-envelope, and confirm the accepted baseline remediation files are retained. If any check fails, dispatch zero implementation workers and report the exact restoration or reconciliation blocker.
• Gate G1 — A1: RAC-1 and RAC-2 pass; no Finder route owns delivery depth.
• Gate G2 — A2: RAC-1 through RAC-4 pass; outcome identity and delivery truth have no temporary bridges.
• Gate G3 — A3: RAC-1 through RAC-5 pass; provider mapping and blocker rejection are GREEN for both adapters.
• Gate G4 — canonical publication: all source tests pass; one reviewed canonical commit is pushed on main; SHA is recorded.
• Gate G5 — distribution: Harness pin/test/receipt match the pushed SHA; generated mirrors and catalogs are consistent; type/check/build/package and consumer validation pass.
• Gate G6 — architecture closure: RAC-1 through RAC-6 pass, forbidden edges are absent, public seams match this plan, and migration ledger is empty.
• Gate G7 — delivery closeout: hi check green; two-axis review clean or repaired within budget; docs ingest complete; exact provider/repository/CI/ published-state readbacks recorded; Linear delivery status reconciled through Write Backlog only.

Review and Docs Routing

• implement-spec must maintain PLAN.md and IMPLEMENTATION-NOTES.md after each validated worker boundary and record one skill-application evidence item per implementation guidance entry.
• After task checks, run simplify on changed source and Harness code before final validation.
• verify-behavior is applicable only to visibly exercisable CLI behavior. The skill-contract and provider readback criteria use CLI/runtime evidence; do not claim browser verification from tests.
• Freeze the final Git target and run two-axis review: Standards and Spec remain separate reports.
• Route private/internal operator, scaffold, architecture, and runbook changes through docs-ingest-phase. Public docs are a no-op unless implementation changes reader-facing product usage.

Risks and Mitigations

• Canonical checkout unavailable: stop before implementation edits and restore/mount the exact source; never substitute a Harness mirror.
• User-owned canonical changes: inventory and reconcile; never reset, overwrite, or use another branch/worktree.
• Shared source Git integration: run disjoint W1 workers together; reserve staging, commit, HEAD, and push exclusively for the parent after W2 without inventing provider blockers.
• Broad sync replacement: inspect full source diff before push and full generated diff after bun run sync:skills; verify exact receipt and parity.
• Generated mirror drift: use sync/build/update commands only; never hand edit .agents/skills/** or apps/cli/skills/**.
• Alias confusion: verify stable provider workspace ID before every read or write.
• Historical-ticket damage: snapshot/read IP-380 through IP-388 before and after; exclude them from mutation intent.
• False provider proof: keep deterministic contract tests and live readback as separate evidence classes.
• Release overreach: classify from changed changelogs; publish only when selected, reviewed, and explicitly requested.
• Tool bootstrap gaps: clawpatch and debug-agent are currently absent. They do not block planning or current scaffold health; any later phase that explicitly requires them must resolve or report the exact blocker.

Unresolved Questions

None in product scope. One external environment condition remains: the accepted canonical source checkout must be restored before implementation. This does not change the plan or requirements.

$show-me Execution View

restore canonical main + reconcile user changes
  W1 parallel: IP-432 Finder | IP-433 Requirements | IP-434 OUT | IP-435 Fog
    W1 cumulative architecture checkpoint
      W2 IP-436 provider hierarchy
        parent commit + push canonical main
          W3 IP-437 sync + full proof
            review -> docs ingest -> exact closeout

This view shows the safe source-worktree order. Provider precedence remains the native graph recorded above.

$wait-what Language Check

The plan uses the canonical terms Product/Backlog Root, Product Area, Initiative, Epic, Story, Task, Fog, Finder intake lens, Grilling child, Requirements Phase, Linear Free projection profile, V* milestone iteration, and Normalization. It states context, ownership, evidence, and stop conditions in direct Simplified Technical English. No new product term or requirement is introduced.

Planning Stop

The execution contract is complete and provider identities are unchanged. Planning made no Linear mutation. Implementation dispatch remains blocked until G0 proves the accepted canonical checkout and user-change reconciliation. Stop here before implementation workers.