forge-workflow 0.0.10 → 0.1.0-beta.2

package/docs/reference/HERMES_INTEGRATION.md

@@ -0,0 +1,118 @@
+# Hermes Integration
+
+> Roadmap lane: `forge-2agy.9.7.x` (Hermes adapter)
+
+This document defines how the **Hermes** harness integrates with a Forge
+project, and — most importantly — the boundary between **Forge Kernel state**
+(shared, authoritative, cited) and **Hermes-native memory** (private to a Hermes
+session or profile).
+
+The consumption contract that Hermes sessions follow lives in
+[skills/hermes-forge/SKILL.md](../../skills/hermes-forge/SKILL.md). The storage
+model Hermes reads against is described in
+[FORGE_KERNEL_STORAGE_MODEL.md](FORGE_KERNEL_STORAGE_MODEL.md), and the
+writeback surface in
+[forge-kernel-issue-command-contract.md](forge-kernel-issue-command-contract.md).
+
+## Why a boundary is needed
+
+Hermes carries its own conversational/profile memory. Forge carries the
+project's durable, provenance-tracked state. If Hermes were allowed to write its
+private memory into Forge state, the two would drift: Forge would accumulate
+Hermes-specific context that other harnesses (Claude Code, Codex, Cursor) cannot
+interpret, and the "single source of truth" guarantee behind `forge orient` /
+`forge recap` would erode.
+
+The integration therefore makes Forge state the authority and Hermes a
+**consumer** that writes back only through the same audited CLI surface it reads
+from.
+
+## The two memory tiers
+
+| | Forge Kernel state | Hermes-native memory |
+| --- | --- | --- |
+| **Owner** | Forge | Hermes |
+| **Scope** | The project — shared across all harnesses | One Hermes session / profile |
+| **Authority** | Source of truth | Convenience cache, never authoritative |
+| **Read path** | `forge orient` / `forge recap` (bounded, cited JSON) | Hermes' own store |
+| **Write path** | Forge CLI only (`forge comment`, `forge update`) | Hermes' own store |
+| **Contains** | Issues, decisions, evidence, design snapshots, claims, queues | Prompts, session scratch, user preferences, Hermes profile data |
+| **Provenance** | Every fact carries `{ path, source_kind, authority, role }` | Not part of the Forge provenance graph |
+
+### What lives in Forge Kernel state
+
+Anything that is a **project fact**: issue records, decisions, evidence,
+design-snapshot content, ready queues, and active claims — all written back
+exclusively through Forge CLI commands.
+
+Not all of that state is surfaced by the bounded `forge orient` / `forge recap`
+envelope. Today the envelope emits the project design snapshot, active-work
+artifacts (`docs/work`), and — for `forge recap <issue-id>` — an issue summary;
+ready queue and active claims currently appear as forward-looking kernel
+placeholders. Issue **evidence/comments are not in the envelope** — read them
+from the issue record itself (e.g. `forge show <id>`). Treat orient/recap as the
+bounded entry point, not the exhaustive store.
+
+### What lives in Hermes-native memory
+
+Anything that only matters to **Hermes**: conversational history, session
+scratchpads, per-user preferences, and the Hermes profile itself. None of this
+belongs in Forge Kernel state.
+
+## Authority rule
+
+Forge Kernel state is the single source of truth. When Hermes needs project
+state it MUST obtain it from `forge orient` / `forge recap` (JSON form) rather
+than reconstructing it from raw files or kernel internals. When two sources
+conflict, prefer the higher `authority` and surface the conflict instead of
+silently choosing.
+
+## Writeback rule
+
+Evidence and decisions discovered in a Hermes session flow back into the Forge
+Kernel **only** through Forge CLI commands:
+
+- `forge comment <id> <body...>` — attach evidence, a decision, or a note to an issue.
+- `forge update <id...> [flags]` — update issue state/fields.
+- `forge create [title] [flags]` — open a follow-up issue.
+
+(`forge audit` is verify-only — `forge audit verify` — and is not an
+evidence-append path; record evidence as an issue comment.)
+
+These writes land in the Forge Kernel issue store and become part of the issue's
+durable history. Note the read/write asymmetry: the bounded `forge orient` /
+`forge recap` envelope is assembled from project docs, `docs/work` artifacts, and
+the issue summary — it surfaces issue/design/decision state but does **not** echo
+individual issue comments back. Evidence added via `forge comment` lives in the
+issue history (reachable from the issue record), not necessarily in the next
+orient/recap payload.
+
+## The no-profile-write guard
+
+The hard boundary, enforced as a contract in the `hermes-forge` skill and
+guarded by tests:
+
+> **Hermes MUST NOT write Hermes profile state into Forge Kernel state.**
+
+Concretely, a Hermes session must never:
+
+- Persist Hermes profile or session memory into Forge Kernel storage.
+- Edit Forge state files (design, decision, issue stores) directly to record
+  Hermes-side context.
+- Use the Forge issue/evidence backend as a dumping ground for
+  Hermes-only data.
+
+If a piece of context only matters to Hermes, it stays in Hermes-native memory.
+If it is a project fact, decision, or evidence item, it is written through the
+Forge CLI so it becomes part of the shared, cited source of truth.
+
+## Token-budget & truncation expectations
+
+`forge orient` and `forge recap <issue-id>` emit the deterministically bounded
+envelope (default ~2000 estimated tokens, `chars_per_token: 4`). Truncation
+follows the published `token_budget.truncation_order`, marks trimmed sections
+with `[truncated deterministically by token budget]`, and sets `truncated: true`.
+Hermes treats truncated sections as incomplete and re-requests with a higher
+`--budget` when completeness matters. (Bare `forge recap` — no issue id —
+returns the legacy activity summary, which is not the bounded envelope.) See the
+skill for the full envelope and provenance model.

package/docs/reference/INSIGHTS_RECAP.md

@@ -0,0 +1,63 @@
+# Insights And Recap
+
+`forge insights` and `forge recap` summarize recurring local workflow evidence from existing Forge and Beads state.
+
+## Commands
+
+```bash
+forge insights
+forge insights --review-feedback
+forge insights --min-count 2 --limit 5
+forge insights --json
+forge insights accept <candidate-id> --note "why this is useful"
+forge insights reject <candidate-id> --note "why this is noise"
+forge recap
+forge recap --json
+```
+
+`--review-feedback` is a compatibility alias. In this MVP it reads Beads interactions and issue evidence; it does not infer external review-provider comments.
+
+## Evidence Sources
+
+- `.beads/interactions.jsonl`: field changes and review/close outcome reasons.
+- `.beads/issues.jsonl`: tokenized issue titles and descriptions for themes, plus statuses and timestamps for recap context.
+- `.forge/log.jsonl` and `.forge/audit.log`: optional audit event counts when present.
+- Beads-backed typed memory: accept/reject decisions are recorded through `lib/memory/typed-api.js`.
+
+## What It Can Infer
+
+- Repeated local workflow patterns.
+- Candidate follow-ups based on frequency, source diversity, and evidence count.
+- Recent issue activity and review outcome counts.
+- Whether history is too sparse for a useful suggestion.
+
+## What It Cannot Infer
+
+- Does not prove a workflow is correct.
+- Reviewer intent is not inferred from provider-specific systems.
+- Trusted executable skills are not installed.
+- It does not modify upgrade safety, lockfile/trust policy, patch intent internals, team dashboards, or issue sync surfaces.
+
+## Example Output
+
+```text
+Forge insights
+Sources: interactions=16, issues=260, audit=0
+Ranked candidates:
+- insight-interaction-status-closed-merged-and-verified (55): status changed to closed (merged-and-verified)
+  Next: Review interaction evidence and consider a local workflow skill only if the pattern is still useful.
+Limitations:
+- Insights are local workflow signals, not proof of correctness.
+```
+
+```text
+Forge recap
+Issues: 260 total, 94 open, 166 closed
+Review outcomes found: 4
+Recent work:
+- forge-besw.12: forge insights --review-feedback PoC (Week 1 deliverable) [open]
+Insight candidates:
+- insight-interaction-status-closed-merged-and-verified: status changed to closed (merged-and-verified)
+Limitations:
+- Sparse Beads interactions or missing Forge audit logs reduce confidence.
+```

package/docs/reference/INSTALL.md

@@ -0,0 +1,164 @@
+# Installing Forge
+
+Forge ships two ways to install:
+
+1. **Standalone binary** (this page) — a single compiled executable, no Node or
+   Bun runtime required. Best for a global CLI you run everywhere.
+2. **npm / npx** — the `forge-workflow` package, if you already live in Node and
+   want Forge as a project dev-dependency. See [npm / npx channel](#npm--npx-channel).
+
+Both deliver the same Forge. The binary bundles Forge's own JavaScript, but **not**
+its external prerequisites — see [Prerequisites](#prerequisites).
+
+---
+
+## One-line install
+
+### macOS / Linux
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/harshanandak/forge/master/scripts/install.sh | sh
+```
+
+Install a specific version:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/harshanandak/forge/master/scripts/install.sh | sh -s -- --version v1.2.3
+```
+
+The script detects your OS, CPU architecture and (on Linux) your libc, downloads
+the matching binary from the latest [GitHub Release](https://github.com/harshanandak/forge/releases),
+makes it executable, and installs it to `~/.local/bin/forge`. If that directory
+is not on your `PATH`, the script prints the line to add.
+
+### Windows (PowerShell)
+
+```powershell
+irm https://raw.githubusercontent.com/harshanandak/forge/master/scripts/install.ps1 | iex
+```
+
+Install a specific version (download the script, then run it with an argument):
+
+```powershell
+$s = irm https://raw.githubusercontent.com/harshanandak/forge/master/scripts/install.ps1
+& ([scriptblock]::Create($s)) -Version v1.2.3
+```
+
+This installs `forge.exe` to `%LOCALAPPDATA%\Programs\forge\` and prints how to
+add it to your `PATH`.
+
+After installing, run `forge setup` inside a git repository to wire Forge up for
+your agent.
+
+---
+
+## Supported platforms
+
+Each GitHub Release publishes these assets. The install scripts pick the right one
+automatically; the table is for manual downloads.
+
+| OS | Architecture | libc | Release asset |
+|----|--------------|------|---------------|
+| macOS | Apple Silicon (arm64) | — | `forge-darwin-arm64` |
+| macOS | Intel (x64) | — | `forge-darwin-x64` |
+| Linux | x64 | glibc | `forge-linux-x64` |
+| Linux | arm64 | glibc | `forge-linux-arm64` |
+| Linux | x64 | musl (e.g. Alpine) | `forge-linux-x64-musl` |
+| Linux | arm64 | musl (e.g. Alpine) | `forge-linux-arm64-musl` |
+| Windows | x64 | — | `forge-windows-x64.exe` |
+
+On an unsupported platform the install script fails with a clear message. Use the
+[npm / npx channel](#npm--npx-channel) instead.
+
+---
+
+## Manual download and run
+
+If you prefer not to pipe a script to your shell, download the asset for your
+platform directly from the [latest release](https://github.com/harshanandak/forge/releases/latest)
+and run it.
+
+Every release also publishes a `checksums.txt` (SHA-256) manifest. **Verify the
+asset before you run it** — the one-line install scripts do this automatically.
+
+### macOS / Linux
+
+```sh
+# Pick the asset for your platform from the table above (here: linux x64 glibc)
+curl -fsSL -o forge \
+  https://github.com/harshanandak/forge/releases/latest/download/forge-linux-x64
+
+# Verify integrity against the release manifest before running:
+curl -fsSL -o checksums.txt \
+  https://github.com/harshanandak/forge/releases/latest/download/checksums.txt
+grep ' forge-linux-x64$' checksums.txt | sha256sum -c -   # must print "forge-linux-x64: OK"
+
+chmod +x forge
+./forge --version
+# Optionally move it onto your PATH:
+mkdir -p ~/.local/bin && mv forge ~/.local/bin/forge
+```
+
+On macOS use `shasum -a 256 -c -` in place of `sha256sum -c -`.
+
+### Windows (PowerShell)
+
+```powershell
+irm https://github.com/harshanandak/forge/releases/latest/download/forge-windows-x64.exe -OutFile forge.exe
+
+# Verify integrity against the release manifest before running:
+irm https://github.com/harshanandak/forge/releases/latest/download/checksums.txt -OutFile checksums.txt
+$expected = ((Get-Content checksums.txt) -match ' \*?forge-windows-x64\.exe$') -replace '\s.*$',''
+if ((Get-FileHash -Algorithm SHA256 forge.exe).Hash -ieq $expected) { "OK" } else { throw "checksum mismatch" }
+
+.\forge.exe --version
+```
+
+A pinned version uses the same URLs with `download/<tag>/` instead of
+`latest/download/`, e.g.
+`https://github.com/harshanandak/forge/releases/download/v1.2.3/forge-linux-x64`.
+
+---
+
+## npm / npx channel
+
+If you already have Node.js, you can skip the binary entirely:
+
+```sh
+# Global install
+npm i -g forge-workflow
+forge --version
+
+# Or run once without installing
+npx forge-workflow status
+
+# Or as a project dev-dependency (recommended for teams)
+bun add -D forge-workflow   # or: npm install --save-dev forge-workflow
+bunx forge setup --agents claude --yes
+```
+
+The npm package and the standalone binary are the same Forge and stay in lockstep
+on every release.
+
+---
+
+## Prerequisites
+
+The binary bundles Forge's JavaScript, but relies on a few external tools being
+installed and on your `PATH`:
+
+- **git** — required for all repository operations.
+- **gh** (GitHub CLI) — required for the PR / review workflow.
+- **Git Bash** (Windows only) — Forge's helper-backed stage flows run under Git
+  Bash on Windows.
+
+These are runtime prerequisites checked by `forge`'s own health checks; the
+installer does not install them for you.
+
+---
+
+## Uninstall
+
+- Binary: delete the installed file (`~/.local/bin/forge`, or
+  `%LOCALAPPDATA%\Programs\forge\forge.exe` on Windows).
+- npm: `npm rm -g forge-workflow`.

package/docs/reference/KERNEL_TAXONOMY_VALIDATION.md

@@ -0,0 +1,161 @@
+# Kernel Taxonomy, Readiness, and Validation
+
+Reference for the Forge Kernel issue taxonomy collapse and its read-model/validation
+layer, implemented per **D18** (see
+[`docs/work/2026-06-06-kernel-backlog-memory-roadmap/decisions.md`](../work/2026-06-06-kernel-backlog-memory-roadmap/decisions.md))
+and roadmap items `forge-2agy.9.2.1`, `.9.2.2`, `.9.2.6`, `.9.2.7`, `.9.2.8`, `.9.2.9`.
+
+The four planning axes are kept **separate** (D5): stored **status**, parent/child
+**hierarchy**, sprint/release planning **bucket**, and workflow **stage** execution. A
+task can be in a sprint, have a parent epic, be derived-ready, and currently sit in the
+`validate` stage — these are not the same field.
+
+---
+
+## 1. Issue types (4) — `lib/kernel/taxonomy-validator.js`
+
+A type only earns existence if it changes Kernel behavior (routing, gates, board
+grouping, rollup). `feature`, `story`, `chore`, and `spike` are **labels**, not types.
+
+| Type | `canParent` | `claimable` | `blocksOthers` | `rollup` | Board group |
+| --- | --- | --- | --- | --- | --- |
+| `epic` | ✅ (only container) | ❌ | ❌ | ✅ | `roadmap` |
+| `task` | ❌ | ✅ | ❌ | ❌ | `backlog` |
+| `bug` | ❌ | ✅ | ❌ | ❌ | `backlog` |
+| `decision` | ❌ | ❌ | ✅ (gates dependents) | ❌ | `decisions` |
+
+`TYPE_BEHAVIORS` is the single source of truth for these mappings. Enums are enforced at
+the **validation layer**, not as DB constraints, so label-based extensibility and derived
+readiness stay outside the stored column set.
+
+## 2. Status lifecycle (5 stored)
+
+Stored statuses: `open`, `in_progress`, `review`, `done`, `cancelled`.
+
+```text
+open ──► in_progress ──► review ──► done
+ ▲           │             │
+ └───────────┘             │   (rework: review ──► in_progress, in_progress ──► open)
+open / in_progress / review ──► cancelled        (done, cancelled are terminal)
+```
+
+`STATUS_TRANSITIONS` encodes the legal moves. `validateStatusTransition(from, to)` throws
+a `TaxonomyValidationError` for illegal moves and unknown statuses; a same-status
+transition is treated as an idempotent no-op. `done` and `cancelled` are terminal — no
+transition leaves them.
+
+## 3. Derived readiness — `lib/kernel/readiness-model.js`
+
+`ready` and `blocked` are **derived read-model facts, never stored statuses** (D18). A
+blocker that clears makes the issue ready again in whatever stored status it held — there
+is no "preserve previous status" hack. `backlog` is the fallback summary state when an
+issue is neither terminal nor ready/blocked/gated/deferred/claimed/disabled — for example
+`open` with readiness conditions unmet, or a non-workable status such as `review`.
+
+`deriveReadiness(issue, context)` returns:
+
+```json
+{
+  "id": "forge-1",
+  "status": "open",
+  "ready": true,
+  "blocked": false,
+  "blocked_by": [],
+  "reasons": [],
+  "state": "ready"
+}
+```
+
+Readiness policy considers: blocking dependencies (upstream not in a terminal status —
+`done` and `cancelled` both clear, so a cancelled blocker never wedges a dependent),
+unresolved decision dependencies, projection **quarantine**/conflicts, required workflow
+**gates**, **defer** windows, **policy-disabled** work, and an **active conflicting
+claim** by another actor. Reason codes (`READINESS_REASONS`): `dependency` (carries a
+`decision: true` flag when the blocker is a decision issue), `quarantine`, `conflict`,
+`gate`, `claimed`, `deferred`, `policy_disabled`.
+
+**Acceptance-criteria and due-date readiness** are modeled through the generic `gates`
+input (an acceptance/definition-of-ready gate, or a due-window gate the caller supplies),
+not as separate hardcoded field checks — so the policy stays open to caller-defined gates
+without the read model owning every "definition of ready" rule.
+
+Summary `state` (precedence high→low): `closed` → `blocked` → `gated` → `deferred` →
+`claimed` → `disabled` → `ready` → `backlog`. `blocked` (dependencies/quarantine/conflict)
+always outranks softer not-ready reasons. Because the single `state` collapses multiple
+conditions, consumers picking next work should read the full `reasons[]` — e.g. a claim
+hidden behind a defer window is in `reasons[]` even when `state` reports `deferred`.
+Terminal issues are `closed` — neither ready nor blocked.
+
+`buildReadinessIndex({ issues, dependencies, claims, conflicts, gates, now, actor,
+policyDisabledIds })` computes readiness for a whole board, resolving each dependency's
+status from the issue set and returning a `readyQueue` ordered by authoritative numeric
+rank then id, plus the `blocked` id list. The ready-work queue excludes terminal,
+deferred, gated, policy-disabled, and claimed-by-other issues.
+
+## 4. Validation layer — `lib/kernel/taxonomy-validator.js`
+
+| Function | Enforces |
+| --- | --- |
+| `validateIssueTaxonomy(issue)` | type/status enum membership; rejects self-parent |
+| `validateStatusTransition(from, to)` | status lifecycle rules (throws) |
+| `findDependencyCycles(deps)` / `assertAcyclicDependencies(deps)` | dependency graph acyclicity (only `blocks` edges) |
+| `validateParentChild(issue, parent)` | parent exists, parent type `canParent`, no self-parent |
+| `findParentCycle(issuesById, startId)` | parent-chain cycle detection |
+| `validateClaim(claim, { now, issueType })` | actor present, valid claim state, claimable type, lease not expired |
+| `validateActiveClaimUniqueness(claims)` | at most one active claim per issue |
+
+These complement (do not replace) the broker/DB claim-lease invariants enforced
+elsewhere; the validation layer is the pure, storage-agnostic checker.
+
+## 5. Priority rank vs P0–P4 projection
+
+A single numeric rank is authoritative for ordering; **P0–P4 is a display projection
+only** (D18). `rankForPriorityLabel(label)` ingests a label/number to the authoritative
+rank; `priorityLabelForRank(rank)` projects a rank to a display label clamped to `P0..P4`;
+`normalizeRank(value)` coerces to a non-negative integer.
+
+## 6. Planning bucket entities — `lib/kernel/planning-buckets-schema.js`
+
+Sprint, release, and milestone are first-class Kernel entities (`forge-2agy.9.2.7`), not
+string fields on issues. Each table (`kernel_sprint`, `kernel_release`,
+`kernel_milestone`) carries `id`, `name`, `state`, `rank`, owner/goal, dates,
+`entity_revision`, and **read-model rollup counters** (`total_count`, `completed_count`).
+The schema reuses the shared `lib/kernel/schema.js` builders and passes
+`validateKernelSchema`; `getPlanningBucketsSchema()` is migration-renderable through the
+existing `buildSchemaMigration` renderer.
+
+State vocabularies:
+
+- Sprint: `planned`, `active`, `completed`, `cancelled`
+- Release: `planned`, `in_progress`, `released`, `cancelled`
+- Milestone: `planned`, `reached`, `missed`, `cancelled`
+
+The extended `kernel_issues` columns wire issues to these buckets and to hierarchy and
+stage: `parent_id` (self-referencing), `sprint_id`, `release_id`, `stage_state`,
+`labels`, `acceptance_criteria`, `estimate`.
+
+## 7. Board rank and mutation event model
+
+Frontend drag/drop and assignment operations must produce Kernel events carrying
+`expected_revision` and `idempotency_key` (`forge-2agy.9.2.6`). `BOARD_MUTATION_EVENT_TYPES`:
+
+- `issue.reordered` — board rank change. Per D18 there is a **single** authoritative
+  numeric ordering rank (`priority_rank`); P0–P4 is its display projection. There is no
+  separate board-only rank column.
+- `issue.status_changed`
+- `issue.sprint_assigned`
+- `issue.release_assigned`
+- `issue.blocked` / `issue.unblocked` — recorded transitions of the derived readiness
+  edge, emitted for audit; readiness itself remains computed, not stored
+- `issue.type_changed`
+
+Each event is validated optimistically against the entity's current revision and is
+idempotent on replay, consistent with the Kernel event/outbox contract.
+
+## Board views (frontend implications)
+
+- **Backlog board** — group by `type`, `priority`, `parent_id`, `release_id`.
+- **Sprint board** — group by `sprint_id` and status.
+- **Ready-work queue** — `buildReadinessIndex(...).readyQueue` (derived).
+- **Agent work view** — filter by claim actor, lease, worktree/session, and `stage_state`.
+- **Roadmap view** — group epics by release/milestone with child rollups.

package/docs/reference/PROTECTED_PATH_MANIFEST.md

@@ -0,0 +1,25 @@
+# Protected Path Manifest
+
+Forge uses `.forge/protected-paths.yaml` as the canonical protected-path contract for the schema and integrity rail.
+
+The manifest defines seven W1 categories:
+
+- `forge_core`: checksum-verified Forge runtime files.
+- `user_protocol`: user-facing protocol files that should be changed through Forge CLI surfaces.
+- `generated_artifacts`: generated harness files that should come from renderers.
+- `append_only_logs`: audit logs that must not be rewritten.
+- `secrets`: env and secret-bearing files.
+- `beads_state`: Beads state owned by `bd` or Forge issue adapters.
+- `immutable`: VCS/runtime internals owned by their tools.
+
+## Harness Enforcement
+
+Claude and Codex use native hook contracts for write/edit enforcement. Cursor fallback remains Forge CLI/pre-commit or file-watcher enforcement until a native Cursor hook surface is proven by fixture evidence.
+
+## Evidence Command
+
+```bash
+node scripts/spikes/protected-path-manifest.js
+```
+
+The command emits machine-readable JSON containing the manifest categories, per-harness enforcement mapping, validation result, and known issue for Cursor fallback.

package/docs/reference/RELEASE.md

@@ -0,0 +1,68 @@
+# Release Reference
+
+This page documents release readiness. Package publishing still requires the explicit publish step after merge.
+
+## v0.0.11 Boundary
+
+v0.0.11 is the public documentation and positioning package release. The release branch bumps package metadata to `0.0.11`; publish only after the release PR is merged, tagged, and validated.
+
+Keep these release steps explicit:
+
+- Release PR with documentation and package metadata
+- GitHub Release
+- npm publish
+- DeepWiki refresh
+
+## Pre-Release Validation
+
+Run from a clean release branch or worktree:
+
+```bash
+git status --short --branch
+bun run check
+npm pack --dry-run
+```
+
+For docs-heavy changes, also run a Markdown link check if available. If no docs checker exists and adding one would broaden the PR, create a follow-up issue instead.
+
+## Packaging Check
+
+`npm pack --dry-run` should show the package contents without publishing. Confirm new canonical docs that should ship are included and generated junk is not.
+
+## Release Notes
+
+Release notes should include:
+
+- user value
+- migration notes
+- feature flags or experimental areas
+- known limitations
+- rollback path
+- adapter compatibility
+- DeepWiki refresh checklist
+
+The v0.0.11 release notes live in [CHANGELOG.md](../../CHANGELOG.md).
+
+## Rollback
+
+For a release PR:
+
+1. Revert the PR if the combined package metadata and public docs create release confusion.
+2. Do not publish until README, CHANGELOG, quickstart, package metadata, and support docs agree.
+3. If DeepWiki generated output is wrong, fix repository docs first, then refresh DeepWiki.
+
+## Post-Merge DeepWiki Checklist
+
+After merge to `master`:
+
+1. Refresh DeepWiki for `harshanandak/forge`.
+2. Confirm the generated index date and commit changed to the merged commit.
+3. Compare generated Overview, Getting Started, and Core Concepts against:
+   - [README](../../README.md)
+   - [Quickstart](../../QUICKSTART.md)
+   - [Docs index](../INDEX.md)
+   - [Workflow templates](../guides/WORKFLOW_TEMPLATES.md)
+   - [Skills and command projections](SKILLS.md)
+   - [Command reference](COMMANDS.md)
+4. File a follow-up issue if generated docs still reflect old seven-stage-only framing.
+5. Record evidence in a PR comment or follow-up issue: DeepWiki index date, indexed commit, pages checked, pass/fail result, and any repository-doc corrections needed.