Plan: App-Surfaced Wiki Root Selection

Initial Situation

Issue #44 reports a third scaffold shape: a repository that is not a true workspace monorepo, but still organizes application surfaces under app/. dp scaffold init currently chooses between apps/wiki for monorepo-shaped targets and wiki for single-repo targets, so it seeded root wiki/ where the project-canonical wiki app later became app/wiki.

Current code evidence:

• apps/cli/src/scaffold/stage.ts owns init-stage wiki root selection through stageWikiTarget().
• apps/cli/src/scaffold/stage.test.ts covers standalone wiki, monorepo apps/wiki, and output already inside apps/wiki.
• apps/cli/src/update/run.ts owns update-time wiki alignment and calls the stage scaffold wiki helpers when staging expected wiki content.
• apps/cli/src/update/run.test.ts covers standalone wiki preservation and existing apps/wiki alignment.
• No dirty pre-existing changes touch the main issue #44 code paths: stage.ts, stage.test.ts, run.ts, or run.test.ts.

Decision Ledger

• Locked: source issue is GitHub issue #44.
• Locked: routed planning surface is apps/wiki/content/docs/project/specs/cli/issue-44-app-surfaced-wiki-root.
• Locked: preserve existing wiki and apps/wiki behavior.
• Locked: deterministically recognize app/wiki when the app-surfaced wiki boundary is observable.
• Locked: preserve an existing selected app/wiki root during update checks.
• Locked: implementation mode is sequential because init and update share stage wiki helpers; parallel implementation would risk write overlap.
• Assumption: no external package docs are required; behavior is repo-local filesystem/path logic.
• Deferred: future explicit user-selected wiki roots for ambiguous layouts are out of scope for issue #44.

Dependencies And Mode

• Backlog item: GitHub issue #44, https://github.com/wearedevpunks/harness-intelligence/issues/44.
• Backlog sync: no provider mutation needed. The issue already exists and this plan links to it.
• Execution mode: parallel: false for implementation. Parallel readonly discovery and plan/spec review already ran; final tests and autoreview may run in parallel only against a frozen diff.
• Worker mode: exactly one implementation worker for T1, then parent validation/review. This follows the repo rule for overlapping implementation scopes.

Task Graph

T1 -> T2 -> T3

Tasks

T1: Implement App-Surfaced Wiki Root Behavior

• depends_on: []
• location: apps/cli/src/scaffold/stage.test.ts, apps/cli/src/scaffold/stage.ts, apps/cli/src/update/run.test.ts, apps/cli/src/update/run.ts
• description: Test-drive the CLI behavior so init selects app/wiki for observable app-surfaced single repos and update preserves an existing selected app/wiki root without proposing competing wiki or apps/wiki trees.
• validation: RED/GREEN evidence proves both init and update behavior while existing wiki and apps/wiki tests still pass.
• status: Completed
• log:
• 2026-06-23: Added RED tests for init app/wiki selection and update app/wiki preservation.
• 2026-06-23: Implemented local wiki-root precedence for observable app/wiki without changing repo-shape detection.
• 2026-06-23: Plan bun test commands are blocked by a pre-existing Bun/@effect-vitest runner issue; package Vitest runner provides behavior evidence.
• 2026-06-23: Follow-up RED corrected init coverage to app-surfaced packages under app/ with no pre-existing app/wiki; minimal detection now seeds app/wiki for that shape without treating workspace-shaped repos as app-surfaced single repos.
• files edited/created:
• apps/cli/src/scaffold/stage.test.ts
• apps/cli/src/scaffold/stage.ts
• apps/cli/src/update/run.test.ts
• apps/cli/src/update/run.ts
• backlog_item_id: issue-44
• backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/44
• relation_mode: body-links
• assigned_skills: effect-authoring, effect-best-practices, effect-backend-structure, effect-recoverable-actions, tdd, codebase-design, simplify, turborepo
• tdd_status: required
• tdd_target: runStageScaffold chooses and prompts for app/wiki, including canonical specs/raw/routed docs/ingest bookkeeping guidance; runUpdate preserves an existing selected app/wiki root.
• red_command: bun test apps/cli/src/scaffold/stage.test.ts -t "seeds app/wiki" && bun test apps/cli/src/update/run.test.ts -t "preserves existing app/wiki"
• expected_red_failure: New init assertions expect app/wiki/AGENTS.md plus prompt text treating app/wiki as the dedicated wiki root for specs, raw inputs, routed project docs, and ingest bookkeeping; new update assertions expect no competing wiki/package.json or apps/wiki/package.json changes. Current code writes or aligns the wrong root.
• green_command: bun test apps/cli/src/scaffold/stage.test.ts && bun test apps/cli/src/update/run.test.ts
• reason_not_testable:
• red_evidence: bun test apps/cli/src/scaffold/stage.test.ts -t "seeds app/wiki" && bun test apps/cli/src/update/run.test.ts -t "preserves existing app/wiki" failed before assertions with TypeError: ctx?.onTestFinished is not a function from @effect/vitest; follow-up behavior RED with bun run --cwd apps/cli test src/scaffold/stage.test.ts -t "seeds app/wiki" failed because a root package plus app/frontend/package.json and app/backend/package.json, with no existing app/wiki, still produced apps/wiki/* instead of app/wiki/*; earlier update RED with bun run --cwd apps/cli test src/update/run.test.ts -t "preserves existing app/wiki" failed before the fix because app/wiki/package.json was absent.
• green_evidence: Plan bun test apps/cli/src/scaffold/stage.test.ts && bun test apps/cli/src/update/run.test.ts remains blocked by the same ctx?.onTestFinished runner issue; package Vitest GREEN with bun run --cwd apps/cli test src/scaffold/stage.test.ts && bun run --cwd apps/cli test src/update/run.test.ts passed 14/14 scaffold tests and 20/20 update tests after review fixes.
• codebase_design_notes: Keep the wiki-root seam small and local. Prefer readable path precedence and filesystem evidence over broad repo-shape reclassification. Add shared helper extraction only if it reduces real duplication across init and update.
• review_mode: cli

T2: Ingest And Document App-Surfaced Wiki Roots

• depends_on: [T1]
• location: docs/README.md, docs/runbooks/dp-cli-scaffolding.md, docs/reference/dp-requirements.md, apps/wiki/content/docs/project/runbooks/dp-cli-scaffolding.md, apps/wiki/content/docs/project/reference/dp-requirements.md, apps/wiki/content/docs/project/specs/cli/issue-44-app-surfaced-wiki-root/PLAN.md
• description: Use docs-ingest expectations before wiki edits, then update operator docs and routed project mirrors so app-surfaced single repos are documented and durable docs are not authored into stale root wiki/.
• validation: Docs mention app/wiki in the root operator surfaces and routed wiki mirrors while preserving apps/wiki and wiki guidance.
• status: Completed
• log:
• 2026-06-23: Routed docs-ingest as private/internal because this changed root operator docs and routed project docs.
• 2026-06-23: Updated root docs and routed wiki mirrors to describe app/wiki for app-surfaced single repos and update preservation.
• 2026-06-23: Wiki build is blocked by unrelated pre-existing dirty cli-tool-validation frontmatter, not issue #44 docs.
• files edited/created:
• docs/README.md
• docs/runbooks/dp-cli-scaffolding.md
• docs/reference/dp-requirements.md
• apps/wiki/content/docs/project/runbooks/dp-cli-scaffolding.md
• apps/wiki/content/docs/project/reference/dp-requirements.md
• backlog_item_id: issue-44
• backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/44
• relation_mode: body-links
• assigned_skills: docs-ingest-phase, parallel-research, simplify, turborepo
• tdd_status: not_applicable
• tdd_target: Documentation reflects the implemented scaffold contract.
• red_command:
• expected_red_failure:
• green_command: rg -n "app/wiki|app-surfaced|app surfaces" docs/README.md docs/runbooks/dp-cli-scaffolding.md docs/reference/dp-requirements.md apps/wiki/content/docs/project/runbooks/dp-cli-scaffolding.md apps/wiki/content/docs/project/reference/dp-requirements.md && bun run check-types --filter=@punks/wiki && bun run build --filter=@punks/wiki
• reason_not_testable: Docs-only change; validated by content assertions and wiki/package checks.
• red_evidence:
• green_evidence: rg -n "app/wiki|app-surfaced|app surfaces" docs/README.md docs/runbooks/dp-cli-scaffolding.md docs/reference/dp-requirements.md apps/wiki/content/docs/project/runbooks/dp-cli-scaffolding.md apps/wiki/content/docs/project/reference/dp-requirements.md found expected coverage in all target surfaces; bun run check-types --filter=@punks/wiki passed. bun run build --filter=@punks/wiki failed on unrelated pre-existing apps/wiki/content/docs/project/specs/cli/cli-tool-validation/IMPLEMENTATION-NOTES.md invalid frontmatter: title: Invalid input: expected string, received undefined.
• codebase_design_notes: not_applicable
• review_mode: cli

T3: Final Validation, Review, And Issue Closeout

• depends_on: [T2]
• location: apps/wiki/content/docs/project/specs/cli/issue-44-app-surfaced-wiki-root/IMPLEMENTATION-NOTES.md, GitHub issue #44
• description: Record implementation evidence, run focused and scaffold validation, run mandatory review, patch accepted findings, then update GitHub issue #44 with the concise outcome.
• validation: Focused tests pass, docs assertions pass, scaffold update check is recorded, autoreview exits clean or accepted findings are resolved, and GitHub issue #44 has a final maintainer comment or closure action.
• status: Completed
• log:
• 2026-06-23: Re-ran focused CLI Vitest suites and docs assertion after docs edits.
• 2026-06-23: Ran repo-local dp update --check --baseline stable --refresh-baseline --json; command exited 1 with packDrift: false, baselineDrift: true, settings/manifest drift, and stale create-plan refs.
• 2026-06-23: Parent review found and fixed update/root precedence regressions around marker-backed app/wiki, canonical apps/wiki, stale roots, route-only app/wiki, and repoShapeMode overrides.
• 2026-06-23: Final scoped autoreview exited clean with no accepted/actionable findings.
• 2026-06-23: GitHub issue #44 closed with validation summary.
• files edited/created:
• apps/wiki/content/docs/project/specs/cli/issue-44-app-surfaced-wiki-root/PLAN.md
• apps/wiki/content/docs/project/specs/cli/issue-44-app-surfaced-wiki-root/IMPLEMENTATION-NOTES.md
• backlog_item_id: issue-44
• backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/44
• relation_mode: body-links
• assigned_skills: review-phase, autoreview, parallel-research, simplify, improve-codebase-architecture, docs-ingest-phase, turborepo
• tdd_status: not_applicable
• tdd_target: Evidence, review, and tracker closeout are complete.
• red_command:
• expected_red_failure:
• green_command: bun test apps/cli/src/scaffold/stage.test.ts && bun test apps/cli/src/update/run.test.ts && rg -n "app/wiki|app-surfaced|app surfaces" docs/README.md docs/runbooks/dp-cli-scaffolding.md docs/reference/dp-requirements.md apps/wiki/content/docs/project/runbooks/dp-cli-scaffolding.md apps/wiki/content/docs/project/reference/dp-requirements.md && bun run check-types --filter=@punks/wiki && bun run build --filter=@punks/wiki && bun run apps/cli/src/index.ts update --check --baseline stable --refresh-baseline --json && .agents/skills/autoreview/scripts/autoreview --mode local --prompt "Scope review to issue #44 app-surfaced wiki-root changes only. Review the issue #44 spec folder plus stage/update code, tests, and app/wiki docs touched for this task. Treat pre-existing cli-tool-validation worktree changes as out of scope unless an issue #44 edit depends on them."
• reason_not_testable: Closeout and evidence task; behavior is validated by prior test task.
• red_evidence:
• green_evidence: Parent validation passed: bun run --cwd apps/cli test src/scaffold/stage.test.ts && bun run --cwd apps/cli test src/update/run.test.ts passed 14/14 scaffold tests and 20/20 update tests; bun run --cwd apps/cli check passed; docs rg assertion passed; git diff --check passed; scoped autoreview exited clean with no accepted/actionable findings. bun run apps/cli/src/index.ts update --check --baseline stable --refresh-baseline --json exited 1 with no pack drift, baseline drift true, .devpunks/settings.json / .devpunks/scaffold-manifest.json drift, wiki .source drift from new routed pages, and stale .agents/skills/create-plan/references/* files.
• codebase_design_notes: not_applicable
• review_mode: cli

Parallel Execution Groups

Validation Strategy

• Run the T1 RED command before production edits and record failure evidence in the plan.
• Run the T1 GREEN command after the minimal implementation and record proof.
• Run docs assertions and wiki checks after T2.
• Run repo-local dp update --check --baseline stable --refresh-baseline --json and record whether remaining scaffold drift is pre-existing.
• Run .agents/skills/autoreview/scripts/autoreview --mode local --prompt "Scope review to issue #44 app-surfaced wiki-root changes only. Review the issue #44 spec folder plus stage/update code, tests, and app/wiki docs touched for this task. Treat pre-existing cli-tool-validation worktree changes as out of scope unless an issue #44 edit depends on them."; fix accepted findings and rerun focused tests/review until clean or explicitly rejected with rationale.

Risks And Mitigations

• Risk: app/ detection could overfit to any folder named app. Mitigation: require observable app-surface evidence and preserve fallback behavior.
• Risk: shared helper extraction could broaden the change. Mitigation: keep logic local unless duplication across init/update becomes harmful.
• Risk: current scaffold drift is unrelated but can affect final update validation. Mitigation: record exact changed files and distinguish pre-existing drift from issue #44 behavior.
• Risk: docs mirrors can drift. Mitigation: update root docs and routed project mirrors in the same task.

Unresolved Questions

• Should future init support an explicit user-selected wiki root for ambiguous layouts? Non-blocking for issue #44 because this plan handles the observed app/wiki shape and documents reconciliation limits.