Plan: Wayfinder Lifecycle Upgrade

Initial Situation

Harness already ships a first Devpunks adaptation of Matt Pocock's Wayfinder:

wayfinder is a lean one-pass route classifier.
finder-phase wraps that classifier and may delegate provider writes to write-backlog.
prototype supports logic and UI experiments but deletes or absorbs the artifact after learning.
parallel-research fans out readonly work but does not own a durable report lifecycle.
create-spec still interviews, may rewrite backlog before drafting, and stops for review.
requirements-phase currently ends at backlog readiness or backlog writing.
write-backlog treats epics as future spec anchors and still uses kind as its canonical taxonomy term.

The confirmed grill at apps/wiki/content/docs/project/grilling/wayfinder-backlog-model-grill-status.md and its decision log supersede those behaviors. All active design branches are 100%, the frontier is empty, and shared understanding is confirmed.

The canonical reusable-skill source is:

/Users/stefan/Desktop/repos/wearedevpunks-skills

Harness copies under apps/cli/skills, .agents/skills, and other scaffold mirrors are generated consumers. They must not be edited as the source of truth.

The current Harness checkout is detached and contains unrelated scaffold/update changes. Implementation must use a clean dedicated Harness worktree or otherwise prove a non-overlapping clean baseline before running the broad skills sync. The canonical skills repository is currently clean at f094c3c on team/stefan/parallel-delivery; the executor must establish task-specific branch intent before editing it. Harness sync currently defaults to the unrelated team/stefan/security-pack@844890d, so the executor must also resolve and prove the intended source ref/pin before syncing.

Problem Statement

The current skill system can classify foggy work, but it cannot maintain and resume a durable decision frontier. Its child routes also lack the accepted evidence and convergence contracts. The surrounding requirements, specification, and backlog skills encode the old backlog-first order, so changing Wayfinder alone would leave the workflow contradictory.

The implementation must produce one coherent lifecycle:

finder-phase
  -> research | prototype-phase | requirements-grill
  -> finder-phase reconciliation
  -> create-spec when the frontier is closed or explicitly parked
  -> write-backlog
  -> delivery-phase / create-plan

Research, prototyping, and grilling are alternative routes. A prototype may reveal a need for grilling, but neither a mandatory grill nor a mandatory bypass is valid.

Solution Shape

Upgrade wayfinder and finder-phase into a resumable destination/map/frontier lifecycle while preserving the Harness backlog root as the living map.
Refresh the existing prototype primitive from Matt's current mechanics and add a standalone prototype-phase that owns claim, user-driven verdict, throwaway-branch evidence, and return to Wayfinder.
Extend parallel-research with an optional durable-report contract and teach docs-ingest-phase to ingest those reports as private/internal learning sources.
Turn create-spec into a no-interview compiler of closed decisions and make requirements-phase invoke it immediately after a confirmed grill.
Move write-backlog after the spec, remove the approval stop and canonical kind vocabulary, then add traceability, tracer-bullet, blocker-graph, and agent-readiness validation before immediate provider mutation.
Add source contract tests, Harness catalog/content tests, planning-pack wiring, generated routing guidance, source-first push/sync evidence, and durable docs.

Resolved Decision Ledger

The user explicitly requested direct planning: no SPEC.md and no backlog sync for this planning run.
Every implementation task that writes or edits a skill must use writing-for-agents while shaping and editing it.
The shared skills repository is edited, validated, committed, and pushed before Harness runs bun run sync:skills.
The Harness backlog root is the living Wayfinder map; no separate map issue is introduced.
finder-phase owns destination, chart/work modes, frontier computation, claims, resumption, routing, reconciliation, fog graduation, and map repair.
wayfinder remains the lean reusable primitive. Provider-specific mutation stays in write-backlog.
Frontier means open, unblocked, and unclaimed decision tickets.
A question graduates from fog when it can be stated precisely now.
The direct backlog concepts are fog, grilling, research, prototype, epic, and story; kind is not canonical domain vocabulary or a required cross-provider field.
prototype remains an artifact-construction primitive; prototype-phase owns the standalone HITL lifecycle.
Prototype accept, iterate, and reject are natural-language user verdicts. Accept and reject return to Wayfinder; iterate keeps the phase active.
PROTOTYPE-VERDICT.md lives beside the prototype on a throwaway branch and is referenced by immutable commit SHA plus path.
A prototype verdict may route to grilling, research, another prototype, or directly to create-spec after Wayfinder recomputes the frontier.
Durable research produces one consolidated primary-source-cited Markdown report on research/<slug>, written by the coordinator or one designated consolidator after readonly lanes finish.
docs-ingest-phase may project a durable research report into canonical routed wiki knowledge while preserving the report as primary evidence.
create-spec consumes closed decisions and does not interview, grill, or mutate backlog to repair missing input.
spec-not-ready writes no partial spec and names each missing decision/evidence item plus its upstream route.
Successful compilation writes readiness: agent-ready and returns spec-written.
Specs contain US-### user stories, AC-### criteria with one-way Covers: US-### traceability, accepted technical/testing decisions, prototype verdicts, and a verification-seam decision or explicit not-applicable rationale.
SPEC.md is provider-neutral authority. Delivery epics/stories are projections created afterward, not future anchors created before the spec.
write-backlog validates agent-ready spec input, complete story/criteria traceability, vertically demonstrable tracer bullets, and an acyclic blocker graph before provider mutation.
write-backlog has no separate approval stop. It writes immediately after validation or fails before any provider mutation.
A pre-spec intake item resolves with an immutable spec link and is not promoted silently into a delivery epic.
Legacy backlog-first migration is parked. Existing items remain untouched.
Concrete files, commands, test cases, worker assignments, and execution order remain plan-owned.

Assumptions And Constraints

This plan is the explicit upstream planning request allowed by create-plan; no spec is required.
Execution uses WAYFINDER_SKILLS_ROOT=/Users/stefan/Desktop/repos/wearedevpunks-skills and WAYFINDER_HARNESS_ROOT=/Users/stefan/.codex/worktrees/wayfinder-lifecycle/harness-intelligence. T0 creates/validates the latter; every later shell command that needs a root declares it explicitly.
After proving local/upstream/remote equality, T7 persists the immutable source commit at /private/tmp/wayfinder-lifecycle-skills.sha and copies it into the task log. T8-T11 load that exact evidence-file value; they may not recompute the expected value from a moving branch head. T11 removes the file only after final evidence is recorded.
The completed requirements grill supplies the ambiguity-reduction input. No additional plan-shaping questions remain.
Backlog fields in every task are not_applicable because the user explicitly excluded backlog work from this planning run.
The plan does not authorize a baseline release, CLI package release, or broad legacy migration.
Do not overwrite unrelated dirty changes in the current Harness worktree. Use a clean dedicated execution worktree before source sync or generated-mirror writes.
Do not hand-edit generated Harness skill mirrors. Change canonical skills, push them, then use the supported sync/scaffold path.
Keep each behavior in one source of truth. finder-phase links to child skills and write-backlog; it does not duplicate their full contracts.
Keep every phase/skill SKILL.md lean. Put branch-specific contracts in progressive-disclosure references only when the split earns its context cost.
Preserve existing disable-model-invocation intent unless the new routing contract requires model discovery. finder-phase remains the model-invoked root route accepted by the grill; child phase invocation is explicit from Wayfinder.
No external package API changes are involved. Context7/opensrc dependency research is intentionally skipped.
The planning-discovery specialist could not be activated because its generated agent registration is absent in this dirty checkout. A readonly explorer substitutes for bounded discovery; final review must still use plan-reviewer when available or record the same explicit fallback.

Codebase Findings

Canonical wayfinder/SKILL.md currently performs one pass: name frontier, choose one concept, place it, return a route.
Canonical finder-phase has no destination, chart/work modes, precise fog-graduation test, dependencies, claims, resume input, or reconciliation loop.
finder-phase is accepted as model-invoked, but its current disable-model-invocation: true and agents/openai.yaml policy both disable implicit invocation.
Canonical prototype says to delete or absorb the prototype and lacks throwaway-branch primary-source retention.
Canonical parallel-research is stronger than Matt's skill at fan-out, disagreement resolution, and synthesis, but has no durable-output mode and only traces “important claims.”
Canonical requirements-phase is explicitly requirements-grill -> write-backlog and forbids spec creation.
Canonical create-spec owns questioning, optional grilling, pre-draft backlog sync, and user review. These references conflict with the accepted compiler role.
Canonical write-backlog derives a kind, treats epics as future spec anchors, and writes from grill artifacts rather than requiring an agent-ready spec.
The shared skills repository already has node:test contract coverage in tests/write-backlog-provider-planning.contract.test.mjs; this is the nearest public verification seam for skill behavior.
Harness catalog wiring lives in apps/cli/src/data/catalog/skills.ts and packs.ts; generated root workflow criteria live in apps/cli/src/content/scaffold-copy.ts; focused coverage lives in apps/cli/src/content/content.test.ts.
Harness sync is bun run sync:skills; apps/cli/.devpunks-cache/skills-sync.json records source provenance.
Harness sync currently points at an unrelated older branch/commit and can regress newer content unless its intended source ref is updated and verified first.
apps/cli/AGENTS.md requires docs/README.md and docs/runbooks/hi-cli-scaffolding.md updates when AI scaffolding behavior changes.
Existing routed writer artifacts under apps/wiki/content/docs/project/public-docs/finder-phase/ must be inspected through docs-ingest-phase; do not overwrite them blindly.
The old implemented plan at apps/wiki/content/docs/project/specs/cli/finder-phase-wayfinder-skill-workflow/PLAN.md documents the v1 classifier and canonical kind model. Preserve it as historical implementation evidence; this plan is a separate v2 execution artifact.

External Research Used

Matt Wayfinder source at commit 2ab958093e83e0ec752e6c1c5932da465bf23e0c: destination, map and decision-ticket contracts, frontier/claim semantics, precise fog graduation, chart/work modes, and one-ticket session discipline.
Matt Prototype source at the same commit: standalone user-driven experiment, logic/UI branches, real-host UI variants, production safeguards, and durable throwaway-branch evidence.
Matt Research source at commit 0d74d01cbc64ca27778a49b38599f70c534e76a0: one claim-cited Markdown report and repository-convention placement.
Matt To Tickets source at commit 2ab958093e83e0ec752e6c1c5932da465bf23e0c: vertically demonstrable tracer bullets, blocker graphs, and agent readiness. Its approval gate was explicitly rejected.
Matt To Spec source: verification seams and compilation from settled conversation. Devpunks preserves separate spec, backlog, and concrete-plan artifacts.
Prior readonly agents independently covered Wayfinder/prototype, research merging, and ticketing differences. Their findings were reconciled against canonical local sources and the confirmed grill.

Design And Test Strategy

The public interface is the instruction contract exposed by each SKILL.md, its disclosed references/templates, the source catalog, and generated root prompts. Test those surfaces, not incidental paragraph order.

Use one source contract suite with behavior-named assertions. It should read the relevant skill trees and prove the durable invariants. Avoid asserting whole files or exact prose. Existing provider-planning tests remain and are updated only where the accepted direct taxonomy/spec-first model supersedes them.

Harness tests cover the distribution seam:

prototype-phase is registered and shipped.
planning/research packs expose the intended primitive/phase split.
synced source directories and required references/templates exist.
generated root guidance describes Finder as the router and preserves the spec-before-backlog lifecycle.
sync receipt commit equals the pushed canonical source commit.

All behavior-changing source tasks use RED -> GREEN through node:test. Catalog/prompt changes use the focused CLI content test. Docs, metadata, sync bookkeeping, and final aggregation are not_applicable for TDD but still have exact validation commands.

Dependency Graph

T0 -> T1 -> T2 -> T3 -> T4 -> T5 -> T6 -> T6.1 -> T7 -> T8 -> T9 -> T9.1 -> T10 -> T10.1 -> T11

One implementation worker owns the sequential cross-repository chain. This avoids overlapping writes in shared skill text, contract tests, catalog state, generated mirrors, and docs. Readonly review remains parent-owned or delegated to a reviewer.

Tasks

T0: Establish Clean Execution Baselines

depends_on: []
location: /Users/stefan/Desktop/repos/wearedevpunks-skills, /Users/stefan/.codex/worktrees/wayfinder-lifecycle/harness-intelligence
description: Verify both remotes, capture starting commits and dirty state, resolve the intended clean source base/ref and downstream sync pin, create or select task-specific non-detached branches, verify the canonical skill source is clean, and verify the Harness execution worktree excludes unrelated scaffold changes. Install/verify the clean worktree's dependencies, including @effect/vitest. Confirm node, bun, git push access, bun run sync:skills, the subagent manifest, and a usable single implementation worker before any edit.
validation: Both repositories have explicit branch/commit baselines; source base and Harness sync ref agree; the Harness execution worktree is clean and its focused tests can collect; the shared source is clean; required commands and worker coverage are available. Stop rather than using the dirty planning checkout or the unrelated default sync pin.
status: Complete
log: 2026-08-04 — Created and validated the dedicated clean Harness worktree on team/stefan/wayfinder-lifecycle; established the clean canonical source branch with the same task name; verified Node/Bun/dependencies and preserved the dirty bbce checkout as artifact-only coordination state.
files edited/created: /Users/stefan/.codex/worktrees/wayfinder-lifecycle/harness-intelligence; canonical branch team/stefan/wayfinder-lifecycle
backlog_item_id: not_applicable
backlog_item_url: not_applicable
relation_mode: none
assigned_skills: [create-plan, parallel-research, swarm-planner, codebase-design]
tdd_status: not_applicable
tdd_target: Execution safety and source-of-truth preflight.
red_command:
expected_red_failure:
green_command: export WAYFINDER_SKILLS_ROOT=/Users/stefan/Desktop/repos/wearedevpunks-skills WAYFINDER_HARNESS_ROOT=/Users/stefan/.codex/worktrees/wayfinder-lifecycle/harness-intelligence && test "$(git -C "$WAYFINDER_HARNESS_ROOT" rev-parse --is-inside-work-tree)" = true && test -z "$(git -C "$WAYFINDER_SKILLS_ROOT" status --porcelain)" && test -z "$(git -C "$WAYFINDER_HARNESS_ROOT" status --porcelain)" && test -n "$(git -C "$WAYFINDER_HARNESS_ROOT" branch --show-current)" && test -f "$WAYFINDER_HARNESS_ROOT/.agents/subagents/manifest.mjs" && command -v node && command -v bun && cd "$WAYFINDER_HARNESS_ROOT" && bun install --frozen-lockfile && bun run --cwd apps/cli test src/content/content.test.ts
reason_not_testable: Readonly repository and worker-guard inspection.
red_evidence:
green_evidence: Both execution worktrees were clean before owned edits; Harness focused content baseline collected successfully after dependency installation.
codebase_design_notes: Preserve canonical-source versus generated-consumer boundaries before edits begin.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: not_applicable

T1: Confirm The Shared Contract Baseline

depends_on: [T0]
location: /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/write-backlog-provider-planning.contract.test.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/fixtures/write-backlog-provider-planning.json
description: Run the existing source contracts unchanged, record their passing baseline, and inventory the public skill/reference/template seams that later vertical slices will test. Do not add future behavior tests here. Each T2-T6 slice must add and observe its own RED immediately before editing its owning skill, then reach GREEN before the next slice.
validation: Existing source tests pass before behavior changes; the log records the exact command/output and confirms that no new lifecycle assertions were added early.
status: Complete
log: 2026-08-04 — Recorded the unchanged canonical provider-planning baseline before lifecycle behavior edits; no future assertion batch was introduced in this task.
files edited/created: none
backlog_item_id: not_applicable
backlog_item_url: not_applicable
relation_mode: none
assigned_skills: [tdd, codebase-design]
tdd_status: not_applicable
tdd_target: Preserve a trusted pre-change test baseline without creating a horizontal RED batch.
red_command:
expected_red_failure:
green_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test tests/write-backlog-provider-planning.contract.test.mjs
reason_not_testable: Readonly baseline capture; behavior RED/GREEN begins within each owning vertical slice.
red_evidence:
green_evidence: node --test tests/write-backlog-provider-planning.contract.test.mjs passed 2/2 before behavior changes.
codebase_design_notes: Inventory stable public skill/reference/template seams; avoid brittle exact-prose snapshots.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: not_applicable

T2: Refresh Prototype And Add `prototype-phase`

depends_on: [T1]
location: /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/wayfinder-lifecycle.contract.test.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/research/prototype/**, new /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/prototype-phase/**, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase/SKILL.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase/phases/prototype.md
description: Work as ordered one-test vertical subcycles, never as a batch of assertions followed by a batch of edits. First add one assertion that prototype-phase exists and delegates artifact construction to prototype; observe RED, make the minimum writing-for-agents edit, and reach GREEN. Then repeat one assertion -> observed RED -> minimum owning edit -> GREEN for: refreshed Matt logic/UI mechanics while retaining local constraints; one-command execution and visible state; real-host variants and stable URL/reload behavior; keyboard-input safety, production gating, and stubbed mutations; ticket/question intake and claim; throwaway branch evidence; natural-language accept/iterate/reject; PROTOTYPE-VERDICT.md plus immutable SHA/path handoff; return to Wayfinder; reusable verdict template; and design-wrapper composition. Do not start the next behavior until the current assertion is GREEN.
validation: Prototype-specific contract tests pass; prototype/SKILL.md remains the artifact primitive; prototype-phase/SKILL.md exposes lifecycle steps and progressively discloses branch/verdict depth.
status: Complete
log: 2026-08-04 — Added the standalone human-verdict phase, durable throwaway-branch evidence, safe/reload-stable real-host UI mechanics, and design-phase composition. Review remediation expanded the verdict with rejected alternatives, rationale, risks, run/inspection instructions, and an optional decision-rich snippet; iterate now commits verdict updates and reject returns the unresolved question to Finder. Used writing-for-agents to keep construction in the primitive and lifecycle in the phase.
files edited/created: tests/wayfinder-lifecycle.contract.test.mjs; skills/agnostic/research/prototype/{SKILL.md,UI.md}; skills/phases/prototype-phase/{SKILL.md,VERDICT-TEMPLATE.md}; skills/phases/design-phase/phases/prototype.md
backlog_item_id: not_applicable
backlog_item_url: not_applicable
relation_mode: none
assigned_skills: [writing-for-agents, prototype, design-phase, tdd, codebase-design]
tdd_status: required
tdd_target: First cycle only: prototype-phase exists and delegates artifact construction to the prototype primitive.
red_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test --test-name-pattern="prototype phase delegates" tests/wayfinder-lifecycle.contract.test.mjs
expected_red_failure: The first assertion reports that prototype-phase does not exist or does not delegate to prototype.
green_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test --test-name-pattern="prototype" tests/wayfinder-lifecycle.contract.test.mjs
reason_not_testable:
red_evidence: prototype phase delegates construction to prototype failed with ENOENT for the absent phase; the UI-safety cycle failed because UI.md did not state reload persistence, focused-input keyboard safety, or stubbed mutations; review remediation prototype verdict preserves decision-rich evaluation evidence failed on the missing rejected-alternatives field.
green_evidence: node --test --test-name-pattern="prototype" tests/wayfinder-lifecycle.contract.test.mjs passed 4/4 prototype contracts; aggregate lifecycle contracts passed 13/13.
codebase_design_notes: Keep artifact construction behind the prototype interface; keep claim/verdict/reconciliation in the phase wrapper. The throwaway branch is evidence, never production code authority.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: not_applicable

T3: Upgrade Wayfinder And Finder Lifecycle

depends_on: [T2]
location: /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/wayfinder-lifecycle.contract.test.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/wayfinder/**, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/finder-phase/**
description: Work as ordered one-test vertical subcycles. First assert that finder-phase is consistently implicitly invokable in both SKILL.md and agents/openai.yaml; observe RED, make the minimum writing-for-agents metadata edit, and reach GREEN. Then repeat one assertion -> RED -> minimum owning edit -> GREEN for: destination; chart/work modes; backlog-root map without a separate map issue; precise-question fog graduation; out-of-scope handling; open/unblocked/unclaimed frontier; native dependencies and claim-before-work; resumable map/ticket input; bounded child-flow dispatch; immutable resolution pointers; semantic reconciliation; invalidated-scope repair; and frontier recomputation. Keep finder-phase/SKILL.md lean and disclose lifecycle/convergence depth through noun-named references and child-skill links. Do not begin a later behavior while an earlier cycle is RED.
validation: Finder/Wayfinder contract tests pass; metadata assertions prove mutually consistent implicit invocation; the skill pair clearly distinguishes charting from working, routing from child execution, and semantic lifecycle from provider mutation.
status: Complete
log: 2026-08-04 — Enabled consistent implicit invocation and split the lean route primitive from destination/mode/frontier/claim/resumption/reconciliation orchestration through earned references. Review remediation made claim and resolution semantic Finder outputs while routing both physical provider writes through write-backlog.
files edited/created: tests/wayfinder-lifecycle.contract.test.mjs; skills/agnostic/planning/wayfinder/SKILL.md; skills/phases/finder-phase/{SKILL.md,agents/openai.yaml,references/frontier-lifecycle.md,references/convergence.md,references/root-routing.md}
backlog_item_id: not_applicable
backlog_item_url: not_applicable
relation_mode: none
assigned_skills: [writing-for-agents, wayfinder, tdd, codebase-design]
tdd_status: required
tdd_target: First cycle only: Finder invocation metadata is mutually consistent and permits implicit model invocation.
red_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test --test-name-pattern="finder implicit invocation" tests/wayfinder-lifecycle.contract.test.mjs
expected_red_failure: The first assertion finds disable-model-invocation: true, missing/false allow_implicit_invocation, or contradictory metadata.
green_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test --test-name-pattern="wayfinder|finder" tests/wayfinder-lifecycle.contract.test.mjs
reason_not_testable:
red_evidence: finder implicit invocation is consistent failed on disable-model-invocation: true and false sidecar policy; the out-of-scope reconciliation cycle failed until convergence explicitly parked/rerouted scope; review remediation finder routes physical claim and resolution mutation through write-backlog failed because convergence directly named native state mutation.
green_evidence: node --test --test-name-pattern="wayfinder|finder" tests/wayfinder-lifecycle.contract.test.mjs passed 3/3 Finder contracts; aggregate lifecycle contracts passed 13/13.
codebase_design_notes: wayfinder is the route/map primitive; finder-phase is the orchestration seam; provider adapters remain behind write-backlog.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: not_applicable

T4: Add Durable Research And Docs-Ingest Bridge

depends_on: [T3]
location: /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/wayfinder-lifecycle.contract.test.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/research/parallel-research/**, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/docs-ingest-phase/phases/private-internal.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/docs-ingest-phase/references/learning-artifacts.md
description: Work as ordered one-test vertical subcycles. First assert that parallel-research exposes an optional durable mode while ordinary audits remain response-only; observe RED, make the minimum writing-for-agents edit, and reach GREEN. Then repeat one assertion -> RED -> minimum owning edit -> GREEN for: 2-4 readonly lanes; coordinator/designated-consolidator single-writer ownership; one post-synthesis report; every retained factual claim citing its primary source; discovered report convention or narrow path; research/<slug> branch; immutable commit SHA/path return; docs-ingest acceptance of the report as primary learning evidence; and normal keep/update/consolidate/replace/stale projection. Do not combine these into one preliminary assertion batch.
validation: Research/docs-ingest contract tests pass; response-only audits remain allowed; durable mode cannot create multiple competing reports or turn research conclusions into product decisions.
status: Complete
log: 2026-08-04 — Preserved response-only audits and added an optional one-writer durable report branch with primary-source claim citations, immutable evidence, and docs-ingest projection semantics. Review remediation made the parent contract explicit: lanes remain readonly and only the coordinator or one designated consolidator writes and commits exactly one report.
files edited/created: tests/wayfinder-lifecycle.contract.test.mjs; skills/agnostic/research/parallel-research/{SKILL.md,DURABLE-REPORT.md}; skills/phases/docs-ingest-phase/phases/private-internal.md; skills/phases/docs-ingest-phase/references/learning-artifacts.md
backlog_item_id: not_applicable
backlog_item_url: not_applicable
relation_mode: none
assigned_skills: [writing-for-agents, parallel-research, docs-ingest-phase, tdd, codebase-design]
tdd_status: required
tdd_target: First cycle only: parallel-research offers optional durable mode without changing response-only audits.
red_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test --test-name-pattern="research durable mode" tests/wayfinder-lifecycle.contract.test.mjs
expected_red_failure: The first assertion reports that optional durable mode is absent or replaces the response-only default.
green_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test --test-name-pattern="research|docs ingest" tests/wayfinder-lifecycle.contract.test.mjs
reason_not_testable:
red_evidence: research durable mode remains optional failed because neither optional durable mode nor response-only output was declared; review remediation research parent enforces one durable report writer failed because the single-writer boundary existed only in the disclosed reference.
green_evidence: node --test --test-name-pattern="research|docs ingest" tests/wayfinder-lifecycle.contract.test.mjs passed 3/3 research/ingest contracts; aggregate lifecycle contracts passed 13/13.
codebase_design_notes: Research orchestration owns evidence synthesis; docs ingest is a separate projection adapter. The report remains primary evidence; routed wiki pages remain canonical reusable knowledge.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: not_applicable

T5: Compile Confirmed Requirements Directly Into Specs

depends_on: [T4]
location: /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/wayfinder-lifecycle.contract.test.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/create-spec/**, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/requirements-phase/**, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/delivery-phase/phases/spec.md
description: Work as ordered one-test vertical subcycles. First assert that create-spec asks no questions and consumes only confirmed decisions; observe RED, make the minimum writing-for-agents edit, and reach GREEN. Then repeat one assertion -> RED -> minimum owning edit -> GREEN for: accepted research/prototype/ADR/glossary/axiom/constraint/system inputs; atomic structured spec-not-ready; no partial write; readiness: agent-ready; US-###, AC-###, and Covers; accepted implementation/testing decisions; prototype verdicts; mandatory verification seams; pruning obsolete references; requirements-phase invoking the compiler immediately after grill confirmation; spec-written before backlog projection; and delivery-spec consumption without restoring interview/review behavior.
validation: Compiler/requirements contract tests pass; no create-spec instruction asks questions, grills locally, syncs backlog first, or stops for user review; failure writes no partial spec.
status: Complete
log: 2026-08-04 — Replaced interview/discovery/backlog-first authoring with a no-interview compiler, atomic readiness failure, traceable agent-ready template, direct post-grill compilation, and delivery consumption. Removed obsolete compiler-owned questioning, grill, discovery, and backlog-sync references. Review remediation added negative readiness fixtures for blocked/unevidenced dependencies, uncovered user stories, and dangling Covers references.
files edited/created: tests/wayfinder-lifecycle.contract.test.mjs; tests/fixtures/create-spec-readiness.json; skills/agnostic/planning/create-spec/{SKILL.md,assets/SPEC-TEMPLATE.md,references/readiness.md,references/folder-naming.md,references/spec-quality-bar.md,references/wiki-bookkeeping.md}; deleted references/{backlog-sync.md,discovery.md,grill-phase.md,questioning.md}; skills/phases/requirements-phase/SKILL.md; skills/phases/delivery-phase/phases/spec.md
backlog_item_id: not_applicable
backlog_item_url: not_applicable
relation_mode: none
assigned_skills: [writing-for-agents, create-spec, requirements-grill, delivery-phase, tdd, codebase-design]
tdd_status: required
tdd_target: First cycle only: create-spec is a no-interview compiler of confirmed decisions.
red_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test --test-name-pattern="create-spec no-interview compiler" tests/wayfinder-lifecycle.contract.test.mjs
expected_red_failure: The first assertion finds discovery questions, local grilling, or non-confirmed input handling in create-spec.
green_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test --test-name-pattern="create-spec|requirements phase|spec compiler" tests/wayfinder-lifecycle.contract.test.mjs
reason_not_testable:
red_evidence: create-spec no-interview compiler failed because the old skill was an authoring/interview orchestrator with local discovery, questioning, grilling, pre-draft backlog sync, and review stop; review remediation spec compiler rejects incomplete dependency and story coverage failed because readiness omitted dependency and graph-integrity gates.
green_evidence: node --test --test-name-pattern="create-spec|requirements phase|spec compiler" tests/wayfinder-lifecycle.contract.test.mjs passed 3/3 compiler contracts; full lifecycle contract file passed 13/13; git diff --check passed.
codebase_design_notes: create-spec becomes a pure artifact compiler seam. Upstream flows own uncertainty; downstream backlog and plan flows own projection and execution detail.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: not_applicable

T6: Make `write-backlog` A Post-Spec Readiness Projection

depends_on: [T5]
location: /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/wayfinder-lifecycle.contract.test.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/write-backlog-provider-planning.contract.test.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/fixtures/write-backlog-provider-planning.json, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/**
description: Work as ordered one-test vertical subcycles because this projection has many independent invariants. First assert that delivery projection rejects input without an authoritative readiness: agent-ready spec; observe RED, make the minimum writing-for-agents edit, and reach GREEN. Then repeat one assertion -> RED -> minimum owning edit -> GREEN for: direct fog, grilling, research, prototype, epic, story taxonomy; removal of canonical kind/Kind while tolerating provider adapter field names; one capability-boundary epic; US/AC story derivation; complete traceability; agent-sized vertically demonstrable tracer bullets; valid blocker targets; acyclic blocker graph; full readiness before mutation; zero partial mutation on failure; immediate write without approval after validation; resolving pre-spec intake with immutable spec link; no silent promotion; and concrete planning remaining downstream. Run both owning suites after every cycle; never accumulate multiple failing assertions.
validation: Backlog and provider contract tests pass; failure is pre-mutation and non-partial; provider assets preserve direct semantics and exactly-one classification without requiring a canonical cross-provider field.
status: Complete
log: 2026-08-04 — Implemented separate pre-spec intake, existing-ticket lifecycle update, and post-spec delivery projection branches. Added direct visible taxonomy, remotely verified spec authority, US/AC traceability, vertical tracer bullets, complete dependency/milestone/provider-representability preflight before any write, immediate mutation without approval, evidence-only learning closure, and provider-native claim/release/resolve updates. Three readonly review rounds drove provider ordering, fallback visibility, remote authority, and four-adapter body parity remediations.
files edited/created: tests/write-backlog-lifecycle.contract.test.mjs; skills/agnostic/requirements/write-backlog/{SKILL.md,REFERENCE.md,EXAMPLES.md,assets/concepts/backlog-model.md,assets/concepts/story-shape.md,assets/providers/*.md}; skills/agnostic/requirements/requirements-grill/SKILL.md
backlog_item_id: not_applicable
backlog_item_url: not_applicable
relation_mode: none
assigned_skills: [writing-for-agents, write-backlog, tdd, codebase-design]
tdd_status: required
tdd_target: First cycle only: delivery projection requires an authoritative agent-ready spec before any provider mutation.
red_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test --test-name-pattern="write-backlog requires agent-ready spec" tests/wayfinder-lifecycle.contract.test.mjs tests/write-backlog-provider-planning.contract.test.mjs
expected_red_failure: The first assertion shows that write-backlog still accepts grill-first, future-spec, or non-agent-ready input.
green_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test --test-name-pattern="write-backlog|taxonomy|readiness|tracer|blocker" tests/wayfinder-lifecycle.contract.test.mjs tests/write-backlog-provider-planning.contract.test.mjs
reason_not_testable:
red_evidence: Individual cycles failed on non-agent-ready input acceptance, canonical kind, missing graph/tracer/readiness gates, create-before-preflight provider ordering, implicit classification bootstrapping, missing intake validation, absent update-existing operations, delivery-authorizing learning closure, incomplete provider body traceability, missing visible fallback taxonomy, and backlog-first grill handoff.
green_evidence: node --test tests/*.test.mjs passed 40/40; all four providers preflight before mutation, support existing-ticket updates, preserve visible direct taxonomy, and carry immutable spec plus US/AC/demonstration/artifact fields; git diff --check and changed-Markdown link audit passed.
codebase_design_notes: write-backlog is the provider projection adapter. Keep capability semantics separate from provider representation and execution chronology.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: not_applicable

T6.1: Align Downstream Shared-Skill Consumers

depends_on: [T6]
location: /Users/stefan/Desktop/repos/wearedevpunks-skills/tests/wayfinder-lifecycle.contract.test.mjs, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/create-plan/references/backlog-sync.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase/phases/backlog.md, /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/docs/docs-onboarding/**
description: Work as ordered one-test vertical subcycles. First assert that create-plan's backlog reference consumes an already-created spec before provider projection; observe RED, make the minimum writing-for-agents pointer edit, and reach GREEN. Repeat the cycle separately for the design backlog handoff, docs onboarding, direct taxonomy, confirmed-grill-to-spec compilation, and post-spec backlog projection. Do not duplicate owning compiler/backlog contracts and do not accumulate several stale-consumer assertions before editing.
validation: Consumer contract assertions pass and no downstream shared skill reintroduces future-spec anchors, canonical kind/Kind, backlog-before-spec, or a create-spec interview.
status: Complete
log: 2026-08-04 — Aligned create-plan, design backlog/prototype composition, docs onboarding, requirements-grill, requirements phase, and delivery spec consumers with closed grill → remotely retained spec → backlog → concrete plan ordering. Nested design prototyping remains on the primitive; standalone prototype-phase remains Finder-owned.
files edited/created: skills/agnostic/planning/create-plan/references/backlog-sync.md; skills/phases/design-phase/phases/{backlog,prototype}.md; skills/agnostic/docs/docs-onboarding/**; skills/agnostic/requirements/requirements-grill/SKILL.md; lifecycle consumer assertions in tests/write-backlog-lifecycle.contract.test.mjs and tests/wayfinder-lifecycle.contract.test.mjs
backlog_item_id: not_applicable
backlog_item_url: not_applicable
relation_mode: none
assigned_skills: [writing-for-agents, create-plan, write-backlog, docs-onboarding, design-phase, tdd, codebase-design]
tdd_status: required
tdd_target: First cycle only: create-plan's backlog reference preserves spec-before-backlog ordering.
red_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test --test-name-pattern="create-plan spec before backlog" tests/wayfinder-lifecycle.contract.test.mjs
expected_red_failure: The first assertion identifies future-spec or backlog-first guidance in create-plan's backlog reference.
green_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test --test-name-pattern="downstream consumers" tests/wayfinder-lifecycle.contract.test.mjs
reason_not_testable:
red_evidence: Focused cycles failed on future-spec/backlog-first consumer wording, design implementation notes in provider bodies, direct design use of the standalone phase, closed grill routing directly to backlog, a broken canonical-model link, and local-only spec authority.
green_evidence: Combined canonical suite passed 40/40; two independent final canonical audits reported no remaining P1/P2 findings.
codebase_design_notes: Owning skills expose the lifecycle contract; consumers keep shallow pointers and local transition rules only.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: not_applicable

T7: Validate, Review, Commit, And Push Canonical Skills

depends_on: [T6.1]
location: /Users/stefan/Desktop/repos/wearedevpunks-skills
description: Run the complete source contract suite, inspect every changed skill and its relative references manually using writing-for-agents, remove duplicated or obsolete instructions, run diff checks, then commit and push the task branch. After remote equality is proven, write the immutable SHA to the task-owned /private/tmp/wayfinder-lifecycle-skills.sha evidence file so later tasks load the same value rather than recomputing a moving branch. Do not sync Harness from unpushed local source.
validation: All source tests and whitespace checks pass; manual skill/frontmatter/reference review is recorded; source worktree is clean after a conventional commit and successful push; local HEAD, upstream branch SHA, and git ls-remote SHA are identical to the SHA persisted in /private/tmp/wayfinder-lifecycle-skills.sha.
status: Complete
log: 2026-08-04 — Completed two-axis readonly review, structured-review remediation, and repeated bounded integration audits. The final canonical source is 9f1e1a057c50a7074f1bb6a9d9c15c358c0c5bff on pushed team/stefan/wayfinder-lifecycle; local HEAD, upstream, and git ls-remote match. Persisted the final SHA for downstream evidence.
files edited/created: canonical final commit 9f1e1a057c50a7074f1bb6a9d9c15c358c0c5bff; /private/tmp/wayfinder-lifecycle-skills.sha
backlog_item_id: not_applicable
backlog_item_url: not_applicable
relation_mode: none
assigned_skills: [writing-for-agents, review, simplify, codebase-design]
tdd_status: not_applicable
tdd_target: Aggregate source validation and immutable distribution provenance.
red_command:
expected_red_failure:
green_command: cd /Users/stefan/Desktop/repos/wearedevpunks-skills && node --test tests/*.test.mjs && git diff --check && test -z "$(git status --porcelain)" && WAYFINDER_SKILLS_SHA=$(git rev-parse HEAD) && test "$WAYFINDER_SKILLS_SHA" = "$(git rev-parse '@{upstream}')" && test "$WAYFINDER_SKILLS_SHA" = "$(git ls-remote --heads origin "$(git branch --show-current)" | awk '{print $1}')" && printf '%s\n' "$WAYFINDER_SKILLS_SHA" > /private/tmp/wayfinder-lifecycle-skills.sha && test "$(tr -d '\n' < /private/tmp/wayfinder-lifecycle-skills.sha)" = "$WAYFINDER_SKILLS_SHA"
reason_not_testable: Aggregates prior RED/GREEN tasks and records git provenance.
red_evidence:
green_evidence: Full source suite passed 40/40 independently in parent and reviewer runs; Markdown link audit and git diff --check passed; source worktree clean after push; local/upstream/remote SHA matched exactly.
codebase_design_notes: Review for invocation clarity, earned disclosure, single source of truth, and removal of contradictory sediment.
review_mode: cli
runtime_validation: required
runtime_target: Git remote for wearedevpunks/skills task branch.
runtime_evidence: Successful push plus identical local, upstream, remote, and evidence-file immutable commit SHA stored in the task log.
runtime_cleanup: Retain the task branch/commit and /private/tmp/wayfinder-lifecycle-skills.sha through T11; remove the evidence file only after final evidence is copied into this plan.

T8: Pin And Sync The Canonical Skills Commit

depends_on: [T7]
location: $WAYFINDER_HARNESS_ROOT/apps/cli/src/scripts/sync-skills-repo.test.ts, $WAYFINDER_HARNESS_ROOT/apps/cli/scripts/sync-skills-repo.mjs, $WAYFINDER_HARNESS_ROOT/apps/cli/.devpunks-cache/skills-sync.json, $WAYFINDER_HARNESS_ROOT/apps/cli/skills/**
description: Load the immutable T7 SHA from /private/tmp/wayfinder-lifecycle-skills.sha. Add one assertion that the sync default commit equals that SHA and capture RED against the unrelated pin. Make the minimum script edit and reach GREEN before adding any further sync assertion. Then run bun run sync:skills, assert the receipt equals the loaded SHA, and byte-compare the entire canonical skills tree with apps/cli/skills. Do not update active agent mirrors here.
validation: Sync-script test passes; default sync fetches the intended pushed commit; receipt SHA matches; the complete source-to-CLI skills trees compare cleanly.
status: Complete
log: 2026-08-04 — Captured RED against team/stefan/security-pack@844890d, updated the default source to the reviewed Wayfinder branch/SHA, synced through bun run sync:skills, and verified the receipt. Compared all 645 tracked canonical files at the immutable commit with all 645 CLI files byte-for-byte; no extra CLI files exist. Literal directory diff reports only three untracked empty canonical directories, so tracked-file parity is the authoritative check.
files edited/created: 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/**
backlog_item_id: not_applicable
backlog_item_url: not_applicable
relation_mode: none
assigned_skills: [autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo]
tdd_status: required
tdd_target: Default skills sync selects the exact canonical branch/SHA produced by T7.
red_command: WAYFINDER_HARNESS_ROOT=/Users/stefan/.codex/worktrees/wayfinder-lifecycle/harness-intelligence && cd "$WAYFINDER_HARNESS_ROOT" && bun run --cwd apps/cli test src/scripts/sync-skills-repo.test.ts
expected_red_failure: Default-ref/default-commit assertion still reports team/stefan/security-pack@844890d instead of T7's recorded branch/SHA.
green_command: WAYFINDER_SKILLS_ROOT=/Users/stefan/Desktop/repos/wearedevpunks-skills WAYFINDER_HARNESS_ROOT=/Users/stefan/.codex/worktrees/wayfinder-lifecycle/harness-intelligence WAYFINDER_SKILLS_SHA=$(tr -d '\n' < /private/tmp/wayfinder-lifecycle-skills.sha) && test -n "$WAYFINDER_SKILLS_SHA" && cd "$WAYFINDER_HARNESS_ROOT" && bun run --cwd apps/cli test src/scripts/sync-skills-repo.test.ts && bun run sync:skills && WAYFINDER_RECEIPT_SHA=$(node -e "const r=require('./apps/cli/.devpunks-cache/skills-sync.json'); process.stdout.write(r.commit)") && test "$WAYFINDER_RECEIPT_SHA" = "$WAYFINDER_SKILLS_SHA" && diff -qr "$WAYFINDER_SKILLS_ROOT/skills" apps/cli/skills
reason_not_testable:
red_evidence: Initial sync expected the Wayfinder branch but received the old team/stefan/security-pack@844890d… default; every review-triggered source commit then produced a focused RED against the previous immutable SHA before resync.
green_evidence: Final sync suite passed 9/9; receipt equals 9f1e1a057c50a7074f1bb6a9d9c15c358c0c5bff; 645/645 tracked files are byte-identical with no extra CLI files.
codebase_design_notes: Sync is the canonical-source-to-CLI adapter; its pinned ref and receipt are part of the public provenance contract.
review_mode: cli
runtime_validation: required
runtime_target: GitHub canonical skills ref consumed by Harness sync.
runtime_evidence: Passing sync test, fetched commit output, matching receipt SHA, and affected source-to-CLI byte parity.
runtime_cleanup: Preserve the sync cache/receipt as provenance; remove only task-owned temporary comparison output.

T9: Register The New Phase And Generated Routing

depends_on: [T8]
location: $WAYFINDER_HARNESS_ROOT/apps/cli/src/content/content.test.ts, $WAYFINDER_HARNESS_ROOT/apps/cli/src/data/catalog/skills.ts, $WAYFINDER_HARNESS_ROOT/apps/cli/src/data/catalog/packs.ts, $WAYFINDER_HARNESS_ROOT/apps/cli/src/content/scaffold-copy.ts, $WAYFINDER_HARNESS_ROOT/apps/cli/src/content/prompts.ts
description: Work as ordered one-test vertical subcycles. First assert prototype-phase catalog registration, capture RED, register only that seam, and reach GREEN. Repeat one assertion -> RED -> minimum owning edit -> GREEN separately for pack membership, global-phase exclusion, synced-path presence, Finder implicit-invocation metadata, root routing, and spec-before-backlog ordering. Do not edit synced skill bytes and do not accumulate several failing content assertions.
validation: Focused content tests and CLI checks pass; catalog/rendered guidance retains Finder's implicit-invocation contract and the accepted lifecycle.
status: Complete
log: 2026-08-04 — Added prototype-phase catalog registration, planning-pack membership with Finder/Wayfinder, global phase exclusion, implicit-invocation assertions, root Finder child routing, and spec-before-backlog generated guidance. Kept the prototype primitive in research while the standalone phase belongs to planning.
files edited/created: apps/cli/src/data/catalog/{skills,packs}.ts; apps/cli/src/content/{content.test,prompts,scaffold-copy}.ts
backlog_item_id: not_applicable
backlog_item_url: not_applicable
relation_mode: none
assigned_skills: [autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo]
tdd_status: required
tdd_target: First cycle only: the catalog registers prototype-phase.
red_command: WAYFINDER_HARNESS_ROOT=/Users/stefan/.codex/worktrees/wayfinder-lifecycle/harness-intelligence && cd "$WAYFINDER_HARNESS_ROOT" && bun run --cwd apps/cli test src/content/content.test.ts --test-name-pattern="prototype-phase catalog"
expected_red_failure: The first assertion reports that prototype-phase is absent from the catalog.
green_command: WAYFINDER_HARNESS_ROOT=/Users/stefan/.codex/worktrees/wayfinder-lifecycle/harness-intelligence && cd "$WAYFINDER_HARNESS_ROOT" && bun run --cwd apps/cli test src/content/content.test.ts && bun run --cwd apps/cli check
reason_not_testable:
red_evidence: Separate content cycles failed on absent catalog entry, missing planning membership, missing phase exclusion, stale Finder child route, old lifecycle order, and missing scoped generated guidance.
green_evidence: Focused aggregate passed 86/86 across sync, content, context, and projection tests; Finder implicit metadata and synced path assertions passed.
codebase_design_notes: Catalog and rendered prompt helpers are the public discovery/routing seam; synced skill bytes remain separately owned by T8.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: not_applicable

T9.1: Validate Bundled And Projected Consumer Surfaces

depends_on: [T9]
location: $WAYFINDER_HARNESS_ROOT/apps/cli/dist/baseline/**, $WAYFINDER_HARNESS_ROOT/apps/cli/src/features/context-planning/public-context-contract.test.ts, $WAYFINDER_HARNESS_ROOT/apps/cli/src/data/scripts/harness-projection/contract.test.ts, $WAYFINDER_HARNESS_ROOT/apps/cli/test-fixtures/public-output/managed-assets.json only if the focused tests prove it stale
description: Build the local baseline from the updated catalog and synced skills, then run the context-planning and portable projection contracts. If a committed managed fixture fails because the public generated inventory legitimately changed, update only that fixture from the owning generator/test workflow and rerun. Validate projections in the tests' run-owned temporary roots; do not apply a local unpublished baseline to this repository's active .agents mirrors.
validation: Baseline build contains prototype-phase and all affected skill trees; context/projection tests pass; any fixture change is generated, scoped, and reviewed; active mirrors match the bundled skill trees required by this lifecycle.
status: Complete
log: 2026-08-04 — Built the local baseline, verified prototype-phase, regenerated the managed-assets fixture only through the owning temp-root scaffold contract, and validated context/projection consumers. 2026-08-05 — Synced the active create-spec, finder-phase, prototype-phase, and writing-for-agents projections to the bundled contracts so repo-local agents follow the same lifecycle.
files edited/created: local apps/cli/dist/baseline/**; apps/cli/test-fixtures/public-output/managed-assets.json
backlog_item_id: not_applicable
backlog_item_url: not_applicable
relation_mode: none
assigned_skills: [autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo]
tdd_status: not_applicable
tdd_target: Generated baseline and projection consumers retain the catalogued lifecycle without mutating active mirrors.
red_command:
expected_red_failure:
green_command: WAYFINDER_HARNESS_ROOT=/Users/stefan/.codex/worktrees/wayfinder-lifecycle/harness-intelligence && cd "$WAYFINDER_HARNESS_ROOT" && bun run --cwd apps/cli baseline:build && test -f apps/cli/dist/baseline/scaffold-baseline/skills/phases/prototype-phase/SKILL.md && bun run --cwd apps/cli test src/features/context-planning/public-context-contract.test.ts src/data/scripts/harness-projection/contract.test.ts
reason_not_testable: Generated/bundled validation aggregates the T8-T9 behavior changes; generated fixture updates are bookkeeping-only.
red_evidence:
green_evidence: Context/projection subset passed 50/50; baseline contains prototype-phase; TypeScript, targeted Oxlint/Oxfmt, and git diff --check -- apps/cli passed. Active .agents mirrors remained untouched. Broad CLI check has one unrelated pre-existing vitest(max-expects) failure at src/scripts/publish-release.test.ts:226 (6 assertions, maximum 5).
codebase_design_notes: Local baseline build and temp-root projection tests validate consumer adapters without pretending an unpublished baseline has updated the live checkout.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: Tests own and remove temporary roots; dist/baseline is disposable local build output.

T10: Align Root Workflow Documentation

depends_on: [T9.1]
location: $WAYFINDER_HARNESS_ROOT/docs/README.md, $WAYFINDER_HARNESS_ROOT/docs/runbooks/hi-cli-scaffolding.md, $WAYFINDER_HARNESS_ROOT/docs/reference/hi-requirements.md, $WAYFINDER_HARNESS_ROOT/docs/reference/dp-requirements.md
description: Update the four fixed root docs surfaces to explain canonical source-first editing, Finder's resumable lifecycle, prototype/research evidence, confirmed-grill-to-spec compilation, spec-first backlog projection, and validation/sync provenance. Preserve historical narrative where explicitly labeled, but remove current guidance that presents canonical kind, backlog-before-spec, mandatory post-prototype grilling, or create-spec interviewing as active behavior.
validation: All four docs contain the new lifecycle and pass explicit negative checks for superseded current guidance plus formatting/whitespace checks.
status: Complete
log: 2026-08-04 — Updated root workflow, requirements, Harness reference, and scaffolding runbook docs with source-first immutable provenance and the implemented lifecycle.
files edited/created: docs/README.md; docs/runbooks/hi-cli-scaffolding.md; docs/reference/{dp-requirements,hi-requirements,harness-intelligence}.md
backlog_item_id: not_applicable
backlog_item_url: not_applicable
relation_mode: none
assigned_skills: [autoreview, codebase-design, docs-onboarding, improve-codebase-architecture, parallel-research, simplify, tdd, writing-beats, writing-fragments, writing-for-agents, writing-shape]
tdd_status: not_applicable
tdd_target: Human-facing workflow and scaffold documentation matches implemented skill behavior.
red_command:
expected_red_failure:
green_command: WAYFINDER_HARNESS_ROOT=/Users/stefan/.codex/worktrees/wayfinder-lifecycle/harness-intelligence && cd "$WAYFINDER_HARNESS_ROOT" && rg -n "finder-phase|prototype-phase|research report|create-spec|spec-written|write-backlog|sync:skills" docs/README.md docs/runbooks/hi-cli-scaffolding.md docs/reference/hi-requirements.md docs/reference/dp-requirements.md && ! rg -n "requirements-grill -> write-backlog|future .*SPEC\.md anchor|canonical .*kind|cross-provider .*Kind|create-spec.*interview" docs/README.md docs/runbooks/hi-cli-scaffolding.md docs/reference/hi-requirements.md docs/reference/dp-requirements.md && git diff --check
reason_not_testable: Documentation and route bookkeeping are validated through content, navigation, and formatting checks.
red_evidence:
green_evidence: Positive/negative lifecycle gates, wiki formatting, content projection, temporary-path scan, and git diff --check passed.
codebase_design_notes: Keep execution contracts in skills and durable operator explanation in docs; do not duplicate full skill bodies in prose.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: not_applicable

T10.1: Align Routed Harness Skill And Entrypoint Docs

depends_on: [T10]
location: $WAYFINDER_HARNESS_ROOT/apps/wiki/content/docs/harness/skills-and-packs/skill-reference.mdx, $WAYFINDER_HARNESS_ROOT/apps/wiki/content/docs/harness/skills-and-packs/phase-wrappers.mdx, $WAYFINDER_HARNESS_ROOT/apps/wiki/content/docs/harness/skills-and-packs/atomic-skills.mdx, $WAYFINDER_HARNESS_ROOT/apps/wiki/content/docs/harness/skills-and-packs/skill-model.mdx, $WAYFINDER_HARNESS_ROOT/apps/wiki/content/docs/harness/skills-and-packs/skill-packs.mdx, $WAYFINDER_HARNESS_ROOT/apps/wiki/content/docs/harness/entrypoints/finder-phase.mdx, $WAYFINDER_HARNESS_ROOT/apps/wiki/content/docs/harness/entrypoints/brainstorming-requirements-backlog.mdx, $WAYFINDER_HARNESS_ROOT/apps/wiki/content/docs/harness/entrypoints/docs-update.mdx, $WAYFINDER_HARNESS_ROOT/apps/wiki/content/docs/harness/entrypoints/design.mdx, $WAYFINDER_HARNESS_ROOT/apps/wiki/content/docs/project/public-docs/finder-phase/fragments.md, $WAYFINDER_HARNESS_ROOT/apps/wiki/content/docs/project/public-docs/finder-phase/beats.md, $WAYFINDER_HARNESS_ROOT/apps/wiki/content/docs/project/public-docs/finder-phase/shape.md
description: Run the private/internal then public routing needed by docs-ingest-phase over these explicit stale Harness skill/entrypoint and Finder writer surfaces. Update only pages whose current behavior contradicts the implemented lifecycle. Preserve route frontmatter, meta.json, and log conventions if routing changes; do not rewrite the historical v1 implementation plan.
validation: Current routed docs explain the primitive/phase boundary, conditional prototype-to-grill route, durable research evidence, no-interview spec compiler, and post-spec backlog projection; explicit negative checks reject superseded current guidance; wiki content routing and formatting checks pass.
status: Complete
log: 2026-08-04 — Applied private/internal and public docs-ingest routing across skill reference, phase wrapper, entrypoint, implementation/AFK/Goal Mode, design, and Finder writer surfaces; refreshed normal project projections and preserved the historical v1 implementation plan.
files edited/created: routed apps/wiki/content/docs/harness/** lifecycle pages; apps/wiki/content/docs/project/public-docs/finder-phase/{fragments,beats,shape}.md; projected project reference/runbook pages
backlog_item_id: not_applicable
backlog_item_url: not_applicable
relation_mode: none
assigned_skills: [create-spec, create-plan, implement-spec, simplify, docs-ingest-phase, writing-for-agents]
tdd_status: not_applicable
tdd_target: Routed skill and entrypoint knowledge matches the implemented lifecycle and remains navigable.
red_command:
expected_red_failure:
green_command: WAYFINDER_HARNESS_ROOT=/Users/stefan/.codex/worktrees/wayfinder-lifecycle/harness-intelligence && cd "$WAYFINDER_HARNESS_ROOT" && rg -n "finder-phase|prototype-phase|research report|spec-written|write-backlog" apps/wiki/content/docs/harness/skills-and-packs/{skill-reference,phase-wrappers,atomic-skills,skill-model,skill-packs}.mdx apps/wiki/content/docs/harness/entrypoints/{finder-phase,brainstorming-requirements-backlog,docs-update,design}.mdx apps/wiki/content/docs/project/public-docs/finder-phase/{fragments,beats,shape}.md && ! rg -n "requirements-grill -> write-backlog|future .*SPEC\.md anchor|canonical .*kind|cross-provider .*Kind|prototype.*must.*grill|create-spec.*interview" apps/wiki/content/docs/harness/skills-and-packs/{skill-reference,phase-wrappers,atomic-skills,skill-model,skill-packs}.mdx apps/wiki/content/docs/harness/entrypoints/{finder-phase,brainstorming-requirements-backlog,docs-update,design}.mdx apps/wiki/content/docs/project/public-docs/finder-phase/{fragments,beats,shape}.md && bun run --cwd apps/wiki check:content && bun run --cwd apps/wiki check && git diff --check
reason_not_testable: Routed documentation is validated through explicit content invariants, navigation/content projection, and formatter/linter checks.
red_evidence:
green_evidence: bun run --cwd apps/wiki check:content, bun run --cwd apps/wiki check, exact positive/negative gates, temporary provenance scan, and git diff --check passed.
codebase_design_notes: Human-facing docs explain interfaces and flow; owning skills retain executable instruction detail.
review_mode: cli
runtime_validation: not_required
runtime_target: not_applicable
runtime_evidence: not_applicable
runtime_cleanup: not_applicable

T11: Final Cross-Repository Validation And Review

depends_on: [T10.1]
location: /Users/stefan/Desktop/repos/wearedevpunks-skills, /Users/stefan/.codex/worktrees/wayfinder-lifecycle/harness-intelligence
description: Run the full focused validation matrix, inspect source and generated diffs, verify no stale contradictory wording or broken reference links, and request readonly plan/code review for dependency, invocation, disclosure, testing, sync, and docs gaps. Apply only actionable in-scope fixes, rerun affected checks, and record evidence in this plan before marking tasks complete. Stop without baseline or package release.
validation: Source contracts, provider contracts, sync and content tests, baseline/projection tests, CLI/wiki checks, whitespace/content assertions, remote/receipt provenance, source-to-CLI comparisons, and reviewer findings are all green or explicitly blocked with evidence.
status: Complete
log: 2026-08-04 — Ran parallel Spec and Standards reviews plus structured autoreview until all accepted findings were fixed. Final Spec and Standards axes are clean. The final structured autoreview retry was unavailable because its Codex engine hit the account usage limit; all findings from earlier successful structured runs were remediated and independently re-reviewed. Completed private/internal and public docs ingest, exact source/receipt parity, focused validation, and closeout evidence without baseline/package release or active-mirror mutation. Committed and pushed the clean Harness integration as 4f89074315a7c04e418d5bfb08c7b51e25862941 on team/stefan/wayfinder-lifecycle; local HEAD, upstream, and remote match.
files edited/created: final review evidence in this plan and IMPLEMENTATION-NOTES.md; canonical SHA 9f1e1a057c50a7074f1bb6a9d9c15c358c0c5bff; Harness commit 4f89074315a7c04e418d5bfb08c7b51e25862941; Harness sync receipt and generated fixture
backlog_item_id: not_applicable
backlog_item_url: not_applicable
relation_mode: none
assigned_skills: [review-phase, review, autoreview, simplify, codebase-design, improve-codebase-architecture, writing-for-agents]
tdd_status: not_applicable
tdd_target: Aggregate proof that canonical source, Harness distribution, and durable docs encode one non-contradictory lifecycle.
red_command:
expected_red_failure:
green_command: WAYFINDER_SKILLS_ROOT=/Users/stefan/Desktop/repos/wearedevpunks-skills WAYFINDER_HARNESS_ROOT=/Users/stefan/.codex/worktrees/wayfinder-lifecycle/harness-intelligence WAYFINDER_SKILLS_SHA=9f1e1a057c50a7074f1bb6a9d9c15c358c0c5bff && cd "$WAYFINDER_SKILLS_ROOT" && node --test tests/*.test.mjs && test "$WAYFINDER_SKILLS_SHA" = "$(git rev-parse HEAD)" && test "$WAYFINDER_SKILLS_SHA" = "$(git ls-remote --heads origin team/stefan/wayfinder-lifecycle | awk '{print $1}')" && cd "$WAYFINDER_HARNESS_ROOT" && bun run --cwd apps/cli test src/content/content.test.ts src/scripts/sync-skills-repo.test.ts src/features/context-planning/public-context-contract.test.ts src/data/scripts/harness-projection/contract.test.ts && bun run --cwd apps/cli check-types && bun run --cwd apps/wiki check:content && bun run --cwd apps/wiki check && test "$WAYFINDER_SKILLS_SHA" = "$(node -e "const r=require('./apps/cli/.devpunks-cache/skills-sync.json'); process.stdout.write(r.commit)")" && git diff --check
reason_not_testable: Final gate aggregates task-level RED/GREEN and static/distribution validation.
red_evidence: Review rounds found and reproduced cross-skill orchestration gaps including provider preflight, immutable retention, execution-mode routing, dependency/base serialization, post-spec projection, Finder durable research, and conditional plan backlog sync. Each accepted finding received a focused RED before source remediation.
green_evidence: Canonical suite passed 54/54; final Harness focused aggregate passed 87/87; CLI types, wiki content/lint/format, and git diff --check passed; receipt matches remote source; 645 tracked canonical files equal 645 CLI files; final Spec and Standards reviews reported no P1/P2.
codebase_design_notes: Review source-of-truth separation, lean interfaces, earned references, adapter boundaries, and absence of obsolete sediment.
review_mode: cli
runtime_validation: required
runtime_target: Pushed canonical skills commit consumed by the clean Harness worktree.
runtime_evidence: Remote source SHA, matching local sync receipt, affected canonical-to-CLI equality, focused test output, local baseline/projection proof, and clean targeted diffs.
runtime_cleanup: Remove disposable validation worktrees only after evidence is recorded and no uncommitted owned changes remain; remove /private/tmp/wayfinder-lifecycle-skills.sha after its value is copied into the completed plan log.

Parallel Execution Waves

Implementation mode is deliberately sequential because all tasks converge on one shared instruction contract and one broad sync operation.

Wave	Tasks	Can start when	Execution rule
0	T0	Immediately	Parent validates clean worktrees and one-worker coverage.
1	T1	T0 complete	Record the unchanged passing source baseline; add no future RED batch.
2	T2	T1 complete	Prototype RED -> implementation -> GREEN.
3	T3	T2 complete	Finder/invocation RED -> implementation -> GREEN.
4	T4	T3 complete	Durable research/docs-ingest RED -> implementation -> GREEN.
5	T5	T4 complete	Spec compiler/requirements RED -> implementation -> GREEN.
6	T6	T5 complete	Backlog projection/readiness RED -> implementation -> GREEN.
7	T6.1	T6 complete	Downstream consumer RED -> alignment -> GREEN.
8	T7	T6.1 complete	Validate and push canonical source; record immutable SHA.
9	T8	T7 complete	Sync-pin RED -> update -> GREEN, then consume the exact source SHA.
10	T9	T8 complete	Catalog/prompt RED -> implementation -> GREEN.
11	T9.1	T9 complete	Build and validate bundled/temp-root projected consumers.
12	T10	T9.1 complete	Update fixed root docs surfaces.
13	T10.1	T10 complete	Ingest/update fixed routed wiki and writer surfaces.
14	T11	T10.1 complete	Cross-repository review and closeout.

Validation Gates

Gate A: Safe source authority

Clean dedicated Harness execution worktree.
Clean canonical skills worktree and explicit task branch.
No generated mirror edited manually.
One implementation worker available.

Gate B: Canonical behavior

Each source slice captures its own behavior RED immediately before editing its owner and reaches GREEN before the next slice.
Prototype, Finder, research, spec, requirements, backlog, and downstream-consumer subcontracts turn GREEN incrementally.
Full node --test tests/*.test.mjs passes.
writing-for-agents review finds no duplicated behavior, weak trigger, premature step disclosure, or obsolete reference sediment.

Gate C: Immutable distribution

Canonical source committed and pushed.
Harness sync consumes that exact commit.
Sync receipt and a complete canonical skills-tree-to-CLI comparison prove provenance.
Local baseline build and run-owned projection tests prove generated consumer behavior without modifying active mirrors from an unpublished baseline.
Focused CLI content tests and checks pass.

Gate D: Durable knowledge

Root docs and CLI scaffolding runbook match proven behavior.
Routed docs/writer artifacts are updated only when selected by docs-ingest-phase.
Historical v1 plan remains intact.

Gate E: Closeout

Readonly reviewer reports no missing dependency, unsafe overlap, missing RED target, broken reference, or invocation contradiction.
Both repos pass targeted git diff --check.
No baseline, npm release, provider backlog mutation, legacy migration, or prototype production promotion occurred.

Risks And Mitigations

Broad sync overwrites unrelated work. Use a clean dedicated Harness worktree and compare the complete sync diff before accepting it.
Wrong sync source regresses current skills. Resolve the canonical source base and replace the unrelated default sync pin before any sync; prove the receipt equals T7's pushed SHA.
Old v1 decisions leak into v2. Contract tests must reject canonical kind, backlog-before-spec, mandatory post-prototype grilling, create-spec questioning/backlog sync, and approval-gated backlog writes.
Skill files become large and repetitive. Apply writing-for-agents to every skill edit; keep ordered steps in SKILL.md, universal rules inline, and branch-specific contracts in earned references/templates.
Parallel research contradicts its readonly rule. Keep lanes readonly and allow exactly one post-synthesis coordinator/consolidator report write only in durable mode.
Prototype evidence is mistaken for production code. Preserve the throwaway branch as primary evidence; only accepted verdict implications enter the spec.
Wayfinder impersonates the human. Prototype and grilling remain HITL. Research may close facts but never silently chooses product direction.
Provider representation recreates Kind as domain vocabulary. Permit physical adapter fields when unavoidable, but keep six direct semantic values and exactly-one validation as the cross-provider contract.
Spec and plan boundaries blur. Spec owns accepted requirements/technical decisions/testing decisions/verification seams; plan owns files, commands, task graph, tests, workers, and execution order.
Existing backlog-first items expand scope. Migration is parked; do not touch legacy items.
Reviewer specialist remains unavailable. Record the failed specialist activation and use a readonly generic reviewer with the exact plan-review checklist; do not claim specialist coverage.

Unresolved Questions

None. Implementation-time provider/API verification and exact generated-diff review are validation work, not open design branches.

Planning Method Record

grilling: satisfied by the confirmed R1-R6 artifacts; no new planning ambiguity remained.
parallel-research: used across Wayfinder/prototype, research merging, ticketing/readiness, and current file-surface discovery.
swarm-planner: used to create the explicit sequential T0-T11 graph with intermediate T6.1, T9.1, and T10.1 slices, gates, and worker-sized tasks.
tdd: used to define the source contract RED suite and Harness distribution RED/GREEN seams before behavior edits.
codebase-design: used to keep primitive, phase, compiler, provider adapter, docs projection, and distribution boundaries deep and non-duplicative.
writing-for-agents: mandatory planning and execution input for every skill-editing task.
Backlog sync: intentionally skipped by explicit user instruction.
Spec creation: intentionally skipped by explicit user instruction.

Wayfinder Lifecycle Upgrade Plan