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

package/skills/setup/evals/scorecard.json

@@ -4,8 +4,8 @@
   "static": {
     "token_cost": {
       "desc_chars": 1021,
-      "body_lines": 74,
-      "score": 43
+      "body_lines": 92,
+      "score": 41
     },
     "caps": {
       "desc_within": true,
@@ -37,5 +37,5 @@
     "variance": null,
     "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
   },
-  "composite": 83
+  "composite": 82
 }

package/skills/shepherd/SKILL.md

@@ -6,8 +6,8 @@ description: >
   open PR, converges CI check state into kernel verdicts, re-runs flaky required
   checks, reaps orphan watchers, and self-retires when no PRs remain; one-shot
   passes (forge shepherd <pr>) exist for a single bounded check. Use when a PR was
-  just opened or shipped; when a session starts with open PRs (start the daemon in
-  a background shell — the singleton lease makes a duplicate start a safe no-op);
+  just opened or shipped; when a session starts with open PRs (Forge automatically
+  wakes the singleton; the lease makes a duplicate start a safe no-op);
   when the user asks "why isn't my PR merging", "what's
   blocking the PR", "is the PR ready", "did a check fail / go red"; when asked to
   "keep watching / keep an eye on / babysit my PRs"; or to read PR verdicts
@@ -27,22 +27,25 @@ Forge owns your open PRs. A singleton daemon converges every open PR toward merg
 `shepherd` is the PR-ownership utility, not a workflow stage. It has two modes over the **single `forge shepherd` verb**:
 
 - **Daemon (default ownership):** `forge shepherd daemon` is a machine-wide singleton for this repo. It heartbeats and converges the whole PR world every ~60s — self-registering hand-opened PRs, restarting killed watchers, reaping verified orphans, converging CI check state into kernel verdicts, retiring merged/closed PRs — then self-retires (releases the lease, kills its children, exits) once no PRs remain open. You do NOT poll by hand; the daemon does.
-- **One-shot pass:** `forge shepherd <pr>` reads one PR's state, takes at most one idempotent Tier-A action, and exits. Use it for a point-in-time question about a single PR.
+- **One-shot convergence:** `forge shepherd <pr>` runs the local review preflight, reads one PR's current-head state, takes at most one idempotent Tier-A action, persists bounded deltas/receipts, and exits. Use it for a point-in-time question or one bounded convergence attempt on a single PR.
 
 ## Which mode? (decision rule)
 
 - User asks about **one PR, right now** ("is #212 ready?", "why is this blocked?") → **one-shot** (`forge shepherd <pr> --pull`).
 - Anything **ongoing** — "keep", "until it merges", "watch", "babysit", multiple PRs, or a session that starts with PRs already open → **ensure the daemon is running**.
 
-## Session-start ritual
+## Automatic attachment
 
-When a session starts and the repo has open PRs, ensure the daemon is running:
+Forge wakes the singleton after a successful supported session start, every
+successful push, and every successful non-dry-run ship. Push does not require a
+locally resolved PR number; the daemon enumerates all open and draft PRs itself.
+Ordinary commands do not launch it.
 
-```bash
-forge shepherd daemon    # start it in the HARNESS BACKGROUND SHELL
-```
-
-The daemon is a **repo singleton** guarded by an O_EXCL lease, so you do NOT need a liveness check first — a second start when one is already running simply exits (the lease is already held). Start it in the harness background shell (Claude Code / Codex background-shell) so it is session-scoped and reaped with the session. NEVER launch a detached spawn from the agent: the detached path is Forge's bare-CLI fallback only. (Automatic per-command launch and a `forge prime` daemon-liveness line are planned follow-ups — W-S4c/W-S5 — not yet wired; until then you start the daemon explicitly as above.)
+The daemon is a **repo singleton** guarded by an O_EXCL lease, so no liveness
+check is needed first. Forge prefers a supplied harness background shell; its
+bare-CLI detached fallback launches from the stable common repository root, not
+the current disposable worktree. Agents never launch a detached spawn directly.
+(A `forge prime` daemon-liveness line remains the separate W-S5 follow-up.)
 
 ## Reading verdicts (the common case)
 
@@ -54,12 +57,22 @@ forge shepherd events <pr> --since <seq>   # only the new events since sequence
 
 `--pull` is strictly read-only (dry-run pass: no rerun, no rebase, no merge, no thread resolution). It returns one bounded, actionable-only payload — `blockers[]`, classified `requiredChecks`, failed-check log `failures[]` (matrix-deduped), and every unresolved `reviewThreads[]` — so you get "everything blocking this PR + what to fix" in one call. Passing checks and satisfied policy are omitted.
 
+A plain `forge shepherd <pr>` also returns a consolidated `localPreflight`, at
+most 128 `deltas`, `receiptIds`, and one explicit `handoff`. The preflight probes
+CodeRabbit and runs strict lint, Sonar parity, structural drift, and affected
+tests. An unavailable or unauthenticated CodeRabbit CLI is reported as
+`UNAVAILABLE`/`INCOMPLETE`, never as a fabricated pass; deterministic failures or
+actual review findings make the remote decision read-only for that pass. A
+checkout that is not the exact PR head is `NOT_APPLICABLE`, never reviewed as if
+it were authoritative.
+
 ### Verdict vocabulary (collapsed, W-S1)
 
 | Verdict | Meaning |
 | --- | --- |
 | `MERGE_READY` | Required checks green, branch up to date — hand off to a human to merge. |
 | `PENDING` | A Tier-A action was taken, or checks are still running — await the next tick/pass. |
+| `INCOMPLETE` | Exact-head local review or durable convergence evidence is unavailable — fail closed and retry after evidence is restored. |
 | `BLOCKED` | Something actionable blocks merge (failing/missing/skipped required check, conflict, behind, unresolved threads, changes requested). Read `blockers[]`. |
 | `CI_DEAD_HEAD` | The head has no required checks running (e.g. an auto-update authored by `GITHUB_TOKEN` never re-triggered CI). Recovery is an **escalation, not an autonomous Tier-A rerun**: it needs a maintainer-provided `FORGE_PR_TOKEN` (contents + pull-requests + checks) to re-author the push so CI re-triggers. |
 | `ESCALATE` | A Tier-C condition (conflict, unreadable required set, persistent failure, oscillation, budget exhaustion). Context is posted to the PR. |
@@ -69,8 +82,8 @@ forge shepherd events <pr> --since <seq>   # only the new events since sequence
 
 | Situation | Command |
 | --- | --- |
-| PR just opened / shipped | ensure `forge shepherd daemon` running |
-| Session starts, open PRs exist, daemon dead | `forge shepherd daemon` (background shell) |
+| PR just opened / shipped | automatic singleton wake; read with `forge shepherd <pr> --pull` |
+| Session starts with open PRs | automatic singleton wake |
 | "Why isn't my PR merging / what's blocking it" | `forge shepherd <pr> --pull` |
 | "Is the PR ready?" | `forge shepherd <pr> --pull` (read `MERGE_READY`) |
 | "A check failed / went red" | `forge shepherd <pr> --pull --json` (read `failures[]`) |
@@ -95,12 +108,22 @@ forge shepherd events <pr> --since <seq>   # only the new events since sequence
 ## Kill-switches
 
 ```bash
-FORGE_SHEPHERD_DISABLE=1        # env: makes the shepherd trigger inert (once the auto-fire wiring lands, W-S4c)
-forge gate disable rail.auto_shepherd   # config gate honored by the trigger + ship/push arming
+FORGE_SHEPHERD_DISABLE=1              # env: makes automatic firing inert
+forge gate disable rail.auto_shepherd # config gate honored by every automatic seam
 ```
 
-Both leave the manual `forge shepherd` surface usable; they only stop the automatic daemon fire.
+CI/test (`NODE_ENV=test`, `BUN_ENV=test`, `CI`, `GITHUB_ACTIONS`, or
+`GITLAB_CI`), dry-run, uninitialized repositories, and disabled paths return
+before lease, Kernel-state, or process work. All leave the manual
+`forge shepherd` surface usable; they only stop automatic daemon fire.
 
 ## State
 
-Progress is durable in GitHub (PR comments, labels, `git`). The one local store is the per-PR journal under `.forge/pr-monitor/<repo>-<pr>/` (append-only `events.ndjson` + snapshot/consumer cursors) — the replay surface for `events --since`. The bounded one-shot pass keeps no separate local state.
+Public Memory is the durable monitor authority and public Flow reducers restore
+its bounded event and watcher-process checkpoints after restart. The per-PR
+journal under `.forge/pr-monitor/<repo>-<pr>/` remains a compatibility delivery
+surface for `events --since`, not authority. Merged/closed evidence produces one
+idempotent terminal MonitorReceipt; conflicting or incomplete replay fails
+closed. For 0.1 no receipt grants continuing lease authority: live ownership is
+re-probed at consequential boundaries, and canonical LeaseReceipt epoch/scope
+plus the same-actor/session ABA fix remain explicitly deferred.

package/skills/shepherd/evals/scorecard.json

@@ -3,9 +3,9 @@
   "fixtures": "present",
   "static": {
     "token_cost": {
-      "desc_chars": 997,
-      "body_lines": 86,
-      "score": 43
+      "desc_chars": 987,
+      "body_lines": 109,
+      "score": 41
     },
     "caps": {
       "desc_within": true,
@@ -37,5 +37,5 @@
     "variance": null,
     "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
   },
-  "composite": 83
+  "composite": 82
 }

package/skills/ship/SKILL.md

@@ -1,18 +1,10 @@
 ---
 name: ship
+invocation: user
 description: >
-  Forge SHIP stage: push the validated feature branch and open a PR populated from the
-  project's OWN PR template (design-doc link, Forge issue IDs, real test/commit data), then
-  hand off for MANUAL merge; never merges or auto-merges. Use once /validate passes and you
-  want a PR on the board. Triggers: "ship it", "ship this branch", "open the PR", "push and
-  open a PR", "gh pr create", "checks passed, now cut the PR". Runs branch-freshness +
-  parallel-PR merge-sim checks, force-with-lease push, records the ship->review handoff, then
-  stops. One stage only; not for: the whole plan->dev->validate->ship->review pipeline or
-  drive-to-done (smith); type-check/lint/tests/security first (validate); addressing PR
-  comments or resolving Greptile/SonarCloud/CodeRabbit threads on an existing PR (review);
-  babysitting an open PR toward merge (shepherd); post-merge CI health check + closing issues
-  (verify); reverting an already-shipped change (rollback). If the PR already exists, this is
-  not the skill.
+  Push a validated feature branch and open its PR from the project's template, then stop for
+  manual merge. Use only when the user asks to ship or open the PR after validation; never
+  merges, auto-merges, reviews an existing PR, or replaces end-to-end Smith.
 allowed-tools: Bash, Read, Edit, Grep, Glob
 next: review
 terminal: false

package/skills/ship/evals/scorecard.json

@@ -3,9 +3,9 @@
   "fixtures": "present",
   "static": {
     "token_cost": {
-      "desc_chars": 993,
+      "desc_chars": 254,
       "body_lines": 237,
-      "score": 28
+      "score": 64
     },
     "caps": {
       "desc_within": true,
@@ -37,5 +37,5 @@
     "variance": null,
     "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
   },
-  "composite": 78
+  "composite": 89
 }

package/skills/validate/SKILL.md

@@ -105,6 +105,9 @@ bun run lint    # or: npm run lint, eslint ., etc.
 - Best practices compliance
 
 ### Step 3: Code Review (if available)
+
+Read `CODING_STANDARDS.md` from the repository root before invoking the reviewer so the review applies the repository's diff-level contract.
+
 ```bash
 /code-review:code-review
 ```

package/skills/validate/evals/scorecard.json

@@ -4,7 +4,7 @@
   "static": {
     "token_cost": {
       "desc_chars": 995,
-      "body_lines": 300,
+      "body_lines": 303,
       "score": 21
     },
     "caps": {

package/skills/worktree/SKILL.md

@@ -71,7 +71,12 @@ forge clean                      # remove worktrees whose branches merged; FF th
 forge clean --dry-run            # show what would be removed, change nothing
 ```
 
-`forge clean` is **squash-aware** — it detects branches that merged via squash, not just fast-forward merges.
+`forge clean` is **squash-aware** — it detects branches that merged via squash, not just fast-forward merges. Removing a merged worktree also closes the kernel issue the branch was linked to, citing the merge as evidence.
+
+Two things it will never touch, because closing an issue is irreversible (`done` is terminal):
+
+- **A branch with no commits of its own.** A freshly created worktree points at a default-branch commit, which git alone reads as "merged". That is unstarted work — it is kept, and its issue stays open.
+- **A worktree it skipped.** Uncommitted changes hold a worktree back, and a held-back worktree never has its issue closed.
 
 ### `forge clean` footguns
 

package/skills/worktree/evals/scorecard.json

@@ -4,8 +4,8 @@
   "static": {
     "token_cost": {
       "desc_chars": 1013,
-      "body_lines": 70,
-      "score": 44
+      "body_lines": 75,
+      "score": 43
     },
     "caps": {
       "desc_within": true,