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

package/skills/gates/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "gates",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 994,
+      "body_lines": 63,
+      "score": 45
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 6,
+    "reachable": true,
+    "keyword_alignment": 1
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 84
+}

package/skills/hermes-forge/SKILL.md

@@ -26,6 +26,7 @@ metadata:
   author: forge
   version: "1.0.0"
   roadmap: forge-2agy.9.7.x
+chainExempt: true
 ---
 
 # Hermes ⇄ Forge consumption contract

package/skills/hermes-forge/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "hermes-forge",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 993,
+      "body_lines": 157,
+      "score": 36
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 2,
+    "reachable": true,
+    "keyword_alignment": 0.33
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 81
+}

package/skills/issue-basics/SKILL.md

@@ -14,6 +14,7 @@ description: >
   the plan->dev->validate->ship pipeline or open a PR (use smith or stage skills); does NOT
   report the current stage or what's in flight (use status).
 allowed-tools: Read, Bash(forge:*)
+terminal: true
 ---
 
 # Issue basics — the CRUD floor

package/skills/issue-basics/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "issue-basics",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 991,
+      "body_lines": 95,
+      "score": 42
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": false,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 60
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 0,
+    "reachable": false,
+    "keyword_alignment": 0
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 63
+}

package/skills/kernel/SKILL.md

@@ -14,6 +14,7 @@ description: >
   merged PR under gates → `smith`; token-bounded state for the Hermes harness →
   `hermes-forge`.
 allowed-tools: Read, Bash(forge:*)
+terminal: true
 ---
 
 # Forge kernel surface
@@ -56,6 +57,43 @@ mutating it — a claim returning ok:true does not by itself prove ownership).
 status → plan → dev → validate → ship → review → verify
 ```
 
+### Chain map (each skill declares its successor)
+
+Every skill carries chain metadata in its frontmatter (`next`, `terminal`,
+`subskills`, `handoffs`); each workflow STAGE skill additionally carries a
+HARD-GATE chain line in its body, so each stage announces the next one. The
+linear ladder:
+
+| Skill | `next` | `terminal` |
+|-------|--------|-----------|
+| `plan` | `dev` | `false` |
+| `dev` | `validate` | `false` |
+| `validate` | `ship` | `false` |
+| `ship` | `review` | `false` |
+| `review` | `verify` | `false` |
+| `verify` | `ship` | `false` |
+
+The `next` column is each stage's DEFAULT / critical-path successor (`plan`
+composes `research`; `ship` and `review` also carry a `shepherd` handoff). The
+actual successor after `ship`, `review`, and `verify` is classification-dependent
+— see the note below. `verify`'s `next` (`ship`) is the `docs`-only pre-ship
+reuse; in every other flow nothing follows `verify`.
+
+Feeders into the chain: `triage-ready` → `claim-safety` → `dev` (rank the pick,
+prove the live lease, then work it). `research` is standalone / callable
+mid-workflow and returns to its CALLER (no forced `next`); it is also a `subskill`
+of `plan`. The `smith` orchestrator composes the six stages (`subskills`).
+Utility/terminal skills (`status`, `shepherd`, `kernel`, `issue-basics`, `memory`,
+`rollback`, `research`, `sonarcloud`, `sonarcloud-analysis`,
+`parallel-deep-research`, `using-forge`) declare no forward-stage `next`. Meta
+skills (`hermes-forge`) are chain-exempt.
+
+The stage `next` values above are the DEFAULT / critical-path successors. The
+actual successor after `ship`, `review`, and `verify` is
+classification-dependent — the authoritative matrix is `lib/workflow/stages.js`
+(Simple/Hotfix/Refactor end at `ship`; Standard ends at `review`; Critical runs
+through `verify`; the `docs` classification reuses `verify` → `ship`).
+
 ## Orchestrator super-skill
 
 `smith` is the flagship: a thin orchestrator that COMPOSES the skills above into

package/skills/kernel/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "kernel",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 993,
+      "body_lines": 187,
+      "score": 33
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 6,
+    "fixtures_best_hit": 0,
+    "reachable": false,
+    "keyword_alignment": 0
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 80
+}

package/skills/memory/SKILL.md

@@ -13,6 +13,7 @@ description: >
   The local backend is always the offline floor. Not for: issue create/list/close ops
   (issue-basics), workflow status (status), or transient scratch notes.
 allowed-tools: Bash, Read, Grep, Glob
+terminal: true
 ---
 
 # Memory
@@ -20,6 +21,16 @@ allowed-tools: Bash, Read, Grep, Glob
 Durable project memory for agents. This skill teaches you where a fact belongs,
 which backend is active, and how to use graph memory when it is enabled.
 
+## Applies to: Forge-managed memory
+
+This skill describes memory managed by **Forge's own store** — `forge remember` /
+`forge recall`, whose backend the Backends section (below) explains. If the repo you are working in ships
+its **own** memory system (a database, an API, a "log a decision" surface, an
+in-app memory service), **that** system is authoritative here and this skill does
+not apply — follow the repo's own memory instructions instead. When unsure, prefer
+the host repo's memory over `forge remember`; a note written to the wrong store is
+a note nobody finds.
+
 ## The one rule
 
 Persistent, project-level knowledge goes to **`forge remember`** — never to a
@@ -33,7 +44,11 @@ is a local file store, so they always work offline with zero setup.
   convention, a decision and its rationale, a non-obvious gotcha, an environment
   quirk, a "we tried X, it failed because Y". Add `--tag <label>` for retrieval.
 - **`forge recall "<query>"`** — before assuming, check what is already known.
-  Search first; do not re-derive knowledge the project already recorded.
+  Search first; do not re-derive knowledge the project already recorded. Note that
+  memory relevant to your current prompt **may already be injected automatically**
+  (a per-turn hook surfaces the best-matching notes; silent when nothing clears the
+  relevance bar). Treat auto-surfaced memory as a head start, and still `recall`
+  explicitly when you need to search for something specific it did not surface.
 - **`forge issue comment <id> "<note>"`** — progress or context that belongs to
   ONE issue's lifecycle (status, a blocker, a hand-off). Issue-scoped, not global.
 - **Rule of thumb:** would a future session on a *different* issue want this? →

package/skills/memory/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "memory",
+  "fixtures": "no-fixtures",
+  "static": {
+    "token_cost": {
+      "desc_chars": 938,
+      "body_lines": 101,
+      "score": 44
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "no-fixtures",
+    "fixtures_total": 0,
+    "fixtures_best_hit": 0,
+    "reachable": null,
+    "keyword_alignment": null
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 83
+}

package/skills/parallel-deep-research/SKILL.md

@@ -17,6 +17,7 @@ compatibility: Requires PARALLEL_API_KEY in .env.local. Uses curl. Takes 3-25 mi
 metadata:
   author: harshanandak
   version: "1.0.0"
+terminal: true
 ---
 
 # Parallel Deep Research

package/skills/parallel-deep-research/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "parallel-deep-research",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 996,
+      "body_lines": 92,
+      "score": 42
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 5,
+    "fixtures_best_hit": 1,
+    "reachable": true,
+    "keyword_alignment": 0.2
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 83
+}

package/skills/plan/SKILL.md

@@ -13,12 +13,18 @@ description: >
   where work stands or what is stale (status), and NOT for everyday issue create/list/close or
   picking the next ready issue (issue-basics / triage-ready).
 allowed-tools: Bash, Read, Write, Edit, Grep, Glob
+next: dev
+terminal: false
+subskills:
+  - research
 ---
 
 Plan a feature from scratch: brainstorm design intent, research technical approach, then set up branch, worktree, and a complete task list ready for /dev.
 
 # Plan
 
+> **Chain (HARD-GATE):** the next skill after `plan` is `dev`. `plan` composes the `research` sub-skill for its Phase 2 technical bundle. Do not skip ahead past `dev`.
+
 `/plan` is the default planning super-skill. A full invocation runs the three legacy sections below (intent, research, setup/task list), but v3 treats the internal planning work as callable sub-skills:
 
 - `plan.intent_capture`

package/skills/plan/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "plan",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 958,
+      "body_lines": 530,
+      "score": 3
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": false,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 60
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 5,
+    "fixtures_best_hit": 4,
+    "reachable": true,
+    "keyword_alignment": 0.8
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 51
+}

package/skills/portability/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: portability
+description: >
+  Forge kernel data portability — getting issue data in and out of the local kernel. `forge
+  export [--dir] [--dry-run]` writes the kernel backlog to deterministic git-tracked JSONL
+  (D16 portability projection); `forge export --import` reads that committed snapshot back
+  into the kernel (hydrate). `forge migrate --from beads [--dry-run] [--source <dir>]` imports
+  a Beads issue store into the kernel — the onboarding path for users coming from Beads. Use
+  when the user says "export the kernel backlog to JSONL", "back up / snapshot the backlog",
+  "re-import / hydrate the backlog", "migrate from beads", or "import a beads store". Honesty:
+  bare `forge migrate --dry-run` (no `--from`) is v2→v3 preview only; a re-import that applies
+  nothing reports "already hydrated". NOT the cloud/backend sync of the kernel (that is `forge
+  sync`, cloud-native), NOT a database/schema migration (plan/dev), NOT memory notes (memory),
+  NOT syncing a git branch with main (ship).
+allowed-tools: Bash, Read, Grep, Glob
+terminal: true
+---
+
+Moving Forge kernel issue data across a boundary: project the backlog to a git-committable snapshot (and hydrate it back), or import an existing issue store into the kernel. This is data portability — distinct from schema/database migrations and from the cloud backend sync (`forge sync`).
+
+# Export / re-import the backlog
+
+```bash
+forge export                     # write the kernel backlog to git-tracked JSONL (deterministic)
+forge export --dir <path>        # choose the projection directory
+forge export --dry-run           # show what would be written, change nothing
+forge export --import            # read the committed JSONL snapshot back INTO the kernel (hydrate)
+```
+
+`forge export` is the **D16 portability projection**: a deterministic, git-committable snapshot of the backlog you can review in a diff and carry between machines or checkouts. `forge export --import` is the reverse — it hydrates the kernel from that on-disk snapshot; a re-import that finds everything already present reports "already hydrated" rather than claiming it imported anything.
+
+# Migrate in from Beads (or preview v2→v3)
+
+```bash
+forge migrate --from beads [--dry-run]     # import a Beads issue store into the kernel
+forge migrate --from beads --source <dir>  # point at exported beads *.jsonl (defaults to auto-detecting .beads/)
+forge migrate --dry-run                    # preview the v2→v3 migration (the ONLY supported mode without --from)
+```
+
+`forge migrate --from beads` is the **onboarding path for users coming from Beads** — it imports a Beads issue store into the Forge Kernel (`--dry-run` reads + maps only, writing nothing). Without `--from`, migrate is **v2→v3 preview only**: `--dry-run` is required and applying the migration is not yet available.
+
+## Boundaries
+
+- The **cloud/backend sync** of the kernel is `forge sync` (cloud-native) — a different operation; this skill is the local, git-based portability projection.
+- A **database/schema** migration (adding a column, altering a table) is application work — that's **plan**/**dev**, not `forge migrate`.
+- Persisting a decision or note is **memory** (`forge remember`), not export.
+- Syncing a git **branch** with main before a PR is **ship**/**worktree**.

package/skills/portability/evals/evals.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Back up the kernel backlog to a git-tracked JSONL snapshot.",
+    "should_trigger": true
+  },
+  {
+    "query": "Export the kernel backlog to git-tracked JSONL.",
+    "should_trigger": true
+  },
+  {
+    "query": "Migrate our Beads issue store into the Forge kernel.",
+    "should_trigger": true
+  },
+  {
+    "query": "Dry-run the beads migration and show what would be imported.",
+    "should_trigger": true
+  },
+  {
+    "query": "Re-import the exported backlog JSONL into the kernel.",
+    "should_trigger": true
+  },
+  {
+    "query": "Migrate the database schema to add the new billing column.",
+    "should_trigger": false
+  },
+  {
+    "query": "Sync my feature branch with main before opening the PR.",
+    "should_trigger": false
+  },
+  {
+    "query": "Remember this decision for later.",
+    "should_trigger": false
+  }
+]

package/skills/portability/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "portability",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 957,
+      "body_lines": 31,
+      "score": 50
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": true,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 100
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 5,
+    "fixtures_best_hit": 5,
+    "reachable": true,
+    "keyword_alignment": 1
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 85
+}

package/skills/research/SKILL.md

@@ -14,6 +14,7 @@ description: >
   heavyweight EXTERNAL market/competitive report (paid Parallel AI); `plan` for the full plan
   stage (brainstorm + tasks); `dev` or `validate` to implement or scan rather than investigate.
 allowed-tools: Bash, Read, Write, Grep, Glob, WebSearch, WebFetch
+terminal: true
 ---
 
 Investigate anything, from anywhere: verify a claim, search the web, find better options, pull

package/skills/research/evals/scorecard.json

@@ -0,0 +1,41 @@
+{
+  "skill": "research",
+  "fixtures": "present",
+  "static": {
+    "token_cost": {
+      "desc_chars": 1014,
+      "body_lines": 179,
+      "score": 33
+    },
+    "caps": {
+      "desc_within": true,
+      "body_within": true,
+      "score": 100
+    },
+    "description_quality": {
+      "has_trigger_cues": false,
+      "has_disambiguation_cues": true,
+      "adequate_length": true,
+      "score": 60
+    }
+  },
+  "router_reachability": {
+    "has_curated_rule": true,
+    "router_exempt": false,
+    "fixtures": "present",
+    "fixtures_total": 5,
+    "fixtures_best_hit": 2,
+    "reachable": true,
+    "keyword_alignment": 0.4
+  },
+  "behavioral": {
+    "trigger_recall": null,
+    "trigger_precision": null,
+    "disambiguation": null,
+    "chain_correctness": null,
+    "outcome_quality": null,
+    "variance": null,
+    "note": "behavioral — W5 (LLM judge): semantic recall/precision/chain/outcome/variance, not deterministic"
+  },
+  "composite": 60
+}

package/skills/review/SKILL.md

@@ -1,24 +1,23 @@
 ---
 name: review
+invocation: user
 description: >
-  Forge REVIEW stage — drives an already-open PR to all-green by resolving EVERY piece of
-  feedback: failing GitHub Actions / CI checks, Greptile and CodeRabbit inline comments and
-  summaries, and the SonarCloud quality gate. It fixes the code, replies to each thread and
-  marks it resolved until checks pass, then runs the pre-merge doc gate and hands the PR off
-  for MANUAL merge — never runs `gh pr merge`. Use whenever a PR has review feedback or red
-  checks: "address the review comments on PR #123", "the bots flagged issues / Greptile score
-  is low", "fix the failing checks and resolve the threads", "CodeRabbit and SonarCloud left
-  comments", "get my PR merge-ready". This MUTATING feedback-resolution stage is distinct from
-  shepherd (only WATCHES an open PR, changes nothing), verify (POST-merge CI health check +
-  closing issues), ship (pushes the branch + opens the PR), validate (PRE-PR local
-  type/lint/test/security), and sonarcloud / sonarcloud-analysis (only QUERY SonarCloud data).
+  Drive an already-open PR's feedback and failing checks to all-green, resolve every thread,
+  run the pre-merge doc gate, then stop for manual merge. Use only when the user asks to
+  address PR feedback or checks; never merges or substitutes for Shepherd monitoring.
 allowed-tools: Bash, Read, Edit, Grep, Glob
+next: verify
+terminal: false
+handoffs:
+  - shepherd
 ---
 
 Process ALL pull request issues including GitHub Actions failures, review-agent inline comments (Greptile, CodeRabbit, Qodo, or human reviewers), SonarCloud analysis, and other CI/CD checks.
 
 # Review
 
+> **Chain (HARD-GATE):** the successor depends on the change classification (source of truth: lib/workflow/stages.js) — Critical → `verify` (post-merge health check); Standard ENDS at `review`. `verify` is the default/critical-path next. While the PR is still open you may hand off to `shepherd` to watch checks toward merge. `review` never merges.
+
 This skill handles ALL issues that arise after creating a pull request.
 
 ## Usage