forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/AGENTS.md

@@ -1,9 +1,14 @@
+<!-- FORGE:START -->
 # Project Workflow Instructions
 
 ## Default TDD-First Workflow Template
 
 This project ships a **default TDD-first workflow template** with 6 workflow stages plus a composable **research** skill (a phase of `/plan` and usable standalone). In v3, these stages are one configurable composition over Forge runtime building blocks, not a product-wide mandatory ladder. Commands may be invoked as full stages or as smaller skill fragments when the active plan permits it. Pre-merge is an embedded gate in `/ship` and `/review` (not a numbered stage); `/status` and `/shepherd` are utilities (not stages).
 
+## Skill Dispatch (auto-trigger)
+
+Before ANY response — including clarifying questions or exploring the codebase — if there is even a 1% chance a Forge skill applies, invoke it, then announce `Using [skill] to [purpose]`. Invoke the `using-forge` dispatch skill (auto-discovered from your agent's own skills — Forge setup installs it into each harness's skills dir; it carries the 1%-rule and routing table), or run `forge skill for "<situation>"` for the deterministic best-fit skill. This is agent-agnostic — never branch on harness identity.
+
 | Stage | Command     | Purpose                                                   | Required For |
 |-------|-------------|-----------------------------------------------------------|--------------|
 | 1     | `/plan`     | Design intent → research → branch + worktree + task list | Critical, Standard, Refactor |
@@ -17,7 +22,7 @@ This project ships a **default TDD-first workflow template** with 6 workflow sta
 
 **Utility**: `/status` — Context check before starting work (not a numbered stage)
 
-**Utility**: `/shepherd <pr>` — Autonomous PR ownership. `forge shepherd daemon` is a singleton reconcile daemon that owns **all** open PRs for the repo: it converges CI check state into kernel verdicts, re-runs flaky required checks (Tier-A), reaps orphan watchers, and self-retires when no PRs remain — so agents read verdicts (`forge shepherd <pr> --pull --json`, `forge shepherd events`) instead of hand-polling. `forge shepherd <pr>` is the one-shot bounded pass for a single PR. It is a utility, **not** a workflow stage. It **never merges** (the human merges in the GitHub UI) and **never resolves review threads** (that stays with `/review`). `--auto-rebase` is opt-in and default OFF; kill-switches: `FORGE_SHEPHERD_DISABLE`, `forge gate disable rail.auto_shepherd`. **Startup/containment**: the daemon is a repo singleton (O_EXCL lease — a duplicate start is a clean no-op) started in the harness background shell so it is session-reaped; agents never launch it as a detached spawn (automatic per-command launch is a planned follow-up, W-S4c). See [docs/reference/shepherd.md](docs/reference/shepherd.md).
+**Utility**: `/shepherd <pr>` — Autonomous PR ownership. `forge shepherd daemon` is a singleton reconcile daemon that owns **all** open PRs for the repo: it converges CI check state into kernel verdicts, re-runs flaky required checks (Tier-A), reaps orphan watchers, and self-retires when no PRs remain — so agents read verdicts (`forge shepherd <pr> --pull --json`, `forge shepherd events`) instead of hand-polling. `forge shepherd <pr>` is the one-shot bounded pass for a single PR. It is a utility, **not** a workflow stage. It **never merges** (the human merges in the GitHub UI) and **never resolves review threads** (that stays with `/review`). `--auto-rebase` is opt-in and default OFF; kill-switches: `FORGE_SHEPHERD_DISABLE`, `forge gate disable rail.auto_shepherd`. **Startup/containment**: Forge automatically wakes the repo-singleton daemon after a supported session start, every successful push, and every successful non-dry-run ship; duplicate starts remain clean no-ops under the O_EXCL lease. Injected CI/test and kill-switch guards return before lock or process work. Forge prefers the session-reaped harness background shell and otherwise detaches from the stable common repository root, never a disposable worktree cwd. See [docs/reference/shepherd.md](docs/reference/shepherd.md).
 
 ## Automatic Change Classification
 
@@ -113,11 +118,13 @@ Task 2: Validation logic
   ✓ Quality review: ✅
 ```
 
-## State Management (Single Source of Truth)
+**Flaky tests:** a test that changes result without the code changing gets
+quarantined and an issue filed — never retried until green. Register it in
+`test/QUARANTINE.md`. Reviewers reject a "re-run CI" as a fix.
 
-> GitHub issue lifecycle may sync to Beads via CI -- see [docs/guides/BEADS_GITHUB_SYNC.md](docs/guides/BEADS_GITHUB_SYNC.md).
+## State Management (Single Source of Truth)
 
-**Current implementation**: The Forge Kernel is the default issue-state authority; issue commands read and write the kernel store unless Beads is explicitly selected (`--issue-backend beads`, `FORGE_ISSUE_BACKEND=beads`, or `issueBackend: beads` in `.forge/config.yaml`), where it serves as an import/export/projection compatibility layer. **Direction (D44)**: continue consolidating issue/workflow/run authority in the Kernel with Beads remaining a compatibility projection. New authority work must follow [docs/work/2026-04-28-skeleton-pivot/forge-kernel-authority-control-plane.md](docs/work/2026-04-28-skeleton-pivot/forge-kernel-authority-control-plane.md) and [docs/reference/FORGE_KERNEL_STORAGE_MODEL.md](docs/reference/FORGE_KERNEL_STORAGE_MODEL.md).
+**Current implementation**: The Forge Kernel is the sole issue-state authority — every issue command reads and writes the kernel store, with no backend to select. Beads exists only as an inbound migration path: `forge migrate --from beads` imports an existing Beads store into the kernel once, and no Forge command depends on Beads at runtime. **Direction (D45)**: the Kernel owns issue/workflow/run authority outright; Beads is retired as a live feature. New authority work must follow [docs/work/2026-04-28-skeleton-pivot/forge-kernel-authority-control-plane.md](docs/work/2026-04-28-skeleton-pivot/forge-kernel-authority-control-plane.md) and [docs/reference/FORGE_KERNEL_STORAGE_MODEL.md](docs/reference/FORGE_KERNEL_STORAGE_MODEL.md).
 
 ```json
 {
@@ -151,6 +158,7 @@ This project uses the **Professional Git Workflow** with Lefthook for automated
 - Offers guided recovery (add tests now, skip with tech debt tracking, emergency override)
 - No AI decision required - automatic validation
 - **Strong default, not a hard floor.** The TDD gate is the default-ON `rail.tdd_intent` rail; turn it off with `forge gate disable rail.tdd_intent` (the `minimal` adoption profile ships it off). The installed hooks read the resolved config at run time, so a disabled rail makes them genuinely inert — enforcement honestly follows your config.
+- **Defers to a gate you already have.** If your repo already runs a TDD / source-test coupling check on pre-commit (any runner: lefthook, husky, the `pre-commit` framework, a raw `.git/hooks/pre-commit`), `forge setup` detects it, does **not** install a second gate on the same commit, turns `rail.tdd_intent` off, and says so. Prefer Forge's gate? Remove yours and run `forge gate enable rail.tdd_intent` — an explicit setting is never overwritten by a later setup.
 
 **Pre-push hook validates tests:**
 - Branch protection: blocks direct push to `main`/`master`
@@ -169,7 +177,7 @@ This project uses the **Professional Git Workflow** with Lefthook for automated
 
 ```bash
 forge push                    # Branch protection + lint + tests, then push
-forge push --quick            # Review-cycle: lint-only push (CI runs full suite)
+forge push --quick            # Review-cycle: lint-only end to end (the pre-push hook's test job is skipped too; CI runs the full suite)
 forge worktree create <slug>  # Create a worktree
 forge test                    # Run tests with correct timeouts
 forge sync                    # Sync issue data
@@ -231,7 +239,7 @@ See [.mcp.json.example](.mcp.json.example) for configuration (Claude Code: copy
 
 **Forge v3 / Kernel Plan (active design):**
 - [docs/work/2026-04-28-skeleton-pivot/forge-kernel-authority-control-plane.md](docs/work/2026-04-28-skeleton-pivot/forge-kernel-authority-control-plane.md) — canonical Forge Kernel authority reset plan for issue authority, local broker, team authority, adapters, storage, and gates
-- [docs/work/2026-04-28-skeleton-pivot/locked-decisions.md](docs/work/2026-04-28-skeleton-pivot/locked-decisions.md) — D1–D44 decisions ledger with rationale + tradeoffs + anti-decisions; D44 supersedes Beads-only authority portions of earlier decisions
+- [docs/work/2026-04-28-skeleton-pivot/locked-decisions.md](docs/work/2026-04-28-skeleton-pivot/locked-decisions.md) — D1–D45 decisions ledger with rationale + tradeoffs + anti-decisions; D44 supersedes Beads-only authority portions of earlier decisions, and D45 retires Beads as a live feature
 - [docs/work/2026-04-28-skeleton-pivot/v3-redesign-strategy.md](docs/work/2026-04-28-skeleton-pivot/v3-redesign-strategy.md) — historical v3 strategy and background; do not use its legacy default-substrate language over D44
 - See [docs/INDEX.md](docs/INDEX.md) for the full reading order across the v3 design folder
 
@@ -303,7 +311,7 @@ forge insights                 # Detect recurring evidence patterns, suggest con
 forge upgrade                  # Preview and self-heal safe Forge upgrade readiness
 forge gate <verb> <gate-id>    # Toggle a workflow gate, or record/query human-gate approval events
 forge role <role> --use <skill> # Bind a role to a skill/ideology in .forge/config.yaml
-forge merge --auto <pr>        # Opt-in conditional auto-merge — merges only when configured rules pass (OFF by default)
+forge merge --auto <pr> --expect-head <full-sha> --issue <issue-id>  # Opt-in guarded merge; exact head + owned issue required (OFF by default)
 ```
 
 ### Rules
@@ -334,6 +342,7 @@ runtime rail. Turn it off only deliberately: `forge gate disable rail.kernel_tra
 - **Unused params**: Prefix with `_` (e.g., `_searchTerm`) — ESLint `no-unused-vars` enforced with `--max-warnings 0`.
 - **Pre-push test env**: `test-env/` fixture tests can fail during actual `git push` due to git mid-push state. Fix the root cause — never use `LEFTHOOK=0`.
 - **Skill sync**: Canonical skills live in `skills/<name>/SKILL.md`; per-agent copies are generated from them. `.agents/skills` (Codex's repo-local discovery path) is committed so a fresh clone gets discovery without `forge setup` — a pre-commit hook keeps it byte-identical to `skills/` and the drift gate enforces it. The other mirrors (`.claude/skills`, `.codex/skills`, `.cursor/skills`, `.hermes/skills`) are gitignored and regenerated at `forge setup`. Never hand-edit a generated mirror — edit the canonical `skills/` source.
+- **Skill invocation metadata**: Canonical skill frontmatter may declare `invocation: model|user`; omission means `model`. Only `ship`, `review`, and `rollback` are currently user-invoked. Keep the field harness-neutral and preserve it byte-identically in every generated mirror.
 
 ## Session Completion
 
@@ -361,3 +370,5 @@ runtime rail. Turn it off only deliberately: `forge gate disable rail.kernel_tra
 - NEVER say "ready to push when you are" - YOU must push
 - If push fails, resolve and retry until it succeeds
 - After fixing review feedback, always push the changes and resolve the related GitHub review threads via the GraphQL API before considering the work complete
+
+<!-- FORGE:END -->

package/CHANGELOG.md

@@ -7,7 +7,85 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 > **Note**: `/check` was renamed to `/validate` and `/merge` was renamed to `/premerge` in v0.0.3. Historical entries below may use the old names.
 
-## [Unreleased]
+## [0.1.0-beta.6] - 2026-09-11
+
+### Added
+
+- **Optional repository-scoped GitHub account context.** Adds clone-local `github.account` binding, native GitHub CLI named-account retrieval, live identity verification, child-only credential scoping across Forge GitHub routes, and concurrent launcher isolation without changing global authentication, Git authorship, or transport configuration. (#554, issue `ee4869d5-77af-4959-909c-190e99b3ada0`)
+- **Dormant Shepherd owner-authority foundation.** Adds the composite-key Kernel schema, migration gate, and bounded transactional owner API without changing any production watcher, daemon, lease, monitor, or command caller. The atomic caller cutover remains isolated in the dependent PR. (#540, issue `ca693a15-c430-404b-9e97-7de59b529eee`)
+- **Atomic Shepherd watcher-authority cutover.** Routes direct, adopt, child, and daemon watcher lifecycles through the Kernel owner row and exact-complete migration gate; reduces the singleton lease to election only; and removes persisted PID, lease-watcher, generation-marker, cleanup-marker, and in-memory authority writers. (#541, issue `700c07c3-e06d-48ed-9b24-229cd7872069`)
+- **Public receipt-bound PR lifecycle authority.** `@forge/memory` now issues exact-head WorkPackets, authenticates RunReceipts, durably links exact `pr.opened` evidence through public Kernel provider seams, requires and rechecks live session-bound ownership and authoritative readiness, preserves Kernel ready order, and fails closed on replay conflicts, stale evidence, unsafe paths, provider loss, and unbounded operations. External merge and terminal `pr.merged` linkage remain owned by the guarded Forge merge path; canonical LeaseReceipt epochs remain explicitly deferred for 0.1. (issue `c2a3c655-ade2-4156-a8dc-e6b4ee2827ad`)
+- **Human-gated legacy claim repair.** Adds a fixed-time, privacy-safe claim preflight, separately restored SQLite backup proof, and exact-digest `BEGIN IMMEDIATE` repair with terminal precedence, null-expiry preservation, CAS drift rejection, idempotent receipts, and interruption rollback. The operator-only script is never run at startup. (PR #528, issue `0fd8b8c1-686c-4808-8d99-f9ed5b9571de`)
+- **Memory recall and session-attention stabilization.** Typed recall now filters before limits, superseded notes hide by default but remain recoverable, Claude read-attention injects only fenced path-matched notes, and session-summary reminders remain current and idempotent. (#504, issue `0874844f-9c0c-449a-994e-a804fe3fc3a5`)
+- **Frozen beta.5 compatibility evidence.** Adds a content-hashed v0.1.0-beta.5 contract and state corpus, privacy-safe inventory, isolated backup/restore proof, and deterministic non-mutating migration dry-run results for Windows and Linux-safe paths. (#498, issue `5dad8dbf-1c49-444d-a407-a48583537817`)
+- **Forge 0.1.0 control-plane foundations.** Adds executable issue-readiness contracts, dead-run claim reconciliation, issue-scoped approval receipts, Kernel-authoritative plan snapshots, fail-closed risk-to-test selection, and distinct npm beta, RC, and stable release channels. (#497; issues `4ee7f9a9-4fa0-42c1-bd96-96638cc9feff`, `9b69a551-f5a0-4057-9d9f-96fb0d744fd3`, `b977b0a2-11f6-40d7-a230-8e2ff5f79115`, `b811a974-a866-47e0-8f83-3f5d2423aded`, `7a6a3fb3-c82c-48e7-86ee-630c171b924c`, `3e46debd-11c3-4b1c-b59a-17304c37cb03`)
+- **Deterministic Bun lockfile ownership.** Protected-state validation can approve a staged root `bun.lock` only when pinned Bun reproduces its exact bytes from captured staged package manifests: first from the committed lock, then from a clean no-lock state only after an exact byte mismatch. Index races, tampering, unsafe paths/configuration, tool drift, and environment-seam hiding fail closed. (issue `a6c52ac8-6f80-4f2d-8d3c-d83eb92becbd`)
+
+### Fixed
+
+- **Legacy claim repair now compares exact Windows file identities and timestamps.** BigInt filesystem metadata prevents rounded device/inode collisions from treating distinct files as aliases, while nanosecond timestamps keep recovery-state drift checks fail closed. (#556, issue `7e164066-4d41-4d14-90ef-1b7ee14e2b73`)
+- **Dep-guard apply-decision tests no longer contend with shared Windows subprocess shards.** The process-heavy suite now uses the existing exclusive resource lane, with exact scheduler coverage and no timeout increase or exemption. (issue `762ae565-0059-4827-9c3d-b4249f2b3364`)
+- **Bun workflow proof tests no longer contend with shared full-suite shards.** The process-heavy commit-boundary proof now uses the existing exclusive resource lane, with exact scheduler coverage and no timeout increase or exemption. (#552, issue `2daab8c0-34d6-4378-8cf4-dce6fdbfb86b`)
+
+- **The protected-state pre-commit check is now merge-aware.** While a merge is in progress (per-worktree `MERGE_HEAD`), a staged protected path is exempt only when its full staged index entry (mode, object type and object id) is identical to that path's entry on `HEAD`, or on a `MERGE_HEAD` contained in the repository's canonical upstream ref (the base remote — `upstream` preferred over `origin`, the same resolution `/ship` uses to pick a PR base, then that remote's default branch) — content already published on the official base rather than on a contributor's fork. The base-remote resolver now lives in `lib/base-remote.js` and is shared with `/ship`, so a change merged from a fork's default branch but never published upstream stays blocked — content already published on the line this repo integrates into, carried in by the merge rather than edited. A local-only branch, an untrusted contributor remote, or a hand-created `refs/remotes/*` ref earns no exemption, an unresolvable `HEAD` grants no exemption context at all, `bun.lock` still requires its regeneration proof, paths differing from every trusted revision stay blocked, the non-merge path is unchanged, and any failed git query fails closed. (issue `f6d43eb1-249d-4d81-b679-32502ffa28c2`)
+- **Worktree dependency repair now covers Bun workspace shapes and reused worktrees.** Workspace discovery accepts array and object-form manifests plus wildcard and exact paths, reused worktrees revalidate dependencies before returning, and full-suite stderr tails redact complete lines before bounded retention. (#550, issue `465f7e62-1928-4bcf-97a5-c2db05504a7e`)
+- **Validation and dependency recovery gates are reproducible and fail closed.** The protected-state hook now accepts either an exact pinned-Bun transition from the committed lock or an exact clean no-lock regeneration after that transition mismatches; the regenerated lock clears all dependency advisories, every active Bun execution surface is pinned to 1.4.2, and `forge validate` gives the full suite measured capture headroom while distinguishing numeric skipped-test counts from an entirely skipped check. (#551; issues `95ed6f9c-6f23-41f4-9bc4-13177a96ccf2`, `1f7baefc-c9cc-4acf-9cad-e98c53f308ba`, `cfffed63-51dd-4145-acb2-a18f41ef2846`)
+- **Bare conditional merge no longer blocks on intentionally skipped optional checks.** `checks_green` now partitions the authoritative protected context/application set from optional check runs: protected and explicit `only` checks remain strict `SUCCESS`, while terminal optional `NEUTRAL` and `SKIPPED` results no longer block. Missing, malformed, unsafe, and nonterminal evidence still fails closed. (#549, issue `fa805e7e-e718-438f-a776-bd860c80e99a`)
+- **The full-suite worker budget now weights subprocess workers by real process cost.** A subprocess-lane worker owns two Windows processes (its own bun runtime plus the `bun.exe` grandchild its tests spawn), so granting three of them on a 4-vCPU runner oversubscribed the box and produced wall-clock-only failures. Grants are now made against the budget by cost (subprocess/exclusive = 2 units on `win32`, 1 elsewhere; unit = 1), the strongest lane always keeps one worker so the schedule can never stall at zero, and the plan log prints the *granted* concurrency plus the cost and budget instead of the nominal lane concurrency. Non-Windows scheduling is unchanged. (issue `9b8dfa31-4a76-4ef2-b7e9-331d248e3850`)
+- **`forge push` no longer kills a passing full test suite.** The pre-push test run is budgeted from the shared full-suite budget in `scripts/test.js` instead of a hardcoded 120s cap, and that shared budget is raised from 10 to 25 minutes — the previous default sat *below* the measured healthy runtime (602.43s for 8038 tests on Windows), so it SIGKILLed good runs. The ceiling now carries >2x headroom because it exists to catch an indefinite hang, not to bound normal runtime; `FORGE_TEST_TIMEOUT_MS` still overrides. A run terminated by a timeout, signal, or spawn error now reports what happened instead of failing with no summary. (issue `e26dbb91-0443-4e53-946e-a9941ec30ca3`)
+- **The targeted PR lane's full-suite fallback now uses the lane-aware runner.** When the execution planner returns `mode=full`, the follow-up job runs `scripts/test-full-suite.js` instead of a raw `bun test test/`, so subprocess-heavy files get resource-lane separation and the worker budget the full matrix already had — closing the Windows-only spawn failures that hit only this lane.
+- **Full-suite validation now respects the computed worker budget.** Resource-aware lanes share the reserved worker pool by default, and `forge validate` uses that runner when available, preventing mixed unit and subprocess shards from oversubscribing Windows runners. (PR #545, issue `8cb52d50-24ea-4c69-8579-b30a0f1ee467`)
+- **Windows legacy-claim repair now preserves owner-only ACL guarantees without PowerShell transport stalls.** The operator-only repair path uses bounded, privacy-safe Windows security-descriptor verification, exact owner/DACL replacement, Unicode-safe targets, transaction-isolated async hardening, and fail-closed timeout cleanup. (#538, issue `eb2c56e8-5054-4542-8f02-3f9fe635fd2d`)
+- **Local full-suite validation is deterministic under Windows process pressure.** Resource-aware lanes, runtime-balanced subprocess shards, isolated coordination state, direct commitlint execution, batched Flow-monitor replay, and exact failure attribution remove rotating shared-state and child-process flakes without weakening timeouts or gates. (#538; issues `51672736-3387-4d0f-950d-4ae6e5e2c13e`, `9eb98ac0-ebe1-4604-a57a-5fefadad6682`)
+- **PR lifecycle acceptance fails closed at its authority and privacy boundaries.** Every opened linkage write now proves exact live claim ownership, timed-out persistence reconciles only through bounded durable trace evidence, and bare POSIX user-home paths are rejected before WorkPacket publication. (#530, issue `50571aa3-b1cd-42f4-9c50-2c7576d1b0d4`)
+- **Official skill-mirror writes retain protected-state authority.** The canonical `.agents/skills` sync now uses one-time, actor/path/content/source-HEAD/worktree-bound authorization and completion receipts, verifies byte equality with `skills/`, and continues to deny direct, stale, replayed, or foreign writes. (issue `209d80bc-f521-4947-9953-e5b5bf7020f6`)
+- **Workspace lockfile proofs are path-independent.** Bun regeneration now receives the isolated proof root explicitly, preventing temporary proof paths from leaking into workspace keys. (issue `3eb1db42-eaa3-4847-9878-7b77310d1beb`)
+- **Windows lockfile proofs canonicalize temporary roots.** Native path resolution prevents 8.3 TEMP aliases from changing regenerated lock bytes. (issue `3eb1db42-eaa3-4847-9878-7b77310d1beb`)
+- **Linked-worktree lockfile proofs no longer mutate shared Git configuration.** Internal proof Git commands discard inherited repository-local Git environment variables while preserving the host toolchain environment. (issue `93cb615f-2e6e-45ff-90c1-6c98e47f0fff`)
+
+## [0.1.0-beta.5] - 2026-08-09
+
+### Added
+
+- **Controlled behavioral skill evaluation.** `forge skill eval <skill> --full --tier <30|100|300>` now runs the frozen two-model × current/bounded protocol with exact-head issue/PR attribution, isolated zero-tool runtimes, privacy-safe semantic evidence, fail-closed conflict handling, and deterministic promotion scoring. Thirty cases remain instrumentation-only; evaluation never supplies merge authority. (issue `198bec40-0d65-42a8-b2c2-c682f44fdb22`)
+- **Host-owned Shepherd background transport.** Session startup now forwards an explicitly supplied harness background-shell capability, runs it from the stable Git common root, and preserves the detached fallback when the capability is absent or fails. (#494, issue `60ccc100-506b-46a6-bf96-b2fce3436ed6`)
+- **Critical merge-flow reliability integration plan.** Defines a deterministic safety floor, executable work contracts, configurable risk policy, zero-token owner monitoring, and a sequential exact-head merge slot without constraining model reasoning. (#493, issue `a57a2b2a-3b0d-4fce-bf13-e3e4a386f1c9`, epic `f30e5d29-9099-4029-baec-af39f08b6ee3`)
+- **Model-neutral evaluation evidence and exact-SHA replay.** Adds a privacy-safe content-addressed envelope with fail-closed drift checks while excluding raw prompts, transcripts, tool payloads, secrets, and personal data. (#491, issue `02f5ea90-4a1a-462f-9b22-54eb5d37f6b3`)
+- **Automatic project-local memory recall for Claude Code.** Forge now repairs and reuses its existing `SessionStart` and `UserPromptSubmit` lifecycle hooks to inject bounded Kernel memory automatically. Confirmed memories are presented as project truth; fresh suggested memories are separated and labeled for verification. Scope, staleness, supersession, and seen-key filtering happen before ranking, and privacy-safe recall telemetry records only bounded identifiers and aggregates—not prompt terms or memory bodies. (`36461e50`)
+
+### Changed
+
+- **Exact-SHA npm publication evidence.** The Forge-generated publish workflow now resolves one immutable tag SHA, requires the complete repository suite and an attributable matching receipt before npm publication, and protects workflow updates with one-time Kernel capabilities instead of forgeable sidecar evidence. (issue `198bec40-0d65-42a8-b2c2-c682f44fdb22`)
+- **Simplified the PR-monitor surface.** The workflow now keeps one canonical
+  `pr-verdict:*` label and writes detailed diagnostics to the Actions job summary
+  (also available via `forge shepherd --pull --json`); it no longer creates a
+  sticky PR comment or the neutral `forge/pr-monitor` check. The label remains a
+  visibility projection and never supplies merge authority. (112a348a)
+- Added portable `invocation: model|user` skill metadata with omission defaulting to `model`; `ship`, `review`, and `rollback` are now explicitly user-invoked while canonical and generated skill projections remain byte-identical. (#467, `588e6973`)
+- Documented why Litestream remains a disaster-recovery candidate rather than Forge's multi-machine authority; self-hosted libSQL remains the Phase 2 server target. (#463, `746d839d`)
+
+### Fixed
+
+- **Windows full-suite drive classification no longer launches a redundant PowerShell probe for every child process.** Persistent mappings still use the bounded `net use` probe; an unclassified non-system drive now fails open as unknown instead of being mislabeled fixed. (#496, issue `1efe5de9-6bfb-448f-8575-624577b829f2`)
+- **Injected synchronous pre-push runners no longer create real process-tracking state.** Targeted-mode unit execution keeps its command and edge-suite assertions while avoiding the Windows process-tree setup that pushed the test beyond Bun's 15-second limit. (issue `54b54219-7cbc-4262-9461-a77112a7c49b`)
+
+## [0.1.0-beta.4] - 2026-07-24
+
+The **Kernel-only authority and autonomous Shepherd wave** removed the remaining live Beads runtime path while expanding Forge's portable skill and PR-monitoring surfaces.
+
+### Added
+
+- Reasoning-driven skill invocation, sub-skill composition, static skill evaluation, and dedicated setup, portability, worktree, and gate skills. (#417-#419, #429-#434)
+- Kernel-backed PR authority, singleton Shepherd leases, reconciliation, daemon execution, and cross-harness triggering guidance. (#420-#428)
+- Query-relevant project-memory recall for supported agent sessions. (#440-#441)
+
+### Changed
+
+- Issue commands, status, and dashboards now use the Forge Kernel exclusively; the live Beads backend and dashboard surfaces were retired. (#435-#439)
+
+### Fixed
+
+- Targeted pre-push selection recognizes Forge CLI surfaces, and Shepherd background processes stay hidden and derive required checks consistently on Windows and CI. (#420-#421, #438)
 
 ## [0.1.0-beta.3] - 2026-07-17
 

package/CLAUDE.md

@@ -1,13 +1 @@
-# Project Instructions
-
-Forge uses **[AGENTS.md](AGENTS.md)** as the single source of truth for all agent
-instructions: the workflow template, change classification, detailed stage
-instructions, git hooks and push workflow, build/shell/MCP toolchain, issue
-tracking, project learnings, and session completion. This file intentionally
-holds no content of its own — it only loads AGENTS.md.
-
 @AGENTS.md
-
-> **IMPORTANT**: Read [AGENTS.md](AGENTS.md) using the Read tool at the start of
-> every session to load the current Forge workflow contract. AGENTS.md is
-> authoritative; do not duplicate its content here.

package/CODING_STANDARDS.md

@@ -0,0 +1,72 @@
+# Coding Standards (read at review time)
+
+This file is **not** loaded every turn. It is read by the review step — the
+`/review` stage, the `code-review` skill, and any human or bot reviewing a diff —
+and nowhere else. Everything here is a property a reviewer can check **by reading
+the diff**. Rules about how an agent shapes its turn (arm the shepherd, work in a
+worktree, don't stall, don't poll on a fixed timer while waiting) live in
+[AGENTS.md](AGENTS.md), because no diff shows them.
+
+**How to add to it:** when you catch an agent (or yourself) doing something wrong
+in a change, add one line here, stated positively, with an evidence tag naming
+where the evidence came from — `[mined: <cluster> ×N]` for the transcript-mining
+counts, `[git: <pattern>]` for repository history, `[incident: <what happened>]`
+for a single concrete failure. No rule without evidence; delete a rule when its
+evidence stops recurring.
+
+---
+
+## Scope
+
+1. Every file in the diff is one the originating issue or design doc named; an
+   unrelated fix found along the way gets its own issue and its own PR.
+   `[mined: scope creep — unrelated fixes into the PR ×6]`
+2. A follow-up noted in the diff cites a kernel issue id, not a bare `TODO` or
+   `FIXME`. `[mined: discussed work not filed as kernel issue ×3]`
+
+## Gates and tests
+
+3. A failing check is fixed at its cause; the diff does not raise a timeout,
+   add a skip, loosen a threshold, or replace a real assertion with a vacuous
+   one to get green. `[mined: weakening gates/tests to pass ×3]`
+4. Tests synchronize on an observable condition (poll until true, await the
+   event), never on a fixed sleep or timer duration.
+   `[mined: waiting a fixed 10 min when reviewers already settled ×2]`
+5. A new or moved source path that needs targeted tests lands in both the
+   targetability checks in `scripts/test.js` and the `DIRECT_TEST_CANDIDATES`
+   mapping in `lib/commands/test.js`, so it does not silently fall into the
+   full-suite lane.
+   `[mined: slow test/CI lanes accepted as normal ×3]` `[git: 13 fix commits touch scripts/test.js]`
+
+## Generated artifacts and single source of truth
+
+6. Skills are edited in the canonical `skills/` tree and mirrors are regenerated
+   by `scripts/sync-agent-skills.js`; the diff never hand-edits `.agents/skills/`
+   or another generated mirror.
+   `[mined: duplicating skills per agent instead of skill-CLI generation ×4]`
+   `[incident: recurring skills-sync-drift failures]`
+7. Adding, deleting, or renaming a `lib/commands/*.js` file includes the
+   regenerated command manifest (`scripts/gen-command-manifest.js`) in the same
+   diff. `[git: 24 fix commits touch bin/forge.js, 15 touch lib/commands/setup.js]`
+
+## Product boundary
+
+8. Issue authority reads and writes go through the kernel; the diff adds no code
+   path that treats Beads or Dolt as a live backend.
+   `[mined: treating beads as live backend ×5]` `[decision: D45 retires Beads as a live feature]`
+9. Shipped code discovers its own paths and config; no maintainer machine path,
+   local username, or personal directory appears in a committed file.
+   `[incident: hardcoded C:\Users\<user>\Downloads\forge in .claude/settings.json]`
+10. A new runtime asset the installed package needs is added to the `files`
+    allowlist in `package.json` in the same diff.
+    `[incident: protected-paths.yaml missing from the npm files allowlist]`
+11. PR-monitoring capability is wired into the substrate — a hook, the ship
+    path, or a gate — not left as a step someone must remember to invoke.
+    `[mined: shepherd not armed/auto-attached on ship ×10]`
+
+## Repository hygiene
+
+12. Machine-local runtime state (per-session caches, saved PR diffs, symlinks
+    into worktrees, stray shell artifacts, and transient kernel .export.lock /
+    .tmp-* files) is gitignored, never committed. Deterministic .forge/kernel/
+    JSONL and manifest projections are tracked export/import artifacts. `[git: triage 2026-08-15 found NUL, gw/, .hermes/, .forge/kernel/, pr*.diff untracked at repo root]`

package/README.md

@@ -89,6 +89,11 @@ truth through `forge status`, `forge prime`, and `forge orient` — so a session
 that dies at 2am resumes cleanly the next morning, on any device, with any
 agent.
 
+In Claude Code, Forge also recalls relevant project-local memory automatically
+through its existing lifecycle hooks. Confirmed memories arrive as project
+truth; suggested memories are visibly separated and require verification.
+Every injected memory is scope-checked, budgeted, and provenance-labeled.
+
 ### 🧹 A lifecycle that cleans up after itself
 
 Merged a PR with squash-merge? `forge clean` still knows the worktree is done —
@@ -151,7 +156,7 @@ so a claim can't quietly outrun the code. What's not delivered yet says
 | --- | --- |
 | Knowledge-graph memory (Graphiti) | `memory.backend: graphiti` in `.forge/config.yaml` — temporal, relational recall ([guide](docs/guides/memory-backends.md)) |
 | Global hooks for Codex/Hermes | `forge hooks install --global` (consent-guarded, `--dry-run` first) |
-| Conditional auto-merge | `forge merge --auto <pr>` — off by default, merges only when configured rules pass |
+| Conditional auto-merge | `forge merge --auto <pr> --expect-head <full-sha> --issue <issue-id>` — off by default; requires exact-head and active issue-ownership leases plus protected checks |
 
 ## A workflow you own
 
@@ -261,7 +266,6 @@ Use `bunx forge ...` (or `npx forge ...`) until the `forge` bin is on your PATH.
 | `--dry-run` | Preview planned writes without touching the repo. |
 | `--symlink` | Link instruction files instead of copying, where supported. |
 | `--merge smart\|preserve\|replace` | Choose how setup handles existing instruction files. |
-| `--sync` | Deprecated. Removes old generated Beads/GitHub sync files; future issue sync belongs to Kernel/server authority. |
 
 ## What you get
 

package/bin/forge-cmd.js

@@ -31,6 +31,16 @@ const VALID_COMMANDS = [
 	'verify',
 ];
 
+/**
+ * Find the planning doc for a work slug under a `docs/work` tree.
+ *
+ * Recurses into dated work directories (`YYYY-MM-DD-<slug>`) and returns the
+ * first `plan.md`, `design.md`, or `tasks.md` whose directory slug matches.
+ *
+ * @param {string} dir - Directory to search (typically `docs/work`).
+ * @param {string} slug - Work slug, without the date prefix.
+ * @returns {string|null} Path to the matching doc, or null when none matches.
+ */
 function findWorkPlanDoc(dir, slug) {
 	if (!fs.existsSync(dir)) return null;
 
@@ -60,6 +70,16 @@ function legacyPlanMatchesSlug(fileName, slug) {
 	return legacySlug === slug;
 }
 
+/**
+ * Resolve the planning doc that backs a branch.
+ *
+ * Strips the conventional-commit branch prefix to get the slug, prefers a
+ * `docs/work/<date>-<slug>/` doc, and falls back to the legacy flat
+ * `docs/plans/` layout.
+ *
+ * @param {string} branch - Branch name, e.g. `feat/slice-d1-deletion`.
+ * @returns {string|null} Path to the planning doc, or null when none exists.
+ */
 function findPlanDocForBranch(branch) {
 	const slug = branch.replace(/^(feat|fix|docs|refactor)\//, '');
 	const workPlan = findWorkPlanDoc('docs/work', slug);