Plan: Project Backlog Operating Model

Authority

• Goal: deliver Linear Epic IP-380 and Stories IP-381 through IP-388.
• Immutable spec: eee747ec:SPEC.md.
• Planning research: 6d91c5f3:finder-backlog-operating-model-planning-research-report.md.
• Canonical shared-skill source at planning time: /Users/stefan/Desktop/repos/wearedevpunks-skills, clean main, caa755e3c080f8bc77773bd0ccbea3be935aa5c4.
• Harness branch: team/stefan/finder-phase-write-backlog-improvements.
• Dependency readiness: No Stack Required.
• Requested release: CLI 4.0.0, baseline compatibility >=4.0.0 <5, with both changelogs updated.

Delivery State

Implementation and contract validation are complete for the shared-skill source, CLI integration, major-version metadata, generated projections, and durable docs. Canonical shared skills are committed and pushed at 57a94c068df753bcafe94fa44dae6675168cf060; the full shared contract suite passed 211/211. Harness focused CLI coverage passed 11/11 across settings, ensure, Finder catalog/prompt, and sync behavior; CLI check-types passed; wiki content/routes tests passed; the exact baseline build passed; and diff checks passed.

The implementation is retained in PR #172 with mixed release classification. Fresh focused validation passed, final review findings were repaired through 642d18c9, and docs ingest now records the implemented state.

Live structural provider mutation was intentionally not performed. .devpunks/settings.json still selects a legacy Linear /project/ destination, while write-backlog requires a Product/Backlog Root and explicit approval for structural writes. This is an operator precondition for using the implemented behavior, not incomplete source work. IP-380 through IP-388 were read back for closeout; erroneous IP-389 through IP-404 were canceled as superseded history.

Earlier aggregate runs exposed unrelated environment failures. The final closeout relies on the complete canonical suite, focused changed-surface tests, CLI typecheck, wiki routes, baseline build, PR review, and exact provider-linked issue evidence.

Problem

The current skill and CLI contracts cannot produce or maintain this accepted model:

Product/Backlog Root
└── Product Area
    └── Initiative
        └── Epic
            └── Story [exactly one contextual V*]
                └── Task 1..n [same V* + blocker relations]

Fog ──provenance/enrichment──> Area | Initiative | Epic | Story | Task
Fog completion ──────────────> complete production evidence only

The delivery must replace the conflicting contracts, retain one physical provider writer, preserve one Task identity graph from backlog through planning and delivery, and prove the synchronized major release.

Resolved Decision Ledger

$grilling planning frontier: empty. The accepted grill, immutable spec, provider audit, and current source inspection resolve every plan-shaping decision. No user question remains.

Architecture Applicability

architecture_applicability: architecture-bearing

Evidence: the work replaces a public workflow graph, adds three public wrapper surfaces, changes the only provider mutation contract, migrates CLI settings validation, changes downstream planning/delivery semantics, and synchronizes generated consumers across two repositories.

Target Ownership Topology

wearedevpunks-skills (canonical policy)
├── finder-phase engine
│   ├── runtime graph + resume/reconciliation
│   └── shared entrypoint/runtime handoffs
├── business-finder       # audience/depth/presentation only
├── functional-finder     # audience/depth/presentation only
├── technical-finder      # audience/depth/presentation only
├── write-backlog
│   ├── semantic branches
│   ├── Linear adapter guidance
│   └── GitHub adapter guidance
└── planning/delivery consumers

harness-intelligence (product integration)
├── hi ensure             # operator-owned destination migration
├── skill catalog/packs/prompts
├── generated projections # exact canonical SHA
├── durable wiki/docs
└── CLI/baseline release authority

Finder owns lifecycle selection and semantic handoffs. write-backlog owns provider mechanics and readback. CLI settings own only destination selection. Planning and Delivery consume identities and facts; they do not redefine provider topology.

Declared Dependency Graph

human wrapper
  -> finder-phase entrypoint contract
  -> one runtime graph gate
  -> accepted stage evidence
  -> write-backlog semantic branch
  -> provider adapter
  -> exact provider readback

technical stage
  -> agent-ready Story SPEC.md
  -> provider Task graph
  -> create-plan preserves Task identities/blockers
  -> implement-spec and delivery-phase report observed facts
  -> write-backlog delivery-status
  -> production evidence can complete Fog

hi ensure
  -> project-settings public service
  -> same backlogProjectUrl key

Allowed cross-owner seams are the documented Finder runtime handoff, write-backlog branch inputs/results, ProjectSettingsService, and delivery phase handoff. Forbidden edges: wrappers owning lifecycle state, Finder calling providers directly, provider adapters redefining product terms, plan-only Tasks diverging from provider Tasks, Delivery inferring deployment from merge, or generated Harness skills becoming source authority.

Public Seam Contract

Any implementation that changes one of these seams amends this plan before dependent work continues.

Responsibility Acceptance Criteria

Architecture Waves

A1 boundary establishment
  T1 base + T2 Finder/Business + T3 writer core
    entry: accepted spec + retained research
    delta: replace old lifecycle and writer boundaries
    temporary seams: current provider adapters and downstream consumers remain readable only
    checkpoint: T3 runs cumulative Finder/writer contracts and advances RAC-1/RAC-2

A2 vertical semantic slices
  T4 Linear + T5 GitHub + T7 Functional + T8 Normalization -> T10 Technical
    entry: A1 checkpoint passes
    delta: add both provider adapters and complete cumulative semantic depth
    temporary seams: old downstream planning/delivery consumers remain until A3
    checkpoint: T10 runs all A1/A2 contracts and proves RAC-1/RAC-2

A3 downstream convergence
  T9 delivery facts -> T11 consumer convergence -> T12 canonical commit/push
    entry: A2 checkpoint passes
    delta: one provider Task identity graph and truthful delivery facts
    temporary seams: Harness still consumes the previous canonical SHA
    checkpoint: T11 proves RAC-4 and regresses RAC-1/RAC-2; T12 retains the exact passing source

A4 durable product closure
  T6 settings migration -> T13 Harness sync -> T15 major compatibility -> T14 docs -> T16 exact-tree proof
    entry: canonical source commit is pushed
    delta: migrate the Harness consumer, operator target, docs, and release contract
    temporary seams: none after T16
    checkpoint: T16 proves RAC-3/RAC-5/RAC-6/RAC-7 and regresses RAC-1..RAC-4

Migration Ledger

Active migration ledger: empty. No temporary seam remains in the implemented source or generated projection.

Provider runtime proof is required when an approved structural or delivery mutation is invoked; it is not an active migration seam or a prerequisite to shipping the implementation contract.

External Research Used

• Linear official Initiatives, Sub-initiatives, Projects, Project milestones, parent/sub-issues, relations, and Cycles documentation.
• GitHub official Projects V2, fields, views, milestones, sub-issues, and issue dependency documentation.
• Authenticated GitHub GraphQL introspection confirmed Project V2 field/view mutations, issue parent/milestone/project inputs, sub-issue mutation, and blocker mutation. It does not replace the required live nested-Task readback.
• Current source inspection in the canonical shared repo and Harness CLI. Full citations and fact/inference separation live in the retained planning research report.

Dependency Graph And Worker Waves

W1   T1   T2
      |    |
W2   |    T3                     # A1 checkpoint
      |     |\
W3   |     T4  T5  T7
      |      \  |  /
W4   |        T8
      |         \
W5   |          T10              # A2 checkpoint
      |            |
W6   |            T9
      |            |
W7   |            T11            # A3 checkpoint
      |            |
W8   |            T12            # canonical commit + push
      |             |
W9   T6 <-----------┘
      |
W10  T13
      |
W11  T15
      |
W12  T14
      |
W13  T16                    # exact committed tree + final proof

Every wave ends before the next architecture wave starts. T1 writes Harness branch history only while T2-T12 write canonical shared source. Harness settings, catalog, prompts, generated projections, docs, and release files begin only after T12 commits and pushes canonical source. One-task waves are used where cumulative checkpoints or one integration authority must converge prior outputs.

Backlog Sync Outcome

An early planning pass incorrectly synchronized internal execution tasks into Linear before implementation:

• Milestone: V4.0 Project Backlog Operating Model (4dd7214c-3f68-4dc6-ac43-41ee43bf05f7).
• Kind/task label: 36ee9785-7079-4134-a519-f02dd73b8cac.
• Existing Stories IP-381 through IP-388 now share that milestone.
• IP-389 through IP-404 were canceled as superseded history after the user reaffirmed that IP-380 through IP-388 were the complete delivery work set.
• The task entries below now point to their owning existing IP-380 through IP-388 issue. They do not authorize a replacement provider Task graph.

Tn remains an internal plan alias. The matching backlog_item_id is the existing owning delivery issue, not a new provider Task identity.

Tasks

T1: Reconcile the delivery branch with current origin/main

• depends_on: []
• location: Harness git history
• owned_paths: []
• wave_boundary: W1
• description: Fetch current origin, preserve the research/spec commits and every unrelated dirty path, reconcile this topic branch with current origin/main, and record the exact merge base. Stop before overwriting or stashing user-owned changes.
• validation: Branch contains origin/main, eee747ec, and 6d91c5f3; unrelated dirty path hashes remain unchanged.
• status: Complete
• log: Merge commit bc6a534516360ca15a6b83763448059f3250b6c9 contains current origin/main, immutable spec eee747ec, and research 6d91c5f3; all pre-existing dirty-path hashes were preserved.
• files edited/created: Git history only; no user-owned dirty path rewritten.
• backlog_item_id: IP-383
• backlog_item_url: https://linear.app/devpunks/issue/IP-383/engineer-resolves-story-delivery-with-technical-finder
• relation_mode: native
• assigned_skills: [create-plan]
• implementation_skill_guidance: []
• tdd_status: not_applicable
• tdd_target: Branch-history reconciliation with dirty-worktree preservation.
• red_command:
• expected_red_failure:
• green_command: git merge-base --is-ancestor origin/main HEAD
• reason_not_testable: Git-history-only task.
• red_evidence:
• green_evidence: bc6a534516360ca15a6b83763448059f3250b6c9; ancestor and retained-source checks passed, with pre-existing dirty hashes preserved.
• codebase_design_notes: not_applicable
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A1
• behavior_owner: Branch integration authority
• integration_surface: Git history
• public_seam: None
• topology_delta: Current base becomes delivery ancestor.
• forbidden_ownership: User-owned dirty changes
• temporary_seams: []
• responsibility_acceptance_criteria: []

T2: Replace Finder engine and add Business Finder

• depends_on: []
• location: canonical shared skills
• owned_paths: [skills/phases/finder-phase/**, skills/phases/business-finder/**, skills/agnostic/planning/wayfinder/SKILL.md, tests/wayfinder-lifecycle.contract.test.mjs, tests/finder-phase-graph.contract.test.mjs, tests/fixtures/finder-phase-routes.json]
• wave_boundary: W1
• description: Test-drive the durable Finder graph, direct-composition wrapper contract, human-only metadata, exact Fog resume/cardinality, Business grilling, support cycles, reconciliation, handback, and target return. Narrow or retire competing Wayfinder behavior.
• validation: Focused Finder tests prove deterministic routes, disable-model-invocation: true, OpenAI implicit policy false, atomic grilling, $show-me/$wait-what, and zero duplicate children.
• status: Complete
• log: Canonical 57a94c0… contains the human-only Business wrapper, one Finder graph, deterministic routing/cardinality contract, support cycles, and narrowed Wayfinder behavior.
• files edited/created: Canonical T2 owned_paths; synchronized Finder/Business projections in Harness.
• backlog_item_id: IP-381
• backlog_item_url: https://linear.app/devpunks/issue/IP-381/business-owner-structures-a-request-with-business-finder
• relation_mode: native
• assigned_skills: [writing-for-agents, write-graph-based-skills, tdd, codebase-design]
• implementation_skill_guidance:
  • skill: writing-for-agents; applicable_behavior: Keep the public wrapper thin; disclose branch-specific engine rules behind sharp pointers with one source of truth.
  • skill: write-graph-based-skills; applicable_behavior: Persist one resumable graph with explicit gates, evidence-selected routes, and exact terminal outcomes.
  • skill: tdd; applicable_behavior: Capture the named Finder route and invocation metadata failures before editing skill sources.
  • skill: codebase-design; applicable_behavior: Keep lifecycle depth in the engine and audience policy in wrappers through a small direct-composition seam.
• tdd_status: required
• tdd_target: A Business invocation creates/resumes one Fog, runs one Business child, and returns at Business depth through one human-only engine.
• red_command: node --test tests/finder-phase-graph.contract.test.mjs tests/wayfinder-lifecycle.contract.test.mjs
• expected_red_failure: Current implicit chart/work Finder lacks wrappers, graph gates, and accepted Fog-child lifecycle.
• green_command: node --test tests/finder-phase-graph.contract.test.mjs tests/wayfinder-lifecycle.contract.test.mjs
• reason_not_testable:
• red_evidence: Canonical test-first run established the absent wrapper/graph/metadata failures; the individual RED transcript was not retained in this Harness handoff.
• green_evidence: Focused Finder/Wayfinder contracts passed and are included in the 211/211 canonical aggregate at 57a94c0….
• codebase_design_notes: Finder is a deep runtime policy module; wrappers are adapters over one target-depth interface.
• 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 engine and Business wrapper
• integration_surface: Human skill invocation and provider-neutral stage handoff
• public_seam: $business-finder; Finder direct-composition contract
• topology_delta: Replaces MIG-1 and establishes wrapper/engine ownership.
• forbidden_ownership: Provider mutation mechanics; Technical requirements policy
• temporary_seams: []
• responsibility_acceptance_criteria: [RAC-1, RAC-5]

T3: Refactor write-backlog into the operating-model router and close A1

• depends_on: [T2]
• location: canonical shared skills
• owned_paths: [skills/agnostic/requirements/write-backlog/SKILL.md, skills/agnostic/requirements/write-backlog/EXAMPLES.md, skills/agnostic/requirements/write-backlog/REFERENCE.md, skills/agnostic/requirements/write-backlog/references/project-context.md, skills/agnostic/requirements/write-backlog/references/backlog-initialization.md, skills/agnostic/requirements/write-backlog/references/fog-intake.md, skills/agnostic/requirements/write-backlog/references/business-projection.md, skills/agnostic/requirements/write-backlog/references/functional-projection.md, skills/agnostic/requirements/write-backlog/references/technical-projection.md, skills/agnostic/requirements/write-backlog/references/issue-reconciliation.md, skills/agnostic/requirements/write-backlog/assets/**, tests/write-backlog-lifecycle.contract.test.mjs, tests/write-backlog-operating-model.contract.test.mjs]
• wave_boundary: W2
• description: Test-drive one concise provider-writer router with progressive references for project context, initialization, Fog intake, three stage projections, identity reconciliation, contextual V*, mandatory Tasks, blocker validation, approval, write, and exact readback. Remove active M* and out-of-scope provider semantics. End by running the cumulative A1 Finder/writer checkpoint.
• validation: Writer tests prove stable-identity-only upsert, full hierarchy, exactly-one V* per Story/Task, full reachable blocker validation, structural approval, and preservation of ticket wording/traceability. Initialization assertions enumerate Product brief, objectives, target users, boundaries, Product Map, durable constraints/non-goals, operating rules, owner, repository/wiki links, current/future V* context, and the AC-035 full-fields-versus-name-only fallback. The A1 checkpoint also reruns T2 evidence.
• status: Complete
• log: Canonical 57a94c0… replaces the monolith with one mutation pipeline and progressive references for project context, initialization, Fog intake, stage projection, reconciliation, provider adapters, and exact readback.
• files edited/created: Canonical T3 owned_paths; synchronized writer references and validator in Harness.
• backlog_item_id: IP-382
• backlog_item_url: https://linear.app/devpunks/issue/IP-382/product-owner-initializes-or-reconstructs-a-linear-backlog
• relation_mode: native
• assigned_skills: [writing-for-agents, tdd, codebase-design, show-me, wait-what]
• implementation_skill_guidance:
  • skill: writing-for-agents; applicable_behavior: Keep always-needed mutation gates in SKILL.md and disclose each conditional semantic/provider branch once.
  • skill: tdd; applicable_behavior: Capture operating-model contract failures before replacing the monolith.
  • skill: codebase-design; applicable_behavior: Make write-backlog the single deep provider seam; prevent provider rules from leaking into callers.
  • skill: show-me; applicable_behavior: Preserve authority-derived topology previews without treating the visual as approval.
  • skill: wait-what; applicable_behavior: Use project language and repitch unclear material without changing accepted terms.
• tdd_status: required
• tdd_target: One validated mutation preserves Root→Area→Initiative→Epic→Story→Task plus lateral Fog provenance, the complete project metadata contract, four views, and the milestone metadata fallback.
• red_command: node --test tests/write-backlog-lifecycle.contract.test.mjs tests/write-backlog-operating-model.contract.test.mjs
• expected_red_failure: Current writer asserts capability modules, M* milestones, Epic/Story-only projection, and no Task contract.
• green_command: node --test tests/write-backlog-lifecycle.contract.test.mjs tests/write-backlog-operating-model.contract.test.mjs
• reason_not_testable:
• red_evidence: Canonical test-first run established the old Epic/Story/M* contract failures; the individual RED transcript was not retained in this Harness handoff.
• green_evidence: Writer lifecycle and operating-model contracts passed and are included in the 211/211 canonical aggregate at 57a94c0….
• codebase_design_notes: Semantic branches are internal modules behind one mutation interface; provider adapters are concrete boundary adapters.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A1
• behavior_owner: write-backlog
• integration_surface: Finder, initialization, Normalization, planning, Delivery
• public_seam: $write-backlog
• topology_delta: Replaces MIG-2 and establishes one semantic/provider mutation boundary.
• forbidden_ownership: Finder lifecycle; CLI settings selection; delivery-event inference
• temporary_seams: []
• responsibility_acceptance_criteria: [RAC-2, RAC-5]

T4: Implement the Linear mapping and initialization branch

• depends_on: [T3]
• location: canonical write-backlog
• owned_paths: [skills/agnostic/requirements/write-backlog/references/providers/linear.md, tests/write-backlog-linear.contract.test.mjs]
• wave_boundary: W3
• description: Encode Initiative→nested Initiative→Project→Issue→sub-issue mapping, workspace identity preflight, milestone/view/field provisioning approval, four accepted views, complete project metadata, milestone fallback, and exact readback.
• validation: Focused contract test plus available Linear readback; alias-only identity and missing representation fail closed. Assertions cover every AC-022 field, Product Map/Roadmap/Fogs/Current Delivery, and AC-035 full milestone metadata or name-only fallback.
• status: Complete
• log: Implementation and contract coverage are complete in canonical 57a94c0…. Live mutation/readback remains conditional on an operator-selected Product/Backlog Root and explicit structural approval.
• files edited/created: Canonical Linear provider reference and contract tests; no Linear provider object mutated.
• backlog_item_id: IP-382
• backlog_item_url: https://linear.app/devpunks/issue/IP-382/product-owner-initializes-or-reconstructs-a-linear-backlog
• relation_mode: native
• assigned_skills: [writing-for-agents, tdd, codebase-design]
• implementation_skill_guidance:
  • skill: writing-for-agents; applicable_behavior: Keep Linear-only mechanics in one provider reference reached only by the Linear branch.
  • skill: tdd; applicable_behavior: Capture fail-closed identity and native hierarchy/readback assertions before provider guidance.
  • skill: codebase-design; applicable_behavior: Treat Linear as an adapter; preserve provider-neutral semantics at the writer seam.
• tdd_status: required
• tdd_target: Linear initialization maps every accepted owner/item, project metadata field, four views, and milestone fallback to supported native state and reads it back.
• red_command: node --test tests/write-backlog-linear.contract.test.mjs
• expected_red_failure: Current Linear payload documents only issue-level Epic/Story writes.
• green_command: node --test tests/write-backlog-linear.contract.test.mjs
• reason_not_testable:
• red_evidence: Canonical test-first run established the former issue-only Linear mapping gaps; the individual RED transcript was not retained in this Harness handoff.
• green_evidence: Linear adapter contract passed within 211/211 and fails closed until configured destination and approval authority are exact.
• codebase_design_notes: Linear reference is a concrete adapter behind provider-neutral mutation intent.
• review_mode: cli
• runtime_validation: required
• runtime_target: Configured Linear workspace
• runtime_evidence: Initiative, nested Initiative, Project, Issue, sub-issue, milestone, field/view, and relation readback when API authority supports them.
• runtime_cleanup: Remove only run-owned test provider structures; retain blocker evidence when API authority is insufficient.
• architecture_wave: A2
• behavior_owner: Linear provider adapter
• integration_surface: write-backlog provider branch
• public_seam: Linear mutation/readback result
• topology_delta: Adds native Linear representation.
• forbidden_ownership: Product-term redefinition; title-only matching
• temporary_seams: []
• responsibility_acceptance_criteria: [RAC-2]

T5: Implement the GitHub Projects V2 mapping and initialization branch

• depends_on: [T3]
• location: canonical write-backlog
• owned_paths: [skills/agnostic/requirements/write-backlog/references/providers/github.md, tests/write-backlog-github.contract.test.mjs, tests/fixtures/write-backlog-provider-planning.json, tests/write-backlog-provider-planning.contract.test.mjs]
• wave_boundary: W3
• description: Encode one Projects V2 semantic surface, fields/views, Issues and recursive sub-issues through Task, repository V*, blockers, provenance, complete project metadata, milestone fallback, setup guidance, and exact readback requirements.
• validation: Contract suite enumerates every AC-022 field, four accepted views, and AC-035 full-fields-versus-name-only fallback. One workflow-created nested Task live readback is required before runtime coverage.
• status: Complete
• log: Implementation and contract coverage are complete in canonical 57a94c0…. This delivery performed no unapproved runtime provider mutation; each invocation must use the configured Product/Backlog Root and approved structural intent.
• files edited/created: Canonical GitHub provider reference, planning fixture, and contract tests; no GitHub provider object mutated.
• backlog_item_id: IP-384
• backlog_item_url: https://linear.app/devpunks/issue/IP-384/product-owner-initializes-or-reconstructs-a-github-backlog
• relation_mode: native
• assigned_skills: [writing-for-agents, tdd, codebase-design]
• implementation_skill_guidance:
  • skill: writing-for-agents; applicable_behavior: Keep GitHub-only mechanics and runtime proof gates in one disclosed provider reference.
  • skill: tdd; applicable_behavior: Capture Project V2 semantic, recursive Task, milestone, blocker, and fail-closed representation assertions first.
  • skill: codebase-design; applicable_behavior: Keep semantic parity behind the provider adapter instead of leaking GitHub storage details.
• tdd_status: required
• tdd_target: GitHub projects the complete project metadata, four views, milestone fallback, and Epic→Story→Task graph with exact field, blocker, and membership readback.
• red_command: node --test tests/write-backlog-github.contract.test.mjs tests/write-backlog-provider-planning.contract.test.mjs
• expected_red_failure: Current provider assets stop at Epic→Story and use M* milestone planning.
• green_command: node --test tests/write-backlog-github.contract.test.mjs tests/write-backlog-provider-planning.contract.test.mjs
• reason_not_testable:
• red_evidence: Canonical test-first run established the former Epic→Story/M* GitHub gaps; the individual RED transcript was not retained in this Harness handoff.
• green_evidence: GitHub adapter and provider-planning contracts passed within 211/211 and require exact runtime readback when invoked.
• codebase_design_notes: GitHub provider is a semantic adapter over a flat Project V2 plus recursive Issue hierarchy.
• review_mode: cli
• runtime_validation: required
• runtime_target: Authenticated GitHub repository and Projects V2
• runtime_evidence: Workflow-created Task read back with exact project membership, parent, repository V*, semantic field, and blocker state.
• runtime_cleanup: Prefix runtime fixtures with the run id; close/delete only those Issues/Project items after retaining evidence.
• architecture_wave: A2
• behavior_owner: GitHub provider adapter
• integration_surface: write-backlog provider branch
• public_seam: GitHub mutation/readback result
• topology_delta: Adds GitHub semantic representation and removes active Azure/monday routing.
• forbidden_ownership: Flat Issues-only fallback; Iteration-field substitution
• temporary_seams: []
• responsibility_acceptance_criteria: [RAC-2]

T6: Migrate backlogProjectUrl behavior through hi ensure

• depends_on: [T1, T12]
• location: Harness CLI project settings
• owned_paths: [apps/cli/src/scaffold/settings-selection.ts, apps/cli/src/scaffold/settings-selection.test.ts, apps/cli/src/cli/ensure-command.ts, apps/cli/src/cli/ensure-command.test.ts]
• wave_boundary: W9
• description: Test-drive provider-aware Linear root URL validation and actionable legacy /project/ guidance. Reuse the current settings-only command, same key, and unknown/unrelated setting preservation; prove a second accepted run is idempotent.
• validation: Public selectRepoSettings and runEnsure tests plus filesystem-backed settings readback.
• status: Complete
• log: Public selector and filesystem-backed hi ensure coverage reject legacy Linear /project/, accept Root Initiative URLs, preserve unrelated settings, and prove idempotence.
• files edited/created: apps/cli/src/scaffold/settings-selection.ts, its focused test, apps/cli/src/cli/ensure-command.ts, and its focused test.
• backlog_item_id: IP-385
• backlog_item_url: https://linear.app/devpunks/issue/IP-385/operator-migrates-the-configured-linear-backlog-destination
• relation_mode: native
• assigned_skills: [effect, tdd, codebase-design]
• implementation_skill_guidance:
  • skill: effect; applicable_behavior: Preserve typed Effect failures and validate untrusted prompt values at the existing boundary without casts.
  • skill: tdd; applicable_behavior: Capture the legacy default acceptance failure and settings-preservation result before production edits.
  • skill: codebase-design; applicable_behavior: Keep provider URL policy at the selector/service seam and retain hi ensure as the small public interface.
• tdd_status: required
• tdd_target: A legacy Linear Project URL cannot silently remain the default; a valid Initiative URL updates only the existing destination contract.
• red_command: bun run --cwd apps/cli test -- settings-selection ensure-command
• expected_red_failure: Current selector accepts a Linear /project/ URL and returns no root-specific migration guidance.
• green_command: bun run --cwd apps/cli test -- settings-selection ensure-command
• reason_not_testable:
• red_evidence: Focused tests initially proved legacy Linear /project/ was accepted and root-specific guidance was absent; exact console transcript was not retained.
• green_evidence: Settings selection and ensure coverage passed within the final focused CLI suite; unknown-field preservation and idempotent second-run readback are asserted.
• codebase_design_notes: selectRepoSettings is the validation seam; ProjectSettingsService is the persistence seam.
• 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 project settings
• integration_surface: hi ensure prompt and .devpunks/settings.json
• public_seam: hi ensure; backlogProjectUrl
• topology_delta: Removes MIG-5 without a new settings key.
• forbidden_ownership: Backlog hierarchy mutation; full scaffold initialization
• temporary_seams: []
• responsibility_acceptance_criteria: [RAC-3]

T7: Add Functional Finder

• depends_on: [T3]
• location: canonical shared skills
• owned_paths: [skills/phases/functional-finder/**, tests/functional-finder.contract.test.mjs]
• wave_boundary: W3
• description: Test-drive the cumulative Business+Functional wrapper, exact existing Epic fast path, Functional child-per-Story intent, accepted workflow/edge/dependency/V* decisions, and Story projection handoff.
• validation: Focused test proves lower-stage reuse, no architecture requirement, one Story per Functional child, $wait-what, and required $show-me decision views.
• status: Complete
• log: Canonical 57a94c0… adds the cumulative Functional wrapper, exact Business fast path, Story-intent cardinality, contextual V*, $show-me, and $wait-what presentation contract.
• files edited/created: Canonical Functional wrapper and contract test; synchronized Harness projection.
• backlog_item_id: IP-386
• backlog_item_url: https://linear.app/devpunks/issue/IP-386/proficient-user-defines-shippable-stories-with-functional-finder
• relation_mode: native
• assigned_skills: [writing-for-agents, tdd, show-me, wait-what]
• implementation_skill_guidance:
  • skill: writing-for-agents; applicable_behavior: Keep the wrapper limited to audience, target depth, inputs, presentation, and return shape.
  • skill: tdd; applicable_behavior: Capture cumulative resume and Story split/V* failures before authoring.
  • skill: show-me; applicable_behavior: Show workflow, split, alternate path, dependency, milestone, and final write decisions from authority.
  • skill: wait-what; applicable_behavior: Repitch unclear product language using accepted project terms.
• tdd_status: required
• tdd_target: Functional Finder reuses accepted Business evidence and emits exactly one milestone-bound Story per accepted Functional child.
• red_command: node --test tests/functional-finder.contract.test.mjs
• expected_red_failure: No Functional wrapper or Functional child contract exists.
• green_command: node --test tests/functional-finder.contract.test.mjs
• reason_not_testable:
• red_evidence: Canonical test-first run established the absent Functional wrapper and child contract; the individual RED transcript was not retained in this Harness handoff.
• green_evidence: Functional Finder contract passed within 211/211 at 57a94c0….
• codebase_design_notes: Thin target-depth adapter; all resume/lifecycle state remains in Finder.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A2
• behavior_owner: Functional wrapper
• integration_surface: Finder engine and write-backlog Functional projection
• public_seam: $functional-finder
• topology_delta: Adds the middle cumulative depth.
• forbidden_ownership: Technical architecture and Task decomposition
• temporary_seams: []
• responsibility_acceptance_criteria: [RAC-1]

T8: Add Normalization

• depends_on: [T4, T5]
• location: canonical write-backlog
• owned_paths: [skills/agnostic/requirements/write-backlog/references/normalization.md, tests/write-backlog-normalization.contract.test.mjs]
• wave_boundary: W4
• description: Test-drive detection and fail-closed reconciliation of invalid children/stages, duplicates, stale links/status, hierarchy/roadmap drift, and wiki/provider disagreement. Auto-repair only exact mappings; require preview/approval for structural changes.
• validation: Focused test covers every drift class and approval boundary without cadence behavior.
• status: Complete
• log: Normalization implementation and contract coverage are complete in canonical 57a94c0…. Live repair remains conditional on exact identity, configured destination, and structural approval.
• files edited/created: Canonical Normalization reference and contract test; no provider repair attempted.
• backlog_item_id: IP-388
• backlog_item_url: https://linear.app/devpunks/issue/IP-388/maintainer-normalizes-backlog-state-safely
• relation_mode: native
• assigned_skills: [writing-for-agents, tdd, show-me]
• implementation_skill_guidance:
  • skill: writing-for-agents; applicable_behavior: Keep all Normalization rules co-located in one conditional reference.
  • skill: tdd; applicable_behavior: Capture unsafe structural auto-repair and missed drift classes before authoring.
  • skill: show-me; applicable_behavior: Present exact before/after topology for approval without inventing consent.
• tdd_status: required
• tdd_target: Normalization repairs one unambiguous stale mapping and stops before one structural reorganization.
• red_command: node --test tests/write-backlog-normalization.contract.test.mjs
• expected_red_failure: No Normalization branch or structural approval boundary exists.
• green_command: node --test tests/write-backlog-normalization.contract.test.mjs
• reason_not_testable:
• red_evidence: Canonical test-first run established the absent Normalization and approval boundary; the individual RED transcript was not retained in this Harness handoff.
• green_evidence: Normalization contract passed within 211/211 and covers safe repair plus structural no-write behavior.
• codebase_design_notes: Normalization is a conditional policy module behind the writer seam.
• review_mode: cli
• runtime_validation: required
• runtime_target: Configured Linear and authenticated GitHub provider fixtures
• runtime_evidence: One unambiguous stale mapping is repaired and read back; one structural change produces a preview and no mutation before approval.
• runtime_cleanup: Use run-owned duplicate/stale fixtures; remove only exact run-owned objects after retaining readback evidence.
• architecture_wave: A2
• behavior_owner: write-backlog Normalization branch
• integration_surface: Wiki/provider comparison and mutation preview
• public_seam: $write-backlog normalization mode
• topology_delta: Adds safe entropy reduction without a compatibility writer.
• forbidden_ownership: Invocation scheduling; silent merge/split/reparent
• temporary_seams: []
• responsibility_acceptance_criteria: [RAC-2]

T9: Add distinct delivery-state mutation policy

• depends_on: [T10]
• location: canonical write-backlog
• owned_paths: [skills/agnostic/requirements/write-backlog/references/delivery-status.md, tests/delivery-backlog-state.contract.test.mjs]
• wave_boundary: W6
• description: Test-drive immediate start/blocker/PR updates, separate observed merge/staging/production facts, exact readback, and production-only Fog completion.
• validation: Focused test rejects merge-as-deployment and premature Fog completion; contains no CI/CD adapter design.
• status: Complete
• log: Delivery-state implementation and contract coverage are complete in canonical 57a94c0…; start, blocker, PR, merge, staging, production, and Fog completion remain distinct. No delivery facts were invented for this code-only change.
• files edited/created: Canonical delivery-status reference and contract test; no provider status mutated.
• backlog_item_id: IP-387
• backlog_item_url: https://linear.app/devpunks/issue/IP-387/delivery-agent-keeps-linked-work-state-current
• relation_mode: native
• assigned_skills: [writing-for-agents, tdd, codebase-design]
• implementation_skill_guidance:
  • skill: writing-for-agents; applicable_behavior: Co-locate event facts, evidence bounds, writes, and completion rules in one delivery-status reference.
  • skill: tdd; applicable_behavior: Capture merge/deployment conflation and missing immediate updates before authoring.
  • skill: codebase-design; applicable_behavior: Keep provider mechanics behind the writer; Delivery supplies only observed facts.
• tdd_status: required
• tdd_target: Merge evidence updates merge state but cannot mark staging, production, or Fog completion.
• red_command: node --test tests/delivery-backlog-state.contract.test.mjs
• expected_red_failure: No distinct delivery-status policy or production-only Fog completion exists.
• green_command: node --test tests/delivery-backlog-state.contract.test.mjs
• reason_not_testable:
• red_evidence: Canonical test-first run established the absent distinct delivery-state policy; the individual RED transcript was not retained in this Harness handoff.
• green_evidence: Delivery-state contract passed within 211/211 and requires direct facts plus exact provider readback when invoked.
• codebase_design_notes: Delivery facts form a small input contract; adapters own state mapping and readback.
• review_mode: cli
• runtime_validation: required
• runtime_target: Linked run-owned Linear and GitHub delivery Tasks
• runtime_evidence: Start, blocked, PR, merge, staging, and production facts are written/read separately; merge leaves deployment unchanged; production completes only exact accepted Fog scope.
• runtime_cleanup: Remove only run-owned delivery fixtures after retaining each state readback.
• architecture_wave: A3
• behavior_owner: write-backlog delivery-status branch
• integration_surface: Delivery lifecycle handoff
• public_seam: Delivery evidence mutation/result
• topology_delta: Establishes truthful state semantics.
• forbidden_ownership: Pipeline triggers; deployment inference
• temporary_seams: []
• responsibility_acceptance_criteria: [RAC-4]

T10: Add Technical Finder and required Task graph

• depends_on: [T4, T5, T7, T8]
• location: canonical shared skills
• owned_paths: [skills/phases/technical-finder/**, tests/technical-finder.contract.test.mjs, tests/requirements-grill-composition.contract.test.mjs]
• wave_boundary: W5
• description: Test-drive cumulative Business+Functional+Technical depth, one $requirements-grill per Story, agent-ready spec gate, mandatory atomic Tasks, same V*, and full blocker graph validation before projection. End by running the cumulative A2 checkpoint.
• validation: Focused tests prove accepted lower-stage reuse, one Technical child per Story, spec-before-Task ordering, nonempty Tasks, and rejection of missing/future/self/cyclic edges. The A2 checkpoint reruns all A1 evidence plus T4, T5, T7, and T8 contracts.
• status: Complete
• log: Canonical 57a94c0… adds Story-scoped Technical resolution, full requirements grilling, spec-before-Task ordering, mandatory Tasks, exact parent-Story V* equality, and executable blocker validation.
• files edited/created: Canonical Technical wrapper, Finder Technical gate, Task graph validator, and contract tests; synchronized Harness projection.
• backlog_item_id: IP-383
• backlog_item_url: https://linear.app/devpunks/issue/IP-383/engineer-resolves-story-delivery-with-technical-finder
• relation_mode: native
• assigned_skills: [writing-for-agents, write-graph-based-skills, tdd, codebase-design]
• implementation_skill_guidance:
  • skill: writing-for-agents; applicable_behavior: Keep Technical presentation in the wrapper and requirements/Task gates in existing authorities.
  • skill: write-graph-based-skills; applicable_behavior: Re-enter one Story-scoped Technical gate and persist exact next/terminal outcomes.
  • skill: tdd; applicable_behavior: Capture spec ordering and complete Task-graph failures before authoring.
  • skill: codebase-design; applicable_behavior: Preserve $requirements-grill and write-backlog as separate deep seams.
• tdd_status: required
• tdd_target: One accepted Story produces an agent-ready spec followed by at least one same-V* atomic Task with a valid blocker graph.
• red_command: node --test tests/technical-finder.contract.test.mjs tests/requirements-grill-composition.contract.test.mjs
• expected_red_failure: No Technical wrapper exists and current backlog contract treats Tasks as optional/internal.
• green_command: node --test tests/technical-finder.contract.test.mjs tests/requirements-grill-composition.contract.test.mjs
• reason_not_testable:
• red_evidence: Canonical test-first run established missing Technical composition and optional/internal Task behavior; the individual RED transcript was not retained in this Harness handoff.
• green_evidence: Technical Finder, requirements composition, and Task graph validation, including exact Task/Story milestone equality, passed within 211/211 at 57a94c0….
• codebase_design_notes: Technical wrapper composes two existing deep modules without absorbing either policy.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A2
• behavior_owner: Technical wrapper
• integration_surface: Finder engine, requirements grill, create-spec, technical projection
• public_seam: $technical-finder
• topology_delta: Completes cumulative Finder depth and Task handoff.
• forbidden_ownership: Provider writes; implementation execution
• temporary_seams: []
• responsibility_acceptance_criteria: [RAC-1, RAC-2]

T11: Converge planning and Delivery on provider Task identities

• depends_on: [T9]
• location: canonical shared planning/delivery skills
• owned_paths: [skills/agnostic/planning/create-plan/SKILL.md, skills/agnostic/planning/create-plan/references/backlog-sync.md, skills/agnostic/planning/create-spec/SKILL.md, skills/agnostic/planning/implement-spec/SKILL.md, skills/agnostic/planning/implement-spec/references/lifecycle.md, skills/agnostic/docs/docs-onboarding/SKILL.md, skills/phases/design-phase/phases/backlog.md, skills/phases/delivery-phase/phases/backlog.md, skills/phases/delivery-phase/phases/implement.md, skills/phases/delivery-phase/phases/closeout.md, skills/phases/delivery-phase/phases/router.md, skills/phases/delivery-phase/references/artifact-state.md, tests/create-plan-backlog-tasks.contract.test.mjs, tests/delivery-backlog-state-integration.contract.test.mjs, tests/routed-glossary-consumers.contract.test.mjs]
• wave_boundary: W7
• description: Remove Epic/Story-only and internal-only Task contracts. Planning must preserve provider Task IDs/blockers; implementation and Delivery must route immediate observed state updates through write-backlog and close only with production evidence. Closeout must create the final path-limited commit after review and docs ingest, then rerun release classification and exact-tree provider proof when that final tree differs from the pre-review candidate. End by running the cumulative A3 checkpoint.
• validation: Consumer tests prove one Task graph, immediate lifecycle writes, no merge-as-deploy, no duplicated provider mechanics, and final-tree closeout reproof after review or docs changes. The A3 checkpoint reruns every A1/A2 contract plus T9 and evaluates RAC-1 through RAC-4.
• status: Complete
• log: Canonical 57a94c0… makes planning and Delivery preserve provider Task IDs and native blockers and route observed delivery facts through write-backlog without a second Task graph.
• files edited/created: Canonical planning, onboarding, design, implementation, and delivery consumer paths listed in owned_paths; synchronized Harness projections.
• backlog_item_id: IP-387
• backlog_item_url: https://linear.app/devpunks/issue/IP-387/delivery-agent-keeps-linked-work-state-current
• relation_mode: native
• assigned_skills: [writing-for-agents, tdd, codebase-design]
• implementation_skill_guidance:
  • skill: writing-for-agents; applicable_behavior: Replace duplicated policy with sharp pointers to writer branches and explicit completion criteria.
  • skill: tdd; applicable_behavior: Capture the current internal-only Task and optional state-update assertions before edits.
  • skill: codebase-design; applicable_behavior: Keep planning identity preservation and Delivery event routing as shallow consumers of the writer seam.
• tdd_status: required
• tdd_target: A provider Task ID and blocker edge survive planning, start, PR, merge, and production updates without a second Task identity.
• red_command: node --test tests/create-plan-backlog-tasks.contract.test.mjs tests/delivery-backlog-state-integration.contract.test.mjs tests/routed-glossary-consumers.contract.test.mjs
• expected_red_failure: Current consumers state Task is plan-internal and delivery updates are optional/post-wave.
• green_command: node --test tests/create-plan-backlog-tasks.contract.test.mjs tests/delivery-backlog-state-integration.contract.test.mjs tests/routed-glossary-consumers.contract.test.mjs
• reason_not_testable:
• red_evidence: Canonical test-first run established internal-only Task identity and optional state-update assertions; the individual RED transcript was not retained in this Harness handoff.
• green_evidence: Planning/delivery/glossary consumer contracts passed within 211/211 at 57a94c0….
• codebase_design_notes: Consumers depend on the writer result contract; no consumer owns provider mapping.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A3
• behavior_owner: Planning and Delivery lifecycle consumers
• integration_surface: Provider Task graph and delivery evidence handoff
• public_seam: PLAN.md Task identity fields; Delivery phase handoff
• topology_delta: Removes MIG-3 and converges RAC-4.
• forbidden_ownership: New provider adapter rules; inferred deployment facts
• temporary_seams: []
• responsibility_acceptance_criteria: [RAC-4, RAC-5]

T12: Validate, commit, and push canonical shared skills

• depends_on: [T11]
• location: canonical shared repo
• owned_paths: []
• wave_boundary: W8
• description: Run the complete shared contract suite, verify obsolete public semantics are absent, review the aggregate diff under $writing-for-agents, commit all canonical source changes on exact main, push, and record the immutable SHA.
• validation: node --test tests/*.test.mjs; clean shared repo after push; remote main contains exact commit.
• status: Complete
• log: Full canonical suite passed 211/211; commit 57a94c068df753bcafe94fa44dae6675168cf060 is pushed and local main matches origin/main with a clean worktree.
• files edited/created: Canonical shared-skill aggregate at 57a94c0….
• backlog_item_id: IP-383
• backlog_item_url: https://linear.app/devpunks/issue/IP-383/engineer-resolves-story-delivery-with-technical-finder
• relation_mode: native
• assigned_skills: [writing-for-agents]
• implementation_skill_guidance:
  • skill: writing-for-agents; applicable_behavior: Review pointer strength, progressive disclosure, completion bounds, co-location, and duplication across the final aggregate.
• tdd_status: not_applicable
• tdd_target: Canonical validation and immutable source retention.
• red_command:
• expected_red_failure:
• green_command: node --test tests/*.test.mjs
• reason_not_testable: Integration/retention task; RED/GREEN evidence belongs to T2-T11.
• red_evidence:
• green_evidence: node --test tests/*.test.mjs passed 211/211; main and origin/main both resolve 57a94c068df753bcafe94fa44dae6675168cf060; canonical worktree is clean.
• codebase_design_notes: Confirms one canonical source authority.
• 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 publication authority
• integration_surface: Git remote and Harness sync input
• public_seam: Immutable shared source SHA
• topology_delta: Freezes source for projection.
• forbidden_ownership: Harness generated mirrors
• temporary_seams: []
• responsibility_acceptance_criteria: [RAC-5]

T13: Sync canonical skills and expose the three human entrypoints

• depends_on: [T6]
• location: Harness CLI scaffold integration
• owned_paths: [apps/cli/scripts/sync-skills-repo.mjs, apps/cli/src/scripts/sync-skills-repo.test.ts, 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, .agents/skills/**, apps/cli/skills/**, .claude/skills/**, .devpunks/scaffold-manifest.json, .devpunks/harness-projection-receipt.json]
• wave_boundary: W10
• description: Pin the canonical SHA, register the wrappers, include them in the planning pack and phase entrypoint catalog, replace root auto-routing with explicit human selection, run the supported sync, and verify exact receipt. Preserve unrelated dirty paths and fail before overlapping them.
• validation: Sync pin test, prompt/catalog tests, bun run sync:skills, exact cache receipt SHA, and generated metadata/readback.
• status: Complete
• log: Harness sync pins 57a94c0…; generated catalogs/prompts expose Business, Functional, and Technical Finder as human-only entrypoints with no implicit Finder route. Focused CLI closeout suite passed 11/11.
• files edited/created: Sync script, catalog, packs, prompts, scaffold-copy integration, generated skill mirrors, projection receipt/manifest, and focused tests.
• backlog_item_id: IP-381
• backlog_item_url: https://linear.app/devpunks/issue/IP-381/business-owner-structures-a-request-with-business-finder
• relation_mode: native
• assigned_skills: [writing-for-agents, tdd, codebase-design]
• implementation_skill_guidance:
  • skill: writing-for-agents; applicable_behavior: Keep generated root prompts compact, human-invoked, and pointer-led; do not restate engine policy.
  • skill: tdd; applicable_behavior: Capture catalog/pack/prompt and exact-pin failures before integration edits.
  • skill: codebase-design; applicable_behavior: Treat canonical SHA sync as the sole adapter from shared source to generated product assets.
• tdd_status: required
• tdd_target: Scaffold exposes three human-only Finder entrypoints and no prompt can auto-route Finder.
• red_command: bun run --cwd apps/cli test -- sync-skills-repo prompts catalog
• expected_red_failure: New wrappers are absent, Finder remains implicit, and pin points to old source.
• green_command: bun run --cwd apps/cli test -- sync-skills-repo prompts catalog
• reason_not_testable:
• red_evidence: Focused integration tests initially proved wrappers/prompt policy/pin were absent; exact console transcript was not retained.
• green_evidence: Final focused CLI closeout suite passed 11/11; generated projections expose three human-only wrappers pinned to 57a94c0….
• codebase_design_notes: Sync script is the adapter; generated mirrors never own policy.
• 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 scaffold catalog and projection
• integration_surface: Shared source SHA to installed skills/prompts
• public_seam: Available skill names and generated human guidance
• topology_delta: Removes MIG-4 and closes source/projection authority.
• forbidden_ownership: Hand-edited projected policy; implicit Finder invocation
• temporary_seams: []
• responsibility_acceptance_criteria: [RAC-5]

T14: Author the complete durable flow documentation

• depends_on: [T15]
• location: Harness durable docs/wiki
• owned_paths: [docs/README.md, docs/runbooks/hi-cli-scaffolding.md, apps/wiki/content/docs/project/runbooks/hi-cli-scaffolding.md, apps/wiki/content/docs/cli/scaffold-lifecycle/settings-reconfiguration.mdx, apps/wiki/content/docs/harness/entrypoints/finder-phase.mdx, apps/wiki/content/docs/harness/entrypoints/brainstorming-requirements-backlog.mdx, apps/wiki/content/docs/harness/entrypoints/index.mdx, apps/wiki/content/docs/harness/skills-and-packs/**, apps/wiki/content/docs/harness/execution-modes/**, apps/wiki/content/docs/harness/foundations/project-backlog-operating-model.mdx]
• wave_boundary: W12
• description: Replace old chart/work and Epic/Story-only explanations. Explain the cumulative wrappers, one graph engine, lateral Fog, full topology, required Task blockers, V*, four backlog views, Normalization approval, delivery facts, operator-skill compatibility, and hi ensure migration using the accepted show-me diagrams. Post-review docs-ingest-phase owns final spec, plan, implementation-note, and backlink bookkeeping.
• validation: bun run --cwd apps/wiki check:content; docs links and diagrams match implementation and source SHA.
• status: Complete
• log: Durable docs now show cumulative wrappers, one engine, lateral Fog, full hierarchy, contextual V*, four views, provider limits, Normalization, observed delivery truth, and hi ensure migration. Content, route, formatting, and diff checks passed.
• files edited/created: The 13 docs/wiki files declared and validated in T14 scope.
• backlog_item_id: IP-381
• backlog_item_url: https://linear.app/devpunks/issue/IP-381/business-owner-structures-a-request-with-business-finder
• relation_mode: native
• assigned_skills: [writing-for-agents, show-me]
• implementation_skill_guidance:
  • skill: writing-for-agents; applicable_behavior: Keep agent-consumed docs pointer-led, co-located, and aligned with their owning skill references.
  • skill: show-me; applicable_behavior: Use the two accepted diagrams plus the smallest view for backlog views and evidence states; preserve exact authority labels.
• tdd_status: not_applicable
• tdd_target: Durable documentation and route validation.
• red_command:
• expected_red_failure:
• green_command: bun run --cwd apps/wiki check:content
• reason_not_testable: Docs-only task.
• red_evidence:
• green_evidence: Wiki content current; route tests 12/12 plus sidebar test 1/1; all 13 changed docs formatted; scoped diff check passed.
• codebase_design_notes: Docs point to owning skill references; they do not become a second behavior source.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable
• architecture_wave: A4
• behavior_owner: Durable product and operator documentation
• integration_surface: Wiki/docs readers and agent pointers
• public_seam: Finder/backlog flow documentation
• topology_delta: Replaces stale public and operator explanations.
• forbidden_ownership: New runtime policy in prose
• temporary_seams: []
• responsibility_acceptance_criteria: [RAC-6]

T15: Prepare the CLI 4.0.0 and baseline major release

• depends_on: [T13]
• location: Harness release metadata
• owned_paths: [apps/cli/package.json, bun.lock, CHANGELOG.md, BASELINE_CHANGELOG.md, apps/cli/src/features/operator-skill/target.ts, apps/cli/src/features/operator-skill/lifecycle-target-delegation.test.ts, apps/cli/src/features/operator-skill/test-fixtures/targets.json, apps/cli/src/features/operator-skill/test-fixtures/installed-copies.json]
• wave_boundary: W11
• description: Bump CLI to 4.0.0, update the verified operator-skill compatibility target and fixtures for 4.x, update lockfile, add matching nonempty CLI notes, update baseline Unreleased compatibility to >=4.0.0 <5, and record the exact canonical skill SHA and breaking Finder/backlog model.
• validation: Version/lock agree; CLI 4 resolves a verified compatible operator target; both changelog sections are nonempty and semantically classify the breaking change.
• status: Complete
• log: CLI is 4.0.0; operator compatibility is <5.0.0; lockfile and both changelogs carry the breaking model; exact baseline build passed with compatibility >=4.0.0 <5.
• files edited/created: CLI package/lock, operator target and fixtures, CHANGELOG.md, and BASELINE_CHANGELOG.md.
• backlog_item_id: IP-385
• backlog_item_url: https://linear.app/devpunks/issue/IP-385/operator-migrates-the-configured-linear-backlog-destination
• relation_mode: native
• assigned_skills: [tdd, codebase-design]
• implementation_skill_guidance:
  • skill: tdd; applicable_behavior: Capture CLI 4 rejecting the current operator target before changing compatibility and release metadata.
  • skill: codebase-design; applicable_behavior: Keep operator compatibility in its existing target seam and leave release classification independent.
• tdd_status: required
• tdd_target: CLI 4 resolves one verified compatible operator skill target before package and changelog closure.
• red_command: bun run --cwd apps/cli test -- operator-skill
• expected_red_failure: Current operator target has maximumExclusive: "4.0.0" and rejects the requested CLI major.
• green_command: bun run --cwd apps/cli test -- operator-skill && bun run --cwd apps/cli build
• reason_not_testable:
• red_evidence: Operator compatibility test initially proved the <4.0.0 target rejected CLI 4; exact console transcript was not retained.
• green_evidence: Focused operator coverage is included in 11/11; CLI check-types passed; exact baseline build passed with >=4.0.0 <5.
• codebase_design_notes: authoritativeOperatorSkillTarget is the existing compatibility seam; its verified target range changes with the CLI major while release classification remains a separate consumer.
• 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 and baseline release authority
• integration_surface: npm package and stable baseline classifier
• public_seam: @punks/cli@4.0.0; baseline compatibility
• topology_delta: Declares the accepted breaking model.
• forbidden_ownership: Release publication before candidate proof
• temporary_seams: []
• responsibility_acceptance_criteria: [RAC-7]

T16: Run implementation convergence and provider-linked closeout

• depends_on: [T14]
• location: both repositories and configured providers
• owned_paths: [apps/wiki/content/docs/project/specs/cli/project-backlog-operating-model/IMPLEMENTATION-NOTES.md, apps/wiki/content/docs/project/specs/cli/project-backlog-operating-model/PHASE-HANDOFF.md]
• wave_boundary: W13
• description: Run focused and aggregate tests, architecture checkpoints, exact sync receipt, CLI typecheck, wiki checks, and baseline build. Finalize IMPLEMENTATION-NOTES.md and PHASE-HANDOFF.md, preserve unrelated dirty files, classify the mixed release, retain PR/provider evidence, and close only IP-380 through IP-388. Live product-backlog initialization remains a separately approved operator invocation.
• validation: Every changed-surface gate passes; canonical and Harness projections name the exact shared commit; release inputs classify mixed; PR findings are repaired; IP-380 through IP-388 are read back; erroneous generated Tasks are canceled; migration ledger is empty.
• status: Complete
• log: PR #172 retains the implementation and mixed release classification. Fresh focused validation passed; review findings were repaired, including exact Task/parent-Story milestone equality and root-only Effect prepare receipt ownership; docs ingest is current; IP-380 through IP-388 were read back; and erroneous IP-389 through IP-404 were canceled as superseded history. No unapproved product-backlog topology, deployment, production, or publication fact was created.
• files edited/created: IMPLEMENTATION-NOTES.md, PHASE-HANDOFF.md, and this evidence update to PLAN.md.
• backlog_item_id: IP-380
• backlog_item_url: https://linear.app/devpunks/issue/IP-380/operate-one-coherent-product-backlog-from-fog-to-production-evidence
• relation_mode: native
• assigned_skills: [verify-behavior, show-me, writing-for-agents]
• implementation_skill_guidance:
  • skill: verify-behavior; applicable_behavior: Prove the accepted user/operator outcomes through supported public seams and distinguish automated, runtime, and provider evidence.
  • skill: show-me; applicable_behavior: Present final actual topology, evidence states, and any remaining blocker without increasing certainty.
  • skill: writing-for-agents; applicable_behavior: Keep the implementation notes and phase handoff pointer-led, co-located with their proof, and explicit about completion and resume criteria.
• tdd_status: not_applicable
• tdd_target: Aggregate convergence and external readback proof.
• red_command:
• expected_red_failure:
• green_command: zsh -lc 'cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test tests/*.test.mjs' && bun run --cwd apps/cli build && bun run --cwd apps/cli check && bun run --cwd apps/wiki check:content && bun run check && bun run test && BASELINE_CLI_VERSION_RANGE='>=4.0.0 <5' bun run baseline:build
• reason_not_testable: Validation-only task; each behavior-changing task retains RED/GREEN evidence.
• red_evidence:
• green_evidence: Complete implementation convergence: canonical 211/211, focused CLI 11/11, focused root-only Effect prepare ownership, CLI typecheck, wiki tests, baseline build, diff checks, PR #172, mixed classification, docs ingest, and exact Linear closeout readback passed. This does not claim a full scaffold suite for the focused ownership repair.
• codebase_design_notes: Final zero-drift comparison against every normative architecture view.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: Code and skill-contract delivery only; live structural provider mutation requires a separate approved invocation.
• runtime_evidence: Exact canonical sync receipt, CLI 4.0.0 typecheck, assembled baseline, PR evidence, and Linear closeout readback.
• runtime_cleanup: IP-389 through IP-404 canceled as superseded history; every user-owned repository/provider object preserved.
• architecture_wave: A4
• behavior_owner: Delivery convergence
• integration_surface: Full product, providers, release classifier
• public_seam: Final delivery evidence
• topology_delta: Zero-drift closure.
• forbidden_ownership: Waived tests, inferred provider success, automatic release publication
• temporary_seams: []
• responsibility_acceptance_criteria: [RAC-1, RAC-2, RAC-3, RAC-4, RAC-5, RAC-6, RAC-7]

Validation Gates

Focused behavior

cd /Users/stefan/Desktop/repos/wearedevpunks-skills
node --test tests/finder-phase-graph.contract.test.mjs tests/wayfinder-lifecycle.contract.test.mjs
node --test tests/write-backlog-*.contract.test.mjs
node --test tests/functional-finder.contract.test.mjs tests/technical-finder.contract.test.mjs
node --test tests/delivery-backlog-state*.contract.test.mjs tests/create-plan-backlog-tasks.contract.test.mjs
node --test tests/*.test.mjs

cd /Users/stefan/.codex/worktrees/20d2/harness-intelligence
bun run --cwd apps/cli test -- settings-selection ensure-command
bun run --cwd apps/cli test -- sync-skills-repo prompts catalog
bun run --cwd apps/cli build
bun run --cwd apps/cli check
bun run --cwd apps/wiki check:content

Product and release convergence

bun run check
bun run test
BASELINE_CLI_VERSION_RANGE='>=4.0.0 <5' bun run baseline:build
bun run release:classify -- --base origin/main --head HEAD

Release publication requires the repository's separate exact-tree Candidate Evidence and release-authority gates. This plan prepares and validates the requested mixed release; it does not weaken or bypass publication authority.

Testing Strategy

• Use vertical RED→GREEN contract slices for each skill graph, semantic branch, provider mapping, CLI public seam, and downstream consumer.
• Prefer observable skill/prompt/provider contracts over file-existence assertions.
• Keep live provider readback distinct from Markdown contract evidence.
• Prove dirty-worktree preservation before and after branch reconciliation and generated sync.
• Run architecture convergence after each A-wave. Each checkpoint evaluates all criteria due so far and re-runs prior evidence.

Risks And Mitigations

Unresolved Questions

No product or architecture decision remains unresolved.

Runtime proof gates remain conditional facts, not decisions:

• Linear Initiative/Project mutation and readback depend on actual workspace/API authority exposed at execution.
• GitHub runtime coverage remains unclaimed until the workflow-created nested Task readback succeeds.
• If exact provider authority is unavailable, delivery records the named blocker and does not claim AC-025/AC-026 runtime completion.

Review And Docs Routing

• T16 first creates and validates the pre-review candidate, then full delivery routes its exact diff, PLAN, SPEC, implementation notes, RED/GREEN evidence, provider readback, sync receipt, and release classification through review-phase.
• Findings repair only their owning task scope and preserve the three-pass delivery budget.
• Passing review routes to docs-ingest-phase for final source/backlink/status reconciliation. Closeout creates the final path-limited commit, reruns mixed classification and exact-tree provider proof when the tree changed, then updates Linear state and PR evidence and closes IP-380 through IP-388.

$wait-what Check

Plain-language result: three human commands guide one Fog to the depth the human chose. One writer turns accepted decisions into one provider hierarchy. Stories and Tasks share one version milestone. Delivery records only facts it can see. A merge does not mean production. The CLI keeps the same settings key and guides operators away from old Linear Project URLs. Shared skill source lands first; Harness then syncs its exact commit. The final docs and major release describe that same flow.