forge-workflow 0.0.10 → 0.1.0-beta.2

package/skills/shepherd/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: shepherd
+description: >
+  Monitor an already-reviewed OPEN pull request toward merge: read the CI/check rollup and the
+  branch-protection required-check set, take at most one idempotent action (re-run a flaky
+  required check, or post a status reply to a thread), then declare MERGE_READY, PENDING, or
+  escalate. Use when the user says "is PR #123 ready to merge yet?", "poll/watch the checks on
+  my PR", "the required CI job is flaky — kick off a re-run", "keep an eye on this PR until
+  it's green", "babysit the checks after /review", "shepherd PR 45", or "monitor the PR toward
+  merge (rebase if behind, --auto-rebase)". NEVER merges (the human merges in the GitHub UI),
+  edits code, or resolves review threads. Do NOT use to fix or reply-and-resolve PR feedback
+  from Greptile/CodeRabbit/SonarCloud — that is `review`; nor to open/push the PR — that is
+  `ship`; nor for the post-merge "CI green on master + close issues" check — that is `verify`;
+  nor for a general "where am I / what's in flight" report — that is `status`.
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+Run one bounded monitor pass over a pull request: read CI and check state, take at most one idempotent action, then hand off. Never merges and never resolves review threads.
+
+# Shepherd
+
+`shepherd` is a **utility command, not a workflow stage.** It automates the polling / rerun / escalation loop that today is done by hand after `/review`. It does **not** replace `/review` (which still owns semantic review and its stage transition) and does **not** perform the pre-merge doc gate (embedded in `/ship` and `/review`).
+
+## Usage
+
+```bash
+forge shepherd <pr-number>
+forge shepherd <pr-number> --auto-rebase   # opt-in, default OFF
+```
+
+## Bounded-pass model (one pass = one invocation)
+
+Each `forge shepherd <pr>` invocation is **ONE discrete bounded pass**: it reads PR state, takes at most the allowed Tier-A action, then **exits**. It never sits in-process polling "until merge-ready."
+
+This mirrors the project's documented ergonomic from `/review`, the pre-merge gate, and the Greptile process: **poll briefly, then stop and hand off.** Any pass that finds checks still pending exits as `PENDING`, and the next scheduled pass picks up where it left off.
+
+A `--watch` affordance, if you want one, lives in an **external scheduler** (e.g. cron or a `/loop`) that re-invokes the bounded pass on an interval with debounce (>= 60s between passes, cancel-in-progress). There is no in-process infinite loop.
+
+## What it never does
+
+- **Never merges.** There is no merge action and no server-side auto-merge latch. The shepherd terminates at `MERGE_READY` and hands off to the human, who merges in the GitHub UI (mirroring the pre-merge gate's merge handoff).
+- **Never resolves review threads.** It may post a status **reply** to a thread (via the existing `.claude/scripts/review-resolve.sh reply` helper), but thread **resolution** is semantic and stays with `/review`.
+
+## Action ladder
+
+- **Tier-A (autonomous, idempotent, reversible):** re-run a flaky **required** check via `gh run rerun --failed` (capped by a rerun budget). Post status replies to threads (reply only).
+- **Tier-B (opt-in per-flag, default OFF):** `--auto-rebase` rebases onto the base and force-pushes with lease. Preconditions: clean working tree, HEAD unchanged during the pass. A lease rejection is a **hard-stop + escalate** — the shepherd never re-arms the lease, because doing so would clobber the concurrent human push the lease exists to protect.
+- **Tier-C (human escalation):** merge conflicts, required-check failures a rerun did not fix, an unreadable required-check set, unknown mergeability, auth/scope failures, oscillation, and budget exhaustion all stop and escalate with context posted to the PR.
+
+## Merge-readiness gate
+
+Merge-ready is declared **only** when the branch-protection required-check set is **known** AND all of it is green AND the branch is not behind base. The required set is read from `gh api repos/{owner}/{repo}/branches/{base}/protection/required_status_checks`. If branch protection is unreadable (insufficient token scope, or the branch is not protected), the shepherd does **not** guess — it escalates with the readable rollup attached.
+
+## Concurrency & safety
+
+- The advisory `shepherd:active` marker is **not** mutual exclusion. The real guard is a per-action HEAD-SHA re-read: before any mutating action the shepherd re-reads the head SHA, and if HEAD moved since the pass started it **aborts** the action.
+- Auth taxonomy: token expiry (401) pauses and surfaces; insufficient scope (403) is a permanent **hard-stop**; a secondary rate limit (403 + `Retry-After`) honors the delay and resumes on the next pass.
+
+## Per-harness behavior
+
+- **Claude Code / Codex:** invoke `forge shepherd <pr>` directly; an external scheduler may drive repeated bounded passes.
+- **Cursor:** manually-invoked only. Run `forge shepherd <pr>` from a terminal — there is no polling-loop affordance and no hook reliance on this surface.
+
+## State
+
+Progress is durable in GitHub: PR **comments** and **labels** plus `git`. There is no separate local state store.

package/skills/shepherd/evals/evals.json

@@ -0,0 +1,42 @@
+[
+  {
+    "query": "Is PR #212 ready to merge yet?",
+    "should_trigger": true
+  },
+  {
+    "query": "The lint check on my PR keeps failing intermittently — kick off a re-run of the failed jobs.",
+    "should_trigger": true
+  },
+  {
+    "query": "Keep an eye on pull request 88 and tell me when all the required checks pass.",
+    "should_trigger": true
+  },
+  {
+    "query": "I just wrapped up /review on this PR — babysit the checks and escalate if it isn't mergeable.",
+    "should_trigger": true
+  },
+  {
+    "query": "Shepherd PR 300 and rebase it onto master if it's behind.",
+    "should_trigger": true
+  },
+  {
+    "query": "Fix all the CodeRabbit and Greptile comments on my PR and resolve each review thread.",
+    "should_trigger": false
+  },
+  {
+    "query": "The PR just merged to master — confirm CI is green there and close the linked issue.",
+    "should_trigger": false
+  },
+  {
+    "query": "Push my validated feature branch and open a pull request from the template.",
+    "should_trigger": false
+  },
+  {
+    "query": "Where am I in the workflow and what work is still in flight right now?",
+    "should_trigger": false
+  },
+  {
+    "query": "Show me the SonarCloud issues flagged on this PR.",
+    "should_trigger": false
+  }
+]

package/{.github/prompts/ship.prompt.md → skills/ship/SKILL.md}

@@ -1,14 +1,26 @@
 ---
 name: ship
-description: Create PR with comprehensive documentation
-tools: []
+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.
+allowed-tools: Bash, Read, Edit, Grep, Glob
 ---
 
 Push code and create a pull request with full context and documentation links.
 
 # Ship
 
-This command creates a PR after validation passes.
+This skill creates a PR after validation passes.
 
 ## Usage
 
@@ -21,12 +33,12 @@ This command creates a PR after validation passes.
 Do NOT create PR until:
 1. /validate was run in this session with all four outputs shown (type, lint, tests, security)
 2. All checks confirmed passing — not assumed, not "was passing earlier"
-3. Beads issue is in_progress
+3. Forge issue is in_progress (`forge issue show <id>` confirms status)
 4. git branch --show-current output is NOT main or master
 </HARD-GATE>
 ```
 
-## What This Command Does
+## What This Skill Does
 
 ### Step 1: Verify /validate Passed
 Ensure all four validation checks completed successfully with fresh output in this session.
@@ -67,7 +79,7 @@ If merge simulation finds conflicts:
 - Display conflicted files
 - Ask: "Merge conflicts detected with base branch. These PRs should merge first: [list]. Proceed with PR creation anyway? (y/n)"
 - If `n`: exit cleanly
-- If `y`: log override via `bd comments add <id> "Ship override: creating PR despite merge conflicts"`, then continue
+- If `y`: log override via `forge comment <id> "Ship override: creating PR despite merge conflicts"`, then continue
 
 After PR creation completes:
 ```bash
@@ -78,12 +90,14 @@ bash scripts/pr-coordinator.sh auto-label <issue-id>
 bash scripts/pr-coordinator.sh stale-worktrees 2>&1 || true
 ```
 
-### Step 3: Update Beads
+### Step 3: Record PR Handoff
 ```bash
-bd update <id> --status done
-bd sync
+forge comment <id> "PR created: <pr-url>. Awaiting review and merge verification."
+forge sync
 ```
 
+Do not mark the Forge issue done during `/ship`. Completion happens only after merge and post-merge verification.
+
 ### Step 4: Push Branch
 
 Use `--force-with-lease` because `/validate` may have rebased the branch, rewriting history. This is safe: it only forces the push if the remote branch hasn't been updated by someone else since the last fetch.
@@ -117,9 +131,9 @@ If a PR template exists:
 2. **Fill in every section** with actual data from the current PR context:
    - Replace HTML comments (`<!-- ... -->`) with real content
    - Check applicable checkboxes (`- [x]`)
-   - Fill in beads issue IDs (replace `beads-xxx` with actual ID)
+   - Fill in Forge issue IDs (replace `forge-xxx` with actual ID)
    - Fill in test results, validation status, and other concrete data
-   - Reference the design doc: `docs/plans/YYYY-MM-DD-<slug>-design.md`
+   - Reference the design doc: `docs/work/YYYY-MM-DD-<slug>/plan.md`
 3. **Do NOT remove any sections** — fill them all, even if "N/A"
 4. **Do NOT restructure the template** — keep the project's chosen format
 
@@ -134,8 +148,8 @@ If no PR template exists, use this minimal fallback:
 ## Testing
 [How it was tested, test results]
 
-## Beads
-Closes beads-xxx
+## Issue
+Closes forge-xxx
 
 🤖 Generated with [Claude Code](https://claude.com/claude-code)
 ```
@@ -148,18 +162,35 @@ gh pr create --title "<type>: <concise description>" --body "<populated-template
 
 Rules for the PR body:
 - **Use the project's template structure** — never substitute your own format
-- **Fill in concrete data** — commit counts, test results, actual file paths, real beads IDs
+- **Fill in concrete data** — commit counts, test results, actual file paths, real Forge IDs
 - **Check applicable checkboxes** — `[x]` for items that apply, `[ ]` for items that don't
-- **Include "Closes beads-xxx"** in the Beads section (required for auto-close in /verify)
+- **Include "Closes forge-xxx"** in the Issue section (required for auto-close in /verify)
 
-### Step 6: Validate Context and Record Stage Transition
+### Step 6: Confirm Context and Record Stage Transition
 ```bash
-bash scripts/beads-context.sh validate <id>
-bash scripts/beads-context.sh stage-transition <id> ship review \
-  --summary "<PR created, checks pending>" \
-  --decisions "<template sections filled, beads linked>" \
-  --artifacts "<PR URL, branch name>" \
-  --next "<review focus areas>"
+# Confirm the issue carries design + acceptance context (helper when present; otherwise inspect the issue).
+# Only falls back to `forge issue show` when the helper is absent — a real validate failure stays visible.
+if [ -f scripts/beads-context.sh ]; then
+  bash scripts/beads-context.sh validate <id>
+else
+  forge issue show <id>
+fi
+
+# Record the ship→review transition (structured helper when present; kernel-native comment otherwise).
+# The fallback comment mirrors the same envelope the helper emits (Stage:/Summary:/Decisions:/Artifacts:/Next:).
+if [ -f scripts/beads-context.sh ]; then
+  bash scripts/beads-context.sh stage-transition <id> ship review \
+    --summary "<PR created, checks pending>" \
+    --decisions "<template sections filled, issue linked>" \
+    --artifacts "<PR URL, branch name>" \
+    --next "<review focus areas>"
+else
+  forge comment <id> "Stage: ship complete → ready for review
+Summary: <PR created, checks pending>
+Decisions: <template sections filled, issue linked>
+Artifacts: <PR URL, branch name>
+Next: <review focus areas>"
+fi
 ```
 
 ### Team sync after PR
@@ -174,42 +205,47 @@ forge team sync 2>&1 || true
 forge team verify 2>&1 || true
 ```
 
-## Example Output
+## Output
 
-```
-✓ Validation: /validate passed (all 4 checks — fresh output confirmed)
-✓ Freshness: Branch is up-to-date with master
-✓ Beads: Marked done & synced (forge-xyz)
-✓ Pushed: feat/stripe-billing
-✓ PR created: https://github.com/.../pull/123
-  - PR body: Problem → Root Cause → Fix → Value (narrative format)
-  - Beads linked: forge-xyz
-  - Implementation details in collapsible section
+`/ship` reports live validation status, branch freshness, Forge issue PR handoff state, push status, PR URL, template sections, linked issue IDs, and CI polling state. Values come from the current branch, issue tracker, and GitHub response; do not copy static IDs, URLs, or branch names into this skill file.
 
-⏸️  PR created, checks started (Greptile, SonarCloud, GitHub Actions)
-   Poll for up to 60 seconds. If checks are still pending, stop here.
+When checks are still pending after the polling window, stop after reporting the PR number and direct the next session to `/review <pr-number>` once automated checks complete or new feedback appears.
 
-Next: /review <pr-number> (when automated checks complete or new feedback appears)
-```
+## Pre-merge gate (before merge)
+
+Pre-merge is a doc-update **gate/checkpoint**, not a separate stage — run it here, before the PR is handed off for merge, whenever the change touches anything documented:
+
+1. **Finish the docs on the feature branch** (update only what genuinely changed):
+   - `CHANGELOG.md` (always) — entry under `## [Unreleased]` using Keep a Changelog categories, with PR number + issue ID.
+   - `README.md` (user-facing), `docs/reference/API_REFERENCE.md` (API), architecture docs (structural).
+   - `CLAUDE.md` — **USER section only** (between the USER markers); never touch other managed blocks.
+   - `AGENTS.md` (agent config, skills, or cross-agent workflow changes).
+   Commit the doc updates to the feature branch and push.
+2. **Confirm CI is green** — doc commits re-trigger CI; poll briefly (~60s), then hand off if still pending. New review feedback → run `/review` again.
+3. **Sync the issue store** — `forge sync`.
+4. **Hand off for MANUAL merge** — present the PR and stop. **Never run `gh pr merge`; never auto-merge.** The user merges in the GitHub UI, then runs `/verify`.
 
 ## Integration with Workflow
 
 ```
-Utility: /status     → Understand current context before starting
-Stage 1: /plan       → Design intent → research → branch + worktree + task list
-Stage 2: /dev        → Implement each task with subagent-driven TDD
-Stage 3: /validate      → Type check, lint, tests, security — all fresh output
-Stage 4: /ship       → Push + create PR (you are here)
-Stage 5: /review     → Address GitHub Actions, Greptile, SonarCloud
-Stage 6: /premerge   → Update docs, hand off PR to user
-Stage 7: /verify     → Post-merge CI check on main
+Utility: /status  -> Understand current context before starting
+
+Default template:
+  /plan      -> Optional default planner; external planners may satisfy /dev entry
+  /dev       -> Implement each task with subagent-driven TDD
+  /validate  -> Type check, lint, tests, security
+  /ship      -> Push + create PR
+  /review    -> Address PR feedback
+  /verify    -> Post-merge health check
+
+Pre-merge gate: doc updates + CI-green checkpoint embedded in /ship and /review (not a separate stage).
 ```
 
 ## Tips
 
 - **Use the project's PR template**: Always read `.github/pull_request_template.md` (or equivalent) and populate it — never substitute your own format
 - **Fill every section**: Even if "N/A" — empty/missing sections cause review friction
-- **Include "Closes beads-xxx"**: Required for auto-close in /verify
+- **Include "Closes forge-xxx"**: Required for auto-close in /verify
 - **Concrete data only**: Test counts, file paths, commit SHAs — not placeholder text
 - **Poll briefly, then stop**: Check PR status for up to 60 seconds, then hand off if checks are still pending
 - **NO auto-merge**: Always wait for /review phase

package/skills/ship/evals/evals.json

@@ -0,0 +1,42 @@
+[
+  {
+    "query": "Validation came back clean — go ahead and open the pull request for this branch.",
+    "should_trigger": true
+  },
+  {
+    "query": "Push my feature branch and raise a PR, and fill in our PR template with the issue and design-doc links.",
+    "should_trigger": true
+  },
+  {
+    "query": "Dev's done and all the checks passed, cut me a PR.",
+    "should_trigger": true
+  },
+  {
+    "query": "Do a gh pr create for feat/rate-limit using the repo's template, not a hand-written body.",
+    "should_trigger": true
+  },
+  {
+    "query": "Everything's green after validate — ship it, but hand it off for me to merge, don't merge it yourself.",
+    "should_trigger": true
+  },
+  {
+    "query": "Take forge-42 from planning all the way to a merge-ready PR — plan it, build it TDD, validate, then ship, checking with me at the gates.",
+    "should_trigger": false
+  },
+  {
+    "query": "The PR's picked up Greptile and CodeRabbit comments — fix them and resolve the threads.",
+    "should_trigger": false
+  },
+  {
+    "query": "Run the type-check, lint, tests and security scan before I push anything.",
+    "should_trigger": false
+  },
+  {
+    "query": "Keep watching PR #128 and ping me the moment its checks go green so I can merge.",
+    "should_trigger": false
+  },
+  {
+    "query": "The PR merged to master — confirm CI is green there and close the linked issue.",
+    "should_trigger": false
+  }
+]

package/skills/smith/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: smith
+description: >
+  The flagship Forge orchestrator: given a goal or a ready issue, it composes the
+  stage skills (triage-ready · claim-safety · plan · dev · validate · ship · review
+  · verify) into the right path for the work, running autonomously between human
+  gates and pausing at them. Use this whenever the user wants to work the next ready
+  issue, drive a feature or fix end-to-end, "take this through to a PR", orchestrate
+  the whole workflow with human checkpoints, or asks some form of "what should I
+  work on and get it done" — even if they never say "smith" or "orchestrate". Reach
+  for it especially when the request spans multiple stages (plan → build → ship) or
+  asks to keep a human in the loop at intent, plan, or merge. Prefer a single stage
+  skill only when the user explicitly wants just that one step (e.g. "just open the
+  PR").
+allowed-tools: Read, Bash(forge:*)
+---
+
+# Smith — the orchestrator super-skill
+
+Smith is a thin orchestrator. It adds no stage behaviour of its own; every step
+below is an existing skill or `forge` verb. What smith contributes is *judgement*:
+which path to take for this piece of work, and how densely to involve the human.
+It is maximally driving between gates and deliberately stops at them — the goal is
+conversational autonomy, not unattended autonomy.
+
+Keep the word "kernel" internal — it is the event store under the hood, not a
+term users should see.
+
+Deeper lookup tables live in
+[references/autonomy-and-gates.md](references/autonomy-and-gates.md): read that
+when you calibrate a specific issue or need the exact gate IDs and commands.
+
+## The orchestration procedure
+
+1. **Pick the work with `triage-ready`.** Rank the ready queue
+   (`forge issue ready --json`) and explain why the top pick is genuinely
+   workable. Readiness is a *derived* model, so recompute it each time rather than
+   trusting a remembered "ready" — you want the item that is actually unblocked
+   now, not a stale guess. Hand off one issue.
+
+2. **Claim it, then prove you own it, with `claim-safety`.**
+   `FORGE_ACTOR=<actor> forge claim <id>`, then `forge issue owns <id>` (exit 0 =
+   owned). A claim returning `ok:true` is not proof — a duplicate replay returns
+   `ok:true` too, and a live lease can be reclaimed once it expires. Proving
+   ownership is what stops two agents from quietly working the same issue. If you
+   are not the owner, don't work it; reselect via `triage-ready`.
+
+3. **Calibrate autonomy during planning.** Read the issue's size × importance ×
+   complexity, map it to a tier (lean / standard / high), and *propose that tier
+   directly to the human* — a short "here's how much oversight I think this needs."
+   This proposal is a plain conversational checkpoint at the start of planning; it
+   is deliberately **not** itself one of the enforcement gates, so it stays reachable
+   even for the Lean tier (which may require no intent gate at all). The human
+   confirms or overrides, and the chosen tier decides **which enforcement gates you
+   require approval for on this issue** (step 5). Keep the two mechanisms distinct:
+   `forge gate enable|disable <gate>` is the **repo-wide default** (a gate the user
+   turned off is always skipped), whereas the per-issue tier is *your* runtime
+   decision about which of the still-enabled gates to actually require for this one
+   issue. Matching checkpoint density to stakes is the whole point: a docs typo
+   should not drag through a full brainstorm, and a risky refactor should not run
+   unattended. When your read is uncertain, lean toward *more* gates — an extra
+   approval costs seconds, a missing one can cost a lot of rework. See the
+   reference for the tier → gate mapping.
+
+4. **Drive the stages along the path that fits.** Sequence
+   `plan → dev → validate → ship → review → verify`, invoking each stage skill as
+   its step arrives. The stage skills already encode the TDD, validation, and
+   review discipline, so smith's job is only to pick the path by change
+   classification (critical / standard / simple / hotfix / docs / refactor): a docs
+   typo skips brainstorming and most of the ladder; a critical feature runs the
+   full ladder.
+
+5. **Stop at every enabled human gate.** Before advancing past a gate, run:
+
+   ```bash
+   forge gate check <issue> <gate>     # exit 0 iff the gate is disabled or approved
+   ```
+
+   On exit 0, proceed. On non-zero, stop and ask the human to
+   `forge gate approve <issue> <gate> [--reason "…"]` (or
+   `forge gate reject <issue> <gate> --reason "…"` to send it back); inspect
+   history any time with `forge gate status <issue>`. Approvals are recorded as
+   durable events, which is what lets smith re-check and continue after a crash or
+   compaction instead of re-asking. The three human gates are `gate.intent`,
+   `gate.plan-approval`, and `gate.merge` (details in the reference).
+
+6. **Re-prove ownership and check readiness before closing.** A lease can expire
+   and be reclaimed while you work, so run `forge issue owns <id>` again before you
+   close — you don't want to close someone else's issue. Then confirm the tree is
+   actually shippable:
+
+   ```bash
+   forge release check --target <version> --json   # success:true ⇒ healthy
+   ```
+
+   Close only when ownership holds and readiness is healthy
+   (`forge close <id> --reason "…"`), then `forge sync`.
+
+## Autonomy tiers at a glance
+
+Full table and the reasoning are in the reference; the short version:
+
+- **Lean** — small · simple · low-importance work: enforce just `gate.merge`, or
+  run under CI with the human gates disabled.
+- **Standard** (default) — an ordinary feature/bug: enforce `gate.intent`,
+  `gate.plan-approval`, and `gate.merge`.
+- **High** — large · important · or complex work: enforce all three, plus
+  per-milestone check-ins and a pre-ship pass.
+
+The tier is a **per-issue** decision: smith requires `check`/approval only for the
+gates its tier calls for on *this* issue and simply skips the rest — it does not
+toggle repo config per issue. Separately, `forge gate disable <gate-id>` is the
+**repo-wide** off switch (a disabled gate makes `check` fall through for *every*
+issue) — use it when the user never wants that checkpoint at all. So a lean run
+skips a checkpoint by not requiring it for this issue; disabling a gate removes it
+everywhere.
+
+## Reliability
+
+- **The human always wins, and uncertainty adds oversight.** Smith proposes a
+  tier; it never lowers the human-loop density on its own, and a rejected gate
+  sends the work back rather than proceeding.
+- **Re-check gates on resume.** After any interruption, trust the recorded events
+  (`check` / `status`), not your memory of what was approved.
+- **Prove ownership twice** — after claiming and again before close/release.
+- **Never bypass a gate or a hook.** A failed gate or failing hook is a stop to
+  resolve, not an obstacle to route around (no `LEFTHOOK=0`, no `--no-verify`).
+
+## Fork points
+
+Smith is a default assembly, not a fixed ladder — re-carve it:
+
+| Knob | Default | How to change |
+|------|---------|---------------|
+| **Stakes heuristic** | size × importance × complexity → tier | Re-weight it (e.g. weight blast-radius or reversibility higher), or map your own change-classes to tiers. |
+| **Tier → gate set** | lean / standard / high (see reference) | Change which human gates each tier enforces; enact per repo with `forge gate enable\|disable <gate-id>`. |
+| **Gate density** | intent · plan-approval · merge | Add a checkpoint (enable a gate or add a per-milestone pause) or drop one (disable it); the human overrides smith's proposal at `gate.intent`. |
+| **Composed flow** | triage → claim → plan → dev → validate → ship → review → verify | Skip stages by change class (docs typo → doc-only path), reorder, or swap in your own `plan`/`dev`/`review` adapter. |
+| **Release target** | `forge release check` default | Pass `--target <version>` for the release you are certifying. |
+
+Smith is the assembled hammer; the sub-skills are the head and handle; the gates
+are the grip adjustments. Ship a good default, then let users re-carve it.

package/skills/smith/evals/evals.json

@@ -0,0 +1,46 @@
+[
+  {
+    "query": "Grab the next ready issue off the board and take it all the way through to a PR for me — plan it, build it TDD, validate, and open the PR, but stop and check with me before it actually merges.",
+    "should_trigger": true
+  },
+  {
+    "query": "I want you to orchestrate the whole workflow for the payments-webhook feature end to end: design the plan, do the dev, run validation, ship it, handle the review comments — just keep me in the loop at the plan-approval and merge points.",
+    "should_trigger": true
+  },
+  {
+    "query": "What should I pick up next? Whatever's highest-priority and ready, claim it and drive it to done with the usual human checkpoints — I don't want to babysit every step but I do want to approve the design and the merge.",
+    "should_trigger": true
+  },
+  {
+    "query": "Take issue forge-9k2 from planning through a merged PR. It's a big risky refactor so keep me involved — I want to sign off at intent, at the plan, and per milestone before you push.",
+    "should_trigger": true
+  },
+  {
+    "query": "Run the full plan through ship flow on the login-rate-limit bug, but it's a tiny fix so don't over-gate it — just let me approve the merge and go.",
+    "should_trigger": true
+  },
+  {
+    "query": "Autonomously work through the ready queue and get each task to a PR, pausing for my approval before any merge.",
+    "should_trigger": true
+  },
+  {
+    "query": "Just open the PR for my current branch, it's already validated and I've written the description.",
+    "should_trigger": false
+  },
+  {
+    "query": "What stage am I in and what's my active work right now? Anything gone stale?",
+    "should_trigger": false
+  },
+  {
+    "query": "Go through the CodeRabbit and SonarCloud comments on PR #288 and address them, then re-request review.",
+    "should_trigger": false
+  },
+  {
+    "query": "Create a feature issue for adding dark mode to the settings page, priority 2, and link it under the theming epic.",
+    "should_trigger": false
+  },
+  {
+    "query": "Just claim forge-abc for me so nobody else picks it up while I look at it.",
+    "should_trigger": false
+  }
+]

package/skills/smith/references/autonomy-and-gates.md

@@ -0,0 +1,94 @@
+# Autonomy calibration & human gates — reference
+
+Read this when you are calibrating how much to involve the human on a specific
+issue, or when you need the exact gate commands and IDs. `SKILL.md` carries the
+procedure; this file carries the lookup tables and the reasoning behind them.
+
+## The three human gates
+
+Forge registers three human gates in the runtime graph as **approval-satisfied
+events** (`requires: []`), additive to the evidence exit-gates. They are the
+points where smith pauses and hands control to the human.
+
+| Gate | Fires | What the human is deciding |
+|------|-------|----------------------------|
+| `gate.intent` | before planning / brainstorm | Do we agree on the goal, and on the autonomy tier smith proposed, before any design work? |
+| `gate.plan-approval` | after the design doc + task DAG exist, before `dev` | Is this plan the right one (approve), or should it be redirected? |
+| `gate.merge` | after `review`, before merge | Is the PR good to merge? |
+
+The evidence exit-gates — `gate.plan-exit`, `gate.dev-exit`,
+`gate.validate-exit`, `gate.ship-entry` — are a different kind: they are
+satisfied by artifacts *inside* the stage skills (a design doc, TDD tests,
+validation output), not by a human. Smith relies on each stage skill's own exit
+checks for those and does not gate on them itself.
+
+### Why gates are events, not prose
+
+Each approval is written to the issue's event stream as a durable
+`gate.approved` / `gate.rejected` record. That is what makes a gated run
+**resume-safe**: if smith is interrupted by a crash or a context compaction, it
+re-reads the event with `check` / `status` on resume and knows whether it may
+proceed — instead of re-asking the human or guessing from memory. Prose in a
+transcript cannot survive a compaction; an event can.
+
+### Gate commands
+
+```bash
+forge gate check <issue> <gate>              # exit 0 iff the gate is DISABLED or APPROVED
+forge gate approve <issue> <gate> [--reason] # human records approval (durable event)
+forge gate reject  <issue> <gate> --reason   # human sends the work back
+forge gate status  <issue> [--json]          # list this issue's gate events (who/when)
+forge gate enable|disable <gate-id>          # repo default toggle: workflow.gates.<id>.enabled
+```
+
+`check` is the enforcement primitive smith calls before advancing past a gate. It
+exits 0 when the gate is disabled for the repo *or* an approval event exists, so a
+disabled gate simply falls through — that is how a lean tier skips a checkpoint.
+
+## Autonomy calibration — stakes → gate density
+
+Match checkpoint density to what is at stake. A one-line docs fix and a risky
+refactor need very different amounts of oversight: forcing the docs fix through a
+full brainstorm wastes everyone's time, while letting the refactor run unattended
+risks a large wrong turn. Smith reads the issue's **size × importance ×
+complexity**, proposes a tier at `gate.intent`, and the human confirms or
+overrides.
+
+| Tier | Stakes read | Enforced human gates | Extra checkpoints |
+|------|-------------|----------------------|-------------------|
+| **Lean** | small · simple · low-importance (docs typo, one-line fix) | just `gate.merge`, or none under CI | skip the intent brainstorm; lean on CI + the evidence exit-gates |
+| **Standard** (default) | an ordinary feature or bug | `gate.intent` · `gate.plan-approval` · `gate.merge` | the evidence exit-gates as configured |
+| **High** | large · important · or complex (critical feature, risky refactor) | all three human gates, enabled | per-milestone / per-task human check-ins (pause + `forge comment`), an explicit pre-ship review pass |
+
+### How a tier is enacted
+
+The tier maps to *which gate events are required* for this issue. The human enacts
+add/drop with `forge gate enable|disable <gate-id>` (the repo default), and smith
+enforces every *enabled* gate via `check`. Because approvals are per-issue events,
+the human can add or drop a checkpoint mid-flight and smith re-reads it on the next
+step — the calibration is not frozen at planning time.
+
+### Why uncertainty adds gates rather than removing them
+
+Smith only *proposes* a tier; it never lowers oversight on its own. When its read
+of size/importance/complexity is low-confidence, it defaults to **more**
+checkpoints, because an unwanted extra approval is a few seconds of the human's
+time, while a missed one can mean a large amount of wasted or wrong work. The
+human always wins the final say.
+
+## Composition map — smith invents nothing
+
+Every step is an existing skill or `forge` verb; smith only sequences them.
+
+| Step | Composed skill / verb |
+|------|-----------------------|
+| Pick work | `triage-ready` (`forge issue ready` / `blocked` / `stats`) |
+| Claim + prove ownership | `claim-safety` (`forge claim` → `forge issue owns`) |
+| Human gates | `forge gate check` / `approve` / `reject` / `status` |
+| Plan | `plan` (intent brainstorm → design doc → task DAG) |
+| Build | `dev` (per-task implementer → spec → quality TDD) |
+| Validate | `validate` (types · lint · security · tests) |
+| Ship | `ship` (push + PR) |
+| Review | `review` (address CI / bot feedback) |
+| Verify | `verify` (post-merge health) |
+| Release readiness | `forge release check --target <version> --json` |