Plan: IP-99 Private Harness Intelligence Wiki App

Initial Situation

apps/wiki exists as a Fumadocs-backed Next app inside the Harness Intelligence Turborepo. It already renders CLI wiki pages, but M2 needs the app foundation to be explicit, internally branded, source-owner disciplined, typecheck/build integrated, and Vercel-ready.

Issue

IP-99 must absorb IP-117 and IP-118. The app must be a real private internal wiki surface under apps/wiki, preserve existing CLI knowledge, and avoid creating a second source layer. The current repo had three concrete gaps: default Fumadocs naming, wiki types:check not participating in root check-types, and Turbo outputs caching .next/cache/**.

Solution Shape

Close the app-foundation slice by tightening the package/app contract, preserving CLI routed pages and source indexes, documenting privacy/deployment constraints, and validating the app through Turborepo plus browser smoke. Do not expand into harness methodology inventory beyond linking to the domain shell; IP-100 owns that content.

Inner Skill Phases

• $grill-me: skipped because the user supplied exact parent and child issue scope; no spec-shaping question remained after Linear fetch.
• $parallel-research: used with readonly subagents for wiki/spec conventions, Turborepo/Vercel readiness, and harness-domain separation.
• $swarm-planner: task graph is dependency-ordered around app contract first, preservation second, validation third.
• $tdd: public targets are build/typecheck/browser routes and acceptance-signal evidence.

Decision Ledger

Codebase Findings

• Root package.json delegates build, check-types, and app dev commands through Turborepo.
• apps/wiki/package.json had types:check but no check-types script.
• turbo.json included .next/** but did not exclude .next/cache/**, which Vercel docs flag as cache bloat.
• apps/wiki/src/lib/shared.ts still used Fumadocs sample app/GitHub values.
• apps/wiki/content/docs/project/specs/index.mdx was missing the latest IP-157 spec.
• Existing CLI pages are already routed under apps/wiki/content/docs/cli; their project-owned source index belongs under apps/wiki/content/docs/project/domains/cli.

External Research Used

• Vercel documentation search confirmed global turbo build is valid for monorepos when Vercel infers a filter from project root, and turbo.json should exclude .next/cache/**.
• Linear fetch confirmed IP-99 parent, IP-117 and IP-118 child descriptions, M2 milestone, statuses, and parent links.

Dependency Graph

T1 -> T2 -> T3 -> T4

Tasks

T1: Align wiki app identity and package tasks

• depends_on: []
• location: apps/wiki/package.json, apps/wiki/src/lib/shared.ts, apps/wiki/src/app/layout.tsx, turbo.json
• description: Replace sample identity, add wiki check-types, set metadata base, and exclude .next/cache/** from Turbo outputs.
• validation: bun run check-types --filter=@punks/wiki, bun run build --filter=@punks/wiki.
• status: Complete
• log: Added check-types, app metadata, Harness wiki naming, GitHub config, and Next cache exclusion.
• files edited/created: apps/wiki/package.json, apps/wiki/src/lib/shared.ts, apps/wiki/src/app/layout.tsx, turbo.json
• backlog_item_id: IP-117
• backlog_item_url: https://linear.app/devpunks/issue/IP-117/private-fumadocs-wiki-app-exists-under-appswiki
• relation_mode: native
• assigned_skills: turborepo, next-best-practices, quality-types, tdd
• tdd_target: Repo-standard wiki typecheck and build prove the app is a real package-owned Next/Fumadocs app.
• review_mode: mixed

T2: Preserve CLI wiki source and routed projection

• depends_on: [T1]
• location: apps/wiki/content/docs/project/domains/cli, apps/wiki/content/docs/cli, apps/wiki/index.md, apps/wiki/log.md, apps/wiki/specs/cli/cli-specs.md
• description: Verify existing CLI concepts/flows stay available and update project spec projection without rewriting CLI knowledge.
• validation: route smoke for /docs/cli; source index still lists CLI concepts and flows.
• status: Complete
• log: CLI domain preserved; project specs projection updated to include M2 specs and IP-157.
• files edited/created: apps/wiki/specs/cli/cli-specs.md, apps/wiki/content/docs/project/specs/index.mdx, apps/wiki/index.md, apps/wiki/log.md
• backlog_item_id: IP-118
• backlog_item_url: https://linear.app/devpunks/issue/IP-118/existing-cli-wiki-knowledge-is-preserved-during-the-wiki-move
• relation_mode: native
• assigned_skills: docs-ingest-phase, simplify, tdd
• tdd_target: Existing CLI routed pages remain renderable after M2 app-foundation updates.
• review_mode: mixed

T3: Record implementation notes and acceptance evidence

• depends_on: [T2]
• location: apps/wiki/specs/cli/IP-99-private-harness-wiki-app
• description: Keep spec folder closeout evidence, deviations, sanity checks, and manual review checklist current.
• validation: IMPLEMENTATION-NOTES.md includes acceptance matrix and manual review checklist.
• status: Complete
• log: Implementation notes created with app-foundation evidence and deployment blocker tracking.
• files edited/created: apps/wiki/specs/cli/IP-99-private-harness-wiki-app/IMPLEMENTATION-NOTES.md
• backlog_item_id: IP-99
• backlog_item_url: https://linear.app/devpunks/issue/IP-99/build-the-private-harness-intelligence-wiki-app
• relation_mode: native
• assigned_skills: implement-spec, review-phase, docs-ingest-phase
• tdd_target: Acceptance evidence maps IP-117/IP-118 signals to repository and runtime proof.
• review_mode: cli

T4: Validate and document deployment readiness

• depends_on: [T3]
• location: docs/README.md, Vercel project settings, local browser`
• description: Run M2 app-foundation validation and either deploy through Vercel or record exact missing project/access blocker.
• validation: bun run check, bun run check-types, bun run build --filter=@punks/wiki, browser smoke, Vercel project inspection/deploy or blocker.
• status: Complete
• log: Local validation and browser smoke passed; Vercel deployment remained blocked until a Vercel project is linked/configured.
• files edited/created: docs/README.md, apps/wiki/specs/cli/IP-99-private-harness-wiki-app/IMPLEMENTATION-NOTES.md
• backlog_item_id: IP-99
• backlog_item_url: https://linear.app/devpunks/issue/IP-99/build-the-private-harness-intelligence-wiki-app
• relation_mode: native
• assigned_skills: turborepo, next-best-practices, review-phase, debugging-phase
• tdd_target: A local buildable/servable private wiki app with exact deploy readiness or blocker evidence.
• review_mode: mixed

Testing Strategy

• Run bun run check for repo formatting/lint.
• Run bun run check-types to prove package check-types coverage includes wiki.
• Run bun run build --filter=@punks/wiki for production Next/Fumadocs build.
• Run bun run dev:wiki and smoke /docs, /docs/harness, /docs/project, and /docs/cli.
• Validate touched meta.json files with jq empty.

Risks and Mitigations

• Privacy overclaim: document that M2 privacy is internal/deployment posture until app auth is specified.
• CLI knowledge drift: preserve CLI pages and source files; only update indexes/projection.
• Vercel ambiguity: rely on current Vercel docs, inspect .vercel/project.json, and report exact missing project linkage when absent.

Validation Gates

• Gate 1: Wiki app identity/package tasks aligned.
• Gate 2: CLI domain preserved and routed.
• Gate 3: Local build/typecheck/browser smoke passes.
• Gate 4: Vercel deploy succeeds or exact access/config blocker is documented.

Unresolved Questions

None blocking implementation. Full app-level auth remains deferred because no auth issue or primitive is in M2 scope.