agentfluent 0.9.0__tar.gz → 0.11.0__tar.gz

agentfluent-0.11.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.11.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.11.0/.claude/loop.config.md

@@ -0,0 +1,119 @@
+# Loop config — AgentFluent
+
+Per-project bindings for the supervised dev loop. `loop-engine.md` (the generic engine)
+references every value below **by parameter name**; this file is the only surface a porting
+project edits. A non-Python / non-`src/` / non-GitHub project revises **all four sections
+below** (parameters, architect triggers, source layout, security routing) — never the engine.
+
+See `.claude/skills/release-loop/loop-engine.md` for the operating procedure and semantics.
+
+---
+
+## 1. Project parameters
+
+The binding table. The engine names each parameter in `CAPS`; the values here are AgentFluent's.
+
+| Parameter | AgentFluent value | Notes |
+|-----------|-------------------|-------|
+| `BACKLOG_SOURCE` | GitHub milestone (e.g. `v0.11.0`) via `gh` | could be a label (an epic is the label case — `gh issue list --label epic:<name>`), or a local `TODO.md` |
+| `SCOPE_AGENT` | `pm` (user-global subagent) | answers scope/priority/requirements questions; remove if project has none |
+| `DESIGN_AGENT` | `architect` (user-global subagent) | reviews plans pre-implementation; remove if none |
+| `CODE_REVIEW` | `/code-review` (Claude Code **built-in skill**) | independent post-impl review; verified 2026-06-29. The repo's `/review`/`/simplify` (CLAUDE.md) are alternatives, not this. |
+| `SECURITY_REVIEW` | local `/security-review` (built-in skill) for `.claude/`-only; else `needs-security-review` label → `security-review.yml` | see §4 below |
+| `VERIFY` | `/verify` (built-in skill) | runtime behavior check when an AC needs proof-by-running |
+| `PRIORITY_LABELS` | `priority:high > priority:medium > priority:low`; tiebreak: issue number ascending | drives selection (engine → Select / Initialization) |
+| `ARCHITECT_TRIGGERS` | see §2 below | **project-specific — edit when porting** |
+| `SOURCE_LAYOUT` | see §3 below | router uses this; **edit when porting** |
+| `TEST_CMD` | `uv run pytest -m "not integration"` | |
+| `LINT_CMD` | `uv run ruff check src/ tests/` | |
+| `TYPE_CMD` | `uv run mypy src/agentfluent/` | |
+| `CI_STATUS_CMD` | `gh pr checks <PR>` | |
+| `BRANCH_FMT` | `feature/<n>-slug` / `fix/<n>-slug` | from CLAUDE.md |
+| `COMMIT_CONV` | Conventional Commits; `.claude/**`→`chore:`/`docs:` | see commit-scope rule below |
+| `PR_TEMPLATE` | `.github/PULL_REQUEST_TEMPLATE.md` (must replicate) | |
+| `MERGE_METHOD` | squash, `--delete-branch`, explicit `--subject` scope | |
+| `APPEND_ONLY_FILES` | `.claude/specs/decisions.md` | guarded by the C1 hook |
+| `PERMISSION_POSTURE` | background agents validate-only → parent implements | see hard constraints below |
+| `LEDGER_ROOT` | `.claude/loop/` | **gitignored** — local working state, never committed |
+| `RELEASE_SCHEME` | SemVer via release-please; PyPI artifact | the engine's merge gate reads "≤ patch bump or no bump"; a project with **no** release cycle (e.g. an epic-sourced run) treats every change as "no release-artifact bump" |
+
+**Workflow conventions (from CLAUDE.md).** Branch from `main`; PR with passing CI before
+merge (naming `BRANCH_FMT`). PR body **must replicate** `PR_TEMPLATE` (CI's `PR Template Check`
+rejects otherwise). Tests required for code changes; no regressions; mypy strict on `src/`.
+
+**Commit-scope rule.** `.claude/**` changes are maintainer-only tooling → `chore:`/`docs:`,
+never `feat:`/`fix:` (avoids release-please mis-bumps). The orchestrator sets the squash
+**`--subject` scope explicitly**, not inheriting the PR title.
+
+**Hard constraints that shape the loop here (project-specific unless noted):**
+1. Background/non-interactive agents are **validate-only** — `settings.local.json` withholds
+   Edit/Write/git/gh from agents that can't prompt. The parent (interactive) thread does all
+   implementation + git/gh; no fan-out of implementation. *(A project without this restriction
+   could parallelize iterations via worktrees — see engine roadmap.)*
+2. *(General, Claude Code)* Subagents can't invoke subagents — the orchestrator drives
+   `SCOPE_AGENT`/`DESIGN_AGENT` directly.
+3. CI is gated on `branches:[main]`; stacked PRs break it → one PR at a time, each from `main`.
+4. `SCOPE_AGENT`/`DESIGN_AGENT` are user-global, not repo-tracked; editing them yields no PR
+   and needs a session restart.
+
+---
+
+## 2. `ARCHITECT_TRIGGERS`
+
+Fire `DESIGN_AGENT` when the plan: touches shared models (`SessionMessage`, `AgentInvocation`);
+changes a cross-module interface; adds a new diagnostics rule, correlation logic, or analytics
+pipeline; **or the orchestrator is unsure.** Bias toward calling it (read-only, cheap vs. a bad
+implementation). Skip for docs and trivial research.
+
+---
+
+## 3. `SOURCE_LAYOUT` — router signals
+
+The project-specific inputs to the engine's Route classification (engine → Router):
+
+- **Package layout:** code in `src/agentfluent/`; tests in `tests/`; research/throwaway
+  scaffolding lives **outside** `src/` with **no runtime-dep leakage** into the package.
+- **`docs` label / path:** GitHub label `documentation`, change confined to `docs/`/markdown.
+- **`research` label / path:** GitHub label `research` or an epic named `*-discovery`; "artifact
+  under study is data"; no test-coverage gate.
+- **`stub-defer` marker:** issue body says "NOT implementation-ready" / is a tracking stub
+  (e.g. #469, D041 — carried, not implemented).
+- **`code` (default):** `bug`/`enhancement` touching `src/` → full pipeline.
+
+---
+
+## 4. Security routing (host-repo / GitHub specifics)
+
+The engine's step-10 security gate reads its *specifics* from here (engine keeps the gate's
+position + confidence-bar discipline):
+
+- **`.claude/`-only change** → run local `SECURITY_REVIEW` (`/security-review`). The labeled
+  workflow (`security-review.yml`) **excludes** `.claude/`, so the label does nothing here; the
+  local skill needs `git remote set-head origin -a` if it errors on `origin/HEAD...`.
+- **Otherwise, sensitive surface touched** → apply the `needs-security-review` label **only when
+  dev-complete** (the workflow triggers on `[labeled]`, not on push — labeling early leaves later
+  commits unreviewed). Skip for docs/no-surface changes.
+
+**Mechanical rules (both learned in the #500 pilot):** `.claude/`-only → local review, not the
+label (workflow excludes `.claude/`; local skill needs `origin/HEAD` set); squash `--subject`
+scope set explicitly (`chore:` for `.claude/**`), not inherited from the PR title.
+
+---
+
+## 5. Project examples referenced by the engine's guidance
+
+The engine states its principles generically; these are the AgentFluent instances it draws on,
+kept here so the engine stays project-agnostic:
+
+- **Post-hoc token/cost analyzer** (engine journal step, `tokens=deferred`): AgentFluent itself,
+  run over the loop's own JSONL corpus.
+- **Externally-cited-source fidelity check** (engine Plan step): a research-scout candidate feed
+  (`anthropic-feature-watch`) is one such source. The #437 / decision **D046** episode is the
+  worked example — a feature extrapolated past what its source established.
+- **Cheap-falsifier-caught-late** (engine Plan step): the #437 corpus pass caught a misdirected
+  feature, but only post-hoc.
+- **Notes-as-decision, not-evidence** (engine Triage step + ledger discipline): the v0.10.0
+  row-12 resume-instability failure is the worked example of mutable live evidence in Notes
+  destabilizing resume.
+- **First route graduation** (engine merge gate, `graduated-routes`): decision **D047** graduated
+  `docs`+`research`.

agentfluent-0.11.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.9.0 → agentfluent-0.11.0}/.claude/settings.json

@@ -9,6 +9,15 @@
             "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\""
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -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.11.0/.claude/skills/release-loop/SKILL.md

@@ -0,0 +1,44 @@
+---
+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.
+
+The operating procedure and all semantics live in two sibling files. Sibling files are read on
+demand, not auto-injected, so **your literal first step is to read both** — do not act on the
+invariants below without them:
+
+1. **`${CLAUDE_PROJECT_DIR}/.claude/loop.config.md`** — the per-project bindings (what
+   `BACKLOG_SOURCE`, `SCOPE_AGENT`, `DESIGN_AGENT`, `CODE_REVIEW`, `PRIORITY_LABELS`, `LINT_CMD`/
+   `TYPE_CMD`/`TEST_CMD`, `BRANCH_FMT`, `COMMIT_CONV`, `MERGE_METHOD`, … resolve to for this repo).
+2. **`.claude/skills/release-loop/loop-engine.md`** — the generic engine: the numbered pipeline
+   (step 0 load/resume → 1 select → 2 route → 3 plan → 4 architect → 5 human gate → 6 implement →
+   7 AC-verify → 8 commit/PR → 9 code-review → 10 security → 11 merge → 12 journal), plus the
+   ledger format, router, AC-verifier, initialization, resume, routing table, and
+   gate/convergence/park-hold/budget semantics.
+
+Read config for **bindings**, engine for **logic**. Execute the engine's pipeline exactly, for
+exactly one issue, then STOP.
+
+## Fail-safe invariants (hold even before the engine loads)
+
+These are restated here so a partial load **over-escalates** (safe) rather than under-gates. The
+engine is authoritative; on any conflict, follow the engine — but never do less than this:
+
+- **One issue per invocation, then STOP and journal.** Never batch. The driver re-invokes with
+  fresh context for the next issue.
+- **Resume before selecting.** If a ledger row is mid-pipeline (interrupted), finish it against
+  live git/PR state before starting anything new. One PR at a time; no stacked PRs.
+- **Never auto-merge under uncertainty.** Default-deny: if you are unsure whether a row is
+  auto-merge-eligible, STOP and ask the human. Never merge red CI, never force-push, never
+  admin-merge, only `--delete-branch` the PR's own branch.
+- **Escalate rather than guess.** Scope/value → `SCOPE_AGENT`; design → `DESIGN_AGENT`; unresolved,
+  contested, or irreversible → the human.
+- **Never edit the user-global `SCOPE_AGENT`/`DESIGN_AGENT` definitions**, and never `git add`
+  unrelated pre-existing working-tree changes.
+- **The ledger is gitignored** — do NOT commit it.