@moretea-labs/forge 1.5.0-rc.1 → 1.5.1

package/assets/reference-configs/agentic-development-flow.md

@@ -1,94 +1,57 @@
 # Agentic Development Flow
 
-Use this reference when choosing the daily agentic development mode. Keep the
-root prompt concise; this file owns the detailed routing.
-
-## Skill Routing
-
-| Work type | Default route | Output |
-|-----------|---------------|--------|
-| Product discovery, demand reality, "is this worth building" | gstack `office-hours` | Product direction or design doc before engineering planning |
-| Complex engineering plan, architecture lock-in, cross-module refactor | gstack `plan-eng-review` | Approved execution plan with architecture, data flow, edge cases, and tests |
-| UI/UX or design-system plan | gstack `plan-design-review` | Design critique and plan fixes before implementation |
-| Small or medium feature/fix plan | Waza `/think` | Concise approved plan, then implementation on request |
-| Bug, regression, error, crash, failing test | Waza `/hunt` | Root cause sentence with evidence before any fix |
-| Implemented diff, pre-merge, release follow-through | Waza `/check` | Review findings, safe fixes, verification, and shipment state |
-| Architecture diagram or system-flow diagram | Markdown Mermaid first, `mermaid` for human HTML | Semantic Mermaid in architecture docs plus optional rendered HTML grounded in repo context |
-
-## forge Command Surface
-
-Use these CLI-backed command facades when the work is about installing,
-migrating, repairing, or verifying this repo-local harness:
-
-| Work type | Command | Boundary |
-|-----------|---------|----------|
-| Decision-complete harness plan | `forge-plan` | Plans only; no repo mutation by default |
-| Review an existing harness plan | `forge-review` | Product, engineering, design, and DevEx review dimensions |
-| Automatic workflow pipeline | `forge-autoplan` | Plan -> two self-review passes -> implementation -> `/check` -> `forge-ship` |
-| Ship finished work | `forge-ship` | Validates finished worktrees, pushes branches, and creates PRs by default |
-| Add harness to an existing repo | `forge-init` | Uses inspector and migration engine; does not create an app stack |
-| Create a new app or module scaffold | `forge-scaffold` | Uses plan catalog A-K, then attaches the harness |
-| Convert legacy workflow surfaces | `forge-migrate` | Archives or preserves user-authored legacy docs |
-| Refresh an installed harness | `forge-upgrade` | Runs manifest-owned upgrade actions only |
-| Add selected capability boundaries | `forge-capability` | Updates capability registry and local contracts without full init/migrate/upgrade |
-| Resolve architecture docs or diagrams | `forge-architecture` | Handles architecture drift requests without full harness refresh |
-| Prepare or resume handoff | `forge-handoff` | Refreshes Codex handoff packets without running full checks |
-| Check deploy and ops config | `forge-deploy` | Read-only deploy/_ops readiness check without publishing |
-| Fix broken current harness behavior | `forge-repair` | Task sync, hook routing, handoff, context, policy, or helper drift |
-| Verify readiness | `forge-check` | Workflow gates, task sync, inspector, migration dry-run, and readiness yellow flags |
-| Generate an upper-layer PRD | `forge-prd` | `$geju` direction pass, Claude-first `claude -p --model opus` drafting, Codex fallback only when needed, PRD in `plans/prds/*.prd.md` |
-| Plan and run a program-level sprint | `forge-sprint` | Upper-layer PRD in `plans/prds/`, sprint backlog in `plans/sprints/`; each row expands through `$think` before plan -> contract -> worktree |
-| Prepare a bounded native goal session | `forge-goal` / `forge:goal` | Codex/Claude `/goal` prompt from detailed PRD or Sprint artifacts; stops to request those documents when missing |
-| Configure GPT Pro local bridge | `forge-gptpro-setup` / `forge:gptpro_setup` | Separates `gptpro_browser` local ChatGPT Web browser/session consults from `gptpro_mcp` ChatGPT Connector MCP sidecar setup; preserves auth, tunnel, and API-billing boundaries |
-| Consult GPT Pro through browser session | `forge-gptpro` / `forge:gptpro` | Uses `gptpro consult/read/continue/open` wording while mapping to `browser-consult`, `browser-session`, `browser-followup`, and `browser-open` engine commands |
-
-`hooks-init`, `docs-init`, and `create-project-dirs` are not public commands.
-They are implementation steps behind `init`, `scaffold`, `migrate`, and
-`upgrade`.
-
-## Due Diligence Levels
-
-P1/P2/P3 is the shared due-diligence protocol underneath the routing.
-
-- `P1_GLOBAL_ARCHITECTURE`: identify real boundaries, entrypoints, owners, authoritative files, dependencies, and out-of-scope areas.
-- `P2_DATA_FLOW_TRACE`: walk one concrete route through requests, UI events, jobs, config, messages, or database values to the final output.
-- `P3_DESIGN_DECISION`: explain why the current shape exists, which invariant must stay true, and why the chosen change is the smallest coherent one.
-
-For small tasks, keep P1/P2/P3 internal and report only the result. For
-`plan-eng-review`, `/hunt`, risky refactors, deployments, auth/payment/data
-work, or shared contracts, report the P1/P2/P3 evidence explicitly.
+Forge owns the workflow contract. External host skills may improve reasoning quality, but they are never required for correctness or lifecycle progress.
+
+## Primary Modes
+
+| Work type | Forge route | Optional enhancement |
+|---|---|---|
+| Understood bounded edit | `/direct` | none required |
+| Plan-only or architecture decision | `/plan` | gstack `plan-eng-review` / `plan-design-review`, Waza `/think` |
+| Bug, regression, failing test, tooling failure | `/debug` | Waza `/hunt` |
+| Diff, acceptance, pre-merge review | `/review` | Waza `/check`, peer `codex-review` / `claude-review` |
+| Release readiness and publication | `/release` | provider-specific release tooling |
+| Concurrency, load, performance, scale verification | `/scale` | benchmark-specific tooling |
+| Product discovery | `/plan` | gstack `office-hours` |
+
+Missing external skills must degrade only the named enhancement. Hooks may suggest Forge modes, but must not route correctness through a third-party skill.
+
+## Public CLI Boundary
+
+The user-facing CLI is intentionally smaller than the implementation surface:
+
+- install/configure: `forge install`, `forge update`, `forge setup`, `forge uninstall`;
+- repository/runtime: `forge adopt`, `forge repo`, `forge runtime`, `forge recovery`;
+- integrations: `forge plugin`, `forge chatgpt`, `forge mcp`, `forge tools`;
+- diagnostics/docs: `forge status`, `forge doctor`, `forge security`, `forge docs`.
+
+Host-dispatch and compatibility machinery such as `hook`, `run`, legacy `controller`, migration helpers, brain sync, and capability-context internals may remain callable for managed workflows but are not normal top-level product entrypoints.
+
+## Due Diligence
+
+P1/P2/P3 remains the shared reasoning protocol:
+
+- `P1_GLOBAL_ARCHITECTURE`: identify real boundaries, entrypoints, owners, authoritative state, dependencies, and out-of-scope areas.
+- `P2_DATA_FLOW_TRACE`: walk one concrete request/event/job/config/data path to the final output.
+- `P3_DESIGN_DECISION`: state the invariant, why the current shape exists, and why the proposed change is the smallest coherent one.
+
+For small work keep this internal. For architecture, debugging, risky refactors, deployment, auth/payment/data, or shared contracts, persist the relevant evidence.
 
 ## Daily Flow
 
-| Agent reads first | Human reviews first |
-|-----------|---------|
-| Current user prompt and referenced files | Human Review Card in `tasks/reviews/<task>.review.md` |
-| `AGENTS.md` / `CLAUDE.md` and active plan | Changed files and active contract scope |
-| Active contract, notes, latest checks, and handoff | Latest trace/checks, residual risk, rollback |
-| `tasks/current.md` only for orientation | External acceptance or manual override |
-
-1. Route the request by intent before reading broadly.
-2. Read the repo-local contract first: `AGENTS.md` or `CLAUDE.md`, `tasks/todos.md`, `tasks/lessons.md`, and `.ai/harness/policy.json`.
-3. Use the selected skill or mode to produce either an approved plan, a root cause, or a review verdict.
-4. When Codex Plan mode, Waza `/think`, or `forge-plan` produces a decision-complete plan, capture it into `plans/` with `.ai/harness/scripts/capture-plan.sh --slug <slug> --title <title>` and the plan text on stdin.
-5. Approved plans must include `## Evidence Contract` with state/progress path, verification evidence, evaluator rubric, stop condition, and rollback surface before execution. `capture-plan.sh` supplies this contract for captured planning output.
-6. Convert approved plans to execution scaffolding with `.ai/harness/scripts/plan-to-todo.sh --plan <plan>`; if approval is already explicit, use `.ai/harness/scripts/capture-plan.sh --status Approved --execute ...`. The plan's own `## Task Breakdown` remains the execution checklist; `tasks/todos.md` remains a deferred-goal ledger. Contract-level plans are projected into a linked `codex/<slug>` worktree when the policy enables it.
-7. For Sprint execution, treat each row in `plans/sprints/*.sprint.md` as a long-task waypoint. Use `$think` to expand the row into a decision-complete `plans/plan-*.md` before coding; do not treat the sprint row itself as an implementation plan.
-8. Use `.ai/harness/scripts/refresh-current-status.sh` for an explicit `tasks/current.md` preview or `--write` snapshot. In non-target worktrees, `git show <target>:tasks/current.md` reads the mainline snapshot, but it never replaces source artifacts.
-9. After substantive changes, run project checks and record evidence in `tasks/`. For contract worktrees, run Waza `/check`, start host-aware external acceptance in parallel, fill the review artifact from both verdicts, then use `forge-ship` for default PR closeout. It calls `.ai/harness/scripts/contract-worktree.sh finish --no-merge`, pushes the `codex/<slug>` branch, and opens a draft PR. Use `forge-ship --local-merge` only when an explicit maintainer workflow wants the older fast-forward merge and cleanup path.
-
-## Passive Plan Capture
-
-- Codex Plan mode and Waza `/think` do not need the user to remember `new-sprint` or `plan-to-todo`.
-- The agent should capture decision-complete planning output with `.ai/harness/scripts/capture-plan.sh`; the script sets `.ai/harness/active-plan`, writes `.ai/harness/active-worktree`, mirrors `.claude/.active-plan`, and writes a timestamped `plans/plan-*.md` artifact.
-- Planning capture is allowed before implementation. Contract, review, notes, and worktree artifacts are generated only after explicit implementation approval; `tasks/todos.md` is not a duplicate of plan tasks.
-- Current-status capture is separate from planning capture: `tasks/current.md` is regenerated from artifacts for orientation, not edited as a plan or task list.
+1. Read the current user request and current Canonical Runtime state first.
+2. Use `/direct`, `/plan`, `/debug`, `/review`, `/release`, or `/scale` according to intent.
+3. Use `rh_context`; request CodeGraph structural context when callers, dependencies, or impact matter.
+4. If a decision-complete plan is useful, capture it into `plans/` as a durable business/engineering artifact. It is not a second Runtime lifecycle authority.
+5. Execute bounded work through Forge repository/Process/Work primitives and collect verification evidence.
+6. Use `/review` plus focused checks before closeout. Optional peer or Waza reviews may add evidence but may not become the only pass condition.
+7. `.ai/harness/session/continuation.md` and `.ai/harness/session/resume.md` are ignored, rebuildable host-session caches only. They never override SQLite/Runtime state, Git source, current user input, or recorded evidence.
+8. A decision that actually requires ChatGPT/user judgement is a Runtime `HandoffItem` surfaced through `rh_inbox`; do not encode it as a session-cache file.
 
 ## Boundaries
 
-- Do not route large architecture decisions through Waza `/think` by default.
-- Do not use gstack plan review for routine local edits where `/think` or direct execution is enough.
-- Hooks may emit advisory Waza `/check` and `/health` route hints on prompt submit. Review/release prompts emit a host-aware `[ExternalAcceptance]` prompt telling the main agent to run the peer reviewer in parallel and paste `## External Acceptance Advice` into the review file; done/finish gates block only on that recorded evidence. Hooks must not mutate files or auto-run peer CLIs based on semantic intent. `[CrossReview]` remains a lightweight debug/spec/test advisory. Plan capture is an agent action after a planning mode produces a concrete plan.
-- Keep `office-hours` for product-demand shaping; use `plan-eng-review` when engineering execution needs to be locked.
-- Treat subagent and parallel-agent execution as a main-agent decision based on task breadth, context impact, raw-log volume, and callable tools. Do not ask the user for spawn confirmation; if no runner is callable or spawning is not worth the context cost, complete the same P1/P2/P3 trace in the main thread and persist evidence-backed conclusions in `docs/researches/`.
-- Do not turn `tasks/current.md` into a hand-written kanban or memo. Use plans, workstreams, notes, reviews, checks, and handoff files as the authoritative surfaces.
+- Do not create a new workflow entity because an old RepoHarness skill once had a command for it.
+- Do not auto-install Waza, gstack, gbrain, or other unrelated third-party skills during ordinary execution.
+- Do not treat session continuation files, `tasks/current.md`, or generated projections as mutable lifecycle authorities.
+- Do not make an Agent process, browser session, hook, or external skill the owner of long-running work. Forge owns durable state; external models provide reasoning and implementation work.
+- Keep compatibility readers isolated and read-only. New writes target the current Forge authority only.

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

@@ -1,56 +1,23 @@
 # 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.
+Forge core correctness does not depend on third-party host skills. The default workflow is owned by Forge `/direct`, `/plan`, `/debug`, `/review`, `/release`, and `/scale`, plus Runtime repository/process/context primitives.
+
+Optional enhancements:
+
+- `gstack`: product discovery and deeper engineering/design-plan review;
+- `Waza`: optional `/think`, `/hunt`, `/check`, `/health` host skills;
+- `gbrain`: optional knowledge tooling;
+- `Mermaid` host skill: optional rendered diagrams; Markdown Mermaid remains sufficient;
+- Forge peer-review helpers (`codex-review`, `claude-review`): optional cross-model acceptance evidence;
+- CodeGraph host MCP/CLI: optional direct host integration. Forge's own `rh_context` structural backend uses the bundled CodeGraph runtime when available.
+
+`forge install` installs the Forge CLI/runtime and managed host adapters. It does **not** install Waza, Mermaid, or cross-review skills unless `--with-external-skills` is explicitly supplied. `forge setup` is the guided readiness workflow; `forge setup check` is the one-shot read-only report.
+
+`forge uninstall` removes Forge-managed Codex/Claude hook adapters only. It does not remove unrelated third-party tooling or user-authored sibling configuration.
+
+`forge update` refreshes Forge-owned user-level runtime by default. Third-party skill updates remain explicit opt-in work.
+
+External tools are never lifecycle authorities. Missing or stale optional tooling may reduce the named enhancement, but must not block ordinary Forge planning, debugging, review, or execution.
 
 ## Detect Safely
 
@@ -153,16 +120,9 @@ 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.
+`CodeGraph` has two integration levels. Forge-internal structural retrieval is provided through `rh_context` and the bundled CodeGraph runtime when available. A global `codegraph` CLI or host MCP entry is optional and exists only for direct Codex/Claude use. Neither replaces workflow checks, tests, architecture evidence, or raw source reads.
 
-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.
+Forge packages a CodeGraph runtime for its own structural context provider and can ensure the repository index without requiring a user-global CLI. `forge tools configure codegraph` remains an explicit optional host integration.
 
 ### Runtime Ownership Boundary
 
@@ -214,7 +174,7 @@ bun add -g @colbymchenry/codegraph && forge tools configure codegraph --target c
 
 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
+`forge install`, `forge adopt`, or explicit tooling configuration. 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

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

@@ -1,18 +1,22 @@
-# Handoff Protocol
+# Session Continuation Protocol
 
-Handoffs make long-running work resumable without trusting chat history.
+This compatibility document describes **host-session recovery only**. It does not define Forge's Runtime `HandoffItem` lifecycle.
 
-## When Handoff Is Required
+A session continuation snapshot lets a fresh Codex/Claude session recover bounded context without trusting chat history or auto-compact. It is ignored, rebuildable cache state under `.ai/harness/session/`.
 
-- 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
+## When A Session Snapshot Is Useful
 
-## Required Sections
+- a host session is ending or approaching context limits;
+- verification is incomplete and a fresh model session will continue the same bounded work;
+- the active source plan/slice changes and a concise recovery snapshot is useful;
+- the agent switches worktrees or host sessions.
+
+A decision that actually requires ChatGPT/user judgement, authorization, or durable attention must be represented as a Runtime `HandoffItem` and surfaced through `rh_inbox`; writing Markdown does not create or resolve that handoff.
+
+## Snapshot Sections
 
 - Goal
-- Decisions
+- Decisions already evidenced by current source/runtime state
 - Files touched
 - Commands run
 - Checks
@@ -23,16 +27,17 @@ Handoffs make long-running work resumable without trusting chat history.
 
 ## 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.
+1. Read the current user message first.
+2. Read Canonical Runtime state for the active Repository/Requirement/Plan/Work when available.
+3. Read authoritative source artifacts and current Git/check evidence.
+4. Read `.ai/harness/session/resume.md` and `.ai/harness/session/continuation.md` only as bounded recovery context.
+5. Treat `tasks/current.md` and other generated ledgers as orientation projections only.
+6. Resume from the verified next step; if state disagrees, Runtime/current user input/source/evidence wins over the session cache.
 
-## Source Of Truth
+## Authority
 
-- 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.
+- Migrated Requirement/Plan/Work lifecycle state is owned by the Canonical Runtime control plane as defined in `docs/architecture/current/control-plane-authority-inventory.md`.
+- Git owns source code and accepted source artifacts; evidence records own their recorded observations.
+- `.ai/harness/session/*` is non-authoritative and rebuildable.
+- Runtime `HandoffItem`/`rh_inbox` is the durable decision/attention handoff surface.
+- Browser login/CAPTCHA foreground handoff is a separate human-interaction-plane concept.

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

@@ -13,7 +13,7 @@ or refreshes a repo. The harness gives agents three durable surfaces:
 - **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
+- **Session cache**: `.ai/harness/session/`, `tasks/current.md`, and
   `.ai/harness/events.jsonl` let a new agent session resume from repo state
   without treating chat history as authority.
 
@@ -25,7 +25,7 @@ with the project.
 
 - **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`.
+- **Evaluator** runs Forge `/review`, then writes `tasks/reviews/<plan-stem>.review.md` using fresh evidence from `.ai/harness/checks/latest.json` and `.ai/harness/runs/*.json`.
 
 ## State Flow
 
@@ -44,8 +44,8 @@ with the project.
 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.
+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 Forge `/review` plus `.ai/harness/scripts/contract-worktree.sh finish`.
+17. `.ai/harness/session/continuation.md` preserves resumable state across sessions.
 18. `.ai/harness/events.jsonl` and `.ai/harness/runs/*.json` retain lightweight execution traces.
 
 ## Session Boundaries
@@ -53,8 +53,8 @@ with the project.
 - 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.
+- Claiming completion should include contract verification evidence, a run snapshot, implementation notes, and a passing Forge `/review` artifact.
+- Stopping a session should refresh `.ai/harness/session/continuation.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.
@@ -118,7 +118,7 @@ Maintainer-facing detail on how the initializer and runtime defaults are wired.
 - 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.
+- Generated and migrated repos route primarily through Forge modes; gstack, Waza, gbrain, and Mermaid are optional host enhancements only.
+- `forge install` bootstraps Forge-owned CLI/runtime and global Codex/Claude hook adapters. Third-party Waza/Mermaid/cross-review skills require explicit `--with-external-skills`; host CodeGraph MCP configuration is optional because Forge structural retrieval uses its bundled backend. `forge setup open/next/close` is the preferred guided 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`.

package/assets/skill-version.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.5.0",
-  "templateVersion": "1.5.0",
+  "version": "1.5.1",
+  "templateVersion": "1.5.1",
   "skillName": "forge",
   "contractId": "tasks-first-harness-v1",
   "compatibility": {

package/assets/templates/helpers/archive-workflow.sh

@@ -283,7 +283,6 @@ fi
 plan_key="$(basename "$plan_file" .md)"
 rm -f ".claude/.plan-state/${plan_key}.todo.md.bak"
 rm -f ".claude/.plan-state/${plan_key}.task-state.json.bak"
-rm -f ".claude/.plan-state/${plan_key}.task-handoff.md.bak"
 
 if [[ -x "scripts/refresh-current-status.sh" ]]; then
   bash "scripts/refresh-current-status.sh" --clear --write --reason "archive-workflow" || true

package/assets/templates/helpers/capture-plan.sh

@@ -103,7 +103,7 @@ extract_task_breakdown() {
 slug=""
 title=""
 status="Draft"
-source_name="codex-plan-or-waza-think"
+source_name="host-plan-or-forge-plan"
 route="planning"
 orchestration_kind="host-plan"
 source_ref=""
@@ -296,13 +296,13 @@ See captured planning output.
 ## Handoff
 
 - Checks file: \`.ai/harness/checks/latest.json\`
-- Session handoff: \`.ai/harness/handoff/current.md\`
+- Session continuation: \`.ai/harness/session/continuation.md\`
 
 ## Evidence Contract
 
 - **State/progress path**: \`${plan_file}\` task breakdown, \`tasks/todos.md\` deferred-goal ledger, \`tasks/contracts/${artifact_stem}.contract.md\`, \`tasks/reviews/${artifact_stem}.review.md\`, and \`tasks/notes/${artifact_stem}.notes.md\`
 - **Verification evidence**: \`.ai/harness/checks/latest.json\`, \`.ai/harness/runs/\`, and the commands named in the captured planning output
-- **Evaluator rubric**: \`tasks/reviews/${artifact_stem}.review.md\` must record a passing Waza /check style recommendation
+- **Evaluator rubric**: \`tasks/reviews/${artifact_stem}.review.md\` must record a passing Forge /review style recommendation
 - **Stop condition**: all task breakdown items are complete, sprint verification passes, and the review recommends pass
 - **Rollback surface**: before execution remove \`${plan_file}\`; after execution revert branch \`codex/${slug}\` or the generated task artifacts
 

package/assets/templates/helpers/check-task-workflow.sh

@@ -724,8 +724,8 @@ helper_compat_dir="$(policy_get '.harness.helper_compat_dir' 'scripts')"
 helper_source="$(policy_get '.harness.helper_source' 'package')"
 context_map_file="$(policy_get '.context.map_file' '.ai/context/context-map.json')"
 brain_manifest_file="$(policy_get '.information_lifecycle.external_knowledge.manifest_file' '.ai/harness/brain-manifest.json')"
-handoff_file="$(policy_get '.harness.handoff_file' '.ai/harness/handoff/current.md')"
-resume_file="$(policy_get '.handoff_resume.resume_packet_file' '.ai/harness/handoff/resume.md')"
+handoff_file="$(policy_get '.session.continuation_file' '.ai/harness/session/continuation.md')"
+resume_file="$(policy_get '.session.resume_file' '.ai/harness/session/resume.md')"
 sprints_dir="$(policy_get '.sprints.dir' 'plans/sprints')"
 sprint_marker_file="$(policy_get '.sprints.active_marker_file' '.ai/harness/sprint/active-sprint')"
 legacy_sprints_dir="tasks/sprints"

package/assets/templates/helpers/codex-handoff-resume.sh

@@ -200,8 +200,8 @@ latest_global_handoff() {
   find "$codex_home/handoffs" -maxdepth 1 -type f -name 'handoff-*.md' 2>/dev/null | sort | tail -1
 }
 
-resume_file="$(safe_repo_file "$(policy_get '.handoff_resume.resume_packet_file' '.ai/harness/handoff/resume.md')" '.ai/harness/handoff/resume.md' '.ai/harness/')"
-repo_handoff="$(safe_repo_file "$(policy_get '.harness.handoff_file' '.ai/harness/handoff/current.md')" '.ai/harness/handoff/current.md' '.ai/harness/')"
+resume_file="$(safe_repo_file "$(policy_get '.session.resume_file' '.ai/harness/session/resume.md')" '.ai/harness/session/resume.md' '.ai/harness/')"
+repo_handoff="$(safe_repo_file "$(policy_get '.session.continuation_file' '.ai/harness/session/continuation.md')" '.ai/harness/session/continuation.md' '.ai/harness/')"
 checks_file="$(safe_repo_file "$(policy_get '.harness.checks_file' '.ai/harness/checks/latest.json')" '.ai/harness/checks/latest.json' '.ai/harness/')"
 research_dir="$(safe_repo_file "$(policy_get '.tasks.research_dir' 'docs/researches')" 'docs/researches' 'docs/researches')"
 todo_file="$(safe_repo_file "$(policy_get '.tasks.todo_file' 'tasks/todos.md')" 'tasks/todos.md' 'tasks/')"
@@ -222,7 +222,7 @@ cat > "$resume_file" <<EOF_RESUME
 
 ## Resume Prompt
 
-You are starting a fresh Codex session for an existing long-running task. Do not rely on prior chat history or Codex auto-compact. First read the source artifacts listed below, then continue from the exact next step in the repo handoff.
+You are starting a fresh Codex session for an existing long-running task. Do not rely on prior chat history or Codex auto-compact. First read the current user input and Canonical Runtime state when available, then source/evidence artifacts, and use the session continuation cache only to recover the exact next step.
 
 Current prompt files first:
 - 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 the repo recovery artifacts below.
@@ -243,7 +243,7 @@ Conditional first reads:
 - Global handoff: ${global_handoff:-(none)}
 
 Execution rules:
-- Treat filesystem artifacts as the source of truth.
+- Treat Canonical Runtime lifecycle state as authoritative for migrated Requirement/Plan/Work state; treat Git source/evidence as authoritative in their own domains and session Markdown as rebuildable cache only.
 - Decide in the main agent whether to use subagents, parallel sidecars, sidecar \`codex exec --json\`, or a bounded main-thread trace for broad research/log scans based on context impact and callable tools; do not ask the user for spawn confirmation.
 - Keep deep research conclusions in \`${research_dir}/\`, not only in chat.
 - Do not run \`/compact\` as the primary recovery path.
@@ -251,7 +251,7 @@ Execution rules:
 
 ## Source Artifacts
 
-- Repo handoff: ${repo_handoff}
+- Session continuation: ${repo_handoff}
 - Resume packet: ${resume_file}
 - Checks: ${checks_file}
 - Todo: ${todo_file}