Harness Intelligence Wiki
SpecsCLIIssue 69 Project Owned Wiki Sync

Plan: Issue 69 Project-Owned Wiki Sync Drift

Plan: Issue 69 Project-Owned Wiki Sync Drift

Generated: 2026-07-10 Backlog item: https://github.com/wearedevpunks/harness-intelligence/issues/69 Mode: parallel: false

Initial Situation

hi update --check compares scaffold output and wiki-alignment output against the working tree. A repository may intentionally customize apps/wiki/scripts/sync-content.mjs, but the current update path reports that script as changed harness drift and exits 1 even when pack, baseline, stale-file, and all other managed-file checks are clean.

The accepted issue contract is the spec: keep scaffold creation of the sync script, but treat an existing wiki sync implementation as project-authored during update drift detection and apply. Other wiki scaffold files remain managed.

Scaffold remediation prerequisite completed before planning: hi update --yes aligned this checkout to CLI 2.5.3 and baseline 2026.07.09-backend-domain-guardrails; follow-up hi check passed.

Resolved Decision Ledger

Locked decisions:

  • Use runUpdate as the public RED/GREEN seam.
  • Exclude only apps/wiki/scripts/sync-content.mjs, the path reported by issue #69; do not weaken general managed-file hash comparisons or silently broaden this patch to other wiki layouts.
  • Preserve scaffold-time generation of the default sync script.
  • Apply the same project-authored classification to normal managed comparison, stale-file handling, wiki alignment, and write mode so that exact customized script is neither reported nor overwritten.
  • Keep implementation sequential and surgical.
  • GitHub issue #69 remains the owning story; no new backlog item is needed.

Assumptions:

  • No external package or API behavior is involved; external research is unnecessary.

Open decisions: none.

Codebase Findings And Design

runUpdate is the deep module interface: callers observe changedFiles, staleFiles, checkFailed, and applied filesystem results. The internal seam is project-authored-file classification plus wiki-alignment expected-file selection. The regression belongs in apps/cli/src/update/run.test.ts, exercising the same public update flow used by the CLI rather than a private predicate.

Dependency Graph

T1 -> T2 -> T3 -> T4

Execution Waves

WaveTasksCan start when
1T1Immediately
2T2T1 is green
3T3T2 review is clear
4T4T3 docs ingest is complete

Tasks

T1: RED/GREEN Project-Owned Wiki Sync Behavior

  • depends_on: []
  • location: apps/cli/src/update/run.test.ts, apps/cli/src/update/run.ts
  • description: Add one public-seam regression with a staged sequence: customize only the sync script and prove a clean check; then introduce another wiki scaffold change as a positive managed-drift control; then apply and prove the custom sentinel survives while the other file updates. Delete the script and prove check reports it missing and write mode restores it. Update the existing contradictory wiki-alignment test at run.test.ts:1577-1617, which currently expects update to report and replace the sync script. Then make the minimal update-path change.
  • validation: With only the customized script, changedFiles and staleFiles exclude it, checkFailed === false, and process.exitCode remains unset. After another wiki file changes, that file remains reported. Apply mode updates the real managed drift without overwriting the custom script. After deletion, check reports the exact path as missing and non-clean, and write mode recreates it. The existing wiki-alignment test no longer requires update to replace this project-owned file; scaffold-generation coverage remains in scaffold/stage.test.ts.
  • status: Completed
  • log: Added the staged public regression, classified only an existing apps/wiki/scripts/sync-content.mjs as project-authored in update, filtered existing scripts from wiki-alignment expectations, and revised the legacy alignment test to assert custom-content preservation. Structured autoreview found that unconditional ownership hid a missing script; the second RED/GREEN cycle made ownership existence-sensitive and proved missing-file drift plus recreation. Simplify found no further production-code reduction beyond the one ownership predicate.
  • files edited/created: apps/cli/src/update/run.ts, apps/cli/src/update/run.test.ts, apps/wiki/content/docs/project/specs/cli/issue-69-project-owned-wiki-sync/PLAN.md, apps/wiki/content/docs/project/specs/cli/issue-69-project-owned-wiki-sync/IMPLEMENTATION-NOTES.md
  • backlog_item_id: GitHub #69
  • backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/69
  • relation_mode: native
  • assigned_skills: autoreview, codebase-design, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo
  • tdd_status: required
  • tdd_target: runUpdate returns a clean check for an existing customized apps/wiki/scripts/sync-content.mjs, preserves it in write mode, still reports other wiki scaffold drift, and reports/restores that exact script when missing.
  • red_command: /opt/homebrew/bin/bun run --cwd apps/cli test src/update/run.test.ts -t "ignores project-owned wiki sync scripts during update checks and writes"
  • expected_red_failure: Cycle 1 fails because the customized existing script appears in changedFiles; cycle 2 fails because unconditional exclusion hides a missing script from drift and recreation.
  • green_command: /opt/homebrew/bin/bun run --cwd apps/cli test src/update/run.test.ts -t "ignores project-owned wiki sync scripts during update checks and writes"
  • reason_not_testable:
  • red_evidence: 2026-07-10 cycle 1: exact red_command exited 1. Vitest failed at run.test.ts:1542 because cleanCheck.changedFiles included apps/wiki/scripts/sync-content.mjs after that script was the only customized file. Cycle 2: after deleting the script, the exact command exited 1 at run.test.ts:1589 because missingCheck.changedFiles was empty instead of reporting the exact path with status: "missing".
  • green_evidence: 2026-07-10 cycle 1: exact green_command exited 0; Vitest passed the new regression (1 passed, 34 skipped). A separate targeted run for aligns existing wiki structure during update also exited 0 after its contradictory assertions were revised. Cycle 2: after the existence-sensitive fix, the exact command exited 0 and proved missing-file reporting plus recreation in the same public regression (1 passed, 34 skipped).
  • codebase_design_notes: Preserved the runUpdate interface and general hash semantics. The exact-path ownership rule stays inside isProjectAuthoredManagedFile, derives ownership from current filesystem existence, and wiki alignment filters expected files through that same classification before diff/apply behavior.
  • review_mode: cli

T2: Validate And Review The Code Slice

  • depends_on: [T1]
  • location: apps/cli/src/update/run.ts, apps/cli/src/update/run.test.ts, apps/wiki/content/docs/project/specs/cli/issue-69-project-owned-wiki-sync/PLAN.md
  • description: Run the focused test, full update test file, CLI typecheck, and a readonly review for over-broad exclusions, missed stale/write behavior, or unintended changes to scaffold generation.
  • validation: Commands pass and review has no unresolved in-scope findings before docs ingest begins.
  • status: Completed
  • log: Structured autoreview accepted one P1: unconditional exact-path exclusion falsely treated a missing sync script as clean and could leave the repaired package build script pointing to a missing file. T1 resolved it with existence-sensitive ownership and a second RED/GREEN cycle. Focused regression, complete update test file, CLI typecheck, and scoped whitespace validation passed with no remaining in-scope finding.
  • files edited/created: apps/cli/src/update/run.ts, apps/cli/src/update/run.test.ts, apps/wiki/content/docs/project/specs/cli/issue-69-project-owned-wiki-sync/PLAN.md, apps/wiki/content/docs/project/specs/cli/issue-69-project-owned-wiki-sync/IMPLEMENTATION-NOTES.md
  • backlog_item_id: GitHub #69
  • backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/69
  • relation_mode: native
  • assigned_skills: autoreview, codebase-design, effect-authoring, effect-backend-structure, effect-best-practices, effect-recoverable-actions, improve-codebase-architecture, parallel-research, quality-types, simplify, swarm-planner, tdd, turborepo
  • tdd_status: not_applicable
  • tdd_target: Verification and readonly review of T1's completed behavior slice.
  • red_command:
  • expected_red_failure:
  • green_command: /opt/homebrew/bin/bun run --cwd apps/cli test src/update/run.test.ts && /opt/homebrew/bin/bun run --cwd apps/cli check-types && git diff --check -- apps/cli/src/update/run.ts apps/cli/src/update/run.test.ts apps/wiki/content/docs/project/specs/cli/issue-69-project-owned-wiki-sync/PLAN.md
  • reason_not_testable: Validation/review task consumes T1's behavior test.
  • red_evidence:
  • green_evidence: 2026-07-10: focused regression passed (1/1), full run.test.ts passed (35/35), CLI tsc --noEmit passed, and scoped git diff --check passed.
  • codebase_design_notes: Review protects exact exclusion locality and the public runUpdate behavior.
  • review_mode: cli

T3: Ingest The Ownership Boundary Into Docs

  • depends_on: [T2]
  • location: docs/README.md, docs/runbooks/hi-cli-scaffolding.md, apps/wiki/content/docs/project/runbooks/hi-cli-scaffolding.md, .agents/notes/index.md, .agents/notes/2026-07-10-project-owned-wiki-sync.md, apps/wiki/content/docs/project/specs/cli/issue-69-project-owned-wiki-sync/PLAN.md
  • description: Through docs-ingest-phase, record that scaffold init creates the default wiki sync script while update/check treats an existing apps/wiki implementation as project-authored and does not report or overwrite it. Update the canonical routed wiki runbook, which currently says update writes this managed script, plus the repo docs and a concise cross-session note.
  • validation: All three documentation surfaces match tested behavior; note index stays lean; scoped whitespace checks pass.
  • status: Completed
  • log: Selected the private/internal docs path. Updated the root truth summary, repo runbook, and canonical routed runbook with the existence-sensitive ownership boundary. The scoped routed-learning scan found no separate flow or concept page warranted; the existing runbook is the canonical future-use hook. Added one concise cross-session note because the present-versus-missing distinction is a hard-to-discover correctness constraint. Normalized spec and implementation-notes ingest metadata, logged the ingest, and added the issue folder to the explicit CLI spec page list.
  • files edited/created: docs/README.md, docs/runbooks/hi-cli-scaffolding.md, apps/wiki/content/docs/project/runbooks/hi-cli-scaffolding.md, .agents/notes/index.md, .agents/notes/2026-07-10-project-owned-wiki-sync.md, apps/wiki/content/docs/project/specs/cli/issue-69-project-owned-wiki-sync/SPEC.md, apps/wiki/content/docs/project/specs/cli/issue-69-project-owned-wiki-sync/PLAN.md, apps/wiki/content/docs/project/specs/cli/issue-69-project-owned-wiki-sync/IMPLEMENTATION-NOTES.md, apps/wiki/content/docs/project/specs/cli/meta.json, apps/wiki/log.md
  • backlog_item_id: GitHub #69
  • backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/69
  • relation_mode: native
  • assigned_skills: agent-browser, async-react-patterns, autoreview, codebase-design, design-taste-frontend, docs-ingest-phase, docs-onboarding, frontend-domain-structure, improve-codebase-architecture, next-best-practices, next-cache-components, parallel-research, quality-types, react-doctor, simplify, tdd, vercel-composition-patterns, vercel-react-best-practices, writing-beats, writing-fragments, writing-great-skills, writing-shape
  • tdd_status: not_applicable
  • tdd_target: Durable operator and maintainer documentation for the tested ownership boundary.
  • red_command:
  • expected_red_failure:
  • green_command: git diff --check -- docs/README.md docs/runbooks/hi-cli-scaffolding.md apps/wiki/content/docs/project/runbooks/hi-cli-scaffolding.md .agents/notes/index.md .agents/notes/2026-07-10-project-owned-wiki-sync.md apps/wiki/log.md apps/wiki/content/docs/project/specs/cli/meta.json apps/wiki/content/docs/project/specs/cli/issue-69-project-owned-wiki-sync
  • reason_not_testable: Documentation and cross-session note update.
  • red_evidence:
  • green_evidence: 2026-07-10: scoped git diff --check passed; trailing-whitespace scan passed for the untracked issue artifacts and note; wiki log contains exactly 50 entries.
  • codebase_design_notes: Document the ownership boundary at existing update/scaffolding runbook seams; add no new conceptual surface.
  • review_mode: cli

T4: Final Validation

  • depends_on: [T3]
  • location: . (command-only parent validation; no edits or scoped review)
  • description: Re-run focused/full CLI validation and scoped whitespace checks after docs ingest; classify any remaining command blockers. T4 does not edit or review files; T2 owns code review and T3 owns docs ingest.
  • validation: Focused regression, complete update test file, CLI typecheck, and scoped diff checks pass.
  • status: Completed
  • log: Final parent validation passed: complete update test file 35/35, CLI typecheck, and repository-wide git diff --check. An extra unplanned hi check exited 1 because remote stable advanced during the task to 2026.07.10-explicit-phase-invocation while this checkout records 2026.07.09-backend-domain-guardrails; it also reported the intentional in-task docs/settings changes. This is external scaffold/release noise, not a failure of issue #69 behavior, and was not remediated.
  • files edited/created: apps/wiki/content/docs/project/specs/cli/issue-69-project-owned-wiki-sync/SPEC.md, apps/wiki/content/docs/project/specs/cli/issue-69-project-owned-wiki-sync/PLAN.md, apps/wiki/content/docs/project/specs/cli/issue-69-project-owned-wiki-sync/IMPLEMENTATION-NOTES.md
  • backlog_item_id: GitHub #69
  • backlog_item_url: https://github.com/wearedevpunks/harness-intelligence/issues/69
  • relation_mode: native
  • assigned_skills: autoreview, quality-types, simplify, tdd, turborepo
  • tdd_status: not_applicable
  • tdd_target: Final verification gate for the complete issue #69 slice.
  • red_command:
  • expected_red_failure:
  • green_command: /opt/homebrew/bin/bun run --cwd apps/cli test src/update/run.test.ts && /opt/homebrew/bin/bun run --cwd apps/cli check-types && git diff --check
  • reason_not_testable: Final validation consumes T1's behavior test and T3's docs checks.
  • red_evidence:
  • green_evidence: 2026-07-10: /opt/homebrew/bin/bun run --cwd apps/cli test src/update/run.test.ts passed 35/35; /opt/homebrew/bin/bun run --cwd apps/cli check-types passed; git diff --check passed.
  • codebase_design_notes: No additional design change; verify the completed public behavior and docs boundary.
  • review_mode: cli

Testing Strategy

Use one vertical TDD slice through runUpdate. Prove RED before production edits, make the narrowest fix, then run the complete update test file and CLI typecheck.

Risks And Mitigations

  • Over-broad exclusion: match only apps/wiki/scripts/sync-content.mjs and retain a positive control for other wiki drift.
  • Check-only fix still overwrites on apply: assert custom content survives write mode.
  • Stale manifest entry reappears as stale drift: route the exact path through the same project-authored classification used by stale filtering.

Backlog Sync

No mutation required. GitHub issue #69 is already the product-facing story.

Review And Docs Ingest

Mandatory readonly code review follows T1. The behavior changes CLI operator workflow, so docs ingest follows that review, then T4 revalidates the complete slice.

Completion

Implemented and validated on 2026-07-10. All four tasks and all six acceptance criteria are complete. No issue-scoped work remains.

Issue 69 Project-Owned Wiki Sync Drift

Previous Page

Implementation Notes

Next Page

On this page

Plan: Issue 69 Project-Owned Wiki Sync DriftInitial SituationResolved Decision LedgerCodebase Findings And DesignDependency GraphExecution WavesTasksT1: RED/GREEN Project-Owned Wiki Sync BehaviorT2: Validate And Review The Code SliceT3: Ingest The Ownership Boundary Into DocsT4: Final ValidationTesting StrategyRisks And MitigationsBacklog SyncReview And Docs IngestCompletion