@moretea-labs/forge 1.5.0-rc.1

package/assets/reference-configs/heartbeat-triage.md

@@ -0,0 +1,57 @@
+# Heartbeat Triage
+
+Heartbeat triage is the repo-local scheduled discovery loop. It records findings
+for a human to review; it does not approve plans, execute fixes, spawn agents,
+open PRs, or install a persistent scheduler.
+
+## Command
+
+Run from the repository root:
+
+```bash
+bash .ai/harness/scripts/heartbeat-triage.sh run --source scheduled
+```
+
+The command appends a run section to `.ai/harness/triage/inbox.md` and writes a
+JSON snapshot under `.ai/harness/runs/`. Each run records:
+
+- `workflow-check`: `bash .ai/harness/scripts/check-task-workflow.sh --strict`
+- `sprint-next`: `bash .ai/harness/scripts/sprint-backlog.sh next` when an active sprint
+  marker exists, with a read-only sprint-file fallback when it does not
+- `drift-requests`: pending files under `docs/architecture/requests/`
+
+## cron
+
+Example cron entry for a local checkout:
+
+```cron
+17 8 * * * cd /path/to/repo && bash .ai/harness/scripts/heartbeat-triage.sh run --source scheduled >/tmp/forge-heartbeat.log 2>&1
+```
+
+## loop
+
+Example long-running loop for a supervised terminal, launch wrapper, or local
+process manager:
+
+```bash
+while true; do
+  cd /path/to/repo && bash .ai/harness/scripts/heartbeat-triage.sh run --source scheduled
+  sleep 86400
+done
+```
+
+## Adoption Review
+
+Every run includes an "Adoption review due" date fourteen days out. The review
+question is narrow: did the inbox produce any human-accepted triage item? If no
+item is accepted during the review window, remove the scheduler and keep the
+runner as an on-demand diagnostic command.
+
+## Guardrails
+
+- Keep scheduler installation manual and host-local.
+- Treat workflow failures and drift requests as inbox entries, not process
+  crashes.
+- Keep `.ai/harness/triage/inbox.md` as runtime state, not a source-of-truth
+  plan or task ledger.
+- Keep execution authority in the normal plan -> contract -> verify flow.

package/assets/reference-configs/hook-operations.md

@@ -0,0 +1,96 @@
+# Hook Operations Reference
+
+> Full troubleshooting runbook: `brain/forge/runbooks/runbook-forge-hook-troubleshooting.md` (`gbrain` slug `runbooks/runbook-forge-hook-troubleshooting`).
+
+## Hook Authority Map
+
+Start with the shortest truth path:
+
+1. `~/.claude/settings.json` and `~/.codex/hooks.json` wire host events into `forge-hook` (bash-shim installs use `bash ~/.forge/hook-shim.sh <hook>.sh`), with `forge hook` as the compatibility fallback.
+2. The dispatcher checks whether the current repo is opted in through `.ai/harness/workflow-contract.json` (and, for the bash shim, that its primary root is trusted in `~/.forge/trusted-repos`).
+3. The route registry selects the ordered hook scripts for that event and route.
+4. Hook scripts resolve **central-first**: env `FORGE_HOOK_SOURCE` (`repo` | `central` | absolute dir) → repo policy pin `"hook_source": "repo"` in `.ai/harness/policy.json` → the central copy → vendored `<repo>/.ai/hooks` fallback. The central copy is `~/.forge/hooks/` (installed by `scripts/forge.sh install`, stamped with `.version`) on the bash chain, and the packaged `assets/hooks/` inside the globally installed CLI on the `forge-hook` chain.
+
+Central-first means one `install` (or one CLI upgrade) updates hook behavior for every trusted opt-in repo at once; vendored `.ai/hooks` copies are inert defaults unless the repo pins `"hook_source": "repo"`. Missing advisory scripts warn and skip, but required guard routes still fail closed. `forge doctor` and `scripts/forge.sh status` report which source is active for the current repo.
+Generated host adapter commands carry a 30 second timeout; long-running work belongs in explicit CLI commands, not hook foreground execution.
+
+`forge adopt`, migration, and new-project scaffold paths do not copy the full hook runtime into ordinary downstream repos. Without a `"hook_source": "repo"` pin they prune stale top-level `.ai/hooks/*.sh` entry scripts and refresh only `.ai/hooks/lib/` helper libraries plus a README tombstone, because active execution should come from the user-level adapter and packaged hooks. Repos that intentionally develop or override hooks must set `"hook_source": "repo"` before syncing a full vendored hook runtime.
+
+`UserPromptSubmit.default` dispatches to the active `prompt-guard.sh` resolved by the central-first hook source decision. For ordinary repos that means the packaged/user-level runtime; `.ai/hooks/prompt-guard.sh` is active only when the repo pins `"hook_source": "repo"`. The shell layer parses host prompt JSON, reads workflow files, performs capture side effects, and renders host-safe output; it pipes `{"prompt": ...}` into `forge-hook prompt-guard-decide`, which owns every prompt-text intent classifier (Unicode-aware, in `src/cli/hook/prompt-intents.ts`) plus the intent x state decision table and returns one verdict JSON line (action, intent facts, derived strings). If the engine is unreachable or predates the protocol, the prompt layer degrades to a one-shot advisory instead of guessing; there is no shell fallback decision table.
+
+Prompt-layer plan/spec/contract gates are advisory routing only. `PreToolUse.edit` keeps real path/scope and private-surface safety checks authoritative, while the plan-state gate defaults to `advice`; repositories may opt into `enforce` or `off` through policy `.guards.edit_plan_gate` or `FORGE_EDIT_PLAN_GATE`. Done-claim gates block only on real failed or missing completion evidence, not on workflow ceremony.
+
+If you are asking "which hook file should I edit?", default to `assets/hooks/` for product changes and mirror into `.ai/hooks/` only for this self-host repo or another repo that pins `"hook_source": "repo"`; runtime pickup outside repo-pinned development happens on the next `install`/CLI upgrade because hooks resolve central-first.
+After installing or refreshing `~/.codex/hooks.json`, open Codex Settings and mark the user-level hook config as trusted; otherwise Codex will not execute it.
+Repo-local `.claude/settings.json` and `.codex/hooks.json` hook adapters are legacy project-level config and should be retired during migration.
+
+`Stop.default` routes through `stop-orchestrator.sh`. On Codex, dispatcher stdout stays quiet for ordinary successful hooks, but valid Stop decision JSON is forwarded so Codex can honor a one-shot planning completeness block; success stderr such as handoff refresh noise remains suppressed.
+
+`SessionStart.default` runs `session-start-context.sh` and `security-sentinel.sh` under one adapter entry and aggregates their context into one JSON payload. The security sentinel is changed-only and advisory; stale repo-local copies emit one drift reminder instead of blocking the host session.
+
+Use this command for an explicit read-only audit:
+
+```bash
+forge security scan --json
+```
+
+`PostToolUse.always` runs one merged observer, `post-tool-observer.sh` (JSONL trace + lightweight advisories); the trace file `.claude/.trace.jsonl` is the single tool-trace record.
+
+`PostToolUse.edit` runs local edit reminders, the FirstPrinciples
+anti-overengineering advisory, then the downstream sync chain: architecture
+drift record, context contract sync, capability-context queueing, repo-to-brain
+mirror sync, and active contract verification. These stages remain advisory. A
+failed downstream stage must emit one `[SyncChain] WARN: ...` line and let the
+edit hook exit 0 so local editing is not blocked by maintenance drift. The
+FirstPrinciples advisory reviews only the current file diff and asks whether new
+dependencies, compatibility branches, abstractions, config surfaces, or
+branch-heavy logic truly need to exist; it must not override trust-boundary
+validation, data-loss prevention, security, accessibility, or explicit
+user-requested behavior.
+
+`.ai/harness/scripts/sync-brain-docs.sh --changed <path>` is hot-path optimized: the PostEdit hook starts it only when the changed repo path appears in the brain manifest. The script still owns authoritative JSON parsing and containment checks. Source files that resolve outside the repo, or brain targets that resolve outside the configured brain root through symlinks, are rejected.
+
+Architecture drift requests use the current capability match as the pending pointer owner. Recording a newer request removes stale pending index lines for the same capability/path. Archiving a request removes it from the index and clears any local `AGENTS.md`/`CLAUDE.md` contract block that still points at that request.
+
+## Hook Failure Playbook
+
+When a hook blocks work:
+
+1. Read the terminal output first.
+2. Read `.ai/harness/failures/latest.jsonl` for the durable failure record.
+3. Read `.claude/.trace.jsonl` for surrounding tool activity and timing.
+4. Use the external runbook for extended examples and historical failure modes.
+
+Common guards:
+
+- `PlanStatusGuard` (edit layer): implementation edit attempted with no active approved plan, or the plan is in the wrong state; the prompt layer emits the same guard name as advisory guidance only.
+- `ContractGuard`: the approved plan has not been projected into contract/review/notes scaffolding.
+- `ContractGuard`: completion was claimed without passing contract verification.
+- `WorktreeGuard`: writes were attempted from the wrong worktree.
+
+## Architecture Drift Hooks
+
+Hook scope is detect, classify, record, and remind:
+
+- `.ai/harness/scripts/architecture-queue.sh` writes requests/events.
+- `.ai/harness/scripts/workstream-sync.sh` maintains durable capability workstreams.
+- `.ai/harness/scripts/context-contract-sync.sh` updates only controlled local agent-context blocks.
+- `forge capability-context request` may enqueue ignored runtime work under `.ai/harness/capability-context/`; `SessionStart` reminds the current agent to run `forge capability-context sync --pending --apply`.
+
+Agents, not hooks, author semantic snapshots and diagrams.
+Hooks do not spawn LLM agents in `PostEdit`.
+
+## Self-Host vs Generated Parity Contract
+
+This repo has two hook surfaces on purpose:
+
+- `assets/hooks/` defines what downstream repos and the central runtime receive (`install` copies it to `~/.forge/hooks/`; the npm package ships it for `forge-hook`).
+- `.ai/hooks/` defines this self-hosted repo's current runtime behavior; the self-host policy pins `"hook_source": "repo"` so hook development runs live working-tree code instead of the central copy.
+- User-level `~/.claude/settings.json` and `~/.codex/hooks.json` are host adapters only.
+
+Every hook change should state whether it affects `self-host`, `generated`, or
+`both`. If behavior must stay aligned, update both surfaces in the same change.
+
+## Verification Checklist
+
+Run after hook or workflow contract changes: `bun run check:task`, `bash .ai/harness/scripts/check-task-sync.sh`, `bash .ai/harness/scripts/check-task-workflow.sh --strict`, and `bash scripts/migrate-project-template.sh --repo . --dry-run`. Reserve `bun run check:main` for the frozen candidate so its one full-suite receipt can be reused.

package/assets/reference-configs/release-deploy.md

@@ -0,0 +1,40 @@
+# Release Process & Deployment Reference
+
+> Externalized: full runbook lives in default brain.
+
+## Default Brain
+
+- File vault: `brain/forge/runbooks/runbook-agentic-release-deploy.md`
+- gbrain slug: `runbooks/runbook-agentic-release-deploy`
+
+## Repo Role
+
+This repo keeps deployment contract surfaces under `deploy/` and private runtime
+state under ignored `_ops/`. Detailed release patterns, Cloudflare examples, and
+rollback playbooks belong in the external runbook.
+
+## Webapp Release Shape
+
+- For a SaaS webapp with public SEO/SSR plus authenticated workspace, prefer one
+  TanStack Start + Vite Cloudflare Worker under `apps/web`.
+- Route `/` as SSR/prerender-capable public landing; route `/app` as client-only
+  with route-level `ssr: false` when it owns auth, WebGL, or browser-only state.
+- Deploy Start/Workers apps with `wrangler deploy`, not `wrangler pages deploy`.
+- Keep API, Agent, MCP, queue, and storage Workers separate only when they own
+  distinct runtime authority; static `apps/marketing` Pages is legacy/rollback
+  or content scope, not the default SEO/SSR webapp shape.
+
+## Release Filings
+
+Release filing documents live under `deploy/release-checklists/` and must use a
+`YYMMDD-<package>-<version>.md` filename, for example
+`260531-forge-0.1.3.md`. The filing records the exact release scope,
+source commit, verification, publish status, and any hold reason. Skill eval
+evidence must record `full_test_count`, `dry_run_ratio`, `grader_pass_rate`, and
+`effectiveness_authority`; full-test evidence is authoritative, dry-run-heavy
+evidence is non-authoritative, and missing eval evidence must be called out as
+unavailable. Readiness yellow flags from `forge-check` must be recorded
+with either the accepted reason or the concrete repair command, including Waza
+staging drift, gbrain warnings, CodeGraph version drift, or non-authoritative
+skill eval evidence. Do not rely only on npm or GitHub release metadata for this
+local audit trail.

package/assets/reference-configs/spa-day-protocol.md

@@ -0,0 +1,14 @@
+# Spa Day Protocol
+
+> Externalized: full runbook lives in default brain.
+
+## Default Brain
+
+- File vault: `brain/forge/runbooks/runbook-agentic-spa-day-protocol.md`
+- gbrain slug: `runbooks/runbook-agentic-spa-day-protocol`
+
+## Repo Role
+
+This file is only a pointer. Use the external runbook for recurring rule
+consolidation, docs pruning, lesson graduation, and contract hygiene cadence.
+

package/assets/reference-configs/sprint-contracts.md

@@ -0,0 +1,89 @@
+# Task Contracts and Sprint Backlogs
+
+Task contracts are the repo-local agreement between planner, generator, and evaluator.
+Sprint backlogs are the ordered program layer that expands into task contracts.
+
+## Three-Layer Glossary
+
+The word "sprint" historically named a single execution slice in this harness. The current vocabulary is exactly three layers:
+
+| Term | Layer | Artifact | Owner |
+|------|-------|----------|-------|
+| **PRD** | Product planning | `plans/prds/<stamp>-<slug>.prd.md` using `.claude/templates/prd.template.md`; lifecycle `Draft -> Approved -> Superseded` | PM + architect planning |
+| **Sprint** | Program execution backlog | `plans/sprints/<stamp>-<slug>.sprint.md` (Source PRD + Architecture Notes + ordered Backlog + Execution Log) | PM + architect planning |
+| **Task Contract** | Execution slice | `tasks/contracts/<plan-stem>.contract.md` plus its review/notes trio | One plan, one worktree |
+
+- A PRD decomposes `docs/spec.md` intent into product direction, users, success criteria, acceptance scenarios, module behavior, data model, performance targets, and developer handoff. `forge-prd` writes PRDs with compact/standard tiers and evidence rules for `[UNKNOWN]` / `[UNVERIFIED]` facts.
+- A Sprint decomposes a PRD or `docs/spec.md` into an ordered backlog; each backlog task executes as one task-contract slice through the existing plan -> contract -> worktree -> verify flow.
+- `tasks/todos.md` stays the deferred-goal ledger; it never carries the sprint backlog or any active checklist.
+- Legacy filenames: `verify-sprint.sh` and `new-sprint.sh` predate the program layer and are kept for downstream compatibility. Read them as task-contract verification helpers. New generated artifact headings and plan metadata should use **Task Contract** and **Task Review**.
+- Sprint lifecycle: `Draft -> Approved -> Executing -> Done -> Archived`, tracked in the sprint file's `> **Status**:` line. Where the sprint layer is installed, `scripts/sprint-backlog.sh` is the compatibility command and delegates to the installed helper runtime under `.ai/harness/scripts/`; `.ai/harness/sprint/active-sprint` (runtime state, not committed) marks the single active sprint. Harness installs predating the sprint layer do not ship the helper, so check for the script before invoking it. `check-task-workflow.sh` rejects Approved/Executing sprints whose PRD/source section is placeholder-only or whose backlog rows lack a concrete acceptance line.
+
+## Inventory First
+
+- Every execution-ready `plans/plan-*.md` should name the active plan, owning worktree, expected contract, review, notes file, deferred-goal ledger, `.ai/harness/checks/latest.json`, `.ai/harness/runs/`, scope authority, plan switching rule, and worktree isolation path.
+- Every `tasks/contracts/*.contract.md` should repeat the source plan, deferred-goal ledger, review, notes, checks, run snapshots, scope gate, and completion gate.
+- If the inventory is incomplete, keep the plan in Draft or revise the contract before editing implementation files.
+
+## Required Sections
+
+- Goal
+- Scope and non-goals
+- Allowed paths
+- Task Profile
+- Delegation contract
+- Exit criteria
+- Verification commands
+- Risks and rollback point
+
+## Task Profiles
+
+New task contracts should declare `> **Task Profile**:` before ownership
+metadata. The profile sets the default human expectation for writable scope and
+review focus.
+
+| Profile | Default expectation |
+|---|---|
+| `code-change` | Runtime behavior may change within the contract's explicit allowed paths. |
+| `docs-only` | Documentation, plans, notes, and reviews only; `src/` and `tests/` are not allowed by default. |
+| `ledger-closeout` | Close already-landed workflow evidence only; runtime source, tests, and hook paths are not allowed by default. |
+| `migration` | Scripts, templates, assets, docs, and tests may change; preserve user-authored files. |
+| `eval-only` | Eval, fixture, run, docs, and review surfaces only; runtime `src/` is not allowed by default. |
+| `delegated-run` | Worker edits only contract-defined paths; parent remains the gate owner. |
+
+Older contracts without `Task Profile` remain valid as legacy contracts, but
+new generated contracts should include the field.
+
+## Delegation Contract Fields
+
+New contracts include a `## Delegation Contract` YAML block between allowed paths and exit criteria. This block is the forward-compatible contract-kappa surface for future delegated execution; it is metadata unless a runner such as `contract-run` consumes it.
+
+- `budget`: optional limits for `tokens`, `tool_calls`, and `wall_time_minutes`. `null` means the current session/default command limits apply; explicit numbers are hard limits only where the runner can enforce them and otherwise advisory in the run manifest.
+- `permission_scope`: the execution permission model. The default `mode: inherit_allowed_paths` means worker edits are limited by the contract `allowed_paths`; `writable_paths: []` means no narrower override; `network: inherited` means no new network permission is granted by the contract itself.
+- `roles`: named responsibilities for `parent`, `explorer`, `worker`, and `verifier`. The parent remains the approval/checkpoint owner; explorer and verifier are read-only; worker may edit only within `allowed_paths` or a narrower `writable_paths` list. The verifier rubric is exactly the contract `exit_criteria`.
+
+Existing contracts without this block remain valid. `.ai/harness/scripts/verify-contract.sh` continues to evaluate only the `exit_criteria` YAML block, so adding delegation metadata must not make old or new contracts fail verification.
+
+## Verification Execution Boundary
+
+`verify-contract.sh --read-only` is read-only for contract state writes only: it does not rewrite the contract `> **Status**:` line. It still executes `tests_pass` with Bun and `commands_succeed` in a non-login Bash with `BASH_ENV` unset so hook-driven done gates can verify the same exit criteria as an explicit maintainer run without sourcing host shell profiles. Do not put mutating commands in `commands_succeed` unless the contract deliberately treats that side effect as part of verification.
+
+## Status Rules
+
+- `Pending`: drafted but not approved for execution
+- `Active`: approved for implementation
+- `Blocked`: waiting on a missing dependency or decision
+- `Verified`: all machine checks passed; awaiting or holding review
+- `Archived`: sprint is complete or superseded
+
+## Review Coupling
+
+- A contract is not truly done until the matching review file records a passing recommendation.
+- `tasks/reviews/<plan-stem>.review.md` should be filled from Waza `/check` after verification and cite the contract, implementation notes, checks file, run snapshot, `## External Acceptance Advice`, and any manual observations.
+- `tasks/notes/<plan-stem>.notes.md` captures task-local decisions and should be archived or promoted deliberately, not left as hidden long-term memory.
+
+## Worktree Lifecycle
+
+- When `.ai/harness/policy.json` has `worktree_strategy.auto_for_contract_tasks: true`, `.ai/harness/scripts/plan-to-todo.sh --plan <approved-plan>` starts a linked `codex/<slug>` worktree instead of mutating the primary tree.
+- Execute the sprint in that linked worktree. The primary worktree remains a merge target and must stay clean before merge-back.
+- After implementation, run Waza `/check` so the review file recommends pass, record passing `## External Acceptance Advice` from the peer reviewer or a concrete manual override, then run `.ai/harness/scripts/contract-worktree.sh finish`. The finish command gates on external acceptance before `verify-sprint.sh`, commits the branch, and fast-forwards the target branch only when the target worktree is clean.

package/assets/reference-configs/workflow-orchestration.md

@@ -0,0 +1,14 @@
+# Workflow Orchestration Reference
+
+> Externalized: full pattern lives in default brain.
+
+## Default Brain
+
+- File vault: `brain/forge/patterns/pattern-agentic-workflow-orchestration.md`
+- gbrain slug: `patterns/pattern-agentic-workflow-orchestration`
+
+## Repo Role
+
+Concrete project execution still flows through plans, contracts, tasks,
+workstreams, checks, and handoff files. The general multi-phase orchestration
+pattern belongs in the external pattern page.

package/assets/skill-hooks.json

@@ -0,0 +1,41 @@
+{
+  "$comment": "Deprecated zero-overhead lifecycle extension point. Default scripts arrays stay empty and this is not part of the Codex/Claude harness runtime path.",
+  "status": "deprecated-zero-overhead",
+  "events": {
+    "pre-init": {
+      "type": "sync",
+      "description": "Runs before project initialization. Failure aborts init.",
+      "scripts": []
+    },
+    "post-init": {
+      "type": "advisory",
+      "description": "Runs after project initialization. Failure is a warning only.",
+      "scripts": []
+    },
+    "pre-assemble": {
+      "type": "sync",
+      "description": "Runs before template assembly. Failure aborts assembly.",
+      "scripts": []
+    },
+    "post-assemble": {
+      "type": "advisory",
+      "description": "Runs after template assembly. Failure is a warning only.",
+      "scripts": []
+    },
+    "pre-migrate": {
+      "type": "sync",
+      "description": "Runs before project migration. Failure aborts migration.",
+      "scripts": []
+    },
+    "post-migrate": {
+      "type": "advisory",
+      "description": "Runs after project migration. Failure is a warning only.",
+      "scripts": []
+    },
+    "on-version-change": {
+      "type": "advisory",
+      "description": "Runs when a version change is detected. Failure is a warning only.",
+      "scripts": []
+    }
+  }
+}

package/assets/skill-version.json

@@ -0,0 +1,189 @@
+{
+  "version": "1.5.0",
+  "templateVersion": "1.5.0",
+  "skillName": "forge",
+  "contractId": "tasks-first-harness-v1",
+  "compatibility": {
+    "minClaudeCodeVersion": "1.0.0",
+    "minBunVersion": "1.0.0"
+  },
+  "breakingChanges": [
+    {
+      "version": "2.0.0",
+      "description": "Migrated from governance/ to assets/initializer-question-pack.v1.json"
+    },
+    {
+      "version": "2.3.0",
+      "description": "Added lifecycle hook system and version stamp in generated projects"
+    },
+    {
+      "version": "2.4.0",
+      "description": "Promoted cross-agent task-sync contracts, skill eval assets, and milestone-only progress tracking"
+    },
+    {
+      "version": "3.0.0",
+      "description": "Upgraded generated repos to a shared long-running harness with spec, sprint review, handoff, structured checks, and read-only Claude auto memory intake signals"
+    },
+    {
+      "version": "3.1.0",
+      "description": "Added run_id-linked verification, 5-dimensional harness profiles, and structured failure_class logging with summary tooling"
+    },
+    {
+      "version": "3.2.0",
+      "description": "Introduced a versioned workflow contract manifest, inspection-first routing, and first-class legacy workflow-doc migration"
+    },
+    {
+      "version": "3.2.1",
+      "description": "Added progressive context and harness policy surfaces, plus fixed nested AGENTS placement and custom-plan monorepo drift"
+    },
+    {
+      "version": "3.3.0",
+      "description": "Removed legacy Skill Factory and auto-memory surfaces, and added guidance-only external tooling detection plus migration defaults"
+    },
+    {
+      "version": "3.4.0",
+      "description": "Added Codex-first Waza harness detection, update drift reporting, and verified Codex runtime sync guidance"
+    },
+    {
+      "version": "3.5.0",
+      "description": "Added agentic development routing, selector-hooked functional-block CLAUDE/AGENTS context generation, removed repo-local Claude hook shims, and hardened workflow migration checks"
+    },
+    {
+      "version": "3.6.0",
+      "description": "Added minimal-agentic documentation generation, functional-block LSP profile metadata, conflict-triggered Codex worktree validation policy, and explicit notes/evidence/asset lifecycle artifacts"
+    },
+    {
+      "version": "4.0.0",
+      "description": "Removed docs/PROGRESS.md and root specs from default generated surfaces, moved durable progress to tasks/workstreams, and added _ref/_ops path governance with hook guards"
+    },
+    {
+      "version": "4.0.1",
+      "description": "Added a contract-driven upgrade strategy for legacy workflow reconfiguration and cleanup, plus a global Claude/Codex working-rules reference"
+    },
+    {
+      "version": "4.0.2",
+      "description": "Installs all router entrypoints into generated repos and hardens capability discovery against ignored worktree caches"
+    },
+    {
+      "version": "5.0.0",
+      "description": "Renamed the public skill surface to forge, added action-style command facades, externalized optional long docs to the default brain, and kept reusable-workflow packaging behind advisory hooks plus user-approved autoplan"
+    },
+    {
+      "version": "5.0.1",
+      "description": "Adds the plugin architecture context map, ignores repo-local runtime trace state, and fixes installed-copy sync through symlinked legacy fallback paths"
+    },
+    {
+      "version": "5.0.2",
+      "description": "Excludes ignored repo-local runtime state from installed-copy sync outputs"
+    },
+    {
+      "version": "5.1.0",
+      "description": "Adds filesystem-owned Evidence Contract gates for approved plans and hardens Waza tooling integrity checks across managed skill directories and shared rules"
+    },
+    {
+      "version": "5.1.1",
+      "description": "Refreshes stale reference and architecture docs for the current forge command, hook, migration, eval, plugin, and minimal-documentation contracts"
+    },
+    {
+      "version": "5.1.2",
+      "description": "Adds generated Codex hook adapter support through .codex/hooks.json while keeping .ai/hooks as the shared implementation layer"
+    },
+    {
+      "version": "5.2.0",
+      "description": "Adds passive plan capture, opt-in repo-to-brain document sync, and required CodeGraph readiness for Codex code navigation"
+    },
+    {
+      "version": "5.2.1",
+      "description": "Fixes terse GO approval prompts so post-plan execution cannot bypass the plans workflow gate"
+    },
+    {
+      "version": "5.2.2",
+      "description": "Starts a Draft plan workflow when explicit Waza think or Codex Plan prompts begin, while preserving approval-time execution gates"
+    },
+    {
+      "version": "5.2.3",
+      "description": "Expands anchored approval intent variants so natural post-plan approval wording reaches capture and projection gates without broadening bug-fix implementation wording"
+    },
+    {
+      "version": "0.4.0",
+      "description": "Retires the separate 5.x generated workflow compatibility line; package, skill, and template stamps now share the forge npm release version"
+    },
+    {
+      "version": "0.4.1",
+      "description": "Adds runtime safety fixes for session-scoped CodeGraph routing, central-first hook execution, and the tasks/todos workflow-document migration"
+    },
+    {
+      "version": "0.4.2",
+      "description": "Adds the PRD-to-Sprint planning hierarchy, isolates generated-project helper runtime under .ai/harness/scripts, and installs the subagent return-channel guard"
+    },
+    {
+      "version": "0.4.3",
+      "description": "Adds bundled runtime docs lookup, init-hook bootstrap audit guidance, first-principles edit guard coverage, and slimmer generated reference-doc assets"
+    },
+    {
+      "version": "0.5.0",
+      "description": "Splits user-level runtime refresh from repo adoption, adds package-dispatched helper commands, documents the eight managed hook routes, and prepares the release README surface"
+    },
+    {
+      "version": "0.5.1",
+      "description": "Fixes CodeGraph readiness detection by preferring the local platform bundle before the npm shim and syncs the downstream helper template"
+    },
+    {
+      "version": "0.5.2",
+      "description": "Adds weekly tooling-update advisory caching, reviewed security exceptions, gbrain fast-doctor warning handling, and Claude review transcript recovery"
+    },
+    {
+      "version": "0.5.3",
+      "description": "Fixes forge update --version so the update command can install a pinned package version without being intercepted by the top-level CLI version flag"
+    },
+    {
+      "version": "0.6.0",
+      "description": "Adds the transactional adoption planner foundation with protocol v1 dry-run plans, manifest-owned bootstrap templates, experimental TypeScript apply, atomic writes, and rollback metadata"
+    },
+    {
+      "version": "0.7.0",
+      "description": "Adds the ChatGPT browser engine with repo-local sessions, opt-in MCP browser tools, an Oracle wrapper, a native Chrome CDP provider spike, and hosted CI gate hardening"
+    },
+    {
+      "version": "0.7.1",
+      "description": "Adds GPT Pro setup and consult command skills over the ChatGPT Web browser bridge and keeps PostBash advisory traces out of the authoritative latest checks trace"
+    },
+    {
+      "version": "0.7.2",
+      "description": "Hardens GPT Pro setup bootstrap gates, preserves ChatGPT MCP connector settings, adds Oracle heartbeat support, and makes Oracle repair guidance source-aware"
+    },
+    {
+      "version": "0.8.0",
+      "description": "Adds the Controller V2 tool surface, explicit long-running Agent timeout propagation, heartbeat and retry evidence, stale Connector diagnostics, and a visual Issue/Task/Run control plane."
+    },
+    {
+      "version": "0.9.0",
+      "description": "Adds the live Task workstation, structured Agent progress, automatic workspace/worktree placement, and automatic worktree integration and cleanup."
+    },
+    {
+      "version": "1.0.0",
+      "description": "Adds the V4 progress ledger, effective Task status, unified worklog timeline, exportable evidence reports, SSE dashboard updates, and optional GitHub Issue/Project plugin configuration."
+    },
+    {
+      "version": "1.1.0",
+      "description": "Adds the V5 execution-closure model with a single current Issue, creation-policy guardrails, governance diagnostics and reconciliation, retryable Run failures, evidence-gate progress, direct launch/verify/accept actions, and historical Issue archiving."
+    },
+    {
+      "version": "1.2.0",
+      "description": "Promotes bounded direct edits to a first-class workflow with request-mode assessment, persisted patch evidence, named-check verification, file-change dashboards, and Issue-free completion for known small changes."
+    },
+    {
+      "version": "1.3.0",
+      "description": "Replaces Issue-wide execution gates with Task-local readiness, risk-adaptive verification, automatic Run continuation, ephemeral Quick Agent sessions, bounded context surfaces, and explicit runtime evidence."
+    },
+    {
+      "version": "1.4.0",
+      "description": "Prepares the public release surface for Forge by syncing package metadata, preserving MIT attribution, trimming packaged audit manifests, and removing hard-coded personal fallback paths from packaged helpers."
+    }
+  ],
+  "generatedProjectStamp": {
+    "format": "forge@{version}+template@{templateVersion}",
+    "displayName": "forge",
+    "location": ".claude/.skill-version"
+  }
+}