[FORGE-97] Worker prompt template + render + guardrail-check verb (P2.5-T06)

[firatcand]

Summary

Lands the host-portable worker prompt template every spawned forge worker subagent reads at task start, plus a pure renderer and a new CLI verb (forge orchestrate guardrail-check) that workers call before writing to architecturally-sensitive paths.

Replaces the uncommitted 6-level precedence chain + drift event/question protocol in spec/ORCHESTRATOR.md with the authority-by-field matrix locked on 2026-05-17 PM (docs/plans/team-mode-minimum-architecture.md §2.1). Critical-path unlock for FORGE-98 (dispatch skill rewrite) and FORGE-99 (doctor).

What changed

• templates/worker-prompt.template.md (NEW, 237 lines) — Authority-by-field matrix + 5 worked examples + 70/30 escalation rule + heartbeat protocol + preflight wrapper + host-conditional blocks (<!-- host: claude --> ... <!-- /host -->).
• src/orchestrator/render-worker-prompt.ts (NEW) — Pure renderer; {{TOKEN}} placeholders validated against an allowlist; strips other-host blocks. Throws on unknown placeholders or unterminated blocks.
• src/orchestrator/glob-match.ts (NEW) — Minimal **/*/literal glob matcher. Zero new deps. **/ enforces segment boundaries (so src/**/foo.ts doesn't match src/barfoo.ts). Compiled regexes memoized.
• src/cli/orchestrate/guardrail-check.ts (NEW) — Read-band verb forge orchestrate guardrail-check --path <p>. Realpath-based containment (rejects symlinks escaping the repo). Returns {architectural, matched_glob, suggested_decision_key}. Best-effort guardrail_checked event when --task + --attempt are supplied (validated via validateIdSegment before any FS access).
• src/schemas/settings.ts — agents.preflight_globs: string[] with default list (10 patterns covering schemas/CLI/specs/CRITICAL/CLAUDE/AGENTS/package.json/phases.yaml).
• src/schemas/attempt.ts — Added guardrail_checked event type to the discriminated union.
• spec/ORCHESTRATOR.md — §Worker prompt template rewritten to describe authority-by-field; §Preflight wrapper rewritten to drop the false "mechanical wrapper" claim (forge can't intercept host tool calls); amendment process-note retired.

Why

The 2026-05-17 PM team-mode-minimum-architecture pivot dropped the 6-level chain + drift workflow. Without this rewrite the worker prompt would still encode the dropped design. Every worker dispatched by FORGE-98 (next ticket) needs the new template as its system prompt.

Architectural decisions (11 forks asked at /plan-task)

See plans/tasks/FORGE-97.plan.md §7 for the full table. Highlights:

• Disagreement protocol → standard forge orchestrate question verb, no drift machinery.
• Preflight wrapper → CLI verb + prompt-discipline + post-hoc audit (deferred). Forge has no PreToolUse hook into Claude Task / Codex subagents — a "mechanical wrapper" is impossible at this layer.
• Host portability → single template with <!-- host: claude --> ... <!-- /host --> blocks; renderer strips other-host content before the prompt reaches the host.
• Placeholder syntax → mustache {{TOKEN}} against an allowlist (rejects ${...} / <TOKEN> alternatives for safety/clarity).
• Filename → worker-prompt.template.md (matches the .template.md convention of the other 7 templates).

Review pass

Multi-model review (per multi-model-review-catches-distinct-bug-classes.md):

• code-reviewer (sonnet) — 4 IMPROVEMENTs, 2 NITs.
• security-auditor (sonnet) — 1 HIGH, 1 MED, 2 LOW.
• Codex (gpt-5-codex via codex exec) — 2 BLOCKs, 4 IMPROVEMENTs, 2 NITs.

Zero overlap on BLOCKs across reviewers — confirms the multi-model thesis. All 13 findings addressed in commit 4ed1e6e:

• B1: symlink containment bypass → realpathSync on repoRoot + target.
• B2: false enforcement claim (complete doesn't actually cross-reference yet) → softened to "forthcoming follow-up."
• B3: unguarded FS probe via --task → validateIdSegment at top of appendGuardrailEvent before any path.join.
• I1: **/ segment-boundary fix.
• I2: Example 1 contradicting the matrix (tracker→phases.yaml).
• I3: stale worker-prompt.md filename in ORCHESTRATOR.md.
• I4: out-of-repo path leak in response envelope.
• I5: hardcoded preflight_globs in scaffold removed (zod default).
• I6: redundant src/cli/migrate.ts removed (dead behind src/cli/**).
• I7: silent catch → process.stderr.write warning.
• N1: dead ?? null / ?? '' branches.
• N2: compileGlob memoized.
• N3: 2 new semantic template tests (regression guards for I2 + B2).

How to test

• npm test — full suite passes from main checkout (1083/1083). From a .forge/worktrees/<id> checkout, 6 e2e/perf tests fail due to FORGE-122 (hardcoded ${repoRoot}/node_modules/.bin/tsx doesn't exist in worktrees — pre-existing, unrelated).
• npm run typecheck — clean.
• npm run build — clean. node dist/bin/forge.cjs orchestrate --help shows guardrail-check in the read-only band.
• node dist/bin/forge.cjs orchestrate guardrail-check --path src/schemas/foo.ts --json (in any forge-initialized project) returns {architectural: true, matched_glob: "src/schemas/**", ...}.
• Symlink-bypass test: create a symlink inside the repo pointing to /tmp/evil.ts, run guardrail-check against it → returns INVALID_ARGS (does not leak path).
• Render test: write a fixture context, render the template, assert all {{TOKEN}} placeholders are substituted and host-blocks for the wrong host are stripped.

Follow-ups filed at /plan-task time

• FORGE-FOLLOWUP-A — Post-hoc enforcement of guardrail-check calls in complete.ts (cross-reference verdict's files_changed against guardrail_checked events; mark verdict_unverified on mismatch). Roughly 30 LOC; deferred to keep this PR's complete.ts touch zero.
• FORGE-FOLLOWUP-B — End-to-end test of the authority-collision question flow. Blocked on FORGE-98 (dispatch skill).
• FORGE-122 — Worktree-infra test failures (6 e2e/perf tests hardcode ${repoRoot}/node_modules/.bin/tsx). Unrelated to this PR; surfaced during /review.

Linked

• Closes FORGE-97
• Implements P2.5-T06 from docs/plans/team-mode-minimum-architecture.md
• Unblocks FORGE-98 (dispatch skill), FORGE-99 (doctor), FORGE-106 (CLAUDE.md docs)

🤖 Generated with Claude Code