Implementation Notes: Issue 44 App-Surfaced Wiki Root Selection
Implementation Notes: Issue 44 App-Surfaced Wiki Root Selection
Summary
- Implement issue #44 so app-surfaced single repositories can keep
app/wikias the canonical scaffold wiki root before durable docs are authored.
Execution Mode
- sequential
- One implementation worker owns the coding/docs loop because init and update share wiki scaffold helpers. Parent owns review, final validation, acceptance audit, and tracker closeout.
Deviations From the Plan
- The plan-mandated
bun test ...commands currently fail before test assertions because Bun's test runner does not provide thectx.onTestFinishedAPI expected by@effect/vitest. Behavior evidence was captured with the CLI package's configured Vitest runner:bun run --cwd apps/cli test ....
Surprises and Decisions
- Plan review rejected parallel implementation because update alignment calls stage wiki helpers, so the CLI source task is intentionally sequential.
app/wikiselection is intentionally evidence-based: the CLI chooses it when the output directory itself isapp/wiki, when marker-backedapp/wikiis already selected, or when direct app package surfaces (app/*/package.json) exist without explicit workspace config (pnpm-workspace.yaml,turbo.json, or rootworkspaces). It does not classify everyapp/directory as a monorepo or app-surfaced wiki.- Update root precedence preserves marker-backed selected roots first: canonical
apps/wiki, then marker-backedapp/wiki, then standalonewiki, then the post-overriderepoShapeModefallback. Empty stale root directories do not override selected wiki roots.
Sanity Checks
| Check | Result | Notes |
| ------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| T1 exact RED command | Blocked before assertions | bun test ... -t ... failed with TypeError: ctx?.onTestFinished is not a function from @effect/vitest. |
| T1 behavior RED | Passed as RED | Vitest showed init wrote the wrong wiki root before the fix; follow-up RED showed app-surfaced packages without pre-existing app/wiki still produced apps/wiki/* instead of app/wiki/*. |
| T1 focused behavior GREEN | Passed | bun run --cwd apps/cli test src/scaffold/stage.test.ts -t "seeds app/wiki" && bun run --cwd apps/cli test src/update/run.test.ts -t "preserves existing app/wiki". |
| T1 full CLI Vitest GREEN | Passed | bun run --cwd apps/cli test src/scaffold/stage.test.ts && bun run --cwd apps/cli test src/update/run.test.ts passed 34 total tests after review fixes. |
| T1 exact GREEN command | Blocked before assertions | bun test apps/cli/src/scaffold/stage.test.ts && bun test apps/cli/src/update/run.test.ts hit the same Bun/@effect-vitest runner mismatch. |
| T2 docs assertion | Passed | rg -n "app/wiki | app-surfaced | app surfaces" ... found matches in all requested docs and routed wiki target files. |
| T2 wiki typecheck | Passed | bun run check-types --filter=@punks/wiki. |
| T2 wiki build | Blocked by unrelated dirty work | bun run build --filter=@punks/wiki failed on pre-existing apps/wiki/content/docs/project/specs/cli/cli-tool-validation/IMPLEMENTATION-NOTES.md invalid frontmatter with missing title. |
| T3 focused CLI 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 scaffold tests and 20 update tests after review fixes. |
| T3 CLI check | Passed | bun run --cwd apps/cli check passed with 0 lint errors and clean formatting. |
| T3 docs assertion | Passed | Re-ran rg -n "app/wiki | app-surfaced | app package | app surfaces" ... successfully and stale wording scan found no matches. |
| T3 scaffold update check | Existing drift plus new page projection drift | bun run apps/cli/src/index.ts update --check --baseline stable --refresh-baseline --json exited 1 with packDrift: false, baselineDrift: true, settings/manifest drift, wiki .source drift from new routed pages, and stale create-plan refs. |
| T3 autoreview | Passed | Scoped local autoreview exited clean with no accepted/actionable findings after accepted findings were fixed and rerun. |
| T3 GitHub issue closeout | Passed | gh issue close 44 --comment ... closed issue #44 with implementation and validation summary. |
Acceptance Criteria Status
| Criterion | Status | Notes |
|---|---|---|
Init does not silently seed root wiki/ for observable app-surfaced single repos | Accepted | New stage test proves app/wiki/* is created from app/frontend and app/backend package surfaces without a pre-existing app/wiki; competing wiki/* / apps/wiki/* roots are not. |
| Init names the resolved canonical wiki root before docs onboarding artifacts | Accepted | Prompt assertions cover app/wiki, specs/raw/routed docs, and ingest bookkeeping wording. |
Existing apps/wiki monorepo behavior is preserved | Accepted | Full scaffold Vitest suite remains green. |
Existing standalone wiki behavior is preserved | Accepted | Full scaffold and update Vitest suites remain green. |
Existing selected app/wiki update root is preserved | Accepted | Update tests prove marker-backed app/wiki stays selected for direct app package surfaces, stale empty apps/wiki, and generic app/*/package.json names. |
Focused regression coverage proves app-surfaced, apps/wiki, and wiki scenarios | Accepted | Covered by full stage.test.ts and run.test.ts Vitest runs, including route-only app/wiki, non-directory app, stale apps/wiki, stale wiki, and repoShapeMode overrides. |
| Operator docs and runbooks describe app-surfaced single-repo wiki roots | Accepted | Root docs, runbook, requirements reference, and routed wiki mirrors describe app/wiki and update preservation. |
Manual Review Checklist
| Area | Check | How to perform | Expected result |
| ----------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| CLI scaffold init | Re-run the focused app-surfaced init test | bun run --cwd apps/cli test src/scaffold/stage.test.ts -t "seeds app/wiki" | Test passes and asserts app/wiki prompt/root behavior. |
| CLI update | Re-run the focused app/wiki update test | bun run --cwd apps/cli test src/update/run.test.ts -t "keeps marker-backed app/wiki ahead of app surface packages and stale apps/wiki" | Test passes and no competing wiki or apps/wiki tree is proposed. |
| Docs | Inspect app-surfaced root guidance | 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 | Root docs and routed wiki mirrors mention app-surfaced wiki roots. |
Pre-existing Issues
- The worktree had unrelated CLI tool-validation changes before issue #44 work began. Keep review and closeout scoped to issue #44 unless a dependency is proven.
- Repo-local
dp update --check --baseline stable --refresh-baseline --jsonalready reported scaffold drift and baseline drift before implementation.
Out of Scope Observations
- None yet.
Remaining Work
- T1 complete.
- T2 complete, with wiki build blocked by unrelated pre-existing
cli-tool-validationfrontmatter. - T3 validation, autoreview, and GitHub issue closeout complete.