specfuse-loop 0.30.0__tar.gz → 0.31.1__tar.gz

{specfuse_loop-0.30.0/specfuse_loop.egg-info → specfuse_loop-0.31.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfuse-loop
-Version: 0.30.0
+Version: 0.31.1
 Summary: Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology.
 Author: Specfuse contributors
 License: Apache-2.0
@@ -152,10 +152,10 @@ specfuse run                                     # the real run
 
 This repository is also a **self-demonstrating reference installation**: its own
 `.specfuse/` contains a worked example feature
-(`features/FEAT-2026-0001-health-endpoint/`). From the repo root you can run:
+(`features/FEAT-LOOP-2026-0001-health-endpoint/`). From the repo root you can run:
 
 ```bash
-python .specfuse/scripts/lint_plan.py .specfuse/features/FEAT-2026-0001-health-endpoint
+python .specfuse/scripts/lint_plan.py .specfuse/features/FEAT-LOOP-2026-0001-health-endpoint
 python .specfuse/scripts/loop.py --dry-run
 ```
 
@@ -180,7 +180,7 @@ specfuse-loop/
     ├── skills/verification/SKILL.md
     ├── scripts/{loop.py, lint_plan.py, gh_features.py, adopt_feature.py, gh_backend.py}
     ├── templates/{PLAN,GATE,WU}.template.md
-    └── features/FEAT-2026-0001-health-endpoint/   (the worked example)
+    └── features/FEAT-LOOP-2026-0001-health-endpoint/   (the worked example)
 ```
 
 `specfuse init` also ships the durable docs — `methodology.md`, `skills.md`, and

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/README.md

@@ -119,10 +119,10 @@ specfuse run                                     # the real run
 
 This repository is also a **self-demonstrating reference installation**: its own
 `.specfuse/` contains a worked example feature
-(`features/FEAT-2026-0001-health-endpoint/`). From the repo root you can run:
+(`features/FEAT-LOOP-2026-0001-health-endpoint/`). From the repo root you can run:
 
 ```bash
-python .specfuse/scripts/lint_plan.py .specfuse/features/FEAT-2026-0001-health-endpoint
+python .specfuse/scripts/lint_plan.py .specfuse/features/FEAT-LOOP-2026-0001-health-endpoint
 python .specfuse/scripts/loop.py --dry-run
 ```
 
@@ -147,7 +147,7 @@ specfuse-loop/
     ├── skills/verification/SKILL.md
     ├── scripts/{loop.py, lint_plan.py, gh_features.py, adopt_feature.py, gh_backend.py}
     ├── templates/{PLAN,GATE,WU}.template.md
-    └── features/FEAT-2026-0001-health-endpoint/   (the worked example)
+    └── features/FEAT-LOOP-2026-0001-health-endpoint/   (the worked example)
 ```
 
 `specfuse init` also ships the durable docs — `methodology.md`, `skills.md`, and

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specfuse-loop"
-version = "0.30.0"
+version = "0.31.1"
 description = "Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology."
 readme = "README.md"
 requires-python = ">=3.10"

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/specfuse/agent/__init__.py

@@ -2,7 +2,7 @@
 # Licensed under the Apache License, Version 2.0. See LICENSE.
 """The specfuse-agent runner (FEAT-2026-0049): a thin conductor over the
 existing loop driver and skills. See `.specfuse/features/
-FEAT-2026-0049-specfuse-agent-runner/PLAN.md` for why this is a sibling
+FEAT-LOOP-2026-0049-specfuse-agent-runner/PLAN.md` for why this is a sibling
 package to `specfuse/loop/` and `specfuse/monitor/` rather than living in
 either.
 """

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/specfuse/loop/agent_policy.py

@@ -33,6 +33,7 @@ import re
 from pathlib import Path
 
 from . import _miniyaml
+from . import ids as _ids
 from .lint_roadmap import roadmap_statuses
 
 __all__ = (
@@ -62,7 +63,7 @@ PROVIDER_VALUES = frozenset({"discord", "slack", "teams", "none"})
 
 REQUIRED_TOP_LEVEL_FIELDS = ("version", "queue", "rules", "budgets", "escalation")
 
-_FEAT_ID_RE = re.compile(r"^FEAT-\d{4}-\d{4}$")
+_FEAT_ID_RE = _ids.FEATURE_ID_RE
 
 _REQUIRED_BUDGET_FIELDS = ("max_tokens_per_run", "max_open_prs", "max_items_per_day")
 _REQUIRED_ESCALATION_FIELDS = ("webhook_env", "assignee", "quiet_hours", "sla_hours")
@@ -644,7 +645,7 @@ def resolve_severity_aliases(path: "str | Path | None" = None) -> dict:
     return resolved
 
 
-def validate_agent_policy(path: str | Path | None = None) -> list[str]:
+def validate_agent_policy(path: str | Path | None = None, repo_root: str | Path | None = None) -> list[str]:
     """Validate *path* (default ``.specfuse/agent-policy.yml``); return findings.
 
     Empty list means valid. A missing file, a parse failure, and a non-mapping
@@ -684,12 +685,12 @@ def validate_agent_policy(path: str | Path | None = None) -> list[str]:
         findings.extend(_check_escalation(parsed["escalation"]))
 
     if "queue" in parsed and isinstance(parsed["queue"], list):
-        findings.extend(_check_queue_against_roadmap(parsed["queue"]))
+        findings.extend(_check_queue_against_roadmap(parsed["queue"], repo_root))
 
     return findings
 
 
-def _check_queue_against_roadmap(queue: list) -> list[str]:
+def _check_queue_against_roadmap(queue: list, repo_root: "str | Path | None" = None) -> list[str]:
     """Cross-check queue entries against roadmap.md's FEAT-ID status.
 
     ERROR when a queue entry has no roadmap row at all (unresolvable, a
@@ -699,15 +700,18 @@ def _check_queue_against_roadmap(queue: list) -> list[str]:
     per the roadmap's own status legend. Skipped without error when
     roadmap.md is absent, so a policy file may exist before a roadmap does.
     """
-    statuses = roadmap_statuses()
+    statuses = roadmap_statuses(repo_root)
     if not statuses:
         return []
+    root = Path(repo_root) if repo_root is not None else Path.cwd()
 
     findings: list[str] = []
     for entry in queue:
         if not isinstance(entry, str) or not _FEAT_ID_RE.match(entry):
             continue
         status = statuses.get(entry)
+        if status is None:
+            status = statuses.get(_ids.resolve(root, entry))
         if status is None:
             findings.append(f"ERROR: queue: {entry!r} has no row in roadmap.md")
         elif status in _DONE_OR_ABANDONED:
@@ -725,7 +729,7 @@ def _check_version(version: object) -> list[str]:
 
 def _check_queue(queue: object) -> list[str]:
     if not isinstance(queue, list):
-        return ["ERROR: 'queue' must be a list of FEAT-YYYY-NNNN strings"]
+        return ["ERROR: 'queue' must be a list of FEAT-YYYY-NNNN or FEAT-<KEY>-YYYY-NNNN strings"]
 
     findings: list[str] = []
     seen: set[str] = set()
@@ -733,7 +737,7 @@ def _check_queue(queue: object) -> list[str]:
         if not isinstance(entry, str) or not _FEAT_ID_RE.match(entry):
             findings.append(
                 f"ERROR: queue[{index}]: {entry!r} does not match "
-                f"FEAT-YYYY-NNNN"
+                f"FEAT-YYYY-NNNN or FEAT-<KEY>-YYYY-NNNN"
             )
             continue
         if entry in seen:
@@ -884,7 +888,7 @@ def _check_feature_overrides(overrides: object) -> list[str]:
         if not _FEAT_ID_RE.match(str(feat_id)):
             findings.append(
                 f"ERROR: rules.features.overrides: key {feat_id!r} does not "
-                f"match FEAT-YYYY-NNNN"
+                f"match FEAT-YYYY-NNNN or FEAT-<KEY>-YYYY-NNNN"
             )
         if value not in GATE_REVIEW_VALUES:
             findings.append(

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/specfuse/loop/arm_eval.py

@@ -10,8 +10,8 @@ structured per-class verdict. Mirrors the shape of `gate_eval.py`'s
 `evaluate_auto_close`: pure evaluation over files, a structured decision
 object, a formatter for the event trail, no side effects. Arming and closing
 are deliberately separate decisions with different inputs — this module does
-not fold into `gate_eval.py`, does not import from it, and does not import
-from `loop.py` (the dependency points the other way: `loop.py` will call
+not fold into `gate_eval.py` (it reads only the `NON_SUBSTANTIVE_TYPES`
+constant from it) and does not import from `loop.py` (the dependency points the other way: `loop.py` will call
 into this module, T04).
 
 The organizing principle: model-authored signals may only veto; only
@@ -38,6 +38,7 @@ from pathlib import Path
 from . import _miniyaml
 from .closing_requirements import gate_review_filename
 from .cost import wu_lifetime_cost_usd
+from .gate_eval import NON_SUBSTANTIVE_TYPES
 from .plan_baseline import load_baseline, load_plan_graph
 
 PREDICATE_VERSION = "v1"
@@ -110,6 +111,7 @@ JUDGE_MODULES = tuple(
         "criteria_state.py",
         "lint_closing.py",
         "lint_plan.py",
+        "ids.py",                # supplies lint_plan's CORRELATION_ID_RE; an edit changes what the close's lint accepts
         "plan_baseline.py",      # the baseline retroactive_edits compares to
         "roadmap_archive.py",    # CLI entry for auto_archive_feature; assert_terminal_flips_fired depends on it
         # The driver: dispatch guards, halt classification, the produces gate,
@@ -629,6 +631,114 @@ def evaluate_arm_predicate(feature_dir: Path, just_closed_gate: int) -> ArmDecis
     )
 
 
+# Literal acknowledgement entry covering any `produces_driver_helper` hit.
+DRIVER_HELPER_ACK_KEY = "produces_driver_helper"
+# Reason prefix of a `clean` verdict that is clean only because of an acknowledgement.
+ACKNOWLEDGED_REASON_PREFIX = "acknowledged by operator: "
+
+
+def _terminal_judge_hits(
+    feature_dir: Path, gate_number: int
+) -> "tuple[list[tuple[str, str]], dict | None]":
+    """The judge-surface hits of `gate_number`'s done substantive units, each as
+    ``(acknowledgement key, rendered hit)``, plus the close unit's
+    acknowledgement (or None). Shared by the verdict and the brief's key list so
+    the two cannot disagree on what an acknowledgement must name."""
+    feature_dir = Path(feature_dir)
+    plan = load_plan_graph(feature_dir)
+    gate = next(
+        (g for g in plan.get("gates", []) or [] if g.get("gate") == gate_number),
+        None,
+    )
+    hits: list[tuple[str, str]] = []  # (acknowledgement key, rendered hit)
+    acknowledgement: "dict | None" = None
+    for ref in (gate.get("work_units", []) or []) if gate else []:
+        wu = _read_wu(feature_dir, ref)
+        if wu is None:
+            continue
+        if wu["type"] == "close" and acknowledgement is None:
+            acknowledgement = _read_judge_edit_acknowledgement(feature_dir / ref["file"])
+        if wu["type"] in NON_SUBSTANTIVE_TYPES or wu["status"] != "done":
+            continue
+        for p in wu["produces"]:
+            if _matches_judge_path(p):
+                hits.append((p, f"{wu['id']} produces {p}"))
+        if wu["produces_driver_helper"]:
+            hits.append((
+                DRIVER_HELPER_ACK_KEY,
+                f"{wu['id']} declares produces_driver_helper "
+                f"{wu['produces_driver_helper']!r}",
+            ))
+    return hits, acknowledgement
+
+
+def terminal_judge_edit_ack_keys(feature_dir: Path, gate_number: int) -> "list[str]":
+    """The sorted entries a `judge_edit_acknowledged.paths` list must contain to
+    cover every current hit of `gate_number`: each judge-surface path, plus
+    `DRIVER_HELPER_ACK_KEY` when any unit declares `produces_driver_helper`.
+    Pure; empty when nothing hits."""
+    hits, _ = _terminal_judge_hits(Path(feature_dir), gate_number)
+    return sorted({key for key, _ in hits})
+
+
+def evaluate_terminal_judge_editing(feature_dir: Path, gate_number: int) -> ClassVerdict:
+    """Report which done substantive units of `gate_number` touch a judge surface.
+
+    Not a successor-arm class: it is absent from `CLASS_NAMES` and `would_arm`
+    never reads it. It is the terminal gate's counterpart of class 2 -- the arm
+    predicate looks at *drafted* units of the next gate; nothing arms after the
+    terminal gate, so this looks at the units that already ran and are about to
+    be closed over. Pure: reads PLAN.md and the gate's unit files only.
+    """
+    hits, acknowledgement = _terminal_judge_hits(feature_dir, gate_number)
+    if not hits:
+        return ClassVerdict(
+            "clean", "no done substantive unit touches judge-path surfaces"
+        )
+    covered = set(acknowledgement["paths"]) if acknowledgement else set()
+    uncovered = [text for key, text in hits if key not in covered]
+    if uncovered:
+        return ClassVerdict("fired", "; ".join(uncovered))
+    names = sorted({key for key, _ in hits})
+    return ClassVerdict("clean", f"{ACKNOWLEDGED_REASON_PREFIX}{', '.join(names)}")
+
+
+def _read_judge_edit_acknowledgement(close_file: Path) -> "dict | None":
+    """The operator-authored `judge_edit_acknowledged` field of a close unit, or
+    None when absent or malformed (a malformed field covers nothing; lint_plan
+    reports it). The driver never writes this field."""
+    fm, _ = _parse_frontmatter(close_file.read_text())
+    raw = fm.get("judge_edit_acknowledged")
+    if not isinstance(raw, dict):
+        return None
+    paths, reason = raw.get("paths"), raw.get("reason")
+    if (not isinstance(paths, list) or not paths
+            or not all(isinstance(p, str) for p in paths)
+            or not isinstance(reason, str) or not reason.strip()):
+        return None
+    return {"paths": paths, "reason": reason}
+
+
+def terminal_judge_edit_acknowledgement(
+    feature_dir: Path, gate_number: int
+) -> "dict | None":
+    """The acknowledgement on `gate_number`'s close unit (``{"paths", "reason"}``)
+    or None."""
+    feature_dir = Path(feature_dir)
+    plan = load_plan_graph(feature_dir)
+    gate = next(
+        (g for g in plan.get("gates", []) or [] if g.get("gate") == gate_number),
+        None,
+    )
+    for ref in (gate.get("work_units", []) or []) if gate else []:
+        wu = _read_wu(feature_dir, ref)
+        if wu is not None and wu["type"] == "close":
+            ack = _read_judge_edit_acknowledgement(feature_dir / ref["file"])
+            if ack is not None:
+                return ack
+    return None
+
+
 def _format_decision(decision: ArmDecision) -> str:
     """Render an ArmDecision to the canonical event-trail block shape."""
     lines: list[str] = [

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/specfuse/loop/changelog.py

@@ -29,6 +29,8 @@ from __future__ import annotations
 import re
 from dataclasses import dataclass, field
 
+from specfuse.loop import ids
+
 ENTRY_CLASSES = ("added", "changed", "fixed", "breaking")
 
 _UNRELEASED_HEADING_RE = re.compile(r"^##\s+\[Unreleased\]\s*$")
@@ -36,7 +38,9 @@ _RELEASED_HEADING_RE = re.compile(r"^##\s+\[(?P<version>[^\]]+)\]\s*-\s*(?P<date
 _ANY_H2_RE = re.compile(r"^##\s+")
 _CLASS_HEADING_RE = re.compile(r"^###\s+(?P<name>\S.*?)\s*$")
 _ENTRY_RE = re.compile(r"^-\s+(?P<summary>.+?)\s+\((?P<trace>[^()]+)\)\s*$")
-_TRACE_RE = re.compile(r"^(FEAT-\d{4}-\d{4}(?:/[A-Za-z0-9-]+)?|#\d+)$")
+_TRACE_RE = re.compile(
+    r"^(" + ids.FEATURE_ID_PATTERN + r"(?:/[A-Za-z0-9-]+)?|#\d+)$"
+)
 
 
 @dataclass

specfuse_loop-0.31.1/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.31.1

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/specfuse/loop/data/docs/concepts/autonomy-stop-classes.md

@@ -48,12 +48,19 @@ cleared by editing driver code; it clears by changing the plan's numbers.
 file under a judge-path surface — paths that would let a work unit edit its
 own verification.
 
-**Does not cover the terminal gate.** The class reads only the successor
-gate's drafted units. A terminal gate has no successor, so what its own units
-change is never checked; a single-gate feature is never checked at all. The
-terminal close goes straight to the judge, and no judge-path check sits on
-that path (#3542). A feature that edits a judge surface in its last gate should
-run under `review`.
+**Terminal gate.** The class reads only the successor gate's drafted units,
+and a terminal gate has no successor. A separate terminal judge-editing check
+covers it: it halts before the close when a done substantive unit of the last
+gate declares a judge-surface path, at every autonomy level. It is not one of
+the eight arm classes and does not touch `would_arm`. The operator clears the
+stop by writing `judge_edit_acknowledged` (`paths` and `reason`) on the close
+unit and running `/unblock-wu`. It uses the same `JUDGE_PATHS`, so the
+universal entries (`.specfuse/verification.yml`, `.specfuse/hooks/`,
+`.specfuse/rules/`, `.github/workflows/`, `pyproject.toml`) also reach consumer
+repositories: a feature there whose last gate edits its CI workflow or
+`pyproject.toml` halts once. The check reads declared `produces:` paths only,
+so an edit a unit never declares is not seen, and `pyproject.toml` matches
+whole-file, so a dependency bump fires it.
 
 **Fires when:** a drafted WU's `produces:` list contains a path matching one
 of `JUDGE_PATHS` — `.specfuse/verification.yml`, `.specfuse/hooks/`,

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/specfuse/loop/data/docs/getting-started.md

@@ -112,7 +112,7 @@ Two ways to create a feature folder under `.specfuse/features/`:
 - **By hand:** start from the bare templates in `.specfuse/templates/`
   (`PLAN`, `GATE`, `WU`) and fill in a small first feature. (The
   `specfuse/loop` source repo also carries a worked example,
-  `FEAT-2026-0001-health-endpoint`, if you want a complete reference to copy
+  `FEAT-LOOP-2026-0001-health-endpoint`, if you want a complete reference to copy
   from.)
 
 A feature folder holds:
@@ -141,7 +141,13 @@ specfuse lint .specfuse/features/FEAT-YYYY-NNNN-your-feature
 ```
 
 The linter checks structure: every WU has the five mandatory sections, the closing
-sequence is present and well-formed, dependencies resolve, IDs are well-formed.
+sequence is present and well-formed, dependencies resolve, IDs are well-formed
+(both `FEAT-YYYY-NNNN` and the keyed `FEAT-<KEY>-YYYY-NNNN` form).
+
+Running several repos? Optionally set `ids.key` in `.specfuse/layout.yml` so new
+IDs read `FEAT-<KEY>-YYYY-NNNN`. Pick a short key distinct across the repos of
+one project (uniqueness is by convention). Existing IDs are never renamed;
+`ids migrate --planned-only` re-keys folderless planned rows only.
 Fix anything it flags before dispatching — it's far cheaper than a failed
 dispatch.
 

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/specfuse/loop/data/docs/glossary.md

@@ -13,7 +13,8 @@ reference.
 intends to build, one row each. Add to it with `/roadmap-add`; pick what to
 build next with `/pick-feature`.
 
-**Feature** — one substantial piece of work, `FEAT-YYYY-NNNN`, with a folder
+**Feature** — one substantial piece of work, `FEAT-YYYY-NNNN` (`FEAT-<KEY>-YYYY-NNNN` when
+`ids.key` is set in `.specfuse/layout.yml`; legacy IDs are never renamed), with a folder
 under `.specfuse/features/`. Its `PLAN.md` holds the goal, the gates, and the
 budget. Roughly: a thing you would describe in a sentence to someone who does
 not work on the project.
@@ -24,7 +25,7 @@ and you decide** — everything inside one runs unattended; the boundary between
 two is yours.
 
 **Work unit (WU)** — the smallest dispatchable piece: one file, one job, one
-fresh session. `FEAT-YYYY-NNNN/T01`. Everything the session needs is in that
+fresh session. `FEAT-YYYY-NNNN/T01` (keyed: `FEAT-<KEY>-YYYY-NNNN/T01`). Everything the session needs is in that
 file, because it starts with no memory of anything before it.
 
 **Verification** — the commands in `.specfuse/verification.yml` that decide

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/specfuse/loop/data/docs/methodology.md

@@ -34,7 +34,8 @@ on both surfaces.
     decision or dependency. The absence of a named blocker is the entire
     difference from `blocked`.
 - **Feature** — a spec-driven *or directly-authored* unit of value, identified by
-  a correlation ID `FEAT-YYYY-NNNN`. A feature owns an ordered list of gates.
+  a correlation ID `FEAT-YYYY-NNNN` (or `FEAT-<KEY>-YYYY-NNNN` when the repo sets
+  `ids.key`; see *Project key* below). A feature owns an ordered list of gates.
 - **Gate** — a milestone partition of a feature: an ordered batch of substantive
   work units followed by a mandatory closing sequence and a human review-and-arm
   checkpoint. Gates are numbered within a feature.
@@ -49,6 +50,30 @@ on both surfaces.
   It carries its own prompt and is the contract between the planner and the
   executor.
 
+**Project key.** A repo may set an optional `ids.key` in `.specfuse/layout.yml`.
+With a key set, new features are allocated as `FEAT-<KEY>-YYYY-NNNN`, and the
+folder anchor uses the lower-cased key (`FEAT-<key>-YYYY-NNNN-slug`). Numbering
+stays per repo and continues from the highest ordinal of either form. Legacy
+unkeyed IDs are permanent: existing IDs are never renamed. The one exception to
+leaving old rows alone is `ids migrate --planned-only`, which re-keys folderless
+planned roadmap rows. Pick a short key distinct across the repos of one project;
+uniqueness is by convention, not enforced. No prompt asks for the key; it is read
+from `layout.yml`. The ID shape lives in `specfuse.loop.ids`.
+
+**Renaming existing features.** `ids migrate --all` is the opt-in full rename: it
+re-keys every feature of the repository, rewriting folder names, PLAN and WU
+frontmatter, roadmap rows and anchors, and `events.jsonl` correlation IDs, and
+records each old-to-new pair in `.specfuse/id-aliases.yml`. It cannot reach git
+history, GitHub issue and PR titles, or other repositories, which keep the old
+IDs. The loop resolves an old ID through the alias map (one hop) wherever an
+operator types one: `--feature`, `gate_eval`, and `[FEAT-…]` issue titles. Prose
+mentions are listed for review (`--include-prose` rewrites them) rather than
+rewritten silently.
+`--rehearse` proves a rename first: it applies it (with post-apply validation) on a
+throwaway worktree of `HEAD`, runs the `tests` gate command there (or
+`--rehearse-command`), reports the failing tests, and removes the worktree; the real
+tree is never written and must have no uncommitted tracked changes.
+
 The correlation ID threads the entire lifecycle — it appears in the feature
 folder name, the WU file, every event-log entry, the branch, the commit trailer
 (`Feature: FEAT-YYYY-NNNN/TNN`), and (in the orchestrator) the GitHub issue.
@@ -406,7 +431,7 @@ Every dispatched attempt emits exactly one `attempt_outcome` event to
 `outcome`, `failure_class`, `failure_signature`, `failure_excerpt`,
 `failing_tests`, `cost_usd`, `duration_seconds`, `attempt`, and
 `re_arm_count`. For the field-by-field schema see
-`.specfuse/features/FEAT-2026-0016-attempt-outcome-rearm-contract/PLAN.md`
+`.specfuse/features/FEAT-LOOP-2026-0016-attempt-outcome-rearm-contract/PLAN.md`
 § "Event payload shape — `attempt_outcome` v1". The full payload is
 not restated here (one fact, one home).
 
@@ -796,11 +821,13 @@ single flip site. What changed is what an armed gate is armed *on*. Before the
 judge, an `auto` feature let the session that did the work write the verdict
 that advanced the feature; now a fresh evaluator that never sees that session's
 prose writes it, and can only lower it. The `judge_editing` stop class vetoes
-arming a successor gate whose drafted units would edit a judge surface. It
-does **not** cover the terminal gate's own units, so a single-gate feature,
-or the last gate of any feature, that edits the loop's verdict machinery
-reaches its close with no human checkpoint under `auto` (#3542). Choose
-`review` for such a feature.
+arming a successor gate whose drafted units would edit a judge surface. The
+terminal gate has no successor, so a separate check covers it: when a done
+substantive unit of the last gate declares a judge-surface path, the driver
+halts before the close, at every autonomy level, and the operator clears the
+stop by writing `judge_edit_acknowledged` on the close unit and running
+`/unblock-wu`. `review` adds no terminal checkpoint; choose it only when a
+wrong arm is expensive to undo.
 
 Tighten to `review` when the judge cannot do its job — a feature whose criteria
 are not judgeable from the evidence bundle (see `judge_disabled` in §3), or one

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/specfuse/loop/data/roadmap.template.md

@@ -46,7 +46,10 @@ flips `blocked` → `active` (or `planned`) and removes the `**Blocked by.**` bl
 
 ## Notes
 
-- Correlation IDs are allocated here, sequentially per year: `FEAT-YYYY-NNNN`. Work
+- Correlation IDs are allocated here, sequentially per year per repo: `FEAT-YYYY-NNNN`,
+  or `FEAT-<KEY>-YYYY-NNNN` when `ids.key` is set in `.specfuse/layout.yml` (numbering
+  continues from the highest ordinal of either form; legacy IDs are never renamed;
+  `ids migrate --planned-only` re-keys folderless planned rows). Work
   units take `FEAT-YYYY-NNNN/TNN`. The same scheme threads commits (trailer
   `Feature: FEAT-YYYY-NNNN/TNN`), the per-feature event log, and — at fold-in —
   GitHub issues across repos.

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/specfuse/loop/data/rules/correlation-ids.md

@@ -24,6 +24,16 @@ Two namespaces, four canonical shapes:
   - `YYYY` is the four-digit calendar year in which the feature was created.
   - `NNNN` is a zero-padded four-digit ordinal, unique within that year's roadmap.
   - Example: `FEAT-2026-0042`.
+- **Keyed feature-level (optional):** `FEAT-<KEY>-YYYY-NNNN`
+  - `KEY` is a per-repository project key: an uppercase letter followed by one to
+    five uppercase letters or digits (`[A-Z][A-Z0-9]{1,5}`). A repository opts in by
+    setting it once (in the loop, `ids.key` in `.specfuse/layout.yml`); without a key,
+    IDs keep the unkeyed shape above.
+  - The key makes an ID say which repository it belongs to, so the same ordinal in
+    two repositories of one project no longer collides. Numbering stays per
+    repository: the ordinal continues from the highest `NNNN` of either shape.
+  - Unkeyed IDs that already exist stay valid permanently and are never renamed.
+  - Example: `FEAT-ACME-2026-0042`; anchor `feat-acme-2026-0042`.
 - **Task-level:** `FEAT-YYYY-NNNN/<task-id>`
   - The feature-level ID, a literal `/`, then the task identifier.
   - Substantive units use `TNN` — `T` followed by a zero-padded two-digit ordinal,
@@ -66,7 +76,7 @@ Collisions between the two namespaces are structurally impossible.
 The combined pattern accepted across all shapes is:
 
 ```
-^(FEAT-\d{4}-\d{4}(/(T\d{2}(H\d*)?|G\d+-(RETRO|LESSONS|DOCS|PLAN|CLOSE-INTERMEDIATE|CLOSE)))?|INIT-\d{4}-\d{4}/F\d{2}(/(T\d{2}(H\d*)?|G\d+-(RETRO|LESSONS|DOCS|PLAN|CLOSE-INTERMEDIATE|CLOSE)))?)$
+^(FEAT-(?:[A-Z][A-Z0-9]{1,5}-)?\d{4}-\d{4}(/(T\d{2}(H\d*)?|G\d+-(RETRO|LESSONS|DOCS|PLAN|CLOSE-INTERMEDIATE|CLOSE)))?|INIT-\d{4}-\d{4}/F\d{2}(/(T\d{2}(H\d*)?|G\d+-(RETRO|LESSONS|DOCS|PLAN|CLOSE-INTERMEDIATE|CLOSE)))?)$
 ```
 
 A string that does not match is malformed.
@@ -123,7 +133,9 @@ that materially describes the work, err toward including the ID.
 ## Generating the next ID
 
 **Feature-level.** The next ordinal for year `YYYY` is one greater than the largest
-`NNNN` that currently appears in `.specfuse/features/FEAT-YYYY-*/`. If no feature
+`NNNN` that currently appears in `.specfuse/features/FEAT-YYYY-*/` or, in a keyed
+repository, `.specfuse/features/FEAT-<KEY>-YYYY-*/` (both shapes count). A keyed
+repository emits the keyed shape. If no feature
 for `YYYY` exists yet, start at `0001`. Padding is always four digits: `0001`,
 `0042`, `1234`. Year rollover does not continue the previous year's counter — each
 year starts fresh at `0001`.

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/specfuse/loop/data/schemas/driver-event.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://specfuse.dev/loop/schemas/driver-event.schema.json",
   "title": "Driver-local envelope registry",
   "description": "Additive to the vendored orchestrator envelope (event.schema.json): shapes the loop driver emits with no orchestrator-side counterpart. validate_event.py resolves each shape against the vendored envelope first; only when absent there does it fall through to this registry. `event_types` (FEAT-2026-0060) widens the event_type enum; task_started, task_completed, and human_escalation are already sanctioned in the vendored enum and must not be duplicated here. `correlation_id` (FEAT-2026-0073) widens the correlation_id pattern to admit the closing-sequence and hygiene shapes `.specfuse/rules/correlation-ids.md` documents; `closing_names` and `hygiene_suffix_pattern` here must state the same set of shapes as that rules file's combined pattern (and as specfuse/loop/lint_plan.py's CORRELATION_ID_RE, which independently enforces the same contract on PLAN.md graphs).",
-  "$comment": "FEAT-2026-0060/T01: event_types derived from the union of every build_event(...) call site in specfuse/loop/loop.py and a corpus sweep of every .specfuse/features/*/events.jsonl, subtracting the vendored envelope enum. attempt_outcome and gate_reached were already-known precedent (loop.py's build_arm_predicate_event docstring); auto_close_decision, arm_predicate_evaluated, re_arm_dispatched, plan_next_draft_lint, and unsandboxed_dispatch are additional driver-local mechanics the orchestrator has no concept of. gate_auto_armed (loop.py build_event call under gate_events.append) and re_arm_rejected (loop.py build_event call under the spinning_reproduction_missing re-arm check) are emitted by real code paths that have never fired in a recorded run, so a corpus-only sweep cannot see them; they are included because call-site derivation does. FEAT-2026-0073/T01: correlation_id added — closing_names and hygiene_suffix_pattern mirror correlation-ids.md's documented shapes and lint_plan.py's CORRELATION_ID_RE verbatim, so the envelope, the rules file, and the PLAN-graph linter state one contract. FEAT-2026-0075/T03: driver_staleness_detected added — emitted at gate completion when a work unit's squash diff touched the driver's own importable surface, naming the editing unit, the driver paths it touched, and the IDs of units this process dispatched afterward (which ran the pre-edit module). FEAT-2026-0100/T02: judged added — emitted once per terminal close after the closing-deliverable guards, carrying the close's own verdict, the judge session's verdict (null when the judge was disabled, timed out, or returned nothing parseable, with the reason beside it), and whether the judge lowered it. FEAT-2026-0109/T01: baseline_attribution added — emitted when the retroactive per-attempt-failure baseline probe (attribute_failure_to_baseline) runs fresh, carrying the gate, the failing-gate set, and the unit whose failed attempt triggered the probe. FEAT-2026-0109/T06: broad_run_result added — emitted whenever the once-per-gate broad verification pass (gate_broad_run_check) actually runs (never on a tree-unchanged dedup skip), carrying the gate, the tree it was measured on, and its pass/fail outcome; a failing broad run additionally raises the existing human_escalation event type with reason: broad_run_gate_failure, which needs no schema addition since human_escalation is already sanctioned in the vendored envelope enum. FEAT-2026-0109/T08: driver_build_pinned added — emitted once per process, before any work unit is dispatched, when this process is itself a materialized pin (`_reexec_pinned`); carries the pin's tree hash and its path so an operator or test can read what build actually ran without inferring it from `ps` output. `driver_staleness_detected` needed no addition here: this unit reuses it with `halted: false` for the pinned, non-halting case (the registry constrains the type list, not the payload), adding `pinned_tree` / `next_pin_tree` fields alongside the existing `halted: true` shape. FEAT-2026-0104/T04: replan added — emitted once a re-plan turn (T03's run_replan_turn) rewrites a unit's body ahead of its last permitted attempt, so gate_eval.py's evaluate_auto_close (check 2, already reading this event_type since FEAT-2026-0018/T02) can disable auto-close for a gate that needed one. FEAT-2026-0115/T01: fix_unit_inserted added — emitted once a blocked RESULT's `blocked_next:` names a drafted fix unit that `insert_fix_unit` validated and inserted ahead of the blocked unit, carrying the fix unit's id, its file, the gate, and the insertion count; the blocked unit's own re-arm (an existing `re_arm_dispatched`, reason `fix_unit_inserted`) rides alongside it, so this is the only genuinely new event_type the mechanic needs.",
+  "$comment": "FEAT-2026-0060/T01: event_types derived from the union of every build_event(...) call site in specfuse/loop/loop.py and a corpus sweep of every .specfuse/features/*/events.jsonl, subtracting the vendored envelope enum. attempt_outcome and gate_reached were already-known precedent (loop.py's build_arm_predicate_event docstring); auto_close_decision, arm_predicate_evaluated, re_arm_dispatched, plan_next_draft_lint, and unsandboxed_dispatch are additional driver-local mechanics the orchestrator has no concept of. gate_auto_armed (loop.py build_event call under gate_events.append) and re_arm_rejected (loop.py build_event call under the spinning_reproduction_missing re-arm check) are emitted by real code paths that have never fired in a recorded run, so a corpus-only sweep cannot see them; they are included because call-site derivation does. FEAT-2026-0073/T01: correlation_id added — closing_names and hygiene_suffix_pattern mirror correlation-ids.md's documented shapes and lint_plan.py's CORRELATION_ID_RE verbatim, so the envelope, the rules file, and the PLAN-graph linter state one contract. FEAT-2026-0075/T03: driver_staleness_detected added — emitted at gate completion when a work unit's squash diff touched the driver's own importable surface, naming the editing unit, the driver paths it touched, and the IDs of units this process dispatched afterward (which ran the pre-edit module). FEAT-2026-0100/T02: judged added — emitted once per terminal close after the closing-deliverable guards, carrying the close's own verdict, the judge session's verdict (null when the judge was disabled, timed out, or returned nothing parseable, with the reason beside it), and whether the judge lowered it. FEAT-2026-0109/T01: baseline_attribution added — emitted when the retroactive per-attempt-failure baseline probe (attribute_failure_to_baseline) runs fresh, carrying the gate, the failing-gate set, and the unit whose failed attempt triggered the probe. FEAT-2026-0109/T06: broad_run_result added — emitted whenever the once-per-gate broad verification pass (gate_broad_run_check) actually runs (never on a tree-unchanged dedup skip), carrying the gate, the tree it was measured on, and its pass/fail outcome; a failing broad run additionally raises the existing human_escalation event type with reason: broad_run_gate_failure, which needs no schema addition since human_escalation is already sanctioned in the vendored envelope enum. FEAT-2026-0109/T08: driver_build_pinned added — emitted once per process, before any work unit is dispatched, when this process is itself a materialized pin (`_reexec_pinned`); carries the pin's tree hash and its path so an operator or test can read what build actually ran without inferring it from `ps` output. `driver_staleness_detected` needed no addition here: this unit reuses it with `halted: false` for the pinned, non-halting case (the registry constrains the type list, not the payload), adding `pinned_tree` / `next_pin_tree` fields alongside the existing `halted: true` shape. FEAT-2026-0104/T04: replan added — emitted once a re-plan turn (T03's run_replan_turn) rewrites a unit's body ahead of its last permitted attempt, so gate_eval.py's evaluate_auto_close (check 2, already reading this event_type since FEAT-2026-0018/T02) can disable auto-close for a gate that needed one. FEAT-2026-0115/T01: fix_unit_inserted added — emitted once a blocked RESULT's `blocked_next:` names a drafted fix unit that `insert_fix_unit` validated and inserted ahead of the blocked unit, carrying the fix unit's id, its file, the gate, and the insertion count; the blocked unit's own re-arm (an existing `re_arm_dispatched`, reason `fix_unit_inserted`) rides alongside it, so this is the only genuinely new event_type the mechanic needs. FEAT-2026-0246/T01: terminal_judge_editing_evaluated added — emitted on every terminal gate immediately before the close (auto or dispatched), carrying the gate, the `arm_eval.evaluate_terminal_judge_editing` verdict status and reason; a `fired` verdict additionally raises the existing human_escalation event type with reason: judge_editing_terminal, which needs no schema addition. FEAT-2026-0246/T02: terminal_judge_editing_acknowledged added — emitted when that check is clean only because the close unit carries an operator-authored judge_edit_acknowledged field covering every hit, carrying the gate, close unit id, acknowledged paths, and the operator's reason. FEAT-2026-0247/T06: the correlation-ID shape (legacy FEAT-YYYY-NNNN and the keyed FEAT-<KEY>-YYYY-NNNN form) now comes from specfuse.loop.ids.",
   "event_types": [
     "attempt_outcome",
     "gate_reached",
@@ -21,7 +21,9 @@
     "broad_run_result",
     "driver_build_pinned",
     "replan",
-    "fix_unit_inserted"
+    "fix_unit_inserted",
+    "terminal_judge_editing_evaluated",
+    "terminal_judge_editing_acknowledged"
   ],
   "correlation_id": {
     "closing_names": [

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/specfuse/loop/data/schemas/event.schema.json

@@ -24,7 +24,7 @@
     "correlation_id": {
       "type": "string",
       "description": "Correlation ID at any level of the unit hierarchy (docs/naming-convention.md): initiative INIT-YYYY-NNNN, dispatched feature INIT-YYYY-NNNN/FNN, work unit INIT-YYYY-NNNN/FNN/<task-id>; or the legacy/component-local feature FEAT-YYYY-NNNN and task FEAT-YYYY-NNNN/<task-id>. The task-id segment carries all three documented work-unit shapes: substantive TNN, hygiene TNNH[N...] (the target unit's ordinal, a literal H, and an optional ordinal), and closing-sequence G<n>-<NAME> where <NAME> is RETRO, LESSONS, DOCS, PLAN, CLOSE-INTERMEDIATE, or CLOSE. Existing FEAT- entries validate unchanged.",
-      "pattern": "^(FEAT|INIT)-\\d{4}-\\d{4}(/F\\d{2})?(/(T\\d{2}(H\\d*)?|G\\d+-(RETRO|LESSONS|DOCS|PLAN|CLOSE-INTERMEDIATE|CLOSE)))?$"
+      "pattern": "^(FEAT-(?:[A-Z][A-Z0-9]{1,5}-)?|INIT-)\\d{4}-\\d{4}(/F\\d{2})?(/(T\\d{2}(H\\d*)?|G\\d+-(RETRO|LESSONS|DOCS|PLAN|CLOSE-INTERMEDIATE|CLOSE)))?$"
     },
     "event_type": {
       "type": "string",

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/specfuse/loop/data/schemas/events/spec_issue_resolved.schema.json

@@ -15,7 +15,7 @@
     "original_issue_correlation_id": {
       "type": "string",
       "description": "The task-level correlation ID from the triggering task that filed the spec issue (e.g. `FEAT-2026-0042/T09`). Links the resolution event back to the original `spec_issue_raised` event and the downstream task that discovered the problem. This is the task-level ID, not the feature-level ID, because spec issues are raised in the context of a specific task's work. The task-id segment accepts every documented work-unit shape: substantive TNN, hygiene TNNH[N...], and closing-sequence G<n>-<NAME> (RETRO, LESSONS, DOCS, PLAN, CLOSE-INTERMEDIATE, CLOSE). See .specfuse/rules/correlation-ids.md.",
-      "pattern": "^((FEAT-\\d{4}-\\d{4})|(INIT-\\d{4}-\\d{4}/F\\d{2}))/(T\\d{2}(H\\d*)?|G\\d+-(RETRO|LESSONS|DOCS|PLAN|CLOSE-INTERMEDIATE|CLOSE))$"
+      "pattern": "^((FEAT-(?:[A-Z][A-Z0-9]{1,5}-)?\\d{4}-\\d{4})|(INIT-\\d{4}-\\d{4}/F\\d{2}))/(T\\d{2}(H\\d*)?|G\\d+-(RETRO|LESSONS|DOCS|PLAN|CLOSE-INTERMEDIATE|CLOSE))$"
     },
     "affected_files": {
       "type": "array",

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/specfuse/loop/data/schemas/events/spec_issue_routed.schema.json

@@ -15,7 +15,7 @@
     "original_issue_correlation_id": {
       "type": "string",
       "description": "The task-level correlation ID from the triggering task that filed the spec issue (e.g. `FEAT-2026-0042/T09`). Links the routing event back to the original `spec_issue_raised` event and the downstream task that discovered the problem. The task-id segment accepts every documented work-unit shape: substantive TNN, hygiene TNNH[N...], and closing-sequence G<n>-<NAME> (RETRO, LESSONS, DOCS, PLAN, CLOSE-INTERMEDIATE, CLOSE). See .specfuse/rules/correlation-ids.md.",
-      "pattern": "^((FEAT-\\d{4}-\\d{4})|(INIT-\\d{4}-\\d{4}/F\\d{2}))/(T\\d{2}(H\\d*)?|G\\d+-(RETRO|LESSONS|DOCS|PLAN|CLOSE-INTERMEDIATE|CLOSE))$"
+      "pattern": "^((FEAT-(?:[A-Z][A-Z0-9]{1,5}-)?\\d{4}-\\d{4})|(INIT-\\d{4}-\\d{4}/F\\d{2}))/(T\\d{2}(H\\d*)?|G\\d+-(RETRO|LESSONS|DOCS|PLAN|CLOSE-INTERMEDIATE|CLOSE))$"
     },
     "target_project": {
       "type": "string",

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/specfuse/loop/data/schemas/events/spec_validated.schema.json

@@ -17,7 +17,7 @@
     "feature_correlation_id": {
       "type": "string",
       "description": "The feature-level correlation ID of the feature whose specs were validated. Duplicated from the envelope `correlation_id` for payload self-containment — downstream consumers that index payloads without re-reading the envelope benefit from the redundancy.",
-      "pattern": "^(FEAT|INIT)-\\d{4}-\\d{4}(/F\\d{2})?$"
+      "pattern": "^(FEAT-(?:[A-Z][A-Z0-9]{1,5}-)?|INIT-)\\d{4}-\\d{4}(/F\\d{2})?$"
     },
     "pass": {
       "type": "boolean",

{specfuse_loop-0.30.0 → specfuse_loop-0.31.1}/specfuse/loop/gate_eval.py

@@ -23,6 +23,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from . import _miniyaml
+from . import ids as _ids
 
 PREDICATE_VERSION = "v1"
 PER_WU_COST_RATIO_CEILING = 1.5
@@ -441,6 +442,7 @@ def _resolve_feature_dir(feature_id: str, repo_root: Path) -> "Path | None":
         return None
 
     candidates = sorted(d for d in features_dir.iterdir() if d.is_dir())
+    feature_id = _ids.resolve(repo_root, feature_id)
 
     # Priority 1: exact directory name
     exact = [d for d in candidates if d.name == feature_id]
@@ -458,8 +460,16 @@ def _resolve_feature_dir(feature_id: str, repo_root: Path) -> "Path | None":
     partial: list[Path] = []
     for d in candidates:
         name = d.name
+        parsed = _ids.parse(name)
+        if parsed is not None:
+            # FEAT-[KEY-]YYYY-NNNN-slug: compare the ordinal and the slug
+            head = str(parsed)
+            nnnn = f"{parsed.ordinal:04d}"
+            slug = name[len(head) + 1:]
+            if nnnn == feature_id or slug == feature_id:
+                partial.append(d)
+            continue
         parts = name.split("-")
-        # FEAT-YYYY-NNNN-slug → parts[2] is the NNNN part
         if len(parts) >= 4:
             nnnn = parts[2]
             slug = "-".join(parts[3:])