@garygentry/feature-forge 0.3.2 → 0.3.4

package/adapters/codex/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")