@event4u/agent-config 5.10.0 → 6.0.0

package/dist/agent-src/commands/challenge-me.md

@@ -0,0 +1,68 @@
+---
+model_tier: medium
+name: challenge-me
+pack: meta
+tier: 2
+description: Challenge-me orchestrator — routes to vision, with-docs
+cluster: challenge-me
+type: orchestrator
+suggestion:
+  eligible: true
+  trigger_description: "challenge me on this plan, grill me, grill me on this, grill me on this plan, grill me through this, grill me until it's clear, grill me hard, frag mich durch, dreh mich durch die Mangel, challenge against existing docs/glossary"
+  trigger_context: "user has a fuzzy plan/idea/feature draft and wants it sharpened interactively rather than reconstructed in one shot — also reachable via /grill-me alias"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /challenge-me
+
+Top-level orchestrator for the `/challenge-me` family. Walks a decision
+tree by asking one question at a time until the agent is confident
+enough to emit a copyable Markdown pitch.
+
+> Also reachable as [`/grill-me`](grill-me.md) — thin alias, identical
+> behaviour, identical sub-commands and triggers.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/challenge-me vision` | `commands/challenge-me/vision.md` | Standard variant — interrogate a fuzzy plan / idea / ticket draft to 95% confidence, emit a vision pitch |
+| `/challenge-me with-docs` | `commands/challenge-me/with-docs.md` | Doc-aware variant — same flow plus session glossary against `CONTEXT.md`, load-bearing claim-vs-code verification, optional `CONTEXT.md` patch + ADR candidates in the pitch |
+
+## When to pick which
+
+- **`vision`** — greenfield idea, fresh ticket draft, or a plan with no
+  existing project glossary / domain docs. Default for "challenge me on
+  this plan".
+- **`with-docs`** — the project has `CONTEXT.md`, an ADR directory
+  (`docs/adr/`, `docs/decisions/`, `agents/decisions/`), or the user
+  uses domain terms that may already be defined. The variant catches
+  glossary conflicts and load-bearing claim-vs-code drift before pitch.
+
+## Dispatch
+
+1. Parse the user's argument: `/challenge-me <sub-command> [flags] [seed]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the routed file and follow its `## Steps` section
+   verbatim with the remaining flags / seed.
+4. If the sub-command is unknown or missing, print the menu and ask:
+
+   > 1. vision — standard 95%-confidence interview, emits a copyable pitch
+   > 2. with-docs — same flow, but checks the seed against `CONTEXT.md` /
+   >    ADRs and emits an optional doc patch in the pitch
+
+## Rules
+
+- **Do NOT chain sub-commands.** One `/challenge-me <sub>` per turn.
+- If the user invokes `/challenge-me` with no argument, **show the menu**
+  — do not guess which sub-command they meant.
+- **No file writes from either sub-command.** Both variants are
+  conversational; the pitch is the only artefact, and it is copyable
+  Markdown the user pastes elsewhere. `with-docs` emits its `CONTEXT.md`
+  patch and ADR candidates inside the same pitch block — agent does not
+  apply them itself.
+- **Mirror the user's language** — sub-commands inherit the
+  `language-and-tone` Iron Law for question blocks and pitch.

package/dist/agent-src/commands/chat-history/import.md

@@ -0,0 +1,172 @@
+---
+model_tier: medium
+name: chat-history-import
+pack: meta
+tier: 2
+cluster: chat-history
+sub: import
+description: Surface prior chat-history sessions as a numbered table, let the user pick one, read it silently, and emit a short summary plus a resume offer — selective, user-driven cross-session import
+suggestion:
+  eligible: true
+  trigger_description: "import a past session into the current chat, pull a prior session into context, pick a session to read"
+  trigger_context: "user wants to selectively pull a prior session's context into the current one as a short summary"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+<!-- cloud_safe: noop -->
+
+# /chat-history import
+
+Read-only, **user-driven** cross-session import. Surfaces prior
+sessions logged in `agents/runtime/.agent-chat-history` as a numbered table,
+the user picks **one**, the agent reads that session **silently**
+and emits a 2–5 sentence summary, then offers to resume the last
+task from that session. The agent does **not** render entries
+verbatim, auto-import, or rewrite the user's context without an
+explicit instruction.
+
+This is the opt-in counterpart to the read-path filter (Phase 3 of
+`road-to-chat-history-session-isolation`): default reads stay
+session-scoped; `import` is the explicit surface for crossing the
+session boundary. For project-improving learnings derived from a
+prior session, see [`/chat-history learn`](learn.md).
+
+## When NOT to use
+
+- Inspect the current session — that is the default of
+  `/chat-history show` plus `scripts/chat_history.py read`.
+- Generate a learning proposal from a prior session — use
+  [`/chat-history learn`](learn.md), which orchestrates
+  `learning-to-rule-or-skill` on the picked session.
+- Bulk-import all sessions — out of scope for v1. One session per
+  invocation; multi-pick is v2.
+- Search prior sessions by content — out of scope for v1; no fuzzy
+  search, no full-text grep. The user picks by `last_ts` and
+  `summary` from the listing.
+
+## Steps
+
+### 1. Check if enabled
+
+Read `chat_history.enabled` from `.agent-settings.yml`. If `false`
+or the section is missing, say so and stop:
+
+```
+> 📒 chat-history is disabled (chat_history.enabled = false).
+> Set it to true in .agent-settings.yml to start logging.
+```
+
+### 2. List sessions
+
+Run `scripts/chat_history.py sessions --json --limit 20 --summary`.
+The helper returns an array of
+`{id, count, first_ts, last_ts, preview, summary}` sorted by
+`last_ts` desc. The `summary` field is built **inside the helper**
+from at most 10 sampled entries per session (5 oldest + 5 newest) —
+token-cheap, no need to ever read the full body for the picker.
+Default excludes empty buckets — only sessions with at least one
+body entry are surfaced.
+
+If the array is empty, stop:
+
+```
+> 📒 No prior sessions found in agents/runtime/.agent-chat-history.
+```
+
+### 3. Surface as a numbered table
+
+Render the sessions as a markdown table — the row number is the
+option (per `user-interaction` Iron Law: numbered options for any
+picker). The session `id` is noise to humans; keep it **internal**
+for step 5's `read --session <id>` call and never render it.
+Format:
+
+```
+Pick a session to import:
+
+| #  | Date             | Entries | Summary |
+|----|------------------|---------|---------|
+| 1  | YYYY-MM-DD HH:MM | N       | {summary} |
+| 2  | YYYY-MM-DD HH:MM | N       | {summary} |
+| …  |                  |         |           |
+| N  | —                | —       | abort — do not read any session |
+```
+
+Format the timestamp as `YYYY-MM-DD HH:MM` (drop seconds and
+timezone — the listing is for orientation, not forensics). Lead the
+`Summary` cell with the helper's `summary` field — that is the
+rough arc the user picks by (`<first user msg> → <last user msg>`
+for normal sessions, or `(N entries — no user prompts; t-mix: …)`
+for tool-only sessions). Do **not** truncate or rewrite `summary` —
+markdown table wrap handles long values. Always include an explicit
+`abort` row as the last numbered option. Track option-number → `id`
+internally so step 5 can call `scripts/chat_history.py read
+--session <id>` with the right id.
+
+### 4. Wait for the pick
+
+**One question per turn** (per `ask-when-uncertain`). Do not chain
+the listing with anything else; do not auto-pick; do not surface a
+default. Wait for the user's response.
+
+If the user picks the abort option, stop without reading.
+
+### 5. Read the picked session silently
+
+Run `scripts/chat_history.py read --session <id> --last <count>`,
+where `<count>` is the picked row's `count` from step 2. The
+`--last` flag is **required** — the helper defaults to 5 entries,
+which would silently truncate any longer session. The helper returns
+the entries as JSON.
+
+**Do not render the entries.** The verbose dump was reversed by the
+user — token cost and scroll fatigue outweighed the verbatim
+contract. Read the JSON in-context, then proceed to step 6.
+
+### 6. Summarise and offer to resume
+
+Emit a **2–5 sentence** summary of the picked session: the topic,
+what was decided or built, and where it left off (the last task in
+progress, if any). Plain prose — no bullets, no headings, no
+verbatim quotes.
+
+Then offer the resume choice as numbered options
+(per `user-interaction`), one question per turn:
+
+```
+1. resume — pick up the last task from that session
+2. stop — keep the summary in context, do nothing else
+```
+
+Wait for the pick. Do **not** auto-resume. If the user picks
+`resume`, hand off to the relevant skill or command for that work;
+do not silently start editing files. The agent does not write to
+the current session's log on the user's behalf without an explicit
+instruction.
+
+## Gotchas
+
+- **Summary, not verbatim.** Earlier Council R2-2 favoured verbatim
+  rendering; reversed in practice — too slow, too token-expensive.
+  The agent reads the picked session in-context and emits a 2–5
+  sentence summary. Verbatim rendering is no longer part of the
+  contract.
+- **One pick per invocation.** Multi-pick is v2. If the user wants
+  a second session, run `/chat-history import` again.
+- **Read-only.** This command never writes to `agents/runtime/.agent-chat-history`
+  and never rotates.
+- **`<legacy>` and `<unknown>` buckets** show up like any other
+  session id when they have body entries — the user can pick them
+  too. The helper aggregates body entries with no `s` field into
+  `<legacy>` and entries with `s == "<unknown>"` into `<unknown>`.
+
+## See also
+
+- [`/chat-history learn`](learn.md) — pick a prior session and turn it into a project-improving proposal via `learning-to-rule-or-skill`
+- [`/chat-history show`](show.md) — current-session inspector
+- [`chat-history-platform-hooks`](../../../agents/settings/contexts/chat-history-platform-hooks.md) — read contract, isolation default, opt-in cross-session path
+- [`scripts/chat_history.py`](../../../scripts/chat_history.py) — `sessions` and `read --session` CLI surface
+- [`user-interaction`](../../rules/user-interaction.md) — numbered-options Iron Law
+- [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) — one-question-per-turn Iron Law

package/dist/agent-src/commands/chat-history/learn.md

@@ -0,0 +1,184 @@
+---
+model_tier: medium
+name: chat-history-learn
+pack: meta
+tier: 2
+cluster: chat-history
+sub: learn
+skills: [learning-to-rule-or-skill]
+description: Pick a prior chat-history session and mine it for project-improving learnings — runs learning-to-rule-or-skill on the picked session, drafts proposal(s) under agents/proposals/
+suggestion:
+  eligible: true
+  trigger_description: "extract a learning from a past session, mine chat-history for proposals, what did we learn last session, codify a pattern from a prior session"
+  trigger_context: "user wants to derive a rule/skill/guideline proposal from the content of one prior session"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+<!-- cloud_safe: noop -->
+
+# /chat-history learn
+
+User-driven **learning extraction** from a prior session. Surfaces
+prior sessions logged in `agents/runtime/.agent-chat-history` as numbered options,
+the user picks **one**, the agent reads that session's entries and
+runs the [`learning-to-rule-or-skill`](../../skills/learning-to-rule-or-skill/SKILL.md)
+workflow on the content — surfacing repeated mistakes, successful
+patterns, or constraints worth codifying as a rule, skill, or
+guideline proposal.
+
+This is the **project-improvement** counterpart to
+[`/chat-history import`](import.md): `import` renders a session
+verbatim into the current chat for the user to act on; `learn`
+mines a session for proposals that improve the agent or the
+project itself.
+
+## When NOT to use
+
+- Pull a prior session into the current chat verbatim — use
+  [`/chat-history import`](import.md).
+- Capture a learning that originated **in the current** session —
+  invoke the [`learning-to-rule-or-skill`](../../skills/learning-to-rule-or-skill/SKILL.md)
+  skill directly. `learn` is for prior-session mining only.
+- Bulk-mine all sessions — out of scope for v1. One session per
+  invocation; multi-pick is v2.
+
+## Steps
+
+### 1. Check if enabled
+
+Read `chat_history.enabled` from `.agent-settings.yml`. If `false`
+or the section is missing, say so and stop:
+
+```
+> 📒 chat-history is disabled (chat_history.enabled = false).
+> Set it to true in .agent-settings.yml to start logging.
+```
+
+### 2. List sessions
+
+Run `scripts/chat_history.py sessions --json --limit 20 --summary`.
+The helper returns an array of
+`{id, count, first_ts, last_ts, preview, summary}` sorted by
+`last_ts` desc. The `summary` field is built inside the helper
+from ≤10 sampled entries per session (5 oldest + 5 newest) —
+token-cheap, no full-body read needed for the picker. Empty
+buckets are excluded by default.
+
+If the array is empty, stop:
+
+```
+> 📒 No prior sessions found in agents/runtime/.agent-chat-history.
+```
+
+### 3. Surface as numbered options
+
+Render each session as a numbered option (per the `user-interaction`
+rule — Iron Law: numbered options for any picker). Lead with the
+helper's `summary` field — the rough arc the user picks by
+(`<first user msg> → <last user msg>`, or
+`(N entries — no user prompts; t-mix: …)` for tool-only sessions).
+Keep the session `id` **internal** for step 5's `read --session <id>`
+call; never render it in the listing. Format:
+
+```
+> Pick a session to mine for learnings:
+>
+> 1. {summary}
+>    {YYYY-MM-DD HH:MM}  ·  {count} entries
+> 2. ...
+> ...
+> N. abort — do not extract any learning
+```
+
+Format the timestamp as `YYYY-MM-DD HH:MM` (drop seconds + timezone
+— orientation, not forensics). Do not truncate or rewrite `summary`
+— the helper already shapes it. Always include an explicit abort
+option last. Track option-number → `id` internally so step 5 calls
+`scripts/chat_history.py read --session <id>` with the right id.
+
+### 4. Wait for the pick
+
+**One question per turn** (per `ask-when-uncertain`). Do not chain
+the listing with anything else; do not auto-pick; do not surface a
+default. Wait for the user's response.
+
+If the user picks the abort option, stop without reading.
+
+### 5. Read the picked session
+
+Run `scripts/chat_history.py read --session <id>` with the picked
+`id`. Hold the entries in working memory — do **not** render them
+verbatim into the chat. The verbatim path is `import`'s job; here
+the entries are input to step 6.
+
+### 6. Run `learning-to-rule-or-skill`
+
+Apply the [`learning-to-rule-or-skill`](../../skills/learning-to-rule-or-skill/SKILL.md)
+procedure on the session content:
+
+1. **Scan** the entries for candidate learnings — repeated
+   mistakes, successful patterns, friction points, or constraints
+   stated by the user.
+2. **Pass each candidate through the Promotion Gate** (§ 0 of the
+   skill): repetition, impact, failure pattern, non-duplication,
+   scope fit, minimal. Drop candidates that fail any gate.
+3. **For each surviving candidate**, run § 4 (search protocol — all
+   four steps), then decide rule / skill / guideline / update / no
+   action per § 3 of the skill.
+4. **Draft a proposal** for every candidate that warrants one,
+   following § 8 of the skill (proposal template under
+   `agents/proposals/<id>.md`).
+
+If multiple candidates survive, draft them as **separate**
+proposals — do not merge unrelated learnings into one.
+
+### 7. Surface the result
+
+Hand back to the user with a structured summary per surviving
+candidate:
+
+```
+> 📒 Mined session {id} — {N} candidate(s) surfaced
+
+> 1. {learning title}
+>    Decision: {rule|skill|guideline|update|no action}
+>    Proposal: agents/proposals/{proposal_id}.md
+>    Gate: {pass|fail — reason}
+> 2. ...
+```
+
+If no candidate cleared the Promotion Gate, say so explicitly:
+
+```
+> 📒 Mined session {id} — no candidate cleared the Promotion Gate.
+```
+
+Do **not** open a PR, do **not** commit the proposals — proposal
+files land in `agents/proposals/` (gitignored or curated per
+project policy) for the user to review and route via
+`upstream-contribute` or merge into `agents/overrides/`.
+
+## Gotchas
+
+- **Promotion Gate is hard.** A grep miss is not proof of
+  non-duplication — § 4 of the skill mandates the four-step search
+  protocol. Do not skip it.
+- **One pick per invocation.** Multi-pick is v2. If the user wants
+  to mine a second session, run `/chat-history learn` again.
+- **Read-only on the log.** This command never writes to
+  `agents/runtime/.agent-chat-history`. It writes proposal drafts under
+  `agents/proposals/` only.
+- **No auto-promotion.** Drafted proposals stay in `proposals/`
+  until the user routes them. `learn` never invokes
+  `upstream-contribute` itself.
+
+## See also
+
+- [`/chat-history import`](import.md) — verbatim render of a prior session
+- [`learning-to-rule-or-skill`](../../skills/learning-to-rule-or-skill/SKILL.md) — the workflow this command orchestrates
+- [`upstream-contribute`](../../skills/upstream-contribute/SKILL.md) — promote a project-scoped proposal upstream
+- [`scripts/chat_history.py`](../../../scripts/chat_history.py) — `sessions` and `read --session` CLI surface
+- [`user-interaction`](../../rules/user-interaction.md) — numbered-options Iron Law
+- [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) — one-question-per-turn Iron Law

package/dist/agent-src/commands/chat-history/show.md

@@ -0,0 +1,113 @@
+---
+model_tier: medium
+name: chat-history-show
+pack: meta
+tier: 2
+cluster: chat-history
+sub: show
+skills: [chat-history]
+description: Show the status of the persistent chat-history log — file size, entry count, header fingerprint, age, and the last few entries
+suggestion:
+  eligible: false
+  rationale: "Status display only; no NL trigger distinct from 'show status'."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+<!-- cloud_safe: noop -->
+
+# /chat-history show
+Inspect `agents/runtime/.agent-chat-history` — the JSONL log appended by the
+structural chat-history hooks (`ChatHistoryAppendHook`,
+`ChatHistoryHaltAppendHook`) for crash recovery.
+
+Shows:
+
+- Whether the file exists and whether logging is currently enabled
+- File size vs `max_size_kb`
+- Header metadata: schema version, `started`, `frequency`
+- Entry count and age of the oldest/newest entry
+- A peek at the last 3–5 entries so the user can see what was captured
+
+Read-only — this command never writes to the file.
+
+## When NOT to use
+
+- Wipe the file → delete `agents/runtime/.agent-chat-history` manually; it is
+  git-ignored and will be recreated on the next hook fire.
+- Configure logging behavior → edit `.agent-settings.yml` directly
+  (`chat_history.*`); see
+  [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
+
+## Steps
+
+### 1. Check if enabled
+
+Read `chat_history.enabled` from `.agent-settings.yml`. If `false` or
+the section is missing, say so and stop:
+
+```
+> 📒 chat-history is disabled (chat_history.enabled = false).
+> Set it to true in .agent-settings.yml to start logging.
+```
+
+### 2. Read status via helper
+
+Run `scripts/chat_history.py status`. The helper returns a JSON object
+with `exists`, `size_bytes`, `size_kb`, `entries`, `header`, and `path`.
+
+If `exists: false`, tell the user the file has not been created yet —
+it will be created on the next agent turn that writes an entry.
+
+### 3. Read last N entries
+
+Run `scripts/chat_history.py read --last 5` (or equivalent — see the
+helper's CLI). Capture timestamps and entry types without loading the
+full file.
+
+### 4. Present the summary
+
+Render a concise report:
+
+```
+> 📒 chat-history status
+>
+> File:       agents/runtime/.agent-chat-history  ({size_kb} KB / {max_size_kb} KB)
+> Entries:    {entries}
+> Schema:     v{header.v}  (started {header.started})
+> Frequency:  {header.freq}
+> Overflow:   {on_overflow}
+>
+> Last entries:
+>   {ts_1}  {type_1}  {preview_1}
+>   {ts_2}  {type_2}  {preview_2}
+>   ...
+```
+
+Keep previews short (≤ 60 chars). Do not render the full entry text
+unless the user asks (avoids flooding the conversation with old log
+data, see [`token-efficiency`](../rules/token-efficiency.md)).
+
+### 5. Offer follow-ups (optional)
+
+If the file is close to `max_size_kb` (> 80 %), mention it — the next
+append may trigger overflow handling. To pull a specific prior
+session into the current chat verbatim, point the user at
+`/chat-history import`; to mine a prior session for project-improving
+learnings, `/chat-history learn`. The body filter on `s` is the v4
+isolation surface in both cases.
+
+## Gotchas
+
+- `agents/runtime/.agent-chat-history` is git-ignored. This command never commits.
+- The helper is the only way to read the file — do not cat or parse
+  the JSONL directly; entry shape is owned by `scripts/chat_history.py`.
+- If `exists: false` but the rule says logging is enabled, the file is
+  created lazily on the first append. That is expected — not an error.
+
+## See also
+
+- [`chat-history-platform-hooks`](../../../agents/settings/contexts/chat-history-platform-hooks.md) — the hook-only contract
+- [`agent-settings` template](../templates/agent-settings.md) — `chat_history.*` reference
+- [`scripts/chat_history.py`](../../../scripts/chat_history.py) — helper API (`status`, `read`, `sessions`, `prune-sessions`)

package/dist/agent-src/commands/chat-history.md

@@ -0,0 +1,60 @@
+---
+model_tier: medium
+name: chat-history
+disable-model-invocation: true
+pack: meta
+tier: 2
+description: Chat-history orchestrator — routes to show, import, learn
+cluster: chat-history
+type: orchestrator
+suggestion:
+  eligible: true
+  trigger_description: "show chat-history status, inspect agents/runtime/.agent-chat-history log, import a prior session into the current chat, mine a prior session for project-improving learnings"
+  trigger_context: "user wants to inspect the persistent agents/runtime/.agent-chat-history log, pull a prior session in verbatim, or extract learnings from a prior session"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+<!-- cloud_safe: noop -->
+
+# /chat-history
+
+Top-level orchestrator for the `/chat-history` family. After the
+hook-only reduction (`road-to-chat-history-hook-only`) writes and
+overflow handling are driven entirely by platform hooks +
+`scripts/chat_history.py` internals; the surfaced sub-commands are
+read-only on the log itself. Sessions coexist in one log file —
+each entry self-tags via the `s` field — so there is no ownership
+layer to recover from.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/chat-history show` | `commands/chat-history/show.md` | Inspect the log — size, entries, header, last entries |
+| `/chat-history import` | `commands/chat-history/import.md` | List prior sessions, pick one, render its entries verbatim — selective cross-session import |
+| `/chat-history learn` | `commands/chat-history/learn.md` | List prior sessions, pick one, mine it for project-improving learnings via `learning-to-rule-or-skill` |
+
+## Dispatch
+
+1. Parse the user's argument: `/chat-history <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the routed file and follow its `## Steps`
+   section verbatim with the remaining args.
+4. If the sub-command is unknown or missing (including the bare
+   `/chat-history` invocation), route to `show` — the safe,
+   current-session inspector default. `import` and `learn` are
+   opt-in only.
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** — `show` and `import` are
+  read-only; `learn` writes proposal drafts under
+  `agents/proposals/` only and does not commit them.
+- **Do NOT chain sub-commands.** One `/chat-history <sub>` per turn.
+- **`import` and `learn` cross the session boundary** — only run
+  them when the user explicitly asked for cross-session reading.
+  The default read path (filtered to current session) stays in
+  effect for every other tool.