@event4u/agent-config 5.10.1 → 6.1.0

package/.agent-src/commands/memory/add.md

@@ -1,146 +0,0 @@
----
-model_tier: medium
-name: memory:add
-tier: 2
-cluster: memory
-sub: add
-description: Interactively add a validated entry to an engineering-memory file (domain-invariants, architecture-decisions, incident-learnings, product-rules)
-skills: [file-editor]
-suggestion:
-  eligible: true
-  trigger_description: "remember this for later, add this to engineering memory, capture this learning"
-  trigger_context: "post-incident or post-decision conversation"
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# /memory add
-Creates or updates a single entry in one of the four engineering-memory
-YAML files under `agents/memory/` in the consumer project. The entry
-is validated against the schema in
-[`engineering-memory-data-format`](../../docs/guidelines/agent-infra/engineering-memory-data-format.md)
-before the file is written.
-
-Absence of these files is legal — this command is the entry point for
-the first write and for every subsequent addition.
-
-## Prerequisites
-
-- Consumer project has an `agents/` directory (package installed).
-- `scripts/check_memory.py` is available (shipped with the package).
-- User can name a concrete pattern — see the "when to reject" section.
-
-## Steps
-
-### 1. Pick the memory type
-
-```
-> Which memory type is this entry for?
->
-> 1. domain-invariants  — architectural boundaries, module rules
-> 2. architecture-decisions — ADR-style decisions with alternatives
-> 3. incident-learnings — post-mortem patterns with guardrails
-> 4. product-rules — intentional business constraints
-```
-
-If the user cannot pick one confidently, stop and ask what the entry
-**describes**. Never guess the type — a misfiled entry is worse than
-no entry.
-
-### 2. Check it does not already exist
-
-Read the target file (single-file layout: `agents/memory/<type>.yml`;
-sharded layout: `agents/memory/<type>/*.yml`). For each existing
-`id:`, compare against the proposed pattern:
-
-- Same `scope:` path + same rule text → **update** existing entry
-  (bump `last_validated`, append evidence to `source:`).
-- Overlapping `scope:` but different rule → surface the conflict and
-  ask which entry supersedes which.
-- No overlap → proceed as new entry.
-
-### 3. Collect the required fields
-
-All four types share the frontmatter in
-[`engineering-memory-data-format`](../../docs/guidelines/agent-infra/engineering-memory-data-format.md#shared-frontmatter-fields).
-Collect in this order, one numbered question at a time:
-
-1. `id` — kebab-case slug, unique within the type.
-2. `status` — `active` · `deprecated` · `archived` (default: `active`).
-3. `confidence` — `low` · `medium` · `high`.
-4. `source` — at least one URL, PR, incident, or ADR reference.
-5. `owner` — team slug.
-6. `last_validated` — today's ISO date (default).
-7. `review_after_days` — integer; suggest 90 for ADRs, 180 for
-   invariants, 365 for product rules.
-
-Then the type-specific fields (see the example templates under
-`.augment/templates/agents/memory/`).
-
-### 4. Show the draft
-
-Render the proposed YAML block to the user and ask for confirmation:
-
-```
-> About to add to agents/memory/<type>.yml:
->
-> <yaml block>
->
-> 1. Write it — run the gate
-> 2. Edit a field — ask which one
-> 3. Cancel — discard draft
-```
-
-### 5. Write and gate
-
-On confirmation:
-
-- Append the entry to the chosen layout (single-file: append under
-  `entries:`; sharded: write `agents/memory/<type>/<hash>.yml`).
-- Run `./agent-config memory:check --path agents/memory`.
-- On non-zero exit: show the error, **revert** the write, return to
-  step 3 or 4 depending on the failure.
-- On zero exit: report the entry `id` and path, remind the user to
-  commit.
-
-### 6. Cross-link
-
-If the entry has a `references:` block pointing to a skill, rule, or
-ADR file, run `python3 scripts/check_references.py` to verify the
-link resolves. Broken link → block and ask the user to fix.
-
-## When to reject
-
-- Vague frustration ("we should be more careful about X") — not a
-  pattern. Ask for a concrete rule or ADR instead.
-- One-off anecdote with no `trigger_conditions:` or `scope:` — not
-  generalizable.
-- Duplicate of an existing entry (step 2) — update instead.
-- Missing `source:` — an entry without evidence cannot be reviewed.
-
-## Output format (verbosity-gated)
-
-Read `verbosity.post_action_reports` from `.agent-settings.yml` (default
-`minimal`).
-
-- `off` → emit nothing on success; surface gate failures only.
-- `minimal` (default) → one line:
-  `✅  Added <type>/<id> (gate: PASS)`.
-- `full` → multi-line block:
-
-  ```
-  ✅  Added <type>/<id> (confidence: <high|medium|low>)
-     Path: agents/memory/<type>.yml (or agents/memory/<type>/<hash>.yml)
-     Gate: scripts/check_memory.py → PASS
-     Next: commit and link from the relevant skill/command.
-  ```
-
-## See also
-
-- [`engineering-memory-data-format`](../../docs/guidelines/agent-infra/engineering-memory-data-format.md)
-  — full schema
-- [`skill:learning-to-rule-or-skill`](../skills/learning-to-rule-or-skill/SKILL.md) —
-  when a learning is better captured as an `incident-learnings` entry vs
-  a rule/skill proposal

package/.agent-src/commands/memory/learn-low-impact.md

@@ -1,147 +0,0 @@
----
-model_tier: medium
-name: memory:learn-low-impact
-tier: 2
-cluster: memory
-sub: learn-low-impact
-skills: [ai-council, upstream-contribute]
-description: Preview validated low-impact entries that would be upstreamed to the package seed (default `--preview`); `--apply` opens a draft PR via `upstream-contribute` after re-redaction.
-suggestion:
-  eligible: true
-  trigger_description: "upstream low-impact decisions, share validated council questions, contribute the learning corpus"
-  trigger_context: "user has accumulated validated entries in agents/decisions/low-impact-decisions.md and wants to share with the package"
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# /memory learn-low-impact
-
-Promote `## Validated` entries from
-[`agents/decisions/low-impact-decisions.md`](../../agents/decisions/low-impact-decisions.md)
-into the upstream seed at
-`.agent-src.uncondensed/data/low-impact-decisions-seed.md` via a DRAFT
-PR against the agent-config package. **Validated entries only** — probation
-entries never upstream, they're unconfirmed signal.
-
-## Flags
-
-| Flag | Default | Behaviour |
-|---|---|---|
-| `--preview` | **on** | Build the plan, run the redactor, render promoted / refused / already-seeded buckets + draft PR body. **No file write, no branch, no PR.** Default behaviour. |
-| `--apply` | off | Mutually exclusive with `--preview`. Required to invoke `upstream-contribute` and open the draft PR. Refusals from the redactor still block. |
-
-Iron Law: ``--apply`` never auto-fires on the first invocation. The
-user always sees the preview block first and re-runs explicitly.
-
-## Iron Law — privacy floor runs TWICE
-
-```
-THE REDACTOR RUNS AT INTAKE (WRITE GATE) AND AGAIN HERE (UPSTREAM GATE).
-ANY VIOLATION → REFUSE THE PR. NO SILENT REWRITES.
-```
-
-See [`low-impact-corpus-privacy-floor`](../rules/low-impact-corpus-privacy-floor.md)
-for the eight forbidden-content classes.
-
-## Steps
-
-### 1. Build the preview plan
-
-Call
-`scripts/ai_council/learn_low_impact_preview.py::build_preview` with
-the project-local corpus and the package seed:
-
-```python
-from scripts.ai_council.learn_low_impact_preview import build_preview
-plan = build_preview(
-    corpus_path="agents/decisions/low-impact-decisions.md",
-    seed_path=".agent-src.uncondensed/data/low-impact-decisions-seed.md",
-    repo_slug="<owner>/<repo>",  # from `git remote get-url origin`
-    repo_root="<absolute repo root>",
-    private_domains=(),   # from .agent-settings.yml policy
-    customer_names=(),    # from .agent-settings.yml policy
-    sql_identifiers=(),   # from .agent-settings.yml policy
-)
-```
-
-The builder runs all three contract checks in one pass:
-
-1. Parses `## Validated` (strict mode — drift surfaces as
-   `CorpusParseError`).
-2. Diffs against the seed file — already-seeded entries land in
-   `plan.already_seeded` and never upstream.
-3. Re-runs `redact_low_impact_entry` on every candidate. Failures
-   land in `plan.refused`.
-
-### 2. Surface the preview block
-
-Print `plan.render()` verbatim. Always. This is the user-facing
-audit trail per `fast-path-marker-visibility` Iron Law — the host
-agent MUST NOT swallow or paraphrase it.
-
-```
-## learn-low-impact preview — repo=<slug>
-last-upstreamed: <sha>
-seed: <path>
-
-### Promoted (N) …
-### Refused (M) — redactor blocked …
-### Already seeded (K) …
-```
-
-### 3. Decide based on the flag
-
-- **`--preview` (default)** — stop here. If `plan.would_open_pr` is
-  true, the rendered block ends with
-  `> Re-run with \`--apply\` to open the draft PR via \`upstream-contribute\`.`
-  Hand control back to the user.
-- **`--apply`** — refuse when `plan.refused` is non-empty; surface
-  the refusals and stop. Otherwise invoke
-  [`upstream-contribute`](../skills/upstream-contribute/SKILL.md)
-  with:
-    - **target file:** `.agent-src.uncondensed/data/low-impact-decisions-seed.md`
-    - **PR title:** `plan.render_pr_body()` first heading
-    - **PR body:** `plan.render_pr_body()`
-    - **patch:** `plan.render_diff()`
-    - **draft:** `true` — never auto-merge; review is a human gate.
-
-### 4. Advance the local baseline (`--apply` path only)
-
-When the PR is opened (step 3 returns a PR URL + new commit SHA on
-the package branch):
-
-```bash
-# update the local pointer so subsequent runs are deltas
-sed -i.bak -E "s|^last-upstreamed: .*|last-upstreamed: <new-sha>|" \
-    agents/decisions/low-impact-decisions.md
-rm agents/decisions/low-impact-decisions.md.bak
-```
-
-### 5. Surface result (`--apply` path only)
-
-```
-> Drafted PR <url>
-> Entries upstreamed: N
-> Provenance bumped: <old-sha> → <new-sha>
-```
-
-## Halt conditions
-
-- Redactor refuses (any class) — surface, stop. `--apply` is rejected.
-- No candidates (`plan.has_work == False`) — exit 0 with the preview
-  block; no PR even on `--apply`.
-- `--preview` (default) — always stops before any side-effect.
-- Package repo unavailable per `upstream-contribute § Step 4` — surface
-  the access options, stop.
-- User explicitly declines the PR option — exit 0, no PR.
-
-## See also
-
-- [`upstream-contribute`](../skills/upstream-contribute/SKILL.md) — PR
-  machinery (branch, commit, gates).
-- [`agents/decisions/low-impact-decisions.md`](../../agents/decisions/low-impact-decisions.md)
-  — the project-local corpus.
-- [`low-impact-corpus-privacy-floor`](../rules/low-impact-corpus-privacy-floor.md)
-  — Iron Law.

package/.agent-src/commands/memory/load.md

@@ -1,175 +0,0 @@
----
-model_tier: medium
-name: memory:load
-tier: 2
-cluster: memory
-sub: load
-description: Load ALL curated entries of a given memory type into the current context — opt-in full load for deep analysis, never auto-triggered
-skills: []
-suggestion:
-  eligible: false
-  rationale: "Description states 'never auto-triggered' — opt-in deep-load only."
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# /memory load
-Loads every entry of a single memory type into the current conversation
-as a formatted block. Use when the normal `memory_lookup` filter is too
-narrow and you need the full type for an architecture decision, audit,
-or migration.
-
-Opt-in only. Agents must never call this implicitly — the cost is linear
-in the entry count and the signal-to-noise degrades fast on large types.
-
-## Prerequisites
-
-- Consumer project has `agents/memory/<type>/` or
-  `agents/memory/<type>.yml`.
-- User explicitly asked for the full view (e.g. "show me everything we
-  know about `domain-invariants`").
-
-## Steps
-
-### 1. Pick the type
-
-```
-> Which memory type should I load in full?
->
-> 1. domain-invariants
-> 2. architecture-decisions
-> 3. incident-learnings
-> 4. product-rules
-> 5. historical-patterns
-> 6. ownership
-```
-
-### 1b. Surface the Tier-0 critical slice
-
-Before loading the requested type, emit every active entry with
-`priority: critical` across **all** memory types as a Tier-0 banner.
-The contract for `priority: critical` is *always-surface regardless of
-query*; this step honours it.
-
-```bash
-./agent-config memory:lookup --priority critical --status active --format yaml
-```
-
-Render the slice in a fenced block titled `Tier-0 (critical)`, ordered
-by `(type, id)`. If the slice is empty, skip the banner silently — do
-not announce absence.
-
-If the lookup helper does not yet support `--priority`, fall back to a
-file-only sweep:
-
-```bash
-python3 - <<'PY'
-import pathlib, yaml
-for f in sorted(pathlib.Path("agents/memory").rglob("*.yml")):
-    data = yaml.safe_load(f.read_text(encoding="utf-8")) or {}
-    for e in data.get("entries", []) or []:
-        if e.get("priority") == "critical" and e.get("status") == "active":
-            print(f"--- {f.parent.name}/{e.get('id')}")
-            print(yaml.safe_dump(e, sort_keys=False), end="")
-PY
-```
-
-The Tier-0 slice is surfaced once per `/memory:load` invocation, even
-when the user picks a type with no critical entries — the slice spans
-types deliberately. Token cost is bounded by the soft cap of 10
-critical entries per type (warned by `scripts/check_memory.py`).
-
-### 2. Warn about volume
-
-Before loading, count the entries:
-
-```bash
-./agent-config memory:lookup --types <type> --format json | \
-  python3 -c "import sys, json; print(len(json.load(sys.stdin)))"
-```
-
-If the count exceeds 25, warn:
-
-```
-> This will load {N} entries (~{N×200} tokens).
->
-> 1. Continue — load everything
-> 2. Narrow by key — run /memory-full with --key pattern
-> 3. Cancel
-```
-
-### 3. Load
-
-```bash
-./agent-config memory:lookup --types <type> --format yaml
-```
-
-Render the output verbatim, grouped by status (`active` first, then
-`deprecated`, then `archived`). Each entry shows `id`, `confidence`,
-`last_validated`, and the rule body. Skip `archived` unless the user
-opts in.
-
-### 4. Confirm absorption
-
-```
-✅  Loaded {N} {type} entries into context.
-    Active: {n_active}  · Deprecated: {n_dep}  · Archived skipped: {n_arch}
-    Source: agents/memory/{type}/ (or agents/memory/{type}.yml)
-```
-
-The agent should now treat every loaded entry as an authority signal
-with its declared `confidence` — see
-[`memory-access`](../../docs/guidelines/agent-infra/memory-access.md) for
-how entries modulate edits.
-
-### 5. Inline-review hook (intake backlog)
-
-After step 4, count unreviewed intake entries for the same type:
-
-```bash
-./agent-config memory:lookup --types <type> --intake-only --format json | \
-  python3 -c "import sys, json; print(len(json.load(sys.stdin)))"
-```
-
-Read `memory.review_threshold` from `.agent-settings.yml` (default 10).
-If the count is **0** or **≤ threshold**, skip this step silently. If
-**> threshold**, surface a numbered preview of the top-3 highest-
-confidence intake signals (see
-[`memory-consolidation`](../../skills/memory-consolidation/SKILL.md)
-§ Phase 3 for the consolidation contract):
-
-```
-> ⚠️  {N} unreviewed intake signals for `{type}` (threshold {T}).
->     Top 3 by confidence:
->
->     1. [conf=high] {sig-id} — {one-line observation}
->     2. [conf=med ] {sig-id} — {one-line observation}
->     3. [conf=med ] {sig-id} — {one-line observation}
->
-> Review now?
-> 1. Promote — run /memory promote on a signal id
-> 2. Mine more — run /memory mine-session for fresh signals
-> s. Skip (default) — proceed with the loaded entries
-```
-
-Default action is **skip** — the load completes regardless. This is a
-nudge, not a gate. If `memory.review_threshold` is `0`, skip this
-step entirely (feature off). Never auto-promote.
-
-## When to reject
-
-- User is mid-implementation and asks for the full load as a shortcut
-  around a targeted `memory_lookup` call — redirect to the narrower
-  lookup; full load is for analysis/audit, not coding.
-- Type directory is empty — respond with "no entries yet, use
-  `/memory-add` to start".
-
-## See also
-
-- [`memory-add`](memory-add.md) — add a single entry
-- [`memory-promote`](memory-promote.md) — promote an intake signal to
-  a curated entry
-- [`memory-access`](../../docs/guidelines/agent-infra/memory-access.md) —
-  how entries flow into agent decisions

package/.agent-src/commands/memory/mine-session.md

@@ -1,156 +0,0 @@
----
-model_tier: medium
-name: memory:mine-session
-tier: 2
-cluster: memory
-sub: mine-session
-description: Mine the active session transcript for memory signals (corrections, preferences, decisions, recurring patterns) — preview-by-default, opt-in transcript access, host-agnostic via TranscriptAdapter.
-skills: [memory-consolidation, file-editor]
-suggestion:
-  eligible: false
-  rationale: "Reads transcript files — opt-in, per-invocation confirmation required."
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# /memory mine-session
-
-Runs the **GATHER SIGNAL** phase of the [`memory-consolidation`](../../skills/memory-consolidation/SKILL.md)
-loop against the current host's transcripts and surfaces normalised
-project-scoped facts as a preview. No file is written without
-`--commit-intake`. No transcript is read without
-`--confirm-transcript-access`.
-
-## When to use
-
-- After a multi-day implementation, before the conversation history
-  rotates out of context.
-- The user says "mine my recent sessions" or "consolidate what we've
-  decided".
-- The `/memory load` inline-review block flagged > 10 unreviewed signals
-  and the user wants to add fresh ones from the live transcript before
-  promoting.
-
-Do NOT use as an automatic post-session hook. Mining is per-invocation
-and confirmed.
-
-## Flags
-
-| Flag | Default | Purpose |
-|---|---|---|
-| `--since <ISO-date>` | 14 days ago | Only mine turns at or after this date. Re-anchors relative phrases like "yesterday" with `YYYY-MM-DD`. |
-| `--confirm-transcript-access` | off | Opt-in gate. Without it, the miner reads zero turns and prints the opt-in hint. Per-invocation, not persistent. |
-| `--preview` | on | Render normalised facts to stdout. No file write. Default behaviour. |
-| `--commit-intake` | off | Mutually exclusive with `--preview`. Append normalised facts to `agents/memory/intake/<primary-tag>.jsonl`. |
-| `--host <claude-code\|cursor\|augment>` | auto-detect | Force the `TranscriptAdapter`. Phase 1 ships `claude-code` only; others print `not-supported-on-this-host` and exit. |
-
-## Steps
-
-### 1. Verify opt-in
-
-If `--confirm-transcript-access` is absent, print:
-
-```
-> Mining reads your session transcript files. Re-run with
-> --confirm-transcript-access to proceed. The flag is per-invocation
-> and not persisted.
-```
-
-Then exit with code 0. **Do not read any file.**
-
-### 2. Resolve TranscriptAdapter
-
-Auto-detect the host (Claude Code → `~/.claude/projects/<repo>/sessions/*.jsonl`).
-If auto-detect fails or `--host` names an unimplemented adapter, print:
-
-```
-> No TranscriptAdapter for host=<name>. Phase 1 supports: claude-code.
-> Use /memory propose to record signals manually.
-```
-
-Then exit with code 0.
-
-### 3. Stream + extract
-
-Iterate transcript turns within the `--since` window through the four
-signal regex families documented in
-[`memory-consolidation`](../../skills/memory-consolidation/SKILL.md)
-§ Phase 2. For each match, normalise the fact (strip pronouns, IDE
-chrome, timestamps, turn-id) and assign a primary tag from the
-schema-routing table.
-
-If the normalised count exceeds 5, **stop after the 5th** and print:
-
-```
-> ⚠️  Miner produced > 5 facts. Tighten patterns or narrow --since.
->     Showing the first 5; the rest are dropped.
-```
-
-This is the strict-gate exit per the skill's exit criteria.
-
-### 4. Render preview
-
-Print one Markdown block to stdout:
-
-```
-## Mining preview — <project> · <window> · host=<name>
-
-| # | Tag | Key | Observation | Source turn |
-|---|---|---|---|---|
-| 1 | convention | <symbol> | <one-line fact> | <ts> |
-| 2 | gotcha     | <path>   | <one-line fact> | <ts> |
-
-Schemas touched: conventions, operational-gotchas
-Stale curated entries (last_validated > 90d, not seen in 30d): <list or "none">
-```
-
-If `--preview` (default), stop here.
-
-### 5. Commit (only with `--commit-intake`)
-
-Append each fact as one JSONL line to
-`agents/memory/intake/<primary-tag>.jsonl` with the contract fields:
-`ts`, `type`, `key`, `observation`, `source: agent`,
-`session_id`, plus the optional `tags: [<one>, <two>]` field.
-
-Confirm:
-
-```
-✅ Appended <N> intake lines across <M> files.
-   Next: /memory promote to lift validated lines into curated YAML.
-```
-
-## Safety
-
-- **Never** writes outside `agents/memory/intake/`.
-- **Never** reads transcripts without `--confirm-transcript-access`.
-- **Never** synthesizes facts. The miner is a strict gate against
-  the four regex families; if zero matches → prints "no signals".
-- **Never** auto-promotes. `/memory promote` is a separate, validated
-  step.
-
-## Gotcha
-
-- `--commit-intake` and `--preview` are mutually exclusive. Passing
-  both → exit with usage error.
-- The `TranscriptAdapter` strips IDE chrome (tool-call boilerplate,
-  reasoning blocks, system reminders) before pattern matching. If the
-  miner under-counts, audit the adapter's redact list, not the regex.
-- Date-discipline: relative phrases (`yesterday`, `last week`) in the
-  observation field are rejected by `scripts/check_memory.py` unless
-  re-anchored with `YYYY-MM-DD` within ±20 chars. The miner re-anchors
-  automatically using the turn's `ts`; verify before commit.
-
-## See also
-
-- [`memory-consolidation`](../../skills/memory-consolidation/SKILL.md) — the
-  four-phase loop (ORIENT → GATHER → CONSOLIDATE → PRUNE) this command
-  implements GATHER SIGNAL for.
-- [`memory:propose`](propose.md) — manual fallback when no
-  `TranscriptAdapter` matches the current host.
-- [`memory:promote`](promote.md) — lifts validated intake lines into
-  curated YAML.
-- [`agent-memory-contract`](../../../docs/contracts/agent-memory-contract.md) —
-  intake JSONL schema, including the `tags` field.