@garygentry/feature-forge 0.3.2 → 0.3.5

package/adapters/gemini/references/stage-exit-protocol.md

@@ -4,7 +4,7 @@ The single source of truth for how every forge stage closes. **One** scripted co
 covers all **nine** covered direct exits — the seven production stages `forge-0-epic`
 through `forge-6-docs`, plus direct `forge-verify` and direct `forge-fix`. It replaces the
 old ad-hoc "Next steps:" bullet lists with one fixed, correctly-ordered sequence:
-**verify (if missing or stale) → `/clear` → run the next command.**
+**verify (if missing or stale) → clear your session / start a fresh session → run the next command.**
 
 Two principles this protocol encodes (do not relitigate — they are locked product
 decisions):
@@ -18,7 +18,7 @@ decisions):
    session, so the findings digest and any fix decision land where the context to act on
    them still exists. This holds for auto-verify too: the stage skill dispatches the
    clean-room verify (and any autoFix) at stage end, in-session, before the exit — it is
-   **not** deferred to the navigator, which runs *after* the `/clear` with none of the
+   **not** deferred to the navigator, which runs *after* the session clear with none of the
    authoring context. Clearing first throws that context away.
 
 ## How this file is used
@@ -47,8 +47,8 @@ an epic member. Only the flags below are stage-specific; pass no others.
 |---|---|---|
 | `forge-0-epic` | `forge-0-epic` | `--next-feature "{member}"` when a concrete member exists |
 | `forge-1-prd` … `forge-4-backlog` | that stage's own id | none beyond identity/capability |
-| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred` |
-| `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete` or `blocked` |
+| `forge-5-loop` | `forge-5-loop` | `--outcome` — one of `complete`, `partial`, `blocked`, `needs-human`, `deferred`, `resolved`; optional `--cause dependency-starvation` with `--outcome partial` |
+| `forge-6-docs` | `forge-6-docs` | `--outcome` — `complete`, `blocked`, or `skipped` (deliberate docs skip, persisted via `state-skip` before the exit; routes like `complete` with honest wording) |
 | direct `forge-verify` | `forge-verify` | `--owner direct`, `--outcome` (`passed`, `findings`, `skipped`, `failed`), and served-stage metadata |
 | nested `forge-verify` | `forge-verify` | `--owner nested`, plus the same outcome and served-stage metadata |
 | direct/nested `forge-fix` | `forge-fix` | the matching `--owner`, a `FixOutcome` (`no-findings`, `decisions`, `failed`, `applied`, `reverified`, `reverify-findings`, `deferred`), and served-stage metadata |
@@ -90,19 +90,19 @@ resolves before running the command, exactly as elsewhere.
 **Close this stage with the Scripted Stage Exit** (contract: `references/stage-exit-protocol.md`; do not improvise a "Next steps" list). Run:
 
 ```bash
-R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
-python3 "$R/scripts/forge-session.py" stage-exit {stage-exit-args} --specs-dir "{specsDir}" --host claude --verify-capability "{verify-capability}"
+python3 "$R/scripts/forge-session.py" stage-exit {stage-exit-args} --specs-dir "{specsDir}" --host generic --verify-capability "{verify-capability}"
 ```
 
 Obey 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.
 <!-- END: scripted-stage-exit-stamp -->
 
-The stamp is shown with `--host claude`; the adapter build substitutes `pi`/`generic` per
+The stamp is shown with `--host generic`; the adapter build substitutes `pi`/`generic` per
 target, and §"Host and capability determination" below governs the value. The literal is
-deliberate — `scripts/build-adapters.py` keys its host translation on the exact string
-`--host claude`, and the stamp sites are compared byte-for-byte, so it is the one token in
-that line that is not a placeholder.
+deliberate — `scripts/build-adapters.py` keys its host translation on the exact canon
+value of that flag, and the stamp sites are compared byte-for-byte, so it is the one token
+in that line that is not a placeholder.
 
 ## Host and capability determination
 
@@ -110,12 +110,13 @@ Before the call, compute the two inputs independently. They are unrelated: **a h
 implies a capability**, and the script takes `--verify-capability` at face value.
 
 **`--host`** describes only the active adapter command surface — `claude`, `pi`, or
-`generic`. It selects command syntax (`/feature-forge:` vs `/skill:` vs host-neutral) and
-fresh-session wording (`/clear` vs `/new` vs neutral prose). Nothing else.
+`generic`. It selects command syntax (Claude's stage-command prefix vs Pi's `/skill:` vs
+host-neutral) and fresh-session wording (Claude's clear command vs Pi's `/new` vs neutral
+prose). Nothing else.
 
 **`--verify-capability interactive`** is passed only when **both** of these hold:
 
-- **(a)** a question mechanism equivalent to `AskUserQuestion` is available, **and**
+- **(a)** a question mechanism equivalent to the host's question mechanism is available, **and**
 - **(b)** a clean-room `forge-verifier` subagent can be dispatched.
 
 If either is absent, or capability cannot be established, pass `manual`.
@@ -151,7 +152,8 @@ production successor** while verification is unresolved.
 - a capable Pi session is `--host pi --verify-capability interactive`, and receives the
   same logical gate a capable Claude session does;
 - Pi without a dispatchable verifier is `--host pi --verify-capability manual`;
-- a Claude session that cannot dispatch is `--host claude --verify-capability manual`.
+- a Claude session that cannot dispatch keeps the Claude host value with
+  `--verify-capability manual`.
 
 Interactive gate options keep their explicit labels, their recommended default, and their
 one-line trade-off descriptions (below). The manual path prints the verify command as the
@@ -199,6 +201,44 @@ second sentinel-terminated block **inside** an outer stage's exit, breaking the
 exactly-one-terminal-block rule — and the canon guard cannot catch it, because both
 wordings legitimately appear in the same file. Judge the token, not the phrasing.
 
+## Caller-side resumption: the declared resume point
+
+The `owner:` token and `terminalOwnedBy` arbitrate who prints — but they specify only
+the **callee** side: a nested skill stays quiet and returns its structured result. This
+section is the reciprocal, caller-side half of that contract.
+
+**On a sub-skill's return, the caller re-owns the terminal.** Every closing instruction
+in the callee's own body — its report-and-stop posture, its "confirm the result" close,
+its own next-steps habits — is void for this turn. The caller resumes at its **declared
+resume point**, in the same turn, and its remaining steps run to its own terminal.
+
+**Every Skill-tool delegation site declares, at the invocation, what happens on
+return.** Suppression without resumption is the failure mode this section closes: the
+callee's closing posture is the freshest instruction in context while the caller's next
+step is the oldest, so an undeclared return silently ends the run one layer too early —
+the caller's remaining steps (validation, state writes, commit, stage exit) dropped,
+with no error surfaced. An implicit "let it run to its natural stopping point" is that
+bug spelled politely, and it is banned on delegation sites. A site takes one of two
+declared postures:
+
+- **Delegate-and-resume** — the callee is a sub-step of the caller: the site names the
+  caller's own step that control returns to, and the caller continues there in the same
+  turn. The callee never owns the caller's terminal. The worked instance is
+  `forge-4-backlog` Step 4's **Return contract** for the `author-backlog` delegation
+  (control returns at Step 5; the sub-skill's direct-invocation posture — its approval
+  gate and its validate-and-confirm close — is explicitly disapplied on the delegated
+  path). New delegation sites follow that pattern rather than re-deriving it.
+- **Terminal handoff** — the caller's job ends at the invocation and the invoked skill
+  owns the terminal from there on (e.g. the navigator's `autoInvokeNextStage`
+  "continue in this session" advance into the next production stage). Declaring the
+  handoff is what keeps it distinct from an accidental drop.
+
+Scope: this contract governs **Skill-tool delegation within one session**. The
+truncated-verifier-return guard (forge-verify's `findings-template.md`, "Truncated
+Verifier Returns") is a different mechanism — it polices what an **Agent-dispatched
+subagent's** return payload must contain, not where a caller resumes. A dispatch site
+can be subject to both; satisfy each on its own terms.
+
 ## Directive consumption order
 
 `stage-exit` emits a DIRECTIVES object and (for a direct owner) a NEXT-STEPS block. The
@@ -243,7 +283,7 @@ reformat, merge, or summarize them, and never dump the state file they were deri
 
 Auto-verify is effective for this stage and verification is outstanding — verify **now,
 in this session** (principle #2 applied to auto-verify: the digest and any fix decision
-land here, where the authoring context still exists — not deferred to a post-`/clear`
+land here, where the authoring context still exists — not deferred to a post-clear
 navigator). The `auto-verify-pending` debt is already durable on disk at this point, so a
 declined or deferred gate leaves recorded debt rather than a silent pass.
 
@@ -252,7 +292,7 @@ declined or deferred gate leaves recorded debt rather than a silent pass.
    same path the navigator uses (`skills/forge-verify/SKILL.md`). Dispatch it
    **synchronously and await its digest inline** — do **not** run it in the background or
    announce it as "still running"; the digest and any fix decision must land in this
-   session. It inherits none of this session's context, so no `/clear` is needed and only
+   session. It inherits none of this session's context, so no session clear is needed and only
    a compact digest returns.
    **If you may not dispatch unsolicited**, present the consent form of the Standard
    Verify Gate first and dispatch on the affirmative choice — see "Consent variant on a
@@ -299,7 +339,11 @@ first:
   a stage's artifact commit.
 - **Skip for now** — go straight to the NEXT-STEPS block without verifying. Record this
   stage's verify status as `skipped` in pipeline state (via `state-verify`, never by hand)
-  **only** on an explicit skip — a skip does not go stale.
+  **only** on an explicit skip — a skip does not go stale. Exception: if the existing
+  entry records `passed` or `findings-applied` (a resolved result whose freshness has
+  merely lapsed), write **nothing** — `state-verify` refuses to demote a resolved status
+  to `skipped` (#203), and the recorded result stands on its own; the user's decline is
+  honored by simply not re-verifying.
 
 **Advancement is allowed only after a pass, or after an explicit skip has been
 persisted.** Choosing to stop, or losing the interaction, produces no advancing terminal
@@ -358,8 +402,8 @@ directive is informational — you do **not** re-derive the wording:
   unchanged; the block appends a non-blocking reminder line ("You also flagged N epic
   change(s) to reconcile when convenient …"). This is *finish-then-edit*.
 
-Either way the added lines are host-neutral (no literal `/clear`) and sit **above** the
-sentinel; just print the NEXT-STEPS block verbatim as always.
+Either way the added lines are host-neutral (they name no fresh-session command) and sit
+**above** the sentinel; just print the NEXT-STEPS block verbatim as always.
 
 ### Deferred decisions — do not solicit next-stage decisions at this exit
 
@@ -376,7 +420,7 @@ a `deferredDecisions[]` entry on this feature's `.pipeline-state.json` by runnin
 epic member — required, per the Pipeline State Protocol in `references/shared-conventions.md`:
 
 ```bash
-R="$(bash -c 'for d in "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 python3 "$R/scripts/forge-session.py" state-decision \
   --feature "{feature}" --question "<phrased for the target stage>" \

package/adapters/gemini/scripts/epic-manifest.py

@@ -12,9 +12,12 @@ Usage:
     python3 epic-manifest.py render-status <epic> [--specs-dir DIR] [--json]
     python3 epic-manifest.py add-feature <epic> <name> --charter TEXT \
         [--depends-on A,B] [--specs-dir DIR] [--json]
+    python3 epic-manifest.py adopt-feature <epic> <name> [--charter TEXT] \
+        [--depends-on A,B] [--specs-dir DIR] [--json]
     python3 epic-manifest.py remove-feature <epic> <name> [--specs-dir DIR] [--json]
     python3 epic-manifest.py reorder <epic> --order A,B,C [--specs-dir DIR] [--json]
     python3 epic-manifest.py set-dep <epic> <name> --depends-on A,B [--specs-dir DIR] [--json]
+    python3 epic-manifest.py set-charter <epic> <name> --charter TEXT [--specs-dir DIR] [--json]
     python3 epic-manifest.py set-status <epic> --status STATE [--specs-dir DIR] [--json]
 
 Exit codes:
@@ -179,6 +182,12 @@ class FeatureStatus(TypedDict):
         blockingEpicChangeRequests: The subset of ``openEpicChangeRequests`` with
             ``blocksCurrent == true`` (pause-now, reconcile-before-specs). Always
             ``<= openEpicChangeRequests``.
+        docsStatus: The member's recorded ``stages["forge-6-docs"].status``, or
+            None when absent/malformed. DISTINCT from the orchestration rollup
+            (which reads forge-5-loop + impl verify and deliberately ignores
+            docs): consumers gating a DOCUMENTATION decision — the epic-level
+            doc offer (#173) — read this, treating ``complete`` and ``skipped``
+            (#197's deliberate skip) both as docs-settled.
     """
 
     name: str
@@ -188,6 +197,7 @@ class FeatureStatus(TypedDict):
     unmetDeps: list[str]
     openEpicChangeRequests: int
     blockingEpicChangeRequests: int
+    docsStatus: str | None
 
 
 class Rollup(TypedDict):
@@ -390,7 +400,8 @@ def atomic_write(path: Path, data: dict) -> None:
     and fsyncs it, then ``os.replace`` swaps it into place. ``os.replace`` is
     atomic on POSIX within a single filesystem, so an interrupted write never
     leaves a partial or corrupt manifest (REQ-ROBUST-03). Concurrent multi-
-    session mutation is out of scope (single-writer assumed, PRD REQ-ROBUST-03).
+    session mutation is out of scope (single-writer assumed, PRD REQ-ROBUST-03;
+    decision record: references/decisions/single-writer-threat-model.md, #180).
 
     Args:
         path: The destination manifest path (e.g. {epic}/epic-manifest.json).
@@ -1202,6 +1213,13 @@ def derive_status(feature_dir: Path) -> FeatureStatus:
     open_count = len(open_reqs)
     blocking_count = sum(1 for r in open_reqs if r.get("blocksCurrent") is True)
 
+    # Docs state for the epic-level doc offer gate (#173). Read directly rather
+    # than folded into `derived`: docs completeness is deliberately invisible to
+    # the orchestration rollup, and conflating them is the bug this field fixes.
+    stages = state.get("stages", {})
+    docs = stages.get("forge-6-docs") if isinstance(stages, dict) else None
+    docs_status = docs.get("status") if isinstance(docs, dict) else None
+
     return {
         "name": name,
         "stage": stage,
@@ -1210,6 +1228,7 @@ def derive_status(feature_dir: Path) -> FeatureStatus:
         "unmetDeps": [],
         "openEpicChangeRequests": open_count,
         "blockingEpicChangeRequests": blocking_count,
+        "docsStatus": docs_status if isinstance(docs_status, str) else None,
     }
 
 
@@ -1232,14 +1251,16 @@ def _next_production_stage(state: dict) -> str | None:
     The epic-side mirror of ``next_stage()`` in forge-session.py, and for the same
     reason its docstring gives: "what runs next" is DERIVED from ``stages[].status``,
     never read from the stored ``currentStage``. A missing, pending, in-progress or
-    stale stage all count as "not done".
+    stale stage all count as "not done"; ``complete`` and ``skipped`` both count as
+    done (``skipped`` is legal only on forge-6-docs — schema ``docsStageEntry`` —
+    so a deliberately docs-skipped member is never re-offered forge-6-docs, #197).
     """
     stages = state.get("stages")
     if not isinstance(stages, dict):
         return _PRODUCTION_STAGES[0]
     for stage in _PRODUCTION_STAGES:
         entry = stages.get(stage)
-        if not isinstance(entry, dict) or entry.get("status") != "complete":
+        if not isinstance(entry, dict) or entry.get("status") not in ("complete", "skipped"):
             return stage
     return None
 
@@ -1607,6 +1628,52 @@ def set_dep(
     return _bump_and_write(epic_dir, specs_dir, manifest)
 
 
+def set_charter(
+    epic_dir: Path, specs_dir: Path, name: str, charter: str
+) -> list[Finding]:
+    """Replace a member feature's charter text (#166).
+
+    The charter is the member field most likely to need revision after creation
+    (an ADR lands, a boundary moves, a member turns out to own more than
+    expected) — and it previously had no mutator, so edit mode had no sanctioned
+    path to rewrite one. Same shape as ``set_dep``: an atomic, re-validated,
+    revision-bumping replacement. EPIC.md prose is NOT touched — the agent
+    re-syncs the mirror afterward (edit-mode Step E5), exactly as for every
+    other mutation.
+
+    Args:
+        epic_dir: The epic subtree directory.
+        specs_dir: The configured specs directory.
+        name: The member feature to edit.
+        charter: The replacement charter text (argparse requires the flag; an
+            empty string is refused below — a charter is required prose, and
+            blanking it would only manufacture a schema-shaped hole).
+
+    Returns:
+        Empty list on success; blocking findings (not-found / empty-charter, or
+        anything re-validation raises) on refusal — manifest left unchanged.
+
+    Raises:
+        UsageError: Unsafe name, corrupt/missing manifest, or write failure.
+    """
+    if not charter.strip():
+        return [{"code": "empty-charter",
+                 "message": "refusing to blank a charter: pass non-empty --charter text",
+                 "feature": name}]
+    manifest = load_manifest(epic_dir)
+    by_name = {
+        f["name"]: f
+        for f in manifest.get("features", [])
+        if isinstance(f, dict) and isinstance(f.get("name"), str)
+    }
+    if name not in by_name:
+        return [{"code": "not-found",
+                 "message": f"feature {name!r} is not a member of epic {epic_dir.name!r}",
+                 "feature": name}]
+    by_name[name]["charter"] = charter
+    return _bump_and_write(epic_dir, specs_dir, manifest)
+
+
 def set_status(epic_dir: Path, specs_dir: Path, status: str) -> list[Finding]:
     """Set the epic-level lifecycle status.
 
@@ -1919,7 +1986,8 @@ def _dispatch(args: argparse.Namespace, specs_dir: Path) -> int:
         return 0
 
     # Mutators ---------------------------------------------------------------
-    if cmd in {"add-feature", "remove-feature", "reorder", "set-dep", "set-status"}:
+    if cmd in {"add-feature", "remove-feature", "reorder", "set-dep", "set-charter",
+               "set-status"}:
         epic_dir = contained_path(specs_dir, args.epic)
         if cmd == "add-feature":
             findings = add_feature(
@@ -1934,6 +2002,8 @@ def _dispatch(args: argparse.Namespace, specs_dir: Path) -> int:
             findings = set_dep(
                 epic_dir, specs_dir, args.name, _split_list(args.depends_on)
             )
+        elif cmd == "set-charter":
+            findings = set_charter(epic_dir, specs_dir, args.name, args.charter)
         else:  # set-status
             findings = set_status(epic_dir, specs_dir, args.status)
         if findings:
@@ -2028,6 +2098,14 @@ def _build_parser() -> argparse.ArgumentParser:
     add_specs_dir(p_setdep)
     add_json(p_setdep)
 
+    # set-charter ----------------------------------------------------------- #
+    p_setcharter = sub.add_parser("set-charter", help="Replace a feature's charter")
+    p_setcharter.add_argument("epic")
+    p_setcharter.add_argument("name")
+    p_setcharter.add_argument("--charter", required=True, help="Replacement charter text")
+    add_specs_dir(p_setcharter)
+    add_json(p_setcharter)
+
     # set-status ------------------------------------------------------------ #
     p_setstatus = sub.add_parser("set-status", help="Set the epic lifecycle status")
     p_setstatus.add_argument("epic")