[FORGE-106] docs(skills,templates): agent-discipline rules — source of truth + precedence + worktree-guard inverse (P2.5-T14)

[firatcand]

Summary

Bundles three durable "agent-discipline" rules into a single docs PR that ships to every adopter via npm install @firatcand/forge. All three emerged from real dogfooding failures observed during this single session.

What changed (7 files, +87/-4)

• CLAUDE.md + templates/CLAUDE.project.template.md — added three sections (identical text in both files):
  • §Source of truth — authority-by-field matrix: SPEC owns architecture, PRD owns product behavior, phases.yaml owns the cached dependency graph (status fields are stale), Tracker owns live execution truth, source code owns implementation. Explicit rule for AI agents: query the tracker directly for any status question; never grep phases.yaml for status/completedAt. Strict precedence (user > SPEC > PRD > phases.yaml > tracker > attempts) included as a one-line tiebreaker.
  • §Skill ↔ verb contract — skills own UX, verbs own state machine. Brief pointer to spec/SPEC.md + spec/ORCHESTRATOR.md for the full state-machine ownership story.
  • §Ephemeral ADR workflow (v0.5 — not active in v0.4) — renamed forge's existing "Decision records" section for terminology consistency with the planned /update-spec skill.
• skills/_shared/worktree-guard.md — appended §Inverse rule: inspecting a worktree from outside. The existing guard refuses mutation from main; the symmetric trap is observational cd .forge/worktrees/<ID> && git log poisoning cwd for every subsequent command in the session. Rule: use git -C <path> <cmd> for read-only inspection from any session not pinned to a worktree by /pickup-task. Includes a wrong-vs-right cd vs git -C example pair.
• skills/pickup-task/SKILL.md — rewrote step 1 to mandate tracker-first lookup with an explicit warning that phases.yaml status fields are stale and must NOT be grep'd; added a top-of-file cross-reference to §Source of truth.
• skills/forge-orchestrate/SKILL.md + skills/sync-status/SKILL.md — top-of-file one-liner: "Status queries always hit the tracker. plans/phases.yaml is a stale cache."
• CONTRIBUTING.md — added a manual git grep recipe to the Local validation section as a guard against removed orchestrate verbs reappearing (no husky in repo, so AC's optional pre-commit hook was rendered as a contributor-facing check).

Why now

Both class-of-bugs the new rules prevent were hit during this single session:

1. Recommended already-shipped tickets twice (FORGE-99, FORGE-94) because I grep'd plans/phases.yaml status: fields instead of querying Linear — exactly the failure §Source of truth now forbids.
2. Stray cd .forge/worktrees/FORGE-88 && git log poisoned cwd of a main-pinned session, causing every following command to resolve against the wrong worktree until caught — exactly the failure §Inverse rule now forbids.

The 6-level precedence contract (original AC) was already in templates/worker-prompt.template.md's "Authority by field" matrix; this PR makes the supervisor-side documentation (CLAUDE.md, skills) match.

Side effect: filed FORGE-136

Discovered mid-implementation: forge orchestrate ensure-worktree hydrated a stale CRITICAL.md that, if committed, would have silently reverted FORGE-88's src/harnesses/** codex-auto-review glob. Filed as P1 follow-up to FORGE-98 with repro details and acceptance criteria.

Test plan

• npm run typecheck — clean
• npm test — 1276 passed / 0 failed / 15 skipped
• npm run build — dual ESM+CJS bundles emit cleanly
• node dist/bin/forge.cjs --version — smoke OK
• gitleaks detect — no leaks
• Manual diff review — confirmed only the 7 intended files
• No CRITICAL.md path touched — multi-model review not required

Linked

Closes FORGE-106.
Related: FORGE-136 (filed mid-implementation).

🤖 Generated with Claude Code