@event4u/agent-config 1.18.0 → 1.19.0

package/docs/contracts/memory-visibility-v1.md

@@ -0,0 +1,138 @@
+---
+stability: beta
+---
+
+# Memory-visibility v1
+
+**Purpose.** Pin the format of the user-facing visibility line that
+every memory-using `/work` and `/implement-ticket` run prints, so the
+user can tell what the agent retrieved and what it ignored.
+Complements [`agent-memory-contract.md`](agent-memory-contract.md):
+that doc describes the **CLI surface and backend states**; this doc
+describes the **operator-facing surface** the engine emits per turn.
+
+**Scope.** Defines the line shape, the privacy floor, the opt-out
+toggle, and the interaction with the chat-history heartbeat. Does
+**not** define how memory entries are scored or routed — that is the
+sibling agent-memory package.
+
+Last refreshed: 2026-05-04.
+
+## Line shape
+
+A single one-line ASCII record, prefixed with the memory icon `🧠`
+and a single space:
+
+```
+🧠 Memory: <hits>/<asks> · ids=[<comma-separated-ids>]
+```
+
+Examples:
+
+```
+🧠 Memory: 3/4 · ids=[mem_42, mem_57, mem_91]
+🧠 Memory: 0/2 · ids=[]
+🧠 Memory: 5/5 · ids=[mem_a01, mem_a02, mem_a03, …+2]
+```
+
+Cap at 5 ids inline; remainder rendered as `…+N`. The full id list
+lives in the decision-trace JSON
+([`decision-trace-v1.md`](decision-trace-v1.md)).
+
+## Field semantics
+
+| Field | Meaning |
+|---|---|
+| `hits` | Count of `memory_retrieve_*` calls during this turn that returned ≥ 1 entry. |
+| `asks` | Count of `memory_retrieve_*` calls during this turn — both successful and empty. |
+| `ids` | Stable memory entry ids returned across all calls, deduped, ordered by retrieval timestamp. |
+
+`hits ≤ asks` is invariant. If `asks == 0`, the engine MUST suppress
+the line entirely — no `0/0` noise.
+
+## Privacy floor
+
+The visibility line and the JSON it derives from MUST NOT contain:
+
+- Entry **bodies**, summaries, or quoted snippets.
+- Secrets, tokens, environment values, or paths outside the
+  package's `agents/state/` and `tests/` allowlist.
+- User identifiers beyond what is already public in the working
+  directory's `.agent-settings.yml` (e.g. developer name).
+
+The privacy floor is enforced by
+`tests/contracts/test_memory_visibility_redaction.py` — any new
+content path that ships memory output adds a fixture there.
+
+## Opt-out
+
+On by default whenever memory is asked at all in a turn. Users can
+suppress the visibility line via:
+
+```yaml
+memory:
+  visibility: off
+```
+
+Off-mode does not silence the underlying memory calls; it only stops
+the line from rendering. The decision-trace JSON still records the
+counts and ids for downstream metrics.
+
+## Interaction with chat-history heartbeat
+
+The chat-history heartbeat (`📒` marker) and the memory-visibility
+line are **independent**:
+
+- Heartbeat fires on cadence boundaries
+  (`per_turn` / `per_phase` / `per_tool`).
+- Visibility line fires whenever `asks ≥ 1` for the current turn,
+  regardless of cadence.
+- Both render on the same reply when both fire — heartbeat first,
+  visibility line second, separated by a single newline.
+
+The visibility line is **not** part of the heartbeat payload — that
+keeps the heartbeat contract bytes-stable.
+
+## Cadence interaction
+
+| Cost profile | Visibility line | Heartbeat |
+|---|---|---|
+| `lean` | suppress unless `asks ≥ 3` | per-phase |
+| `standard` | always when `asks ≥ 1` | per-turn |
+| `verbose` | always when `asks ≥ 1` | per-tool |
+
+Cost-profile lookup respects `.agent-settings.yml`'s `cost_profile`
+key. Default is `standard`.
+
+## Audit-as-memory feed
+
+The visibility output produced by the engine is the input to the
+audit-as-memory pipeline (consumed by the sibling distribution +
+adoption work). Concretely:
+
+- The engine emits the line + the underlying counts to the
+  decision-trace JSON.
+- A consumer hook reads `agents/state/work/<work-id>/decision-trace-*.json`,
+  rolls counts up to the session level, and feeds the result back
+  into the agent-memory store as an audit entry.
+
+This contract pins the **producer** side. The audit-feed consumer
+lives outside the package's stable surface and must read this
+contract before parsing.
+
+## Stability
+
+Beta. Breaking changes between v1 and v2 are allowed in a minor
+release if the change appears in `CHANGELOG.md` under a `### Breaking`
+heading. Engines MUST gate on the visibility line shape — clients
+parsing the stream MUST treat unknown trailing fields as forward-
+compat extensions.
+
+## Cross-references
+
+- CLI surface and backend states:
+  [`agent-memory-contract.md`](agent-memory-contract.md).
+- Decision-trace JSON consumes the same counts:
+  [`decision-trace-v1.md`](decision-trace-v1.md).
+- Privacy regression test path:
+  `tests/contracts/test_memory_visibility_redaction.py`.

package/docs/contracts/one-off-script-lifecycle.md

@@ -0,0 +1,109 @@
+---
+stability: beta
+---
+
+# One-off-script lifecycle
+
+**Purpose.** Pin the naming, location, age, and purge policy for
+**one-off scripts** so the package does not accumulate a graveyard
+under `scripts/`. One-off here means: a script written for a
+specific migration, retrofit, audit, or council run, with no ongoing
+caller and no place in the durable Taskfile.
+
+**Scope.** Defines the file pattern, the directory, the maximum age,
+the TTL extension mechanism, and the CI purge gate. Does **not**
+specify the content of any specific one-off — that belongs to the
+script itself or the cleanup-mechanics context.
+
+Last refreshed: 2026-05-04.
+
+## Naming
+
+One-off scripts MUST match this regex:
+
+```
+^_one_off_[a-z0-9-]+\.py$
+```
+
+The `_one_off_` prefix is the load-bearing signal. Files outside
+this prefix are treated as durable scripts and MUST be referenced by
+the Taskfile or by another script.
+
+## Location
+
+```
+scripts/_one_off/<YYYY-MM>/_one_off_<slug>.py
+```
+
+`<YYYY-MM>` is the UTC month the script was first committed. The
+month directory groups one-offs for archival sweeps. Scripts MUST
+NOT live at `scripts/_one_off/_one_off_*.py` (no month) or under
+`scripts/` directly (no `_one_off/`).
+
+## TTL
+
+| State | Action |
+|---|---|
+| Age ≤ 60 days from month-directory date | active, no warning |
+| 60 < Age ≤ 90 days | warning emitted by `lint_one_off_age.py`, no failure |
+| Age > 90 days | `lint_one_off_age.py` fails CI; the script is purged in the next housekeeping pass |
+
+Age = `today − first-of-month(<YYYY-MM>)` in UTC days. The 60-day
+soft floor and 30-day grace window are intentional — they cover one
+release cycle plus a sprint of grace.
+
+## TTL extension
+
+A one-off MAY extend its TTL exactly once, by adding a frontmatter
+block at the top of the script:
+
+```python
+"""
+---
+ttl_extended_until: 2026-08-31
+ttl_reason: blocked on PROJ-123 — re-runs after cutover
+---
+"""
+```
+
+The linter respects `ttl_extended_until` if it is ≤ 180 days from
+the file's `<YYYY-MM>` directory date. Beyond 180 days, the linter
+hard-fails — no second extension. The intent is: if a "one-off" is
+still live at six months, it is a durable concern and belongs in
+`scripts/` or a Taskfile group.
+
+## Purge mechanism
+
+`lint_one_off_age.py` runs in `task ci`. On a clean working tree, it
+prints purge candidates as a list. Purge itself is a separate human-
+or-CI action — `task purge-one-offs` removes flagged files. The
+linter does not auto-delete.
+
+## Allowed exceptions
+
+Two patterns are exempt from the prefix requirement:
+
+- **Bundler / orchestrator helpers** under `scripts/ai_council/`
+  that exist to support the council CLI — they are not one-offs even
+  though council *runs* are one-offs.
+- **`scripts/_one_off/<YYYY-MM>/README.md`** — a free-form readme is
+  allowed in each month directory documenting why the scripts exist.
+
+Council run scripts that wrap a question and write the response file
+DO live under `scripts/_one_off/<YYYY-MM>/` and DO follow the prefix
+rule.
+
+## Cross-references
+
+- The contract that defines council CLI surface (and so what gets
+  archived as a one-off): the council CLI section of the package's
+  command catalog.
+- The cleanup-mechanics context for housekeeping passes:
+  `agents/contexts/cleanup-mechanics.md`.
+- Linter implementation: `scripts/lint_one_off_age.py`.
+
+## Stability
+
+Beta. Breaking changes (e.g. raising the age cap, changing the
+prefix, or removing TTL extensions) require a minor-version bump and
+a `### Breaking` entry in `CHANGELOG.md`.

package/docs/contracts/rule-interactions.yml

@@ -221,6 +221,28 @@ pairs:
       - .agent-src.uncompressed/rules/ask-when-uncertain.md#iron-law--one-question-per-turn-always
       - .agent-src.uncompressed/rules/direct-answers.md#iron-law-3--brevity-by-default
 
+  - id: scope-x-verify-before-complete
+    rules: [verify-before-complete, scope-control]
+    relation: complements
+    conflict: >-
+      Agent has just finished a change that touches user-permission-gated
+      operations (push, branch, PR, tag) and is preparing to claim "done"
+      in the same turn. Both rules can fire: `verify-before-complete`
+      gates the completion claim on fresh evidence; `scope-control`
+      gates the git operation on explicit permission this turn.
+    resolution: >-
+      Both rules apply independently and compose. The
+      `verify-before-complete` Iron Law still requires fresh
+      verification output in this message before any "done" claim,
+      regardless of whether the user has authorised the next git op.
+      Conversely, verification passing does not authorise pushing or
+      merging — those stay behind the `scope-control` permission gate.
+      Skipping either is a rule violation; satisfying one does not
+      satisfy the other.
+    evidence:
+      - .agent-src.uncompressed/rules/verify-before-complete.md#the-iron-law
+      - .agent-src.uncompressed/rules/scope-control.md#git-operations--permission-gated
+
   - id: language-x-direct-answers
     rules: [language-and-tone, direct-answers]
     relation: complements

package/docs/customization.md

@@ -66,6 +66,7 @@ those sections.
 | `ai_council.cost_budget.max_calls` | `10` | Maximum council members per invocation. |
 | `ai_council.cost_budget.max_total_usd` | `0.0` | Per-invocation USD ceiling. `0` disables (token caps still apply). |
 | `ai_council.cost_budget.daily_limit_usd` | `0.0` | Rolling 24h USD ceiling across all `/council` calls. `0` disables. Ledger lives at `~/.config/agent-config/council-spend.jsonl` (mode 0600). |
+| `ai_council.session_retention_days` | `14` | Auto-prune for `agents/council-sessions/` audit folders. Older session directories are removed on the next `save()`. `0` disables (keep forever). |
 
 > **Experimental.** AI Council is not yet validated by external users. API costs apply per consultation.
 

package/docs/development.md

@@ -17,7 +17,10 @@
 
 ## Task Commands
 
-All commands use [Task](https://taskfile.dev/). See `Taskfile.yml` for the full list.
+All commands use [Task](https://taskfile.dev/). The root `Taskfile.yml` orchestrates
+`ci`/`_ci-*` and includes the four task groups under `taskfiles/`
+(`ci-fast.yml`, `content.yml`, `engine.yml`, `release.yml`) with `flatten: true`,
+so every task stays in the root namespace. Run `task --list` for the full list.
 
 ### CI & Verification
 

package/docs/guidelines/agent-infra/layered-settings.md

@@ -152,27 +152,46 @@ MUST follow these rules. Initial file creation and legacy migration
 are owned by `scripts/install.py`; these rules govern every edit
 after that.
 
+The contract is **additive merge with user-line preservation** —
+the user's file is the ground truth, the template only contributes
+keys the user is missing. Round-trip parser and merger live in
+[`scripts/sync_yaml_rt.py`](../../scripts/sync_yaml_rt.py); the
+supported YAML subset (block-mappings, scalars, lists, comments,
+CRLF/LF) is documented in its module docstring. The stdlib-only
+choice (vs. `ruamel.yaml`) and its revisit triggers are recorded in
+[`docs/contracts/adr-settings-sync-engine.md`](../../contracts/adr-settings-sync-engine.md).
+
 For each section in the template
-([`agent-settings.md`](../../templates/agent-settings.md)), walked in
-template order:
+([`agent-settings.md`](../../templates/agent-settings.md)):
 
-- Keep the section header and its comments verbatim from the template.
 - For each key under the section:
-  - **Key exists in user's file** → use the user's current value.
-  - **Key missing** → use the template default.
-- **Unknown sections/keys** the user has added → preserve at the end
-  of the section (or in a trailing `_user:` block if no matching
-  section exists).
+  - **Key exists in user's file** → keep the user's line **verbatim**
+    (value, quoting, inline comment, indent — all preserved).
+  - **Key missing** → insert the template's line at the position
+    after the user's last preceding sibling that is also in the
+    template (max-index insertion).
+- **Unknown sections/keys** the user has added → preserved verbatim
+  at their existing position. They are not moved to a trailing
+  `_user:` block, not re-prefixed, not flattened.
 
 Invariants:
 
-- Template section **order** always wins — reorder existing keys to
-  match.
+- **User order wins.** Template order is only consulted to decide
+  where to insert missing keys; existing user keys are never
+  reordered.
 - Existing scalar values are **never overwritten** unless the user
   asked for that specific change.
-- New keys added to the template land with their default value.
-- Comments from the template replace user comments in the same
-  position — comments are documentation, not user data.
+- New keys added to the template land with their default value and
+  the template's leading comments.
+- **User comments are preserved verbatim** on every existing key.
+  Template comments only land with keys the merger inserts; once a
+  key is in the user's file, its surrounding comments are owned by
+  the user.
+- Legacy `_user._user.foo` corruption (accumulated by older buggy
+  syncs) heals on the next sync — the leading `_user.` chain is
+  stripped and the leaf is re-homed at its template path, or kept
+  as a single-level orphan under `_user:` if no template home
+  exists.
 - Write with 2-space indent, no tabs, no trailing whitespace.
 - Never commit — `.agent-settings.yml` is git-ignored.
 - If a legacy flat `.agent-settings` (key=value) is still present,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.18.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

@@ -76,9 +76,20 @@ Commands:
                              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
 
@@ -102,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.
@@ -343,6 +357,20 @@ cmd_context_hygiene_hook() {
   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
@@ -438,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
@@ -466,9 +505,14 @@ main() {
     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

@@ -8,6 +8,28 @@
 > `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

package/scripts/ai_council/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