agentfluent 0.8.0__tar.gz → 0.10.0__tar.gz

agentfluent-0.10.0/.claude/claude-security-guidance.md

@@ -0,0 +1,69 @@
+# Security Guidance — AgentFluent
+
+Threat model and review checklist for the `security-guidance` plugin's
+LLM-backed review layers (end-of-turn diff review and commit/push review).
+
+> **Status:** Currently dormant. The LLM layers are disabled
+> (`ENABLE_CODE_SECURITY_REVIEW=0` in `.claude/settings.json`), so only the
+> free deterministic pattern layer runs today. This file activates the moment
+> those layers are turned on — keep it in sync with the CI workflow's
+> `custom-security-scan-instructions` in `.github/workflows/security-review.yml`
+> so the in-session review and the PR-time review share one threat model.
+
+## What AgentFluent is
+
+A local-first Python CLI that reads user session data and agent definitions
+from `~/.claude/projects/` and `~/.claude/agents/`. It stores no credentials and
+transmits no user data, and runs no web server, HTML rendering, or webview. Its
+**only** network egress and subprocess use is the `gh` / `git` CLI (the Tier 3
+GitHub-signals feature in `src/agentfluent/github/` and `diagnostics/`), invoked
+list-form with `shell=False`. No in-process HTTP client
+(`requests`/`httpx`/`urllib`/`socket`) is imported anywhere outside
+`src/agentfluent/github/`.
+
+## Attack surfaces to focus on
+
+1. **JSONL parser** (`src/agentfluent/core/parser.py`) — reads arbitrary
+   user-controlled content. Check for unsafe deserialization, resource-exhaustion
+   on malformed/oversized input (unbounded reads, pathological nesting), and any
+   code path that evaluates or executes parsed strings.
+2. **Agent definition parser** (`src/agentfluent/config/scanner.py`) — parses
+   YAML frontmatter. Must use `yaml.safe_load` (never `yaml.load`) to prevent
+   arbitrary code execution via YAML tags.
+3. **Path handling in discovery** (`src/agentfluent/core/discovery.py`) —
+   iterates user directories. Check for path traversal, symlink following that
+   escapes the projects root, and TOCTOU races between stat and open.
+4. **CLI argument parsing** (`src/agentfluent/cli/`) — user strings from
+   `--project`, `--agent`, `--session` are matched against discovered data.
+   Ensure none reach a shell, `subprocess`, or any eval-like API.
+
+## Project-specific sensitivities
+
+- **Secret hygiene in output.** AgentFluent reads session transcripts that may
+  contain credential-looking values. Flag any new code path that echoes raw tool
+  output, renders un-redacted file contents, or logs values matching
+  `KEY|TOKEN|SECRET|PASSWORD`. (Two enforcement hooks already guard secret reads
+  and output — see `docs/SECURITY.md`.)
+- **Untrusted strings into rendering.** Sanitize user-controlled strings before
+  passing them to Rich/terminal formatting; never interpolate them into shell
+  commands.
+
+## Low priority (typically non-issues here)
+
+No web server, no HTML rendering, no webview, no authentication surface. The only
+sanctioned network egress is the `gh` / `git` CLI (`src/agentfluent/github/`,
+`diagnostics/`); findings that assume an in-process HTTP or web attack surface
+elsewhere are almost certainly false positives — note them but rank low.
+
+## Review checklist
+
+- [ ] No `eval`, `exec`, `os.system`, `subprocess(..., shell=True)`, or
+      `compile()` on parsed/user-derived strings.
+- [ ] YAML loaded only via `yaml.safe_load`; no `pickle.load` /
+      `pickle.loads` on file or session content.
+- [ ] User-supplied paths are resolved and confined to their expected root
+      (no `..` escape, no symlink escape).
+- [ ] Parser bounds memory/CPU on malformed input — no unbounded buffering.
+- [ ] No credential-shaped value is logged, printed, or rendered un-redacted.
+- [ ] New external calls (file I/O, any future network) are wrapped in
+      try/except with user-friendly, non-leaking error messages.

agentfluent-0.10.0/.claude/hooks/guard_append_only.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: protect append-only spec logs from entry-dropping writes.
+
+Receives the PreToolUse event JSON on stdin. For a `Write` targeting a
+registered append-only file (currently `.claude/specs/decisions.md`), it
+compares the set of decision-entry IDs (`## Dxxx` headings) already on disk
+against the set in the proposed `content`. If the write would drop any
+existing entry, the call is denied.
+
+Background: an append-only decision log was once clobbered by an agent whose
+`Write` tool does full-file replacement -- a pm intending to append one
+`Dxxx` entry replaced the entire file, dropping D001-D042 in the working copy
+(GitHub issue #500). This hook is the durable, agent-agnostic guard.
+
+Scope and bypass surface (deliberately bounded):
+- Guards the `Write` tool only. `Edit` is surgical (it cannot easily drop the
+  whole file) and simulating its result to detect drops is fragile, so it is
+  not guarded.
+- It does NOT cover `Bash` redirection (`cat > file`, `tee`, `sed -i`), which
+  an agent with Bash could use to clobber the file. This hook therefore
+  protects *entry existence against full-file Writes*, not body content, and
+  is not an absolute "any tool" guarantee. A Bash-command scan is the natural
+  follow-up extension if that guarantee is needed.
+
+Emits a JSON decision on stdout and exits 0 (the modern pattern); exit 2 +
+stderr is the fail-closed fallback for an unparseable event, matching
+`block_secret_reads.py`.
+
+Cross-platform: stdlib only, no shell dependencies.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path, PurePath
+from typing import Any
+
+# Registry of append-only files to protect, keyed by path SUFFIX (not bare
+# basename, to avoid false positives on unrelated `decisions.md` files
+# elsewhere in the tree). Each value is the anchored, multiline regex that
+# captures the entry IDs whose existence must be preserved across a write.
+# To protect another append-only spec, add its suffix + ID pattern here.
+#
+# The ID capture includes an optional `-<suffix>` segment so suffixed entries
+# (e.g. `## D038-A:`) are tracked as distinct IDs. Without it, `D\d+` would
+# truncate `D038-A` to `D038`, collapsing it with a sibling `## D038:` entry
+# and silently allowing one of them to be dropped (the exact #500 hazard).
+DECISION_ID_PATTERN = re.compile(r"^##\s+(D\d+(?:-[A-Za-z0-9]+)?)", re.MULTILINE)
+
+APPEND_ONLY_FILES: dict[str, re.Pattern[str]] = {
+    ".claude/specs/decisions.md": DECISION_ID_PATTERN,
+}
+
+DENY_REASON = (
+    "Blocked by AgentFluent append-only guard hook "
+    "(.claude/hooks/guard_append_only.py). "
+    "This Write would drop one or more existing entries from an append-only "
+    "log, which is a data-loss risk (see issue #500). "
+    "The guard protects entry existence (`## Dxxx` headings), not body text -- "
+    "editing the body of an existing entry is fine as long as no entry is "
+    "removed. To add an entry, append to the file (e.g. read the current "
+    "content and write it back with the new entry appended, or use Edit), "
+    "preserving every existing `## Dxxx` heading."
+)
+
+
+def normalize(path_str: str) -> str:
+    """Return a forward-slash path string for suffix matching."""
+    return PurePath(path_str).as_posix()
+
+
+def match_registered_file(path_str: str) -> re.Pattern[str] | None:
+    """Return the ID pattern for a registered append-only file, else None."""
+    if not path_str:
+        return None
+    normalized = normalize(path_str)
+    for suffix, pattern in APPEND_ONLY_FILES.items():
+        # Require a path-component boundary so an unrelated file whose tail
+        # merely ends in the suffix string (e.g. `.../vendor.claude/specs/
+        # decisions.md`) is not mistaken for the protected log.
+        if normalized == suffix or normalized.endswith("/" + suffix):
+            return pattern
+    return None
+
+
+def extract_ids(text: str, pattern: re.Pattern[str]) -> set[str]:
+    """Extract the set of entry IDs from text using the registered pattern."""
+    return set(pattern.findall(text))
+
+
+def evaluate(
+    existing_content: str, proposed_content: str, pattern: re.Pattern[str]
+) -> tuple[bool, str]:
+    """Decide whether a write should be blocked. Pure (no I/O).
+
+    Returns (blocked, reason). Blocks when any ID present in the existing
+    content is absent from the proposed content.
+    """
+    existing_ids = extract_ids(existing_content, pattern)
+    if not existing_ids:
+        # Nothing to protect yet (file exists but has no recognized entries).
+        return False, ""
+    proposed_ids = extract_ids(proposed_content, pattern)
+    missing = sorted(existing_ids - proposed_ids)
+    if missing:
+        return True, f"{DENY_REASON} (would drop: {', '.join(missing)})"
+    return False, ""
+
+
+def check(event: dict[str, Any]) -> tuple[bool, str]:
+    """Inspect a PreToolUse event; return (blocked, reason)."""
+    if event.get("tool_name", "") != "Write":
+        return False, ""
+
+    tool_input = event.get("tool_input") or {}
+    path = tool_input.get("file_path") or ""
+    pattern = match_registered_file(path)
+    if pattern is None:
+        return False, ""
+
+    proposed_content = tool_input.get("content") or ""
+
+    try:
+        existing_content = Path(path).read_text(encoding="utf-8")
+    except FileNotFoundError:
+        # New file: there is nothing to drop.
+        return False, ""
+    except (OSError, UnicodeDecodeError) as e:
+        # A real read error on an existing protected file means we cannot
+        # verify the write is safe. Fail closed -- deny rather than risk a
+        # silent clobber. (Such errors on a local file are vanishingly rare.)
+        return True, (
+            f"{DENY_REASON} (could not read the existing file to verify no "
+            f"entries are dropped: {e})"
+        )
+
+    return evaluate(existing_content, proposed_content, pattern)
+
+
+def emit_decision(decision: str, reason: str) -> None:
+    payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": decision,
+            "permissionDecisionReason": reason,
+        }
+    }
+    sys.stdout.write(json.dumps(payload))
+
+
+def main() -> int:
+    try:
+        event = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError) as e:
+        # Fail closed: if we can't parse the event we can't confirm the write
+        # is safe, so deny rather than allow through a malformed event.
+        print(
+            f"guard_append_only: failed to parse hook event JSON, "
+            f"denying by default: {e}",
+            file=sys.stderr,
+        )
+        return 2
+
+    blocked, reason = check(event)
+    if blocked:
+        emit_decision("deny", reason)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agentfluent-0.10.0/.claude/security-patterns.json

@@ -0,0 +1,40 @@
+{
+  "_comment": "Project-specific custom patterns for the security-guidance plugin's free pattern layer. Complements (does not duplicate) the 25 built-in rules. Authored from the architect review on issue #524. JSON (not YAML) so the plugin's hook runtime never needs PyYAML. Globs use a leading wildcard because the hook matches against the absolute path with its leading slash stripped (file_path.lstrip('/') in check_patterns), and fnmatch anchors at the start.",
+  "patterns": [
+    {
+      "rule_name": "no-shell-true",
+      "regex": "shell\\s*=\\s*True",
+      "paths": ["*src/agentfluent/*.py"],
+      "exclude_paths": ["*/tests/*"],
+      "reminder": "AgentFluent never invokes a shell. Use list-form subprocess.run([...], shell=False); never shell=True. CLI args (--project/--agent/--session) must not reach a shell."
+    },
+    {
+      "rule_name": "no-dynamic-subprocess-args",
+      "regex": "subprocess\\.(run|Popen|call|check_output|check_call)\\(\\s*f[\"']",
+      "paths": ["*src/agentfluent/*.py"],
+      "exclude_paths": ["*/tests/*"],
+      "reminder": "Pass subprocess args as a list of literals/typed values, never an f-string or string-concatenated command. Building the command from interpolated input reintroduces injection even with shell=False."
+    },
+    {
+      "rule_name": "no-inprocess-http-client",
+      "regex": "(?:^|\\n)\\s*(import|from)\\s+(requests|httpx|urllib\\.request|urllib3|http\\.client|socket|aiohttp|ftplib|smtplib)\\b",
+      "paths": ["*src/agentfluent/*.py"],
+      "exclude_paths": ["*/tests/*", "*src/agentfluent/github/*"],
+      "reminder": "AgentFluent's only network egress is the gh CLI (Tier 3 GitHub signals). Do not import an in-process HTTP client. If you are adding a network feature, route it through the gh subprocess path or open a design discussion first."
+    },
+    {
+      "rule_name": "no-archive-extractall",
+      "substrings": [".extractall(", "tarfile.open(", "zipfile.ZipFile("],
+      "paths": ["*src/agentfluent/*.py"],
+      "exclude_paths": ["*/tests/*"],
+      "reminder": "AgentFluent reads JSONL, never archives. extractall() is a zip-slip / tar-slip path-traversal sink. If you genuinely need extraction, validate every member path stays within the target dir."
+    },
+    {
+      "rule_name": "no-render-secret-shaped-values",
+      "regex": "(print|log(ger)?\\.\\w+|console\\.print)\\([^)]*(api_key|api-key|secret|password)",
+      "paths": ["*src/agentfluent/*.py"],
+      "exclude_paths": ["*/tests/*"],
+      "reminder": "Session transcripts can contain secret-shaped values. Never print/log a variable named api_key/secret/password un-redacted. Redact at the boundary; see docs/SECURITY.md."
+    }
+  ]
+}

{agentfluent-0.8.0 → agentfluent-0.10.0}/.claude/settings.json

@@ -6,7 +6,16 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 .claude/hooks/block_secret_reads.py"
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/block_secret_reads.py\""
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard_append_only.py\""
           }
         ]
       }
@@ -17,7 +26,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 .claude/hooks/detect_secrets_in_output.py"
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/detect_secrets_in_output.py\""
           }
         ]
       }
@@ -32,5 +41,13 @@
         ]
       }
     ]
+  },
+  "enabledPlugins": {
+    "security-guidance@claude-plugins-official": true
+  },
+  "env": {
+    "ENABLE_CODE_SECURITY_REVIEW": "0",
+    "SECURITY_REVIEW_MODEL": "claude-sonnet-4-6",
+    "SG_AGENTIC_MODEL": "claude-sonnet-4-6"
   }
 }

agentfluent-0.10.0/.claude/skills/release-loop/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: release-loop
+description: Run one routed iteration of the supervised dev loop over a backlog (milestone/label). Selects the next unblocked issue, routes it, drives plan→architect→implement→review→merge with human gates on uncertainty, and journals to the ledger. Invoke once per issue; re-invoke (or drive via /loop) for the next. Use when the user wants to work a backlog as a loop, "run the release loop", or "do the next issue".
+---
+
+# Release Loop — orchestrator (ONE issue per invocation)
+
+You are the orchestrator of a supervised dev loop. Each invocation handles exactly ONE
+issue end-to-end, journals, and stops. State lives in the ledger, not your context — so a
+fresh invocation resumes correctly. Read the project parameters in
+`.claude/specs/prd-loop-engineering.md` §4.0.
+
+## 0. Load or initialize state
+1. Identify the active run (most recent `LEDGER_ROOT/<run>/`). If it already carries a
+   `RUN COMPLETE` sentinel (§9), report done and STOP — do not re-scan. If no run exists, ask
+   the user which milestone/label to run, then INITIALIZE per §7.5 of the spec.
+2. Read `queue.md` (note its `mode:` / `graduated-routes:` header and any `hold` rows) and the tail of `progress.md`.
+3. **Resume before selecting (spec §7.6).** If any row sits in an *interrupted* status —
+   non-terminal and NOT `queued`/`routed`/`hold` (i.e. `planning`/`plan-approved`/
+   `implementing`/`in-pr`/`in-review`) — a prior iteration was cut off. Reconcile it against
+   LIVE git/PR state as the source of truth — branch exists? PR open? already merged? CI
+   status? — plus the working tree (status is only a coarse anchor; git wins on conflict),
+   then re-enter the pipeline at the matching stage and FINISH that issue BEFORE selecting a
+   new one. This is what makes "one PR at a time" hold across `/clear`/compaction. A `hold`
+   row is NOT an interruption: skip it here, leave it held — it stays parked until the human
+   releases the hold and does not block working other issues.
+
+## 1. Select
+**Budget cap (iteration start, retrospective).** Read `iteration-cap:` / `subagent-cap:` from the
+`queue.md` header (both default `none` = uncapped). Cumulative iterations = the count of **distinct
+issues at a terminal status** (`done`/`deferred`/`blocked`) in `queue.md` — never count
+`progress.md` blocks (a `/clear`-resume re-enters an iteration and double-counts). Breach = that
+count ≥ `iteration-cap`, OR the **prior** iteration's journaled `- Budget:` line (§12) shows
+`subagent-runs` ≥ `subagent-cap`. On breach: **manual re-invoke is advisory** — journal + surface
+it and proceed (the human who invoked is the budget authority); **the driver halts.** Inert while
+both caps are `none`.
+
+A row is **selectable** if its status is `queued`/`routed`, OR it is `blocked` on an unmet
+dependency that has SINCE cleared (all its `Depends on` issues are now `done` — re-route it via
+§2; this does NOT apply to a `blocked: too-large` park, which waits on a split). Among
+selectable rows pick by `PRIORITY_LABELS` order, tiebreak issue-number ascending. If none are
+selectable:
+- If EVERY row is terminal (`done`/`deferred`/`blocked`), append the §9 `RUN COMPLETE —
+  <run-slug>` sentinel to `progress.md` (counts + any blocked/deferred items) and STOP
+  (convergence).
+- Else if the only non-terminal rows are `hold`, report "<n> held — awaiting human
+  merge-release" and STOP **without** the sentinel (the run is not complete).
+- Else (rows still blocked on open in-run dependencies) report what's pending and STOP
+  without the sentinel.
+**Size guard:** before entering the pipeline, estimate scope from the issue body — if it
+plausibly touches many files or spans multiple unrelated acceptance-criteria clusters (won't
+fit one context window), mark it `blocked: too-large`, escalate to SCOPE_AGENT to split, and
+go back to select. Aggressively offload reading/analysis to subagents (architect, AC-verifier)
+within an iteration to conserve the parent's context.
+
+## 2. Triage / route (if not already routed)
+Run §7.3 to set the row's **Route** (`code`/`research`/`docs`/`stub-defer`) and its **initial
+Status** (Route and Status are distinct — §6.1): `stub-defer` → Status `deferred` (terminal);
+an unmet dependency → Status `blocked` (parked; record the dep, or `too-large`, in Notes — the
+Route is retained so the row resumes as that route when the dependency clears, §1); otherwise →
+Status `routed`. If the Status is `deferred` or `blocked`, journal why and go back to §1 — do
+not implement.
+
+## 3. Plan
+Set the row status to `planning`. Fetch the issue (`gh issue view <N>`). Write
+`issue-<N>.plan.md` (template in spec §6.3), copying acceptance criteria verbatim. Lighter for
+research/docs.
+
+**Value framing (opens the plan, route-scaled).** State *why this should exist* in
+user terms — the question the architect/AC-verifier/code-review gates never ask (they check we
+build the thing right, not that it's the right thing). You write it inline; it is not extra
+ceremony. Scale it to the route:
+- **`feat:`** — a compact user-story map: one backbone activity + 1–3 `as a <user>, I want
+  <capability>, so that <outcome>` stories. Each carries **who benefits**, its **prevalence**
+  (how often real configs/corpora actually hit it), and a **falsifier** — *what single
+  observation would show this feature is misdirected?* (e.g. "~0 matching instances in any real
+  corpus"). A story with no credible user, or no checkable falsifier, is a red flag.
+- **`fix:`** — one line: who hits the bug, how often, what breaks without the fix.
+- **`docs:`** — who reads it and what it unblocks.
+- **`research:`** — the question, the downstream decision it informs, and what a **null result**
+  would mean (a null that changes nothing is a sign the question isn't worth asking).
+- **`chore:` / `refactor:`** — one line: what internal tooling or quality this serves and why
+  now; no user-facing story required (state "internal tooling, no PyPI-visible change" if so).
+
+**Discharge cheap falsifiers at plan time — don't just state them.** If a story's falsifier is
+checkable *before* code (a grep / corpus / prevalence pass), RUN it now, or escalate; a
+stated-but-unrun falsifier is not sufficient. This is the load-bearing step: the cheap corpus
+pass is exactly what caught #437 — but only post-hoc. Defer discharge only when the check
+genuinely requires the built feature.
+
+**Source-fidelity check (any externally-cited justification).** If the issue's rationale leans on
+an external source — a research-scout (`anthropic-feature-watch`) candidate, a linked article, a
+postmortem — confirm the source actually supports the generalization the issue makes: **locus**
+(does the incident occur on the surface this feature inspects?), **evidence base** (n, scope,
+whether the source itself generalizes), and **current relevance** (already fixed upstream?
+version-specific?). An issue that extrapolates past what its source establishes is misdirected
+regardless of implementation quality. (The #437 lesson — decision D046.)
+
+**When you can't articulate it, escalate — don't build.** If you cannot state a credible user
+*and* a checkable falsifier, route the issue to SCOPE_AGENT (pm) BEFORE implementing; do not
+proceed on a plan whose value story doesn't hold.
+
+## 4. Architect gate (conditional)
+If any §7.2 trigger fires OR you are unsure about the design, invoke the DESIGN_AGENT with
+the plan; address `blocking`/`important` concerns before coding. Skip for docs and trivial
+research.
+
+## 5. Human gate (conditional — every mode)
+The plan gate is **conditional in every mode** — `mode:` gates the merge gate only (§11), never
+this one. It is **value-first**: present the §3 value framing (user-story map / value statement)
+alongside the approach, and treat a **non-credible value story — no plausible user, or no
+checkable falsifier — as itself a reason to STOP**, not just ambiguous ACs. Present the plan and
+STOP for approval when: the value story doesn't hold; acceptance criteria are ambiguous; the
+change is risky/irreversible; SCOPE/DESIGN agents disagree or punt; or you are otherwise unsure.
+Otherwise proceed (note "auto-approved" + why in the journal). Route scope/value questions to
+SCOPE_AGENT and design questions to DESIGN_AGENT BEFORE escalating to the human. On approval
+(human or auto), advance the row to `plan-approved`.
+
+## 6. Implement (you, the parent thread)
+Advance the row to `implementing`. Create the branch (`BRANCH_FMT`). Implement code + tests +
+docs per the plan. TDD where it fits (write failing tests, commit, do not modify tests later).
+Run `LINT_CMD`, `TYPE_CMD`, `TEST_CMD` until green. Do NOT stage unrelated pre-existing
+working-tree changes.
+
+## 7. Verify done (independent, fresh context)
+Run the AC-verifier (spec §7.4): a fresh check that the diff satisfies EVERY acceptance
+criterion — verify state, not your claim. If gaps, fix and re-verify (max 2 rounds, else
+escalate).
+
+## 8. Commit + PR
+Commit with correct `COMMIT_CONV` scope. Open the PR; **replicate `PR_TEMPLATE` fully** in
+the body; make the Security-review choice up front. Advance the row to `in-pr` and record the
+PR number. Wait for CI; fix until green.
+
+## 9. Code review
+Advance the row to `in-review`. Run CODE_REVIEW on the diff. Implement viable findings;
+decline others with a one-line rationale; **verify recs were applied**. Bounded to 2 rounds —
+contested findings escalate to the human, do not loop. Commit fixes.
+
+## 10. Security review (by route)
+- `.claude/`-only change → run local `/security-review` (the labeled workflow excludes
+  `.claude/`; the local skill needs `git remote set-head origin -a` if it errors on
+  `origin/HEAD...`).
+- Otherwise, if a sensitive surface is touched → apply `needs-security-review` ONLY now
+  (dev-complete). Skip for docs/no-surface changes.
+Address findings ≥ the project's confidence bar.
+
+## 11. Merge
+Read the run `mode` and `graduated-routes` from the `queue.md` header. The merge gate is the
+**only** gate `mode` changes (§5 is conditional in every mode). A row is **auto-merge-eligible**
+only when ALL of these hold:
+- `mode: escalation-only`, AND
+- the row's Route is listed in the header's `graduated-routes` field, AND
+- the version bump is ≤ patch — a `docs`/`chore` change produces no bump, which qualifies, AND
+- the row is **not** `hold`, AND
+- none of the always-escalate conditions apply: a `feat:`/breaking change, a risky/irreversible
+  change, a touched security surface, or a contested review finding.
+
+**Default-deny:** if route graduation or any always-escalate condition is uncertain, the row is
+**not** auto-merge-eligible — fall back to the human merge gate.
+
+If the row is **not** auto-merge-eligible — which includes *every* row under `mode: calibration`
+(the default) and any `hold` row — STOP and ask the human before merging; never auto-merge.
+**If the human holds the merge (now or in any later invocation),
+WRITE the hold to the row before stopping** — set Status `hold` (record the reason in Notes) so
+it persists across `/clear`; resume (step 0.3), §1, and this gate all key on Status `hold` and
+honor it until the human clears it (restoring the row's prior status). When the row **is**
+auto-merge-eligible (or the human has approved), and CI + security are green AND the row is not
+`hold`:
+squash-merge with an explicit `--subject` carrying the correct `COMMIT_CONV` scope,
+`--delete-branch`. Confirm the issue closed.
+
+## 12. Journal + stop
+Append the iteration block to `progress.md`, including a `- Budget:` line (spec §6.2):
+`subagent-runs=<n>` · `gate-rounds=architect=<a>,code-review=<c>,ac-verify=<v>` ·
+`wall-clock=<elapsed, includes gate-wait — not a cap input>` · `tokens=deferred` (computed
+post-hoc by AgentFluent over the loop JSONL; the named slot keeps the line forward-stable).
+Set the `queue.md` row to `done` (or `blocked`/`deferred` with reason); note newly-unblocked
+issues. The ledger is gitignored — do NOT commit it (spec §6.4). STOP. (Driver re-invokes with
+fresh context for the next issue.)
+
+## Escalation rubric (when unsure)
+Scope/priority/requirements — including any plan whose value story lacks a credible user or a
+checkable falsifier (§3) — → SCOPE_AGENT (pm), before implementing. Design/implementation →
+DESIGN_AGENT. Escalate to the HUMAN only when those disagree/punt, ACs are unresolvable, an
+action is destructive/irreversible, a review finding is contested, or the same step failed twice.
+
+## Guardrails
+One PR at a time (no stacked PRs). **Stuck = the same error SIGNATURE recurs** — grep the FULL
+`progress.md` (not just the tail) for the signature: an identical CI failure, or the same
+tool+args failing again — NOT merely re-entering a status (a legitimate `/clear`-resume
+re-enters `implementing` and must not be flagged). On a genuine repeat: stop, escalate, mark
+`blocked`, move on. Respect any iteration/budget cap (`iteration-cap:`/`subagent-cap:` in the
+`queue.md` header): checked at iteration start (§1) against the ledger — **advisory in manual
+re-invoke (journaled + surfaced, not gating), halted by the driver**.
+
+## Tool surface — and what you must NOT do
+This skill intentionally runs with the full session toolset (no `allowed-tools` restriction):
+an orchestrator needs Write/Edit, Bash(git+gh+tests), Agent (pm/architect/AC-verifier), and
+the built-in review skills. With that power come hard limits — never force-push; never bypass
+failing CI (no `gh pr merge --admin`, never merge red); only `--delete-branch` the PR's own
+branch; never `git add` unrelated pre-existing working-tree changes; never edit the
+user-global SCOPE_AGENT/DESIGN_AGENT definitions. The C1 append-only guard and the
+human/merge gates are the enforced backstops; the rest of this list is your contract.