@event4u/agent-config 1.17.0 → 1.19.0

package/docs/guidelines/agent-infra/verify-before-complete-demos.md

@@ -0,0 +1,128 @@
+---
+demo_for: verify-before-complete
+layer: pattern-memory
+prose_delta:
+  rule_chars_before: 2196
+  rule_chars_after: 2603
+  measured_at: phase-3.3-cross-link-landing
+  note: "+407 chars from the Examples cross-link block; future prose-pruning rounds (out of scope for Phase 3) will pull pattern prose from the rule into this demo and drive the after-count below the before-count."
+---
+
+# verify-before-complete — Pattern Memory
+
+> Wrong / right / why demos for the `verify-before-complete` Iron
+> Law (no completion claim without fresh evidence in this message).
+> Linked from
+> [`verify-before-complete`](../../.agent-src.uncompressed/rules/verify-before-complete.md)
+> § Examples. Outcome baseline at
+> [`tests/golden/outcomes/verify_before_complete.json`](../../tests/golden/outcomes/verify_before_complete.json).
+
+## Demo 1 — Hedged completion claim
+
+### Wrong shape
+
+```
+User: ist der Fix fertig?
+
+Agent: Ja, sollte jetzt durchlaufen — ich habe die fehlende
+Bedingung ergänzt und die Tests müssten grün sein.
+```
+
+**Failure mode:** "sollte", "müssten" are red-flag hedges (§ Red
+flags — STOP immediately). No fresh command output in this message.
+The claim rides on inference, not evidence.
+
+### Right shape
+
+```
+User: ist der Fix fertig?
+
+Agent: Frisch gerade ausgeführt:
+
+$ python3 -m pytest tests/test_load_context.py -v
+============================== 7 passed in 0.07s ===============================
+
+Exit code 0, 7/7 grün. Damit ist der Fix verifiziert.
+```
+
+### Why it works
+
+Literal command line, fresh output, exit code, pass count — all in
+this message. The user can scroll up and see the same shape that
+the test runner produced. No hedging vocabulary.
+
+## Demo 2 — Trusting an earlier run
+
+### Wrong shape
+
+```
+[12 messages earlier, agent ran tests — green]
+
+User: also fertig zum committen?
+
+Agent: Ja, die Tests waren ja grün vorhin. Du kannst committen.
+```
+
+**Failure mode:** "Trusting a previous run from earlier in the
+conversation" — explicit red flag. Code drifted in the meantime;
+the earlier run is stale evidence.
+
+### Right shape
+
+```
+User: also fertig zum committen?
+
+Agent: Ich verifiziere kurz — Tests laufen jetzt:
+
+$ python3 -m pytest tests/ -q
+... 47 passed in 2.31s
+
+Grün. Plus ein quality-tools-Lauf:
+
+$ task ci
+... ✅  All checks passed
+
+Jetzt ist der Stand sauber.
+```
+
+### Why it works
+
+Re-runs both gates *now*. The `quality-tools` skill handles the
+specific commands; the rule only mandates "fresh in this message".
+"Stand sauber" is anchored on actual exit codes, not on memory.
+
+## Demo 3 — Partial verification claimed as complete
+
+### Wrong shape
+
+```
+User: ready für den PR?
+
+Agent: Tests sind grün, ich öffne den PR.
+```
+
+**Failure mode:** "Relying on partial verification (ran tests but
+not PHPStan)" — explicit red flag. PR-readiness needs the full
+gate, not a single channel.
+
+### Right shape
+
+```
+User: ready für den PR?
+
+Agent: Ich check beide Gates:
+
+$ vendor/bin/pest
+... 47 passed
+$ vendor/bin/phpstan analyse
+... [OK] No errors
+
+Beide grün. Soll ich den PR jetzt erstellen?
+```
+
+### Why it works
+
+Both gates run fresh, both outputs in the message, exit summaries
+visible. The follow-up question is permission-gated per
+`scope-control` § Git operations — the verification is done
+independently of the user's go-ahead.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.17.0",
+    "version": "1.19.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/agent-config

@@ -72,9 +72,24 @@ Commands:
                              (CHECKPOINT fallback for platforms without native hooks)
   roadmap-progress:hook      PostToolUse hook entry point (read JSON from stdin)
                              Regenerates roadmaps-progress.md when a tool wrote under agents/roadmaps/
+  onboarding-gate:hook       Hook entry point (drains stdin)
+                             Writes .augment/state/onboarding-gate.json from .agent-settings.yml
+  context-hygiene:hook       PostToolUse hook entry point (read JSON from stdin)
+                             Maintains .augment/state/context-hygiene.json (turn count, loop, freshness)
+  dispatch:hook              Universal hook dispatcher (Phase 7, hook-architecture-v1.md)
+                             Usage: dispatch:hook --platform <name> --event <event> [--native-event <native>]
+                             Reads scripts/hook_manifest.yaml and runs the resolved concern chain.
+  hooks:status               Print the runtime hook matrix (per-platform install + bindings)
+                             Flags: --format json|table, --strict (CI), --project-root <path>
   telemetry:record           Append one artefact-engagement event (default-off)
   telemetry:status           Print artefact-engagement telemetry status (read-only)
   telemetry:report           Aggregate the engagement log into a quartile report
+  council:estimate           Pre-call council cost preview (no API call, no spend)
+                             Usage: council:estimate <question> [--input-mode prompt|roadmap]
+  council:run                Run the council. Requires --confirm to spend.
+                             Usage: council:run <question> --output <path> --confirm
+  council:render             Re-render a saved council responses JSON to markdown
+                             Usage: council:render <responses.json>
   help                       Show this help
   --version, -V              Print package version
 
@@ -98,6 +113,9 @@ Examples:
   ./agent-config telemetry:status --format json
   ./agent-config telemetry:report --since 30d --top 20
   ./agent-config telemetry:report --since 7d --format json --top 0
+  ./agent-config council:estimate prompt.txt
+  ./agent-config council:run prompt.txt --output agents/council-sessions/out.json --confirm
+  ./agent-config council:render agents/council-sessions/out.json
 
 All commands operate on the CURRENT DIRECTORY (your project root).
 The CLI is strictly consumer-facing. Maintainer tasks live in Taskfile.yml.
@@ -325,6 +343,34 @@ cmd_roadmap_progress_hook() {
   exec python3 "$script" "$@"
 }
 
+cmd_onboarding_gate_hook() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/onboarding_gate_hook.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
+cmd_context_hygiene_hook() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/context_hygiene_hook.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
+cmd_dispatch_hook() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/hooks/dispatch_hook.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
+cmd_hooks_status() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/hooks_status.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
 cmd_chat_history_checkpoint() {
   require_python3
   local script
@@ -420,6 +466,17 @@ cmd_keys_install_openai() {
   exec bash "$script" "$@"
 }
 
+# Council CLI — non-interactive wrapper around scripts.ai_council.orchestrator.
+# Three subcommands share one Python entry point; we forward the subcommand
+# verb so `./agent-config council:run --confirm` lands on `council_cli.py run`.
+cmd_council() {
+  require_python3
+  local sub="$1"; shift || true
+  local script
+  script="$(resolve_script "scripts/council_cli.py")" || return 1
+  exec env PYTHONPATH="$PACKAGE_ROOT" python3 "$script" "$sub" "$@"
+}
+
 main() {
   local cmd="${1-}"
   [[ $# -gt 0 ]] && shift || true
@@ -446,9 +503,16 @@ main() {
     chat-history:hook)       cmd_chat_history_hook "$@" ;;
     chat-history:checkpoint) cmd_chat_history_checkpoint "$@" ;;
     roadmap-progress:hook)   cmd_roadmap_progress_hook "$@" ;;
+    onboarding-gate:hook)    cmd_onboarding_gate_hook "$@" ;;
+    context-hygiene:hook)    cmd_context_hygiene_hook "$@" ;;
+    dispatch:hook)           cmd_dispatch_hook "$@" ;;
+    hooks:status)            cmd_hooks_status "$@" ;;
     telemetry:record)        cmd_telemetry_record "$@" ;;
     telemetry:status)        cmd_telemetry_status "$@" ;;
     telemetry:report)        cmd_telemetry_report "$@" ;;
+    council:estimate)        cmd_council estimate "$@" ;;
+    council:run)             cmd_council run "$@" ;;
+    council:render)          cmd_council render "$@" ;;
     help|--help|-h|"")        usage ;;
     --version|-V)            print_version ;;
     *)

package/scripts/ai_council/bundler.py

@@ -38,11 +38,11 @@ class CouncilContext:
 # placeholder. Order matters — the most specific pattern goes first.
 
 _REDACTION_LINE_PATTERNS: list[tuple[re.Pattern[str], str]] = [
-    (re.compile(r".*~?/?\.config/agent-config/[^/\s]+\.key.*"),
+    (re.compile(r"~?/?\.config/agent-config/[^/\s]+\.key"),
      "[redacted: agent-config key path]"),
-    (re.compile(r"^\s*Authorization:\s.*", re.IGNORECASE),
+    (re.compile(r"^\s*Authorization:\s", re.IGNORECASE),
      "[redacted: Authorization header]"),
-    (re.compile(r"(?i).*(api[_-]?key|secret|token|password)\s*[:=].*"),
+    (re.compile(r"(?i)(api[_-]?key|secret|token|password)\s*[:=]"),
      "[redacted: secret-like assignment]"),
     (re.compile(r"sk-ant-[A-Za-z0-9_\-]{8,}"), "[redacted: anthropic-key-like token]"),
     (re.compile(r"sk-[A-Za-z0-9_\-]{20,}"), "[redacted: openai-key-like token]"),

package/scripts/ai_council/clients.py

@@ -34,6 +34,16 @@ OPENAI_KEY_PATH = Path.home() / ".config" / "agent-config" / "openai.key"
 DEFAULT_ANTHROPIC_MODEL = "claude-sonnet-4-5"
 DEFAULT_OPENAI_MODEL = "gpt-4o"
 
+# OpenAI reasoning models (o1, o3, o4 families) reject `max_tokens` and the
+# `system` role; they require `max_completion_tokens` and accept only `user`
+# (and `developer`) messages.
+_REASONING_PREFIXES = ("o1", "o3", "o4")
+
+
+def _is_reasoning_model(model: str) -> bool:
+    name = model.lower()
+    return any(name == p or name.startswith(p + "-") for p in _REASONING_PREFIXES)
+
 
 class KeyGateError(RuntimeError):
     """Raised when a provider key file violates the 0600 contract."""
@@ -189,15 +199,21 @@ class OpenAIClient(ExternalAIClient):
 
     def ask(self, system_prompt: str, user_prompt: str, max_tokens: int = 1024) -> CouncilResponse:
         t0 = time.monotonic()
+        kwargs: dict[str, object] = {"model": self.model}
+        if _is_reasoning_model(self.model):
+            # o1/o3/o4 reasoning models reject `max_tokens` and `system` role.
+            kwargs["max_completion_tokens"] = max_tokens
+            kwargs["messages"] = [
+                {"role": "user", "content": f"{system_prompt}\n\n---\n\n{user_prompt}"},
+            ]
+        else:
+            kwargs["max_tokens"] = max_tokens
+            kwargs["messages"] = [
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ]
         try:
-            response = self._client.chat.completions.create(
-                model=self.model,
-                max_tokens=max_tokens,
-                messages=[
-                    {"role": "system", "content": system_prompt},
-                    {"role": "user", "content": user_prompt},
-                ],
-            )
+            response = self._client.chat.completions.create(**kwargs)
         except Exception as exc:  # noqa: BLE001 - normalise all SDK errors
             return CouncilResponse(
                 provider=self.name, model=self.model, text="",

package/scripts/ai_council/one_off_archive/2026-05/README.md

@@ -0,0 +1,67 @@
+# One-off archive — 2026-05
+
+> Archived per **Phase 0a.2** of `agents/roadmaps/road-to-rule-hardening.md`.
+> Each script here was a single-purpose AI-council probe or measurement
+> tied to a specific phase of `road-to-structural-optimization.md` (now
+> archived) or `road-to-rule-hardening.md`. The session output lives
+> under `agents/council-sessions/` (durable evidence) and the linter
+> `scripts/check_one_off_location.py` enforces that no new
+> `_one_off_*.py` lands outside this folder.
+
+## Going forward — use the CLI, not new one-offs
+
+> **Canonical pattern (Phase 6.7+):** new council runs go through
+> `./agent-config council:{estimate,run,render}`. The CLI handles
+> bundling, redaction, the cost gate, the `0600` key contract, the
+> `enabled` check, and session persistence — every concern these
+> archived one-offs reimplemented inline.
+>
+> ```bash
+> ./agent-config council:estimate <question.md>
+> ./agent-config council:run <question.md> \
+>     --output agents/council-sessions/<UTC-ts>.json --confirm
+> ./agent-config council:render agents/council-sessions/<UTC-ts>.json
+> ```
+>
+> Wire-level access (`scripts.ai_council.orchestrator`,
+> `scripts.ai_council.bundler`) is still public for tests and library
+> use, but writing a new `_one_off_*.py` purely to fan out to the
+> council members is **not** the path. The scripts below are kept as
+> historical evidence of the runs that produced specific roadmap
+> decisions; they are not a template for new work.
+
+## Lifecycle rule (uniform — Phase 0.2 of context-layer-maturity)
+
+> A one-off is **archived**, never deleted. The session manifest under
+> `agents/council-sessions/` is the audit trail; the script itself is
+> kept here so a future contributor can re-read intent, re-run a probe
+> on a future branch, or extract a reusable helper.
+
+## Inventory
+
+| Script | Roadmap / Phase | Council session id |
+|---|---|---|
+| `_one_off_2a4_acceptance.py` | structural-optimization 2A.4 | various 2A sessions |
+| `_one_off_context_layer_v1_estimate.py` | context-layer-maturity v1 cost estimate | `2026-05-03T17-56-21Z` |
+| `_one_off_context_layer_v1_review.py` | context-layer-maturity v1 review | `2026-05-03T17-56-21Z` |
+| `_one_off_followups_review.py` | road-to-1-16-followups review | session under `agents/council-sessions/` |
+| `_one_off_nondestructive_inline_audit.py` | non-destructive-by-default audit | session under `agents/council-sessions/` |
+| `_one_off_phase4_dispatch_latency.py` | structural-optimization 4.3.1 cluster latency benchmark | local benchmark, no council |
+| `_one_off_phase6_trigger_jaccard.py` | structural-optimization Phase 6 trigger overlap | local measurement |
+| `_one_off_phase_2a_budget_rebalance.py` | structural-optimization 2A budget rebalance | `2026-05-03T*` |
+| `_one_off_phase_2a_post_revert.py` | structural-optimization 2A post-revert | `2026-05-03T*` |
+| `_one_off_rebalancing_audit.py` | rebalancing roadmap audit | session under `agents/council-sessions/` |
+| `_one_off_roundtrip.py` | council client roundtrip smoke test | local smoke test |
+| `_one_off_rule_hardening_v1.py` | rule-hardening v1 review | `2026-05-03T19-16-25Z` |
+| `_one_off_structural_open_questions.py` | structural-optimization open questions | session under `agents/council-sessions/` |
+| `_one_off_structural_optimization.py` | structural-optimization initial review | session under `agents/council-sessions/` |
+| `_one_off_structural_v3_gaps.py` | structural-optimization v3 gap audit | session under `agents/council-sessions/` |
+| `_one_off_structural_v3_review.py` | structural-optimization v3 review | session under `agents/council-sessions/` |
+
+## Re-running an archived script
+
+Imports may have shifted (e.g. `scripts.ai_council.*`). If a probe
+needs to be re-run against a current branch, copy it back to its
+original location, fix imports, run, then move the working copy
+back here. Do **not** edit in place — keep the archive immutable
+beyond cosmetic README updates.

package/scripts/ai_council/one_off_archive/2026-05/_one_off_budget_v2_audit.py

@@ -0,0 +1,206 @@
+"""Council audit of Budget-v2 result (Phase 4.5 of road-to-context-layer-maturity).
+
+Phase 4 of road-to-context-layer-maturity selected two 4d-trim paths
+(`direct-answers`, `no-cheap-questions`) from a fixed option set
+documented in agents/contexts/budget-v2-matrix.md and shipped them.
+Exit-gate actuals (run 2026-05-04): total 44,928 / 49,000 chars
+(91.7 %, 4,072 chars headroom) — ≥ 4,000 headroom goal hit. Top-3
+sum unchanged. Safety-floor rules untouched.
+
+Phase 4.5 requires a council audit before archival: confirm the
+trim choices were sound, no semantic drift introduced, no better
+path missed inside the Phase 4 inputs gate.
+
+Invocation:
+    .venv/bin/python -m scripts.ai_council.one_off_archive.2026-05._one_off_budget_v2_audit
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from scripts.ai_council.bundler import bundle_files
+from scripts.ai_council.clients import (
+    AnthropicClient,
+    OpenAIClient,
+    load_anthropic_key,
+    load_openai_key,
+)
+from scripts.ai_council.orchestrator import (
+    CostBudget,
+    CouncilQuestion,
+    consult,
+    estimate,
+)
+from scripts.ai_council.pricing import estimate_cost, load_prices
+from scripts.ai_council.project_context import detect_project_context
+from scripts.ai_council.session import SessionManifest, save as save_session
+
+REPO_ROOT = Path(__file__).resolve().parents[4]
+ARTEFACTS = [
+    REPO_ROOT / "docs/contracts/load-context-budget-model.md",
+    REPO_ROOT / "agents/contexts/budget-v2-matrix.md",
+    REPO_ROOT / ".agent-src.uncompressed/rules/direct-answers.md",
+    REPO_ROOT / ".agent-src.uncompressed/rules/no-cheap-questions.md",
+]
+
+ORIGINAL_ASK = (
+    "Phase 4 of road-to-context-layer-maturity trimmed two always-rules "
+    "(direct-answers, no-cheap-questions) under the locked Model (b) "
+    "literal budget contract, hitting the ≥ 4,000-chars headroom goal "
+    "(actual: 4,072). Council task: audit the trim choices for "
+    "soundness and semantic drift before roadmap archival."
+)
+
+REVIEW_PROMPT = """\
+# Council Audit — Budget-v2 Trim Result (Phase 4.5)
+
+## Context
+
+Phase 4 selected two 4d-trim paths from a fixed option set documented
+in `budget-v2-matrix.md`. The matrix evaluated 4a (demote→auto), 4b
+(merge), 4c (shared-context, locked at 3a Model (b) literal — no-op),
+and 4d (compress prose) for every touchable always-rule. Safety-floor
+rules (scope-control, non-destructive-by-default, commit-policy,
+agent-authority) were untouchable. Outcome-untested rules were
+restricted to 4d only per the Phase 4.0 inputs gate.
+
+## Selected paths and result
+
+- **4d on `direct-answers`** — emoji-scope subsection trimmed,
+  failure-mode collapsed to pointer. Δ ext: 4,098 → 3,987 (−111).
+- **4d on `no-cheap-questions`** — "What counts as cheap" subsection
+  collapsed to pointer at `asking-and-brevity-examples.md`. Δ ext:
+  4,257 → 3,933 (−324).
+
+Combined: −435 chars · headroom 3,637 → 4,072 (+435) · top-3 sum
+unchanged · safety-floor rules untouched.
+
+## Audit questions (please address each)
+
+1. **Trim soundness** — do the surviving Iron Laws in both rules still
+   carry the rule's purpose, or did the prose trim sacrifice precision?
+   Cite the specific subsection if you find drift.
+
+2. **Path selection** — was 4d the right choice for these two rules
+   given the matrix? Or should one of the deferred paths (4a, 4b)
+   have been picked despite the matrix verdict?
+
+3. **Missed leverage** — inside the Phase 4 inputs gate (4d only on
+   outcome-untested rules; safety-floor untouchable), is there a
+   higher-leverage 4d target the matrix missed?
+
+4. **Headroom durability** — 4,072 chars is +72 over the 4,000 goal.
+   Is this margin stable against expected near-term rule edits, or
+   should Phase 5 be tightened to defend it?
+
+## Output Contract (STRICT)
+
+```
+### Verdict
+**Trim choices sound:** <YES — archive · NO — escalate>
+**One-sentence rationale:** <≤ 30 words>
+```
+
+```
+### Per-question findings (1–4 above)
+  1. <≤ 2 sentences>
+  2. <≤ 2 sentences>
+  3. <≤ 2 sentences>
+  4. <≤ 2 sentences>
+```
+
+```
+### Risk note
+**Single biggest residual risk:** <one sentence>
+**Mitigation (if any):** <one sentence or NONE>
+```
+
+Be decisive — total response ≤ 800 words. Artefacts follow verbatim.
+"""
+
+
+def main() -> int:
+    anthropic = AnthropicClient(api_key=load_anthropic_key(), model="claude-sonnet-4-5")
+    openai = OpenAIClient(api_key=load_openai_key(), model="gpt-4o")
+    members = [anthropic, openai]
+
+    context = bundle_files(ARTEFACTS)
+    project = detect_project_context(REPO_ROOT)
+    table = load_prices()
+
+    user_prompt = REVIEW_PROMPT + "\n\n---\n\n" + context.text
+
+    question = CouncilQuestion(mode="files", user_prompt=user_prompt, max_tokens=2048)
+
+    estimates = estimate(question, members, table, project=project, original_ask=ORIGINAL_ASK)
+    print("=== ESTIMATE (single round) ===")
+    total_est = 0.0
+    for c, e in zip(members, estimates):
+        print(f"  {c.name}/{c.model}: ~{e.input_tokens} in + {e.output_tokens} out = ${e.total_usd:.4f}")
+        total_est += e.total_usd
+    print(f"  TOTAL per round (max): ${total_est:.4f}\n")
+
+    budget = CostBudget(
+        max_input_tokens=200_000,
+        max_output_tokens=80_000,
+        max_calls=20,
+        max_total_usd=2.50,
+    )
+
+    rounds_collected: list[list] = []
+
+    def _on_round_complete(round_idx: int, round_responses) -> None:
+        rounds_collected.append(list(round_responses))
+        print(f"=== ROUND {round_idx + 1} COMPLETE ===")
+        for r in round_responses:
+            if r.error:
+                print(f"  [error] {r.provider}/{r.model}: {r.error}")
+                continue
+            actual = estimate_cost(r.provider, r.model, r.input_tokens, r.output_tokens, table)
+            print(f"  [done] {r.provider}/{r.model}: {r.input_tokens} in / "
+                  f"{r.output_tokens} out · {r.latency_ms} ms · ${actual.total_usd:.4f}")
+        print()
+
+    print("=== CONSULT (1 round, Phase 4.5 Budget-v2 audit) ===")
+    consult(
+        members, question, budget,
+        rounds=1,
+        on_round_complete=_on_round_complete,
+        table=table, project=project, original_ask=ORIGINAL_ASK,
+    )
+
+    if not rounds_collected:
+        print("[error] no rounds completed", file=sys.stderr)
+        return 1
+
+    actual_total = 0.0
+    for round_responses in rounds_collected:
+        for r in round_responses:
+            if r.error:
+                continue
+            actual = estimate_cost(r.provider, r.model, r.input_tokens, r.output_tokens, table)
+            actual_total += actual.total_usd
+    print(f"=== TOTAL ACTUAL: ${actual_total:.4f} ===")
+
+    final_round = rounds_collected[-1]
+    if not [r for r in final_round if not r.error]:
+        return 1
+
+    manifest = SessionManifest(
+        mode="files",
+        artefact="agents/roadmaps/road-to-context-layer-maturity.md",
+        original_ask=ORIGINAL_ASK,
+        members=[f"{r.provider}/{r.model}" for r in final_round],
+        rounds=len(rounds_collected),
+        cost_usd_estimated=total_est,
+        cost_usd_actual=actual_total,
+        extra={"purpose": "Phase 4.5 Budget-v2 trim-result audit"},
+    )
+    session_dir = save_session(manifest=manifest, responses=rounds_collected)
+    print(f"[saved] {session_dir.relative_to(REPO_ROOT)}/")
+    return 1 if any(r.error for round_r in rounds_collected for r in round_r) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/ai_council/{_one_off_roundtrip.py → one_off_archive/2026-05/_one_off_roundtrip.py}

@@ -1,14 +1,19 @@
-"""One-off Phase-1 round-trip runner.
+"""One-off Phase-1 round-trip runner — HISTORICAL ARCHIVE.
 
-Used exactly once to generate the evidence artefact required to lift
-the capture-only fence on `road-to-ai-council.md` Phase 2+ and the
-end-to-end verification on `road-to-council-modes.md` Phase 2a.
+Going forward, council runs go through the CLI:
 
-Not part of the public CLI surface — `/council` remains the supported
-entry point. This script is committed under `scripts/ai_council/` so
-the evidence is reproducible from the git history alone.
+    ./agent-config council:estimate <question.md>
+    ./agent-config council:run <question.md> \
+        --output agents/council-sessions/<UTC-ts>.json --confirm
+    ./agent-config council:render agents/council-sessions/<UTC-ts>.json
 
-Invocation:
+This script predates `scripts/council_cli.py` (Phase 6.7) and is kept
+only as the evidence artefact that lifted the capture-only fence on
+`road-to-ai-council.md` Phase 2+ and the end-to-end verification on
+`road-to-council-modes.md` Phase 2a. Do **not** copy it as a template
+for new one-offs — write a question file and use the CLI instead.
+
+Invocation (historical):
     .venv/bin/python -m scripts.ai_council._one_off_roundtrip
 """
 from __future__ import annotations