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

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
 
@@ -115,9 +120,7 @@ Task 2: Validation logic
 
 ## State Management (Single Source of Truth)
 
-> GitHub issue lifecycle may sync to Beads via CI -- see [docs/guides/BEADS_GITHUB_SYNC.md](docs/guides/BEADS_GITHUB_SYNC.md).
-
-**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 +154,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 +173,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 +235,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 +307,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 +338,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 +366,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,49 @@ 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.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/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);