[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75GXMB7NTF1PQATSS9THR7A":3,"skill-same:01M75GXMB7NTF1PQATSS9THR7A":59},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":13,"repositoryHtmlUrl":27,"repositoryHomepageUrl":28,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M75GXMB7NTF1PQATSS9THR7A","forge-4-backlog",null,"Generate a structured backlog.json from forge implementation specs, then validate it via the loop runner. Use when user runs \u002Ffeature-forge:forge-4-backlog or asks to create a backlog for a forge feature after specs are complete. This is the canonical backlog generator for the forge pipeline. Do NOT trigger for standalone backlog creation outside the forge pipeline context.","garygentry\u002Ffeature-forge","garygentry","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F12444042?v=4","01M75GWTRXHQMKFWDVG9N8ENNS","01M75GWTSZ5NV3MYKFWVCZJKW4",0,"MIT","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-4-backlog\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\n# GENERATED — DO NOT EDIT. Source: skills\u002Fforge-4-backlog\u002FSKILL.md. Regenerate: python3 scripts\u002Fbuild-adapters.py\nname: forge-4-backlog\ndescription: Generate a structured backlog.json from forge implementation specs, then validate it via the loop runner. Use when user runs \u002Ffeature-forge:forge-4-backlog or asks to create a backlog for a forge feature after specs are complete. This is the canonical backlog generator for the forge pipeline. Do NOT trigger for standalone backlog creation outside the forge pipeline context.\nargument-hint: \u003Cfeature-name>\n---\n\n# forge-4-backlog — Backlog Generator (pipeline orchestrator)\n\nGenerate a complete, validated `backlog.json` from the implementation spec\nsuite, ready for the loop runner.\n\nThis skill is a **thin orchestrator**: it owns the *pipeline* concerns\n(prerequisite checks, spec loading, plan review, validation, pipeline-state and\ncommit). The actual **authoring craft** — granularity, acceptance criteria,\n`agentDelegation`, the schema, examples — lives in the rauf plugin's\n**`author-backlog`** skill, which this skill delegates to. That keeps a single\nhome for backlog-authoring knowledge, shared with the repo-wide ad-hoc flow.\n\n## Prerequisites\n\nRead and follow `references\u002Fshared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding. Resolve the feature directory `{resolvedFeatureDir}` via the **Feature Directory Resolution** block in `references\u002Fshared-conventions.md` — do not hardcode `{specsDir}\u002F{feature}\u002F` (see Step 1).\n\nResolve the **backlog directory** `{backlogDir}`:\n- **`backlogDir` unset (default):** the backlog lives at the resolved feature directory — `{resolvedFeatureDir}\u002Fbacklog.json` — for both flat and nested features, exactly as today.\n- **`backlogDir` configured:** compose a **per-feature subpath** — `{backlogDir}\u002F{feature}\u002F` — so each epic member's backlog stays independent (the authored file lands at `{backlogDir}\u002F{feature}\u002Fbacklog.json`). A bare shared `backlogDir` would collide across a multi-feature epic and violate REQ-COMPAT-03; the `{feature}` segment prevents that. Standalone features under a configured `backlogDir` likewise resolve to `{backlogDir}\u002F{feature}\u002F`, which is backward-compatible because each standalone feature name is already unique.\n\nThis is the **single** place this rule is implemented. forge-5-loop's backlog-file check must read the same composed `{backlogDir}\u002F{feature}\u002Fbacklog.json` (that matching forge-5-loop edit lands in item 016), and forge-verify's backlog-mode load uses the same path. rauf itself is unchanged: backlogs remain per-feature and rauf is still launched against a single per-feature backlog path — only the *path composition* changes (REQ-COMPAT-03).\n\n**Let `{resolvedBacklogDir}` denote the composed target of this rule** — i.e. `{backlogDir}\u002F{feature}` when a `backlogDir` is configured, else `{resolvedFeatureDir}`. Every downstream step below (authoring, validation) uses `{resolvedBacklogDir}`, never the bare config value, so the per-feature `{feature}` segment is never dropped.\n\nResolve the **loop runner** with the command below — it merges this project's `loopRunner` block over the schema defaults deterministically (defaults to rauf), so do not read the config schema for defaults. Use the emitted object as the effective `loopRunner`; you need its `bin`, `validateCommand`, `versionCommand`, `minRunnerVersion`, and `installHint`. If the call exits 2, surface the plain `Error:` line from stderr verbatim and fall back to the documented rauf defaults.\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" effective-config --config .\u002Fforge.config.json --json\n```\n\n**Turn structure reminder:** Text first, then `AskUserQuestion` for all questions — never embed one in your text (it stalls). At rung 2\u002F3, see the Interaction Capability Ladder.\n\n## Step 1: Validate Prerequisites\n\n**Resolve the feature directory first.** Invoke the **Feature Directory Resolution** block in `references\u002Fshared-conventions.md` to turn the bare feature name into `{resolvedFeatureDir}` (exit 0 → stdout is the absolute dir; exit ≥ 1 → STOP and surface the finding verbatim). Read state and specs from `{resolvedFeatureDir}\u002F` everywhere this skill previously wrote `{specsDir}\u002F{feature}\u002F`. Standalone features resolve to their flat path exactly as today.\n\n**Prerequisite check:** Read `{resolvedFeatureDir}\u002F.pipeline-state.json`. If not in force mode, stages `forge-1-prd`, `forge-2-tech`, and `forge-3-specs` must all be `complete`. If not, STOP and tell the user which prerequisites are missing.\n\n**Carried-over note check.** If that state's top-level `notes` is a non-empty string, surface it verbatim before proceeding and treat it as input to this stage — it was persisted for exactly this cross-session handoff (often at the previous stage's exit), and it can carry backlog-shaping constraints (e.g. \"no item may create file X\"). It never overrides the specs or config; raise any conflict instead of silently following either side.\n\nAfter the prerequisite check, invoke the **Stage-Entry Guard** block in `references\u002Fshared-conventions.md` with `{stage}` = `forge-4-backlog` — it detects an interrupted or complete `backlog.json`, runs the resume\u002Frestart or new-version gate, and stamps entry before Step 2 loads the specs. (The backlog is a single artifact, so \"resume\" means: reuse the existing `backlog.json` if the previous run wrote it, rather than re-authoring from scratch.)\n\nThen invoke the **Epic-Member Base Guard** block in `references\u002Fshared-conventions.md` (this stage does not run Epic Context Injection, so invoke it explicitly here). It self-gates to a no-op for standalone features; for a nested epic member on a branch that lacks the epic manifest it stops with a home-branch pointer (Issue #125).\n\n**Verification check.** Derive whether the upstream specs have been verified from the settled on-disk record, never by eyeballing conversational state. Run `verify-state --for-stage forge-3-specs` — it reads the served stage's `forge-verify-specs` entry and returns `{case, verified, stale, message, nextCommand}`. Add `--epic \"{epic}\"` when this feature is an epic member (nested layout). The full case enum and its rationale live in `references\u002Fverify-state.md`.\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" verify-state --feature \"{feature}\" --for-stage forge-3-specs --specs-dir \"{specsDir}\" --json\n```\n\nIf `verified` is true, proceed with no prompt. Otherwise print the returned `message`, then use `AskUserQuestion` to warn with the cost of skipping — unverified specs can carry gaps or contradictions that get baked into backlog items and only surface mid-loop, where they're far more expensive to fix — and offer **Verify first (recommended)** (run the returned `nextCommand`) · **Continue without verifying**. This is a pre-stage read of the upstream artifact, so the proceed-anyway path writes nothing.\n\n## Step 2: Load All Specs\n\nRead all spec documents into context:\n- `{resolvedFeatureDir}\u002FPRD.md`\n- `{resolvedFeatureDir}\u002Ftech-spec.md`\n- `{resolvedFeatureDir}\u002F##-*.md` (all implementation specs)\n\nIf the spec suite is large (8+ documents), focus on loading the architecture layout (01-*), shared types (00-*), and testing strategy documents first. Load individual subsystem specs as needed when writing the corresponding backlog items, rather than loading all specs simultaneously.\n\n## Step 3: Plan the Backlog\n\nBefore writing any JSON, walk the specs and create a backlog plan: discrete work items, ordered by dependency (foundation first), with priorities, each scoped for a single loop iteration.\n\nPresent the plan as a numbered list:\n```\nProposed backlog for {feature} ({N} items):\n\n  001 [P1] Scaffold module with project manifest, build config, and entry points\n      Depends on: (none)\n      Specs: 00-core-definitions.md, 01-architecture-layout.md\n\n  002 [P1] Implement shared types and error hierarchy\n      Depends on: 001\n      Specs: 00-core-definitions.md\n  ...\n```\n\nAfter presenting the plan as text, use `AskUserQuestion` following the **Decision Support** protocol in `references\u002Fshared-conventions.md`: recommend this breakdown as the default (it's your evidence-backed read of the specs and dependency order) and name the trade-off that governs item granularity — finer items are each easier to verify in one loop iteration but multiply coordination and dependency edges; coarser items mean fewer handoffs but risk an item too big to complete or verify in a single iteration. Lead with: \"I recommend this breakdown. Any items to split, merge, or reorder?\" Do NOT include this question in your text output. Wait for the user's response before generating the JSON.\n\n## Step 4: Author backlog.json — delegate to `author-backlog`\n\n**Invoke the rauf plugin's `author-backlog` skill** (via the Skill tool) to write\n`{resolvedBacklogDir}\u002Fbacklog.json`. Pass it:\n\n- the target backlog directory `{resolvedBacklogDir}`,\n- the approved plan from Step 3,\n- the spec context loaded in Step 2,\n- the project's `typeCheckCommand` \u002F `testCommand` (from `forge.config.json`) so acceptance criteria are concrete and runnable.\n\n`author-backlog` owns all item-quality rules (granularity hard limits, self-contained descriptions, acceptance criteria, `agentDelegation`, the correct `type`\u002F`status` enums, `dependsOn`, `specReferences`, the schema source). Do not re-encode them here — follow whatever it produces.\n\n**Return contract.** This is the **delegate-and-resume** posture of \"Caller-side resumption: the declared resume point\" in `references\u002Fstage-exit-protocol.md`. `author-backlog` is a sub-skill of this stage, not its terminal: when it returns, control returns to **this skill, at Step 5** — forge-4 still owns the stage and its terminal output. Two of the sub-skill's own instructions do not apply on this delegated path (it also serves direct user invocation, and those instructions are its direct-invocation posture): its wait-for-user-approval-before-writing gate is already satisfied by Step 3's approved plan — do not re-ask; and its closing \"run `rauf backlog validate` … and confirm the validated result\" posture is subsumed by Step 5, which owns validation (see Step 5's ownership note). Do not adopt the sub-skill's report-and-stop terminal — it is the freshest instruction in context after the return, but it belongs to the sub-skill: continue to Step 5 in the same turn; Steps 6 and 7 still run, and the stage closes only at Step 7's exit.\n\n> **If the rauf plugin \u002F `author-backlog` skill is not available:** fall back to\n> authoring inline using the schema source rule (prefer the project's installed\n> `{stateDir}\u002Fbacklog.schema.json`, else the published `$id`\n> `https:\u002F\u002Fraw.githubusercontent.com\u002Fgarygentry\u002Frauf\u002Fmain\u002Fschemas\u002Fbacklog.schema.json`),\n> and tell the user the rauf plugin provides richer authoring guidance.\n\n**Forge-specific item requirements** layered on top of `author-backlog`'s output:\n- `specReferences` must be paths **relative to the project root** (e.g. `specs\u002Fauth\u002F00-core-definitions.md`), NOT relative to the backlog file. The validator resolves them from the project root (not from `--specs-dir`, which only gates the check).\n- **Epic members — cross-member shared-state coupling (#144).** When authoring the backlog for an epic member, check whether this feature writes or migrates a file that a *sibling* member's already-shipped tests pin (its `mutatesShared[]` hint in `epic-manifest.json`, or a shared data corpus \u002F generated fixture its specs say it mutates). If so, schedule a **reconciliation item up front** — before the first mutating item — that regenerates or re-pins the sibling's fixture (or updates the sibling test to the new shape), so the sibling suite stays green instead of red-gating every commit mid-loop. This is the authoring counterpart to forge-verify's CHECK-E10.\n- **Generated-artifact freshness vs. `testCommand` `--check` gates (#145).** If the project's `testCommand` gates on staleness of generated artifacts (`\u003Cgenerator> --check`-style sub-commands that fail when a checked-in generated file is out of date), then any item that regenerates **one** such artifact must regenerate **and commit all** the sibling artifacts those `--check` gates depend on — enumerate the whole gated set, not just the artifact the item is \"about\", or the item passes locally yet red-gates on the stale-generated check. Pass this to `author-backlog` alongside `testCommand` so the full regeneration sequence lands in each affected item; forge-verify's CHECK-B26 flags a partial set or an ungated regenerator after the fact.\n- **Lifecycle-gated artifacts — no test item forcing a forbidden transition (#150).** A test\u002Fe2e item whose acceptance asserts a *published \u002F released \u002F approved \u002F human-reviewed* artifact state must either (a) `dependsOn` an explicit, human-gated publish\u002Freview item that legitimately produces that state, or (b) assert the state via a **dev-build \u002F fixture path**. A test item must **never** be the only thing forcing a lifecycle transition another item pins the other way (e.g. one item keeps artifact `X` *draft* while a test demands it *published*, with nothing between to publish it) — the loop, unable to publish or obtain a human sign-off, will **fabricate** the provenance. `author-backlog` owns the general rule; forge-verify's CHECK-B27 flags a contradictory pair with no publisher in the dependency closure after the fact.\n\n> **Backlog schema & rauf contract are unchanged (REQ-COMPAT-03).** Epic membership adds **no** fields to backlog items — dependency edges live in the epic manifest, never in any backlog item. The JSON written here is byte-for-byte the same shape as a pre-epic standalone feature's backlog, and rauf is still launched against a single per-feature backlog path. Only the *path composition* changes (the `{feature}` segment in the backlog-directory rule above), not the schema or rauf's CLI surface.\n\n## Step 5: Validate via the loop runner\n\n**Validation ownership.** This step is authoritative for validation, whether or not `author-backlog` already ran its own `rauf backlog validate`: this stage carries the degradation rules for a missing\u002Fold\u002Fnot-set-up runner (below) that the sub-skill does not, and this step's result is what Step 6 reports. A validate the sub-skill already ran cleanly makes this a cheap idempotent re-run, never a reason to skip it — and the sub-skill's validate never discharges this step.\n\nValidate the generated backlog by running the runner's **validate command**\n(`loopRunner.validateCommand`), rendered with `{resolvedBacklogDir}` and `{specsDir}`\nsubstituted — the rauf default:\n\n```bash\nrauf backlog validate . --backlog {resolvedBacklogDir} --specs-dir {specsDir} --json\n```\n\nInterpret the result:\n- **exit 0** → valid (warnings allowed). Proceed.\n- **exit 1** → validation findings. Parse `{ valid, findings[] }`, fix the items, re-run. Do NOT present the backlog to the user until it validates.\n- **exit 2** → usage\u002FIO error (unreadable file, bad JSON). Fix and re-run.\n\n> **forge-4 runs before forge-5's install gate**, so the runner may not be set\n> up yet. Degrade gracefully rather than hard-failing:\n> 1. First run `loopRunner.versionCommand` (`rauf version --json`). If the\n>    binary is **missing**, or its version is **\u003C `minRunnerVersion`**\n>    (semver-compare), do NOT block authoring: keep the authored backlog, emit a\n>    loud warning with `loopRunner.installHint`, mark validation as skipped, and\n>    continue to Step 6. forge-5 will enforce the gate before running.\n> 2. If the binary is present and new enough but the project isn't set up\n>    (`validate` reports the project marker missing), likewise warn and continue\n>    — validation will run cleanly once `rauf install .` has been done.\n\n## Step 5b: Topology Report (advisory)\n\nAfter validation (or a recorded skip), report the backlog's dependency topology. Pipe the runner's **list command** (`loopRunner.listCommand`, rendered with `{resolvedBacklogDir}` — the rauf default shown below) into the topology verb. It is a pure function over the runner's item array and never takes a `backlog.json` path:\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\nrauf backlog list . --backlog {resolvedBacklogDir} --json | python3 \"$R\u002Fscripts\u002Fforge-session.py\" backlog-topology --items-stdin --json\n```\n\nALWAYS print the metrics, citing the runner counts from the payload:\n\n```\nTopology: {itemCount} items, {rootCount} roots, max chain depth {maxChainDepth}.\nPer-root fan-out (gated subtree size): {id}→{gatedCount}, … (largest first).\n```\n\nOnly when the payload's `warnings` array is non-empty, also render this block, including only the bullet(s) for warnings that actually fired:\n\n```\n⚠️ Fragile topology (advisory — does not block authoring):\n  - single-root-fanout: root {id} gates {gatedCount}\u002F{itemCount} items (≥50%).\n  - chain-depth: max chain depth {maxChainDepth} is ≥50% of {itemCount} items.\nA single defect in a high-fan-out root or a long chain can strand most of the backlog\n(the loop-recovery incident: 3 roots gating 81%, 13-deep chain). Consider splitting the\ngating root's subtree or flattening the chain — this is a heads-up, not a gate.\n```\n\nThis step is **guidance only — it never fails authoring**. If the topology command itself errors, note the error and continue to Step 6 (advisory).\n\n## Step 6: Review with User\n\nPresent a summary: total items N, dependency-chain depth, estimated loop iterations (`ceil(pendingItems * loopIterationMultiplier)`). Note whether validation passed or was skipped (runner not yet available).\n\nThis is a **non-blocking review (invitation)** — per the **Stage Review Gate** in `references\u002Fshared-conventions.md`: sibling stages block here; this stage deliberately does not, and the invitation obliges you to continue, not stop.\n\nState that the backlog is ready and invite adjustments before committing — a statement, not a forced gate: \"Backlog is ready. Tell me if you want any items split, merged, or reordered; otherwise I'll record state and commit.\" **Proceed to Step 7 in this same turn** unless the user asks for changes — emitting the invitation and stopping strands the stage before Step 7 runs.\n\n## Step 7: Update Pipeline State and Commit\n\nBefore writing state or running the stage exit, invoke the **Stage-Completion Re-check** block in `references\u002Fshared-conventions.md` with `{stage}` = `forge-4-backlog` — a resumed mid-stage continuation must not overwrite a committed `backlog.json` or re-fire a finished exit.\n\nPipeline state is written by the `state-*` verbs — see the Pipeline State Protocol in `references\u002Fshared-conventions.md`. Follow the Git Commit Protocol in `references\u002Fshared-conventions.md`.\n\n1. Record completion by running `state-complete` (below) with `--version`, `--artifact backlog.json`, and `--based-on forge-1-prd=\u003Ccurrent version> --based-on forge-2-tech=\u003Ccurrent version> --based-on forge-3-specs=\u003Ccurrent version>`. It sets `status: \"complete\"`, `completedAt`, the version and `basedOnVersions`, and applies the downstream staleness cascade deterministically, so no downstream status is set by hand.\n2. **Offer a note — don't force one.** As a statement (not a blocking question), let the user know they can jot anything worth preserving across sessions and you'll store it in the `notes` field. If they volunteer something, store it via `state-note` — it **overwrites** the single `notes` string (latest note wins), so fold any still-relevant existing note into the one combined string; otherwise proceed. The next stage's Step 1 reads and surfaces this note.\n3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol: stage files, attempt commit (marking `stages.forge-4-backlog.status` `complete` with `commitHash: null` in that commit), then record the artifact-commit hash via the protocol's two-commit follow-up (never `--amend`) only on success. If commit fails, leave status as `in-progress`.\n4. If verification was available but the user chose to skip it, persist that skip through `state-verify` using the fence below — never by hand. The choice to proceed unverified is durable state owned by the scripted writer.\n5. **Close with the Stage Exit Protocol** (single-sourced in `references\u002Fstage-exit-protocol.md`; do not improvise a \"Next steps\" list). Lead with the item count (\"Backlog complete with {N} items.\"), then:\n\nThe `state-complete` call for item 1 — and the `state-note` call only when the user volunteered a note in item 2 — with the portable plugin-root prelude. Add `--epic \"{epic}\"` to each call when this feature is an epic member — required, per the Pipeline State Protocol in `references\u002Fshared-conventions.md`:\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" state-complete \\\n  --feature \"{feature}\" --stage forge-4-backlog --version {n} \\\n  --based-on \"forge-1-prd=\u003Cn>\" --based-on \"forge-2-tech=\u003Cn>\" --based-on \"forge-3-specs=\u003Cn>\" \\\n  --artifact backlog.json --specs-dir \"{specsDir}\"\n# ONLY run the next call if the user volunteered a note in item 2 — otherwise stop here.\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" state-note \\\n  --feature \"{feature}\" --note \"\u003Cwhat the user volunteered>\" --specs-dir \"{specsDir}\"\n```\n\nThe `state-verify` call for item 4 — **only** when verification was available and the user explicitly chose to skip it. A verifier that could not be dispatched is not a skip, so do not run this on an unavailable-tool path. And only over an entry that is absent or unresolved: if `stages.forge-verify-backlog` already records `passed` or `findings-applied`, do **not** run the call — those statuses are resolved, the verb refuses to demote them to `skipped` (#203), and the existing result stands with nothing written. Add `--epic \"{epic}\"` when this feature is an epic member — required, per the Pipeline State Protocol in `references\u002Fshared-conventions.md`:\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" state-verify \\\n  --feature \"{feature}\" --stage forge-4-backlog --status skipped --specs-dir \"{specsDir}\"\n```\n\nIf that verb exits 2, surface its plain `Error:` line verbatim and stop — the skip is not persisted, so the exit below would route on state that does not exist on disk.\n\n**Determine `--verify-capability` before running the exit** per **Host and capability determination** in `references\u002Fstage-exit-protocol.md` (summarized under **Verify Capability** in `references\u002Fshared-conventions.md`): pass `interactive` only when a question mechanism equivalent to `AskUserQuestion` is available **and** dispatching a clean-room `forge-verifier` is *permitted* (the test is \"may I dispatch right now\", not tool presence) — otherwise `manual`. That reference owns the full rule, including why a consent-only bar is still `interactive` and the `none`-gate consent variant. Add `--epic \"{epic}\"` to the call below when this feature is an epic member.\n\n**Close this stage with the Scripted Stage Exit** (contract: `references\u002Fstage-exit-protocol.md`; do not improvise a \"Next steps\" list). Run:\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" stage-exit --feature \"{feature}\" --stage forge-4-backlog --specs-dir \"{specsDir}\" --host claude --verify-capability \"{verify-capability}\"\n```\n\nObey the DIRECTIVES it prints, in the consumption order this protocol fixes: surface `invalidAutoVerifyKeys` and every `warnings` entry first; `runInStageVerify: true` → run the in-stage clean-room verify chain now (honoring `autoFixEligible`, and asking through the Standard Verify Gate first when you may not dispatch unsolicited); `verifyGate: \"standard\"` → present the Standard Verify Gate; `verifyGate: \"manual-print\"` → print the `verifyCommand` for the user and do **not** dispatch inline. Then, and only when `terminalOwnedBy` is `\"self\"`, **print the NEXT-STEPS block verbatim as your absolute last output — nothing after its sentinel line.** A `terminalOwnedBy: \"outer\"` payload carries `nextSteps: null`: return your structured result to the caller and print no terminal block at all.\n\n## Gotchas\n\n- The loop runs each item in a FRESH context. Every item description must be self-contained — `author-backlog` enforces this, but double-check Step-3 plan items aren't \"same as above.\"\n- Spec references must be project-root-relative paths that actually exist — the validate command enforces this when `--specs-dir` is passed (resolving them from the project root).\n- Don't present a backlog to the user before it validates (or before you've explicitly recorded that validation was skipped because the runner isn't installed yet).\n","# forge-4-backlog — Backlog Generator (pipeline orchestrator)\n\nGenerate a complete, validated `backlog.json` from the implementation spec\nsuite, ready for the loop runner.\n\nThis skill is a **thin orchestrator**: it owns the *pipeline* concerns\n(prerequisite checks, spec loading, plan review, validation, pipeline-state and\ncommit). The actual **authoring craft** — granularity, acceptance criteria,\n`agentDelegation`, the schema, examples — lives in the rauf plugin's\n**`author-backlog`** skill, which this skill delegates to. That keeps a single\nhome for backlog-authoring knowledge, shared with the repo-wide ad-hoc flow.\n\n## Prerequisites\n\nRead and follow `references\u002Fshared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding. Resolve the feature directory `{resolvedFeatureDir}` via the **Feature Directory Resolution** block in `references\u002Fshared-conventions.md` — do not hardcode `{specsDir}\u002F{feature}\u002F` (see Step 1).\n\nResolve the **backlog directory** `{backlogDir}`:\n- **`backlogDir` unset (default):** the backlog lives at the resolved feature directory — `{resolvedFeatureDir}\u002Fbacklog.json` — for both flat and nested features, exactly as today.\n- **`backlogDir` configured:** compose a **per-feature subpath** — `{backlogDir}\u002F{feature}\u002F` — so each epic member's backlog stays independent (the authored file lands at `{backlogDir}\u002F{feature}\u002Fbacklog.json`). A bare shared `backlogDir` would collide across a multi-feature epic and violate REQ-COMPAT-03; the `{feature}` segment prevents that. Standalone features under a configured `backlogDir` likewise resolve to `{backlogDir}\u002F{feature}\u002F`, which is backward-compatible because each standalone feature name is already unique.\n\nThis is the **single** place this rule is implemented. forge-5-loop's backlog-file check must read the same composed `{backlogDir}\u002F{feature}\u002Fbacklog.json` (that matching forge-5-loop edit lands in item 016), and forge-verify's backlog-mode load uses the same path. rauf itself is unchanged: backlogs remain per-feature and rauf is still launched against a single per-feature backlog path — only the *path composition* changes (REQ-COMPAT-03).\n\n**Let `{resolvedBacklogDir}` denote the composed target of this rule** — i.e. `{backlogDir}\u002F{feature}` when a `backlogDir` is configured, else `{resolvedFeatureDir}`. Every downstream step below (authoring, validation) uses `{resolvedBacklogDir}`, never the bare config value, so the per-feature `{feature}` segment is never dropped.\n\nResolve the **loop runner** with the command below — it merges this project's `loopRunner` block over the schema defaults deterministically (defaults to rauf), so do not read the config schema for defaults. Use the emitted object as the effective `loopRunner`; you need its `bin`, `validateCommand`, `versionCommand`, `minRunnerVersion`, and `installHint`. If the call exits 2, surface the plain `Error:` line from stderr verbatim and fall back to the documented rauf defaults.\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" effective-config --config .\u002Fforge.config.json --json\n```\n\n**Turn structure reminder:** Text first, then `AskUserQuestion` for all questions — never embed one in your text (it stalls). At rung 2\u002F3, see the Interaction Capability Ladder.\n\n## Step 1: Validate Prerequisites\n\n**Resolve the feature directory first.** Invoke the **Feature Directory Resolution** block in `references\u002Fshared-conventions.md` to turn the bare feature name into `{resolvedFeatureDir}` (exit 0 → stdout is the absolute dir; exit ≥ 1 → STOP and surface the finding verbatim). Read state and specs from `{resolvedFeatureDir}\u002F` everywhere this skill previously wrote `{specsDir}\u002F{feature}\u002F`. Standalone features resolve to their flat path exactly as today.\n\n**Prerequisite check:** Read `{resolvedFeatureDir}\u002F.pipeline-state.json`. If not in force mode, stages `forge-1-prd`, `forge-2-tech`, and `forge-3-specs` must all be `complete`. If not, STOP and tell the user which prerequisites are missing.\n\n**Carried-over note check.** If that state's top-level `notes` is a non-empty string, surface it verbatim before proceeding and treat it as input to this stage — it was persisted for exactly this cross-session handoff (often at the previous stage's exit), and it can carry backlog-shaping constraints (e.g. \"no item may create file X\"). It never overrides the specs or config; raise any conflict instead of silently following either side.\n\nAfter the prerequisite check, invoke the **Stage-Entry Guard** block in `references\u002Fshared-conventions.md` with `{stage}` = `forge-4-backlog` — it detects an interrupted or complete `backlog.json`, runs the resume\u002Frestart or new-version gate, and stamps entry before Step 2 loads the specs. (The backlog is a single artifact, so \"resume\" means: reuse the existing `backlog.json` if the previous run wrote it, rather than re-authoring from scratch.)\n\nThen invoke the **Epic-Member Base Guard** block in `references\u002Fshared-conventions.md` (this stage does not run Epic Context Injection, so invoke it explicitly here). It self-gates to a no-op for standalone features; for a nested epic member on a branch that lacks the epic manifest it stops with a home-branch pointer (Issue #125).\n\n**Verification check.** Derive whether the upstream specs have been verified from the settled on-disk record, never by eyeballing conversational state. Run `verify-state --for-stage forge-3-specs` — it reads the served stage's `forge-verify-specs` entry and returns `{case, verified, stale, message, nextCommand}`. Add `--epic \"{epic}\"` when this feature is an epic member (nested layout). The full case enum and its rationale live in `references\u002Fverify-state.md`.\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" verify-state --feature \"{feature}\" --for-stage forge-3-specs --specs-dir \"{specsDir}\" --json\n```\n\nIf `verified` is true, proceed with no prompt. Otherwise print the returned `message`, then use `AskUserQuestion` to warn with the cost of skipping — unverified specs can carry gaps or contradictions that get baked into backlog items and only surface mid-loop, where they're far more expensive to fix — and offer **Verify first (recommended)** (run the returned `nextCommand`) · **Continue without verifying**. This is a pre-stage read of the upstream artifact, so the proceed-anyway path writes nothing.\n\n## Step 2: Load All Specs\n\nRead all spec documents into context:\n- `{resolvedFeatureDir}\u002FPRD.md`\n- `{resolvedFeatureDir}\u002Ftech-spec.md`\n- `{resolvedFeatureDir}\u002F##-*.md` (all implementation specs)\n\nIf the spec suite is large (8+ documents), focus on loading the architecture layout (01-*), shared types (00-*), and testing strategy documents first. Load individual subsystem specs as needed when writing the corresponding backlog items, rather than loading all specs simultaneously.\n\n## Step 3: Plan the Backlog\n\nBefore writing any JSON, walk the specs and create a backlog plan: discrete work items, ordered by dependency (foundation first), with priorities, each scoped for a single loop iteration.\n\nPresent the plan as a numbered list:\n```\nProposed backlog for {feature} ({N} items):\n\n  001 [P1] Scaffold module with project manifest, build config, and entry points\n      Depends on: (none)\n      Specs: 00-core-definitions.md, 01-architecture-layout.md\n\n  002 [P1] Implement shared types and error hierarchy\n      Depends on: 001\n      Specs: 00-core-definitions.md\n  ...\n```\n\nAfter presenting the plan as text, use `AskUserQuestion` following the **Decision Support** protocol in `references\u002Fshared-conventions.md`: recommend this breakdown as the default (it's your evidence-backed read of the specs and dependency order) and name the trade-off that governs item granularity — finer items are each easier to verify in one loop iteration but multiply coordination and dependency edges; coarser items mean fewer handoffs but risk an item too big to complete or verify in a single iteration. Lead with: \"I recommend this breakdown. Any items to split, merge, or reorder?\" Do NOT include this question in your text output. Wait for the user's response before generating the JSON.\n\n## Step 4: Author backlog.json — delegate to `author-backlog`\n\n**Invoke the rauf plugin's `author-backlog` skill** (via the Skill tool) to write\n`{resolvedBacklogDir}\u002Fbacklog.json`. Pass it:\n\n- the target backlog directory `{resolvedBacklogDir}`,\n- the approved plan from Step 3,\n- the spec context loaded in Step 2,\n- the project's `typeCheckCommand` \u002F `testCommand` (from `forge.config.json`) so acceptance criteria are concrete and runnable.\n\n`author-backlog` owns all item-quality rules (granularity hard limits, self-contained descriptions, acceptance criteria, `agentDelegation`, the correct `type`\u002F`status` enums, `dependsOn`, `specReferences`, the schema source). Do not re-encode them here — follow whatever it produces.\n\n**Return contract.** This is the **delegate-and-resume** posture of \"Caller-side resumption: the declared resume point\" in `references\u002Fstage-exit-protocol.md`. `author-backlog` is a sub-skill of this stage, not its terminal: when it returns, control returns to **this skill, at Step 5** — forge-4 still owns the stage and its terminal output. Two of the sub-skill's own instructions do not apply on this delegated path (it also serves direct user invocation, and those instructions are its direct-invocation posture): its wait-for-user-approval-before-writing gate is already satisfied by Step 3's approved plan — do not re-ask; and its closing \"run `rauf backlog validate` … and confirm the validated result\" posture is subsumed by Step 5, which owns validation (see Step 5's ownership note). Do not adopt the sub-skill's report-and-stop terminal — it is the freshest instruction in context after the return, but it belongs to the sub-skill: continue to Step 5 in the same turn; Steps 6 and 7 still run, and the stage closes only at Step 7's exit.\n\n> **If the rauf plugin \u002F `author-backlog` skill is not available:** fall back to\n> authoring inline using the schema source rule (prefer the project's installed\n> `{stateDir}\u002Fbacklog.schema.json`, else the published `$id`\n> `https:\u002F\u002Fraw.githubusercontent.com\u002Fgarygentry\u002Frauf\u002Fmain\u002Fschemas\u002Fbacklog.schema.json`),\n> and tell the user the rauf plugin provides richer authoring guidance.\n\n**Forge-specific item requirements** layered on top of `author-backlog`'s output:\n- `specReferences` must be paths **relative to the project root** (e.g. `specs\u002Fauth\u002F00-core-definitions.md`), NOT relative to the backlog file. The validator resolves them from the project root (not from `--specs-dir`, which only gates the check).\n- **Epic members — cross-member shared-state coupling (#144).** When authoring the backlog for an epic member, check whether this feature writes or migrates a file that a *sibling* member's already-shipped tests pin (its `mutatesShared[]` hint in `epic-manifest.json`, or a shared data corpus \u002F generated fixture its specs say it mutates). If so, schedule a **reconciliation item up front** — before the first mutating item — that regenerates or re-pins the sibling's fixture (or updates the sibling test to the new shape), so the sibling suite stays green instead of red-gating every commit mid-loop. This is the authoring counterpart to forge-verify's CHECK-E10.\n- **Generated-artifact freshness vs. `testCommand` `--check` gates (#145).** If the project's `testCommand` gates on staleness of generated artifacts (`\u003Cgenerator> --check`-style sub-commands that fail when a checked-in generated file is out of date), then any item that regenerates **one** such artifact must regenerate **and commit all** the sibling artifacts those `--check` gates depend on — enumerate the whole gated set, not just the artifact the item is \"about\", or the item passes locally yet red-gates on the stale-generated check. Pass this to `author-backlog` alongside `testCommand` so the full regeneration sequence lands in each affected item; forge-verify's CHECK-B26 flags a partial set or an ungated regenerator after the fact.\n- **Lifecycle-gated artifacts — no test item forcing a forbidden transition (#150).** A test\u002Fe2e item whose acceptance asserts a *published \u002F released \u002F approved \u002F human-reviewed* artifact state must either (a) `dependsOn` an explicit, human-gated publish\u002Freview item that legitimately produces that state, or (b) assert the state via a **dev-build \u002F fixture path**. A test item must **never** be the only thing forcing a lifecycle transition another item pins the other way (e.g. one item keeps artifact `X` *draft* while a test demands it *published*, with nothing between to publish it) — the loop, unable to publish or obtain a human sign-off, will **fabricate** the provenance. `author-backlog` owns the general rule; forge-verify's CHECK-B27 flags a contradictory pair with no publisher in the dependency closure after the fact.\n\n> **Backlog schema & rauf contract are unchanged (REQ-COMPAT-03).** Epic membership adds **no** fields to backlog items — dependency edges live in the epic manifest, never in any backlog item. The JSON written here is byte-for-byte the same shape as a pre-epic standalone feature's backlog, and rauf is still launched against a single per-feature backlog path. Only the *path composition* changes (the `{feature}` segment in the backlog-directory rule above), not the schema or rauf's CLI surface.\n\n## Step 5: Validate via the loop runner\n\n**Validation ownership.** This step is authoritative for validation, whether or not `author-backlog` already ran its own `rauf backlog validate`: this stage carries the degradation rules for a missing\u002Fold\u002Fnot-set-up runner (below) that the sub-skill does not, and this step's result is what Step 6 reports. A validate the sub-skill already ran cleanly makes this a cheap idempotent re-run, never a reason to skip it — and the sub-skill's validate never discharges this step.\n\nValidate the generated backlog by running the runner's **validate command**\n(`loopRunner.validateCommand`), rendered with `{resolvedBacklogDir}` and `{specsDir}`\nsubstituted — the rauf default:\n\n```bash\nrauf backlog validate . --backlog {resolvedBacklogDir} --specs-dir {specsDir} --json\n```\n\nInterpret the result:\n- **exit 0** → valid (warnings allowed). Proceed.\n- **exit 1** → validation findings. Parse `{ valid, findings[] }`, fix the items, re-run. Do NOT present the backlog to the user until it validates.\n- **exit 2** → usage\u002FIO error (unreadable file, bad JSON). Fix and re-run.\n\n> **forge-4 runs before forge-5's install gate**, so the runner may not be set\n> up yet. Degrade gracefully rather than hard-failing:\n> 1. First run `loopRunner.versionCommand` (`rauf version --json`). If the\n>    binary is **missing**, or its version is **\u003C `minRunnerVersion`**\n>    (semver-compare), do NOT block authoring: keep the authored backlog, emit a\n>    loud warning with `loopRunner.installHint`, mark validation as skipped, and\n>    continue to Step 6. forge-5 will enforce the gate before running.\n> 2. If the binary is present and new enough but the project isn't set up\n>    (`validate` reports the project marker missing), likewise warn and continue\n>    — validation will run cleanly once `rauf install .` has been done.\n\n## Step 5b: Topology Report (advisory)\n\nAfter validation (or a recorded skip), report the backlog's dependency topology. Pipe the runner's **list command** (`loopRunner.listCommand`, rendered with `{resolvedBacklogDir}` — the rauf default shown below) into the topology verb. It is a pure function over the runner's item array and never takes a `backlog.json` path:\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\nrauf backlog list . --backlog {resolvedBacklogDir} --json | python3 \"$R\u002Fscripts\u002Fforge-session.py\" backlog-topology --items-stdin --json\n```\n\nALWAYS print the metrics, citing the runner counts from the payload:\n\n```\nTopology: {itemCount} items, {rootCount} roots, max chain depth {maxChainDepth}.\nPer-root fan-out (gated subtree size): {id}→{gatedCount}, … (largest first).\n```\n\nOnly when the payload's `warnings` array is non-empty, also render this block, including only the bullet(s) for warnings that actually fired:\n\n```\n⚠️ Fragile topology (advisory — does not block authoring):\n  - single-root-fanout: root {id} gates {gatedCount}\u002F{itemCount} items (≥50%).\n  - chain-depth: max chain depth {maxChainDepth} is ≥50% of {itemCount} items.\nA single defect in a high-fan-out root or a long chain can strand most of the backlog\n(the loop-recovery incident: 3 roots gating 81%, 13-deep chain). Consider splitting the\ngating root's subtree or flattening the chain — this is a heads-up, not a gate.\n```\n\nThis step is **guidance only — it never fails authoring**. If the topology command itself errors, note the error and continue to Step 6 (advisory).\n\n## Step 6: Review with User\n\nPresent a summary: total items N, dependency-chain depth, estimated loop iterations (`ceil(pendingItems * loopIterationMultiplier)`). Note whether validation passed or was skipped (runner not yet available).\n\nThis is a **non-blocking review (invitation)** — per the **Stage Review Gate** in `references\u002Fshared-conventions.md`: sibling stages block here; this stage deliberately does not, and the invitation obliges you to continue, not stop.\n\nState that the backlog is ready and invite adjustments before committing — a statement, not a forced gate: \"Backlog is ready. Tell me if you want any items split, merged, or reordered; otherwise I'll record state and commit.\" **Proceed to Step 7 in this same turn** unless the user asks for changes — emitting the invitation and stopping strands the stage before Step 7 runs.\n\n## Step 7: Update Pipeline State and Commit\n\nBefore writing state or running the stage exit, invoke the **Stage-Completion Re-check** block in `references\u002Fshared-conventions.md` with `{stage}` = `forge-4-backlog` — a resumed mid-stage continuation must not overwrite a committed `backlog.json` or re-fire a finished exit.\n\nPipeline state is written by the `state-*` verbs — see the Pipeline State Protocol in `references\u002Fshared-conventions.md`. Follow the Git Commit Protocol in `references\u002Fshared-conventions.md`.\n\n1. Record completion by running `state-complete` (below) with `--version`, `--artifact backlog.json`, and `--based-on forge-1-prd=\u003Ccurrent version> --based-on forge-2-tech=\u003Ccurrent version> --based-on forge-3-specs=\u003Ccurrent version>`. It sets `status: \"complete\"`, `completedAt`, the version and `basedOnVersions`, and applies the downstream staleness cascade deterministically, so no downstream status is set by hand.\n2. **Offer a note — don't force one.** As a statement (not a blocking question), let the user know they can jot anything worth preserving across sessions and you'll store it in the `notes` field. If they volunteer something, store it via `state-note` — it **overwrites** the single `notes` string (latest note wins), so fold any still-relevant existing note into the one combined string; otherwise proceed. The next stage's Step 1 reads and surfaces this note.\n3. If `gitCommitAfterStage` is true, follow the Git Commit Protocol: stage files, attempt commit (marking `stages.forge-4-backlog.status` `complete` with `commitHash: null` in that commit), then record the artifact-commit hash via the protocol's two-commit follow-up (never `--amend`) only on success. If commit fails, leave status as `in-progress`.\n4. If verification was available but the user chose to skip it, persist that skip through `state-verify` using the fence below — never by hand. The choice to proceed unverified is durable state owned by the scripted writer.\n5. **Close with the Stage Exit Protocol** (single-sourced in `references\u002Fstage-exit-protocol.md`; do not improvise a \"Next steps\" list). Lead with the item count (\"Backlog complete with {N} items.\"), then:\n\nThe `state-complete` call for item 1 — and the `state-note` call only when the user volunteered a note in item 2 — with the portable plugin-root prelude. Add `--epic \"{epic}\"` to each call when this feature is an epic member — required, per the Pipeline State Protocol in `references\u002Fshared-conventions.md`:\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" state-complete \\\n  --feature \"{feature}\" --stage forge-4-backlog --version {n} \\\n  --based-on \"forge-1-prd=\u003Cn>\" --based-on \"forge-2-tech=\u003Cn>\" --based-on \"forge-3-specs=\u003Cn>\" \\\n  --artifact backlog.json --specs-dir \"{specsDir}\"\n# ONLY run the next call if the user volunteered a note in item 2 — otherwise stop here.\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" state-note \\\n  --feature \"{feature}\" --note \"\u003Cwhat the user volunteered>\" --specs-dir \"{specsDir}\"\n```\n\nThe `state-verify` call for item 4 — **only** when verification was available and the user explicitly chose to skip it. A verifier that could not be dispatched is not a skip, so do not run this on an unavailable-tool path. And only over an entry that is absent or unresolved: if `stages.forge-verify-backlog` already records `passed` or `findings-applied`, do **not** run the call — those statuses are resolved, the verb refuses to demote them to `skipped` (#203), and the existing result stands with nothing written. Add `--epic \"{epic}\"` when this feature is an epic member — required, per the Pipeline State Protocol in `references\u002Fshared-conventions.md`:\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" state-verify \\\n  --feature \"{feature}\" --stage forge-4-backlog --status skipped --specs-dir \"{specsDir}\"\n```\n\nIf that verb exits 2, surface its plain `Error:` line verbatim and stop — the skip is not persisted, so the exit below would route on state that does not exist on disk.\n\n**Determine `--verify-capability` before running the exit** per **Host and capability determination** in `references\u002Fstage-exit-protocol.md` (summarized under **Verify Capability** in `references\u002Fshared-conventions.md`): pass `interactive` only when a question mechanism equivalent to `AskUserQuestion` is available **and** dispatching a clean-room `forge-verifier` is *permitted* (the test is \"may I dispatch right now\", not tool presence) — otherwise `manual`. That reference owns the full rule, including why a consent-only bar is still `interactive` and the `none`-gate consent variant. Add `--epic \"{epic}\"` to the call below when this feature is an epic member.\n\n**Close this stage with the Scripted Stage Exit** (contract: `references\u002Fstage-exit-protocol.md`; do not improvise a \"Next steps\" list). Run:\n\n```bash\nR=\"$(bash -c '[ -z \"${FEATURE_FORGE_ROOT:-}\" ] || [ -x \"$FEATURE_FORGE_ROOT\u002Fscripts\u002Fforge-root.sh\" ] || { echo \"feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts\u002Fforge-root.sh\" >&2; exit 2; }; for d in \"${FEATURE_FORGE_ROOT:-}\" \"${CLAUDE_PLUGIN_ROOT:-}\" \"$HOME\"\u002F.claude\u002Fskills\u002Ffeature-forge \"$HOME\"\u002F.claude\u002Fplugins\u002Fcache\u002F*\u002Ffeature-forge\u002F* \"$HOME\"\u002F.claude\u002Fplugins\u002F*\u002Ffeature-forge \"$HOME\"\u002F.agents\u002Fskills\u002Ffeature-forge .\u002F.agents\u002Fskills\u002Ffeature-forge; do [ -x \"$d\u002Fscripts\u002Fforge-root.sh\" ] && exec \"$d\u002Fscripts\u002Fforge-root.sh\"; done')\"\n[ -n \"$R\" ] || { echo \"feature-forge: cannot locate plugin root\" >&2; exit 1; }\npython3 \"$R\u002Fscripts\u002Fforge-session.py\" stage-exit --feature \"{feature}\" --stage forge-4-backlog --specs-dir \"{specsDir}\" --host claude --verify-capability \"{verify-capability}\"\n```\n\nObey the DIRECTIVES it prints, in the consumption order this protocol fixes: surface `invalidAutoVerifyKeys` and every `warnings` entry first; `runInStageVerify: true` → run the in-stage clean-room verify chain now (honoring `autoFixEligible`, and asking through the Standard Verify Gate first when you may not dispatch unsolicited); `verifyGate: \"standard\"` → present the Standard Verify Gate; `verifyGate: \"manual-print\"` → print the `verifyCommand` for the user and do **not** dispatch inline. Then, and only when `terminalOwnedBy` is `\"self\"`, **print the NEXT-STEPS block verbatim as your absolute last output — nothing after its sentinel line.** A `terminalOwnedBy: \"outer\"` payload carries `nextSteps: null`: return your structured result to the caller and print no terminal block at all.\n\n## Gotchas\n\n- The loop runs each item in a FRESH context. Every item description must be self-contained — `author-backlog` enforces this, but double-check Step-3 plan items aren't \"same as above.\"\n- Spec references must be project-root-relative paths that actually exist — the validate command enforces this when `--specs-dir` is passed (resolving them from the project root).\n- Don't present a backlog to the user before it validates (or before you've explicitly recorded that validation was skipped because the runner isn't installed yet).\n",{"name":5,"description":7,"argument-hint":23},"\u003Cfeature-name>","main","ce0d6d40bba1d87039b0397041d15cb56c934037","adapters\u002Fclaude\u002Fskills\u002Fforge-4-backlog","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge","https:\u002F\u002Fgarygentry.github.io\u002Ffeature-forge\u002F","https:\u002F\u002Fgithub.com\u002Fgarygentry","2026-10-15 10:14:13",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add garygentry\u002Ffeature-forge --skill forge-4-backlog",{"tool":37,"command":38},"bunx","bunx skills add garygentry\u002Ffeature-forge --skill forge-4-backlog",{"tool":40,"command":41},"pnpm","pnpm dlx skills add garygentry\u002Ffeature-forge --skill forge-4-backlog","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-4-backlog\u002FSKILL.md",true,[45,51,55],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"references\u002Fshared-conventions.md","REFERENCE","参考文档",74013,"https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-4-backlog\u002Freferences\u002Fshared-conventions.md",{"path":52,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":53,"sourceHtmlUrl":54},"references\u002Fstage-exit-protocol.md",35663,"https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-4-backlog\u002Freferences\u002Fstage-exit-protocol.md",{"path":56,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":57,"sourceHtmlUrl":58},"references\u002Fverify-state.md",5018,"https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Fadapters\u002Fclaude\u002Fskills\u002Fforge-4-backlog\u002Freferences\u002Fverify-state.md",[60,67,72,78,83,89],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":18},"01M75H8RTWSJ2HYCPPKA3FRG42","alpha","A valid skill description.","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-nested-metadata\u002Fskills\u002Falpha\u002FSKILL.md",[],[],{"skillNo":68,"name":62,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":18},"01M75H8QXKFS116EF1009KB3CY","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-malformed\u002Fskills\u002Falpha\u002FSKILL.md",[],[],{"skillNo":73,"name":62,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":18},"01M75H8PKNSV4WEREK6D91G9T4","This is a folded scalar description.","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-folded-scalar\u002Fskills\u002Falpha\u002FSKILL.md",[],[],{"skillNo":79,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":18},"01M75H8MAV261C8QJ4S8CGRHV5","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-crlf\u002Fskills\u002Falpha\u002FSKILL.md",[],[],{"skillNo":84,"name":62,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":18},"01M75H8KDW98YF0PBHPD5V1GKR","foo: bar","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-colon-value\u002Fskills\u002Falpha\u002FSKILL.md",[],[],{"skillNo":90,"name":62,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":18},"01M75H8JFYFCGYNRCRTS4PMKKX","A valid description.","https:\u002F\u002Fgithub.com\u002Fgarygentry\u002Ffeature-forge\u002Fblob\u002Fmain\u002Ftests\u002Ffixtures\u002Freader-blank-lines\u002Fskills\u002Falpha\u002FSKILL.md",[],[]]