@moretea-labs/forge 1.5.0-rc.1

package/assets/reference-configs/external-tooling.md

@@ -0,0 +1,374 @@
+# External Tooling
+
+Generated repos route external tooling by host/runtime shape. Task-level
+skill routing lives in `docs/reference-configs/agentic-development-flow.md`.
+
+- `gstack` supplies `office-hours`, `plan-eng-review`, and `plan-design-review`
+- `Waza` supplies `/think`, `/hunt`, and `/check` for daily small/medium work
+- Codex automation requires `health`, `check`, and `mermaid` from `~/.codex/skills`
+- `gbrain` supports knowledge capture, repo sync, and handoff retrieval
+- `CodeGraph` is required agent readiness for code navigation and impact tracing
+
+Waza is Codex-first in this contract. `~/.codex/skills` is the Codex runtime
+source, while `~/.agents/skills` is only the skills CLI staging/cache path used
+to receive upstream `tw93/Waza` updates before syncing verified copies into
+Codex.
+
+`forge install` is allowed to bootstrap the workflow-owned global runtime
+in one pass: the `forge` CLI, forge runtime aliases, user-level
+Codex/Claude hook adapters, Waza (`think`, `hunt`, `check`, `health`), brain
+root persistence, Mermaid, and CodeGraph CLI/MCP configuration.
+`forge init` remains the explicit legacy bootstrap command for existing Forge automation, while `forge setup open/next/close` is the preferred first-run workflow. Neither path may silently install unrelated toolchains or Claude marketplace plugins.
+
+`forge uninstall` removes forge managed Codex/Claude hook
+adapters. It intentionally does not uninstall Waza, Mermaid, CodeGraph, gbrain,
+brain config, package-manager globals, or user-authored sibling hook entries.
+
+`forge update` refreshes only the CLI and forge-owned user-level
+runtime by default. Third-party tooling and CodeGraph registration stay
+readiness findings from `forge setup check` unless the update command is
+run with an explicit opt-in such as `--with-external-skills` or
+`--configure-codegraph`.
+
+The cross-review skills are **harness-owned and self-contained** — their source
+lives in `assets/skills/<skill>/` and they wrap the peer CLI (`codex exec` /
+`claude -p`) in a read-only sandbox with no gstack dependency, so installing them
+is a workflow-owned runtime concern, not an unrelated toolchain. They install
+host-aware during `forge install`/`init` and explicit external-skill refreshes:
+`codex-review` only into `~/.claude/skills` (a Claude session asking
+Codex for an independent review) and `claude-review` only into `~/.codex/skills`
+(a Codex session asking Claude). When gstack is present, its `/codex` and
+`gstack-claude` skills are a more featureful superset; the harness skills are the
+zero-dependency baseline that always ships with `init` and the peer acceptance
+gate surface for `## External Acceptance Advice`.
+
+The review scope is the current reviewable diff, not just committed branch
+history: branch diff against the default base, staged changes, unstaged tracked
+changes, and untracked files are all in scope. A timeout or missing peer CLI is
+reported as unavailable review evidence, not as a pass.
+
+The Codex automation profile is a runtime reference, not a vendored copy. It
+requires Waza `health`, Waza `check`, and the standalone `mermaid` skill to
+exist under `~/.codex/skills`; the skill bodies stay owned by their original
+installations.
+
+## Detect Safely
+
+Use `bash .ai/harness/scripts/check-agent-tooling.sh` for a read-only tooling report.
+Init and migration reports run the detector without update checks by default;
+set `FORGE_CHECK_TOOLING_UPDATES=1` when that advisory pass should
+also compare upstream versions.
+
+Supported flags:
+
+- `--host claude|codex|both`
+- `--json`
+- `--check-updates`
+- `--strict-readiness`
+
+The detector intentionally avoids side-effecting commands. It does not run:
+
+- `gstack setup`
+- `npx skills check`
+- `npx skills update`
+- `gbrain serve`
+- `gbrain sync`
+- `codegraph init`
+- `codegraph sync`
+- `codegraph install`
+
+With `--check-updates`, Waza update checks fetch upstream GitHub raw
+`SKILL.md` and shared `rules/` files, then compare versions/hashes against each
+host path. The detector also compares each host's Waza skill directories and
+shared rules against the `~/.agents` staging cache so helper files under
+`references/`, `scripts/`, `agents/`, and cross-skill `rules/` links cannot
+silently drift. Network failures are reported as `unknown`; the detector never
+updates skills.
+
+## Install
+
+### gstack
+
+Claude Code:
+
+```bash
+git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
+cd ~/.claude/skills/gstack && ./setup
+```
+
+Codex:
+
+```bash
+test -d ~/.claude/skills/gstack || git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
+cd ~/.claude/skills/gstack && ./setup --host codex
+```
+
+### Waza
+
+Both hosts:
+
+```bash
+npx -y skills add tw93/Waza -g -a claude-code codex -s think hunt check health -y
+```
+
+Single host:
+
+```bash
+npx -y skills add tw93/Waza -g -a claude-code -s think hunt check health -y
+```
+
+Replace `claude-code` with `codex` when installing for Codex only.
+
+After installing or updating through the skills CLI, verify Codex has its own
+runtime copy:
+
+```bash
+for d in think hunt check health; do
+  rsync -a --delete ~/.agents/skills/$d/ ~/.codex/skills/$d/
+done
+mkdir -p ~/.codex/rules
+for f in anti-patterns.md chinese.md durable-context.md english.md; do
+  cp ~/.agents/rules/$f ~/.codex/rules/$f
+done
+for d in think hunt check health; do
+  diff -qr ~/.agents/skills/$d ~/.codex/skills/$d
+done
+for f in anti-patterns.md chinese.md durable-context.md english.md; do
+  cmp -s ~/.agents/rules/$f ~/.codex/rules/$f
+done
+```
+
+### gbrain
+
+```bash
+bun install -g github:garrytan/gbrain
+```
+
+Do not install npm registry `gbrain`; that package is unrelated to the GBrain
+CLI and does not ship the forge advisory command.
+
+`gbrain` is optional advisory tooling for knowledge sync and retrieval. `setup
+check` may report its local state, but missing or stale `gbrain` must not
+create Agent repair/update actions or change the setup readiness result.
+
+### CodeGraph
+
+`CodeGraph` is required readiness for agent code navigation. It speeds up
+Codex and Claude exploration for indexed TypeScript and other supported languages, but it
+does not replace `.ai/context/capabilities.json`, workflow checks, tests,
+architecture drift events, or shell-script review.
+
+This self-host repo vendors CodeGraph as a dev dependency so `bun install`
+materializes `node_modules/.bin/codegraph`; its source-only
+`scripts/ensure-codegraph.sh` can manage the local index. Generated downstream
+repos keep the global MCP installer default and should use the `codegraph`
+command directly unless local policy explicitly opts into vendoring.
+
+### Runtime Ownership Boundary
+
+`forge setup check --target <host> --check-updates --json` reports the
+execution base as separate `runtime.*` checks. Keep the boundary explicit:
+
+| Capability | Owner | Required for |
+|---|---|---|
+| `bun` | forge | forge-owned global installs, local dependency install, tests, and runtime execution |
+| `bash` | forge | helper scripts, migration, setup checks, and contract verification wrappers |
+| `npm` | npm registry | registry readbacks, publish gates, and opt-in update checks; not forge-owned global install repair |
+| `npx` / `skills_cli` | external Skills CLI | Waza and Mermaid skill bootstrap/update commands |
+| `rsync` | platform filesystem | Waza staging-to-Codex sync and installed-copy runtime mirroring |
+| `symlink` | platform filesystem | link-mode aliases; copy mode is the fallback |
+
+The policy is Bun-first, not Bun-only. Forge-owned install/repair commands
+use `bun add -g` or `bun install`. Waza/Mermaid remain explicit external Skills
+CLI dependencies until a separate plan replaces that integration. Missing
+optional capabilities should degrade the named feature, not blur command
+ownership.
+
+Installed-copy sync has two explicit modes. `AGENTIC_DEV_LINK_INSTALLED_COPIES=1`
+uses symlinks and does not require `rsync`; if symlink creation fails, the
+script reports unsupported link-mode and tells the caller to use copy-mode.
+`AGENTIC_DEV_LINK_INSTALLED_COPIES=0` uses copy-mode and requires `rsync`; if
+`rsync` is missing, the script reports unsupported copy-mode instead of a
+generic command failure.
+
+Read-only check:
+
+```bash
+codegraph status .
+```
+
+Local index mutation:
+
+```bash
+codegraph init -i .
+codegraph sync .
+```
+
+Do not ask users to copy MCP TOML or Claude JSON by hand. The user-facing path
+is one terminal command, or explicit authorization for their agent to run the
+same command:
+
+```bash
+bun add -g @colbymchenry/codegraph && forge tools configure codegraph --target codex --location global
+```
+
+This delegates host-specific MCP config to CodeGraph's target adapters for
+Codex and Claude, so do not run CodeGraph setup automatically from
+`forge init`, `migrate`, or `upgrade`. Restart Codex after the installer
+finishes so the MCP server is discovered; Claude Code should pick up its config
+according to its own settings reload behavior. If a launch environment still
+cannot find `codegraph`, an authorized agent should diagnose `PATH` and the
+`~/.local/bin/codegraph` shim. Do not make the user hand-edit MCP config as the
+fallback.
+
+For troubleshooting only, inspect host config snippets without writing:
+
+```bash
+codegraph install --print-config codex
+codegraph install --print-config claude
+```
+
+Project-local indexes are ignored runtime state:
+
+```bash
+codegraph init -i .
+codegraph status .
+```
+
+Before non-trivial code work, agents should sync the local index and use it for
+P1/P2 discovery:
+
+```bash
+codegraph sync .
+codegraph context "<task>"
+codegraph query <symbol> --json
+codegraph callers <symbol> --json
+codegraph callees <symbol> --json
+codegraph impact <symbol> --json
+```
+
+For this repo, do not treat `codegraph affected` as an authoritative test
+selector. Many tests execute scripts by path or subprocess rather than import
+edges, so run the repo verification commands instead.
+
+### Bash Output Evidence and RTK
+
+`forge` treats Bash output as runtime evidence, not durable task state.
+`PostToolUse:Bash` records command metadata in `.ai/harness/checks/` and stores
+large or failed command output under ignored `.ai/harness/runs/bash-output/` with
+the byte count, SHA-256 digest, and relative evidence path.
+
+RTK can be useful as a user-level compression tool for noisy successful shell
+commands, but it is optional and advisory-only. Hooks may suggest `rtk` when it
+is already on `PATH`, the command is broad, and the command succeeded; hooks must
+not rewrite Bash commands, require RTK, or suggest compression for failed
+commands. Failed command output stays raw so test, build, and review evidence is
+not hidden by a compressor.
+
+## Update
+
+### gstack
+
+Claude Code:
+
+```bash
+cd ~/.claude/skills/gstack && git pull && ./setup
+```
+
+Codex:
+
+```bash
+cd ~/.claude/skills/gstack && git pull && ./setup --host codex
+```
+
+### Waza
+
+```bash
+npx -y skills update
+for d in think hunt check health; do
+  rsync -a --delete ~/.agents/skills/$d/ ~/.codex/skills/$d/
+done
+mkdir -p ~/.codex/rules
+for f in anti-patterns.md chinese.md durable-context.md english.md; do
+  cp ~/.agents/rules/$f ~/.codex/rules/$f
+done
+for d in think hunt check health; do
+  diff -qr ~/.agents/skills/$d ~/.codex/skills/$d
+done
+for f in anti-patterns.md chinese.md durable-context.md english.md; do
+  cmp -s ~/.agents/rules/$f ~/.codex/rules/$f
+done
+```
+
+### gbrain
+
+```bash
+gbrain check-update --json
+gbrain upgrade
+```
+
+### CodeGraph
+
+```bash
+bun add -g @colbymchenry/codegraph@latest && codegraph sync . && codegraph status .
+```
+
+## Manual Knowledge Sync
+
+`gbrain` stays advisory-first in this contract. Manual repo sync is allowed:
+
+```bash
+gbrain sync --repo <path>
+```
+
+## Default Brain Vault
+
+Long-lived external knowledge should land in the default brain file vault before
+or alongside `gbrain` import:
+
+```text
+brain/<project>/*
+```
+
+For this repo, use:
+
+```text
+brain/forge/*
+```
+
+The retired project-skill and project-initializer staging paths have been fully removed; no tooling recognizes, syncs, or cleans them up. Do not use them as sync targets.
+
+Keep runtime contracts, hooks, scripts, checks, evidence, and migration state in
+the repo. The default brain stores reusable explanations, runbooks, decisions,
+and patterns only.
+
+Repo stubs that point to default brain pages are indexed in
+`.ai/harness/brain-manifest.json`. Valuable repo-authored docs can opt into
+one-way mirroring by adding a manifest entry with:
+
+```json
+{
+  "id": "project-decision-log",
+  "repo_path": "docs/decisions.md",
+  "brain_path": "brain/<project>/decisions/project-decision-log.md",
+  "gbrain_slug": "decisions/project-decision-log",
+  "sync": { "direction": "repo-to-brain" }
+}
+```
+
+After that, PostEdit hooks sync only that source file. Manual sync and drift
+checks are also available:
+
+```bash
+bash .ai/harness/scripts/check-brain-manifest.sh
+bash .ai/harness/scripts/sync-brain-docs.sh --all
+bash .ai/harness/scripts/sync-brain-docs.sh --check
+```
+
+## Why gbrain MCP Stays Off by Default
+
+- `gbrain` is useful even when only the CLI is healthy.
+- Missing `gbrain` CLI is not a setup dependency failure.
+- Local MCP endpoints are more failure-prone than the CLI health path.
+- The policy keeps `gbrain` as a candidate MCP entry, not a required runtime dependency.
+- Re-enable MCP only after the local host config is explicitly updated and `gbrain doctor --json` is healthy enough for your workflow.

package/assets/reference-configs/git-strategy.md

@@ -0,0 +1,14 @@
+# AI-Driven Version Control Strategy Reference
+
+> Externalized: full reference lives in default brain.
+
+## Default Brain
+
+- File vault: `brain/forge/references/ai-driven-version-control-strategy.md`
+- gbrain slug: `references/ai-driven-version-control-strategy`
+
+## Repo Role
+
+Repo-local git rules stay in `AGENTS.md`, workflow contracts, and active task
+files. Cross-project branching and version-control strategy guidance lives in
+the external reference.

package/assets/reference-configs/global-working-rules.md

@@ -0,0 +1,64 @@
+# Global Working Rules
+
+Use this content for user-level `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md` when a runtime needs concise but enforceable engineering behavior. Keep repo-local workflow contracts in the repo; do not paste Codex or Claude tool-compatibility maps into global files.
+
+```md
+# Global Working Rules
+
+- Use Chinese by default for this user; keep technical terms in English. If the user writes in another language, mirror that language.
+- Act as an engineering collaborator: finish the concrete task, verify it, then report conclusion, actual change, reason, verification, and residual risk.
+- Prefer direct execution over repeated confirmation. Stop to ask only when continuing would likely produce output contrary to the user's intent.
+
+## Progressive Due Diligence
+
+For non-trivial engineering work, do P1/P2/P3 before design decisions or code edits.
+
+### P1: Architecture Map
+
+Identify the real system boundary, major modules, entrypoints, ownership boundaries, config surfaces, runtime paths, authoritative files, strong/weak dependencies, and explicit out-of-scope areas. Do not infer architecture from filenames alone.
+
+### P2: Concrete Trace
+
+Walk one real path end to end: request to handler, UI event to state update, CLI command to execution, job payload to worker, config value to runtime behavior, or database value to user-visible output. Name the input source of truth, contracts crossed, transformations, async boundaries, error paths, final side effect, and exact pressure point.
+
+For bug hunts, this trace is mandatory before fixing.
+
+### P3: Design Decision
+
+Before changing behavior, infer why the current shape exists: compatibility boundary, deployment shape, persistence model, performance constraint, security boundary, product intent, or migration history. Preserve the core invariant, state the tradeoff, name what fails first at 10x scale, and choose the smallest coherent change.
+
+Do not introduce a new abstraction unless it removes real complexity, matches an existing local pattern, or protects a cross-module invariant.
+
+## Reporting
+
+For small tasks, keep P1/P2/P3 internal and report only the conclusion.
+
+For architecture reviews, bug hunts, risky refactors, deployment issues, auth/payment/data work, or shared contracts, explicitly report:
+
+- P1: map
+- P2: traced path
+- P3: decision rationale
+
+Reports must be concise and grounded in files, commands, runtime behavior, observed code, or verified system state.
+
+## Completion Summary Rule
+
+For non-trivial completed tasks, include a short `下一刀` section at the end of the final delivery report unless there is genuinely no meaningful follow-up.
+For non-trivial completed tasks, include a short `下一刀` section only when verified state shows a concrete next bottleneck, unresolved risk, failing check, deployment gap, review gap, or active-plan item that materially affects the user's stated goal.
+
+Do not manufacture follow-up work just to keep slicing. If the task is reasonably complete and the remaining work would be speculative, low-value polish, or over-engineering, omit `下一刀` and stop at the completion report.
+
+The recommendation is not a question. It must be one concrete, bounded next slice derived from verified state: active plan, todo, handoff, failing checks, review gaps, deployment state, unresolved risk, or observed system behavior.
+When included, the recommendation is not a question. It must be one concrete, bounded next slice derived from verified state: active plan, todo, handoff, failing checks, review gaps, deployment state, unresolved risk, or observed system behavior.
+
+Format:
+
+**下一刀**
+建议切 `<具体方向>`。理由是 `<最影响推进的未闭环点>`。入口是 `<路径/命令/验证面>`。
+
+The recommendation must also explain why this is the next bottleneck, why the slice is sufficient rather than an open-ended continuation, and the entrypoint file, command, route, artifact, or verification surface.
+
+## Research Delegation
+
+When a task requires broad research, repo archaeology, multi-source synthesis, or background surveys, delegate or isolate the research pass when the runtime supports it. Keep the main thread focused on planning, integration, and decisions.
+```

package/assets/reference-configs/handoff-protocol.md

@@ -0,0 +1,38 @@
+# Handoff Protocol
+
+Handoffs make long-running work resumable without trusting chat history.
+
+## When Handoff Is Required
+
+- Verification fails and the work is not resolved in-session
+- The active sprint changes
+- The session is ending
+- The user or agent needs a durable checkpoint before switching sessions or worktrees
+
+## Required Sections
+
+- Goal
+- Decisions
+- Files touched
+- Commands run
+- Checks
+- Blockers
+- Exact next step
+- Resume prompt
+- Source artifacts
+
+## Restore Flow
+
+1. Start a fresh Codex session instead of relying on auto-compact or `codex resume` when the old session is near the limit.
+2. If the current user message lists files under `# Files mentioned by the user`, references `pasted-text.txt`, or includes an explicit attachment/file path, read those current-input files before repo recovery artifacts.
+3. Read source artifacts first: active plan, active contract, review file, latest checks trace, and any user-mentioned files.
+4. Read `.ai/harness/handoff/resume.md`.
+5. Read `.ai/harness/handoff/current.md`.
+6. Read `tasks/current.md` as an orientation snapshot only; in a non-target worktree, compare it with `git show <target>:tasks/current.md`.
+7. Resume from the exact next step.
+
+## Source Of Truth
+
+- Markdown, JSON, and JSONL files remain the canonical handoff surface.
+- SQLite, Codex thread state, and chat history are read models only.
+- `tasks/current.md` is a tracked derived snapshot. It helps branch/worktree orientation, but stale or surprising state must be checked against plans, workstreams, handoff, and checks.

package/assets/reference-configs/harness-overview.md

@@ -0,0 +1,124 @@
+# Harness Overview
+
+This repo uses a shared long-running harness. The durable workflow lives in repo-local artifacts, not in chat memory.
+
+## Adoption Model
+
+Use this file as the first onboarding map after `forge adopt` installs
+or refreshes a repo. The harness gives agents three durable surfaces:
+
+- **Shared standards**: `docs/spec.md`, `docs/reference-configs/`, root
+  `AGENTS.md`, and root `CLAUDE.md` explain stable product intent, coding
+  rules, and local workflow boundaries.
+- **Task contracts**: `plans/`, `tasks/contracts/`, `tasks/reviews/`, and
+  `.ai/harness/checks/` turn a request into scoped implementation work with
+  evidence-backed completion.
+- **Session journal**: `.ai/harness/handoff/`, `tasks/current.md`, and
+  `.ai/harness/events.jsonl` let a new agent session resume from repo state
+  without treating chat history as authority.
+
+The install is not an app scaffold or an agent gateway. It adds a reviewable
+workflow contract around an existing repo, then leaves product code ownership
+with the project.
+
+## Roles
+
+- **Planner** updates `docs/spec.md`, researches constraints, and writes or approves `plans/plan-*.md`.
+- **Generator** implements only against the active sprint contract and the plan's `## Task Breakdown`, leaving `tasks/todos.md` as a deferred-goal ledger, and records task-local implementation judgments in `tasks/notes/<plan-stem>.notes.md`.
+- **Evaluator** runs Waza `/check`, then writes `tasks/reviews/<plan-stem>.review.md` using fresh evidence from `.ai/harness/checks/latest.json` and `.ai/harness/runs/*.json`.
+
+## State Flow
+
+1. `docs/spec.md` captures stable product intent.
+2. `plans/plan-*.md` captures a concrete execution approach.
+3. `tasks/contracts/<plan-stem>.contract.md` defines done for the active sprint.
+4. `tasks/current.md` is a tracked mainline status snapshot derived from workflow artifacts; it is not a live lock, kanban board, or implementation gate.
+5. `tasks/todos.md` is the deferred-goal ledger; the plan's `## Task Breakdown` and active contract carry sprint execution.
+6. `tasks/notes/<plan-stem>.notes.md` records design decisions, deviations, tradeoffs, open questions, and promotion candidates for this sprint only.
+7. `tasks/reviews/<plan-stem>.review.md` records evaluator judgment.
+8. `.ai/harness/policy.json` is the machine-readable workflow contract.
+9. `information_lifecycle` inside `.ai/harness/policy.json` separates notes, raw evidence, reusable assets, advisory memory, and external knowledge.
+10. `agentic_development` inside `.ai/harness/policy.json` captures product, engineering, design, bug-hunt, and review routing.
+11. `external_tooling` inside `.ai/harness/policy.json` captures host install/update defaults for gstack, Waza, gbrain, and required CodeGraph readiness.
+12. `.ai/context/capabilities.json` declares capability prefixes, contract files, architecture modules, and workstream directories.
+13. `.ai/context/context-map.json` indexes stable root context and discoverable capability context derived from the registry.
+14. `documentation` inside `.ai/harness/policy.json` keeps generated docs minimal and moves optional docs to agent-created, evidence-backed output.
+15. `lsp_profiles` inside policy and context-map files select tooling hints per capability.
+16. `worktree_strategy` inside policy tells agents when to isolate contract-level work in `codex/<slug>` worktrees, start execution through `.ai/harness/scripts/contract-worktree.sh start --plan <plan>`, and finish with Waza `/check` plus `.ai/harness/scripts/contract-worktree.sh finish`.
+17. `.ai/harness/handoff/current.md` preserves resumable state across sessions.
+18. `.ai/harness/events.jsonl` and `.ai/harness/runs/*.json` retain lightweight execution traces.
+
+## Session Boundaries
+
+- Exploration and planning are allowed before a contract exists.
+- Before implementation, the plan and contract should both expose a concrete workflow inventory so the agent does not rediscover or guess active artifacts.
+- Implementation should prefer `docs/spec.md`, an approved plan, and an active sprint contract.
+- Claiming completion should include contract verification evidence, a run snapshot, implementation notes, and a passing Waza `/check` review artifact.
+- Stopping a session should refresh `.ai/harness/handoff/current.md` for easier resume; while pending planning orchestration is open, Stop may block once to force a plan completeness self-review before execution.
+- Refresh `tasks/current.md` with `.ai/harness/scripts/refresh-current-status.sh --write --reason <reason>` only at explicit lifecycle boundaries or as a deliberate maintainer action; ordinary hooks should not dirty tracked files.
+- In non-target worktrees, read the target branch snapshot with `git show <target>:tasks/current.md` and verify stale or surprising state against the source artifacts before acting.
+- Use `docs/reference-configs/agentic-development-flow.md` for skill routing and `docs/reference-configs/external-tooling.md` for install/update commands.
+- Use `docs/reference-configs/global-working-rules.md` as the user-level Claude/Codex rule template; keep repo-local workflow contracts in repo files.
+- Externalized reference docs are indexed by `.ai/harness/brain-manifest.json` and checked by `.ai/harness/scripts/check-brain-manifest.sh`. Valuable repo docs can opt into default-brain mirroring with `sync.direction=repo-to-brain`; `post-edit-guard.sh` then calls `.ai/harness/scripts/sync-brain-docs.sh --changed <path>` for that specific file.
+- Contract-level execution should run in an isolated `codex/<task-slug>` worktree. Merge back only after the contract is fulfilled, `tasks/reviews/<plan-stem>.review.md` recommends pass, and the target worktree is clean.
+- Architecture-sensitive work also runs `scripts/check-architecture-sync.sh`: the check keeps the request index derived from `docs/architecture/requests/` and, when policy is strict, blocks finish if the current diff touches a capability with a pending architecture request at or above `architecture.gate_min_severity`.
+- Migration cleans legacy root `scripts/<forge-helper>` files only when content is identifiable as generated forge runtime; ambiguous app-owned root scripts are reported and preserved.
+
+## Documentation Profile
+
+- Default profile: `minimal-agentic`.
+- Required docs: `docs/spec.md` and `docs/architecture/index.md`.
+- Optional docs such as `docs/brief.md`, `docs/tech-stack.md`, `docs/decisions.md`, `docs/architecture.md`, and `docs/packages.md` are created only when the agent has concrete repo evidence or the user asks.
+- Root `specs/` is a legacy scaffold surface; use `docs/spec.md`, `interfaces/`, and tests instead.
+- Use `docs/reference-configs/document-generation.md` for the creation rules.
+
+## Information Lifecycle
+
+- Notes: `tasks/notes/<plan-stem>.notes.md` is task-local and auditable. It should not be treated as durable knowledge by default.
+- Current status: `tasks/current.md` is a tracked derived snapshot for orientation only. It must be regenerated from source artifacts and must not contain hand-written kanban/checklist state.
+- Evidence: `.ai/harness/checks/latest.json` is the current gate, while `.ai/harness/runs/*.json` keeps immutable verification snapshots for later audit.
+- Memory: `docs/researches/`, `tasks/lessons.md`, and gbrain are advisory. Current repo state and evidence override summaries.
+- External knowledge: `brain/<project>/*` stores long-form explanations, runbooks, decisions, and patterns. Hooks may write only explicitly opted-in `repo-to-brain` manifest entries; checks must not require gbrain or MCP.
+- Assets: policies, hooks, scripts, templates, and reference configs only change when a pattern has evidence across tasks or fixtures.
+
+## Trace Evidence
+
+`scripts/verify-sprint.sh` writes `.ai/harness/checks/latest.json` and an immutable `.ai/harness/runs/*.json` snapshot using `schema: forge-run-trace.v1`. The trace is local evidence for workflow grading, not a cloud tracing dependency.
+
+Required v1 fields:
+
+- `run_id`, `generated_at`, `status`, `exit_code`, and `source`
+- `task_profile`, `active_plan`, `contract`, `review`, `worktree`, and `branch`
+- `commands`, `guards`, `handoffs`, `files_changed`, and `allowed_paths_check`
+- `external_acceptance`, `failure_class`, and `next_step`
+
+`scripts/check-task-workflow.sh --strict` validates the latest trace shape when a non-empty latest checks file exists. `scripts/harness-trace-grade.sh --run <trace> --strict` applies the local graders used for workflow regression checks: active plan resolves, contract profile is valid, Human Review Card passes, command evidence exists, and changed files stay inside allowed paths.
+
+## Capability Context
+
+- Do not infer agent context boundaries from physical layout globs such as `apps/*`, `packages/*`, or `services/*`.
+- Declare capabilities in `.ai/context/capabilities.json`; each capability owns prefixes, paired contract files, an architecture module, a workstream directory, and local verification hints.
+- Add selected capabilities with `forge-capability` or `bun .ai/harness/scripts/capability-config.ts add --prefix <path>` when the harness already exists and a full init/migrate/upgrade pass would be too broad.
+- Resolve edited paths through `.ai/harness/scripts/capability-resolver.ts match --path <path>`; longest prefix wins and equal-length ambiguity fails.
+- Treat `.ai/context/agent-context-blocks.txt`, `FORGE_CONTEXT_BLOCKS`, and existing nested `CLAUDE.md`/`AGENTS.md` files as migration inputs or compatibility fallbacks only.
+- Selected capabilities receive paired `CLAUDE.md` and `AGENTS.md` files so Claude Code and Codex share the same local contract.
+- Use `forge capability-context status|request|sync` to keep paired local context files aligned with the registry. The command writes only the controlled `CAPABILITY CONTEXT` block and preserves hand-authored content plus the separate architecture contract block.
+- `.ai/context/capability-source-map.json` is the optional human-edited source-map manifest for capability positioning and source pointers. Missing entries fall back to registry/architecture/workstream metadata; `--auto-fill-positioning` writes deterministic draft entries explicitly, not from hooks.
+- `.ai/harness/capability-context/` is ignored runtime queue state. Post-edit hooks may enqueue requests, and `SessionStart` only reminds the current agent to run `forge capability-context sync --pending --apply`.
+- `SessionStart` also summarizes pending architecture request cards so a resumed agent can see drift debt before claiming finish.
+
+## Initializer and Runtime Model
+
+Maintainer-facing detail on how the initializer and runtime defaults are wired.
+
+- Question flow uses **12 grouped decision points** with harness defaults inferred first.
+- Plan menu is tiered: **Core Plans (A-F)** first, **Custom Presets (G-K)** only when needed.
+- Skill routing is inspection-first: `scripts/inspect-project-state.ts`, `scripts/migrate-workflow-docs.ts`, `assets/workflow-contract.v1.json`.
+- Runtime mode is configurable with template vars: `{{RUNTIME_MODE}}`, `{{RUNTIME_PROFILE}}`, `{{RECOVERY_PROFILE}}`, `{{STATE_PROFILE}}`.
+- Question-pack source of truth: `assets/initializer-question-pack.v4.json`.
+- Generated repos default to the repo-local harness flow: `docs/spec.md -> plans/ -> tasks/contracts/ -> tasks/reviews/ -> .ai/context/context-map.json -> .ai/harness/*`.
+- Generated and self-hosted repos install `.ai/harness/workflow-contract.json` and `.ai/harness/policy.json`.
+- Generated and migrated repos default `external_tooling` to: `complex -> gstack`; `simple -> Waza` with Codex-first runtime copies in `~/.codex/skills`; `knowledge -> gbrain`.
+- `forge install` bootstraps the Codex/Claude runtime pieces for the default workflow: refreshes `forge` skill aliases, installs global Codex/Claude hook adapters, installs Waza skills (`think`, `hunt`, `check`, `health`) and Mermaid through the skills CLI, persists the brain root in `~/.forge/config.json`, and configures CodeGraph MCP for selected host agents. `forge init` remains the explicit legacy bootstrap command for existing Forge automation; `forge setup open/next/close` is the preferred first-run workflow.
+- Other external tooling stays advisory-only: `bash scripts/check-agent-tooling.sh --host both --check-updates`; Waza update checks compare upstream `tw93/Waza` `SKILL.md` hashes without running `npx skills check`; no automatic gstack, gbrain MCP, CodeGraph daemon, or provider setup.
+- Manual distillation stays repo-local: repeated corrections -> `tasks/lessons.md`; deep findings and hidden contracts -> topic-scoped `docs/researches/*.md`; sprint verification evidence -> `tasks/reviews/*.review.md`; durable capability progress -> `tasks/workstreams/`; release history -> `docs/CHANGELOG.md`.