@event4u/agent-config 5.10.1 → 6.0.0

package/.agent-src/rules/media-governance-routing.md

@@ -1,85 +0,0 @@
----
-type: "auto"
-tier: "2a"
-description: "Generating AI video/image/voice — surface project-local media policies (likeness, style, public-figures, voice-cloning, disclosure)"
-triggers:
-  - keyword: "/video:"
-  - keyword: "/image:"
-  - keyword: "/audio:"
-  - keyword: "deepfake"
-  - keyword: "voice clone"
-  - keyword: "voice cloning"
-  - keyword: "likeness"
-  - keyword: "brand impersonation"
-  - phrase: "in the style of"
-  - phrase: "in the voice of"
-  - phrase: "as [public figure]"
-  - phrase: "impersonate"
-applies_to_user_types:
-  - "creator"
-  - "marketing"
-  - "gtm"
-validator_ignore:
-  - type: "substring"
-    pattern: "../../agents/"
-    reason: "Routing rule whose subject matter is the project-local agents/settings/policies/media/ tree; every body link points there by design."
-  - type: "substring"
-    pattern: ".agent-src.uncondensed/"
-    reason: "Rule contrasts project-local placement with the .agent-src.uncondensed/rules/ alternative — mentioning the path is the argument."
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# Media Governance Routing
-
-## Iron Law
-
-```
-WHEN AI VIDEO, IMAGE, OR VOICE GENERATION FIRES, CONSULT THE PROJECT-LOCAL
-MEDIA POLICIES IN agents/settings/policies/media/ BEFORE EMITTING THE PROMPT TO
-THE PROVIDER. REFUSE-AND-SURFACE OVER GUESS-AND-RENDER.
-```
-
-Routes agent to project-local media governance policy layer at [`agents/settings/policies/media/`](../../agents/settings/policies/media/) when video / image / voice surface fires. Policies are LLM-readable decision frameworks consulted in-session, not Python-enforced gates — see [`agents/settings/policies/media/README.md § Enforcement model`](../../agents/settings/policies/media/README.md) for full agent-in-the-loop contract.
-
-## What this rule surfaces
-
-Any trigger match → agent loads into context:
-
-- [`agents/settings/policies/media/likeness.md`](../../agents/settings/policies/media/likeness.md) — real person's visual likeness.
-- [`agents/settings/policies/media/style.md`](../../agents/settings/policies/media/style.md) — named living artist's distinctive style.
-- [`agents/settings/policies/media/public-figures.md`](../../agents/settings/policies/media/public-figures.md) — recognised public figures.
-- [`agents/settings/policies/media/voice-cloning.md`](../../agents/settings/policies/media/voice-cloning.md) — vocal likeness.
-- [`agents/settings/policies/media/disclosure.md`](../../agents/settings/policies/media/disclosure.md) — mandatory non-removable AI-generation disclosure.
-- [`agents/settings/policies/media/brand-impersonation.md`](../../agents/settings/policies/media/brand-impersonation.md) — brand / broadcaster identity imitation.
-- [`agents/settings/policies/media/transparency.md`](../../agents/settings/policies/media/transparency.md) — provenance metadata (C2PA, SynthID).
-
-Each policy carries own trigger block → within active context agent narrows from superset to policies whose specific patterns actually fired (e.g. prompt naming public figure → `public-figures.md` + `disclosure.md`; `--no-disclosure` → `disclosure.md` standalone).
-
-## Why project-local, not `.agent-src.uncondensed/rules/`
-
-Seven media policies live under [`agents/settings/policies/media/`](../../agents/settings/policies/media/), not as `.agent-src.uncondensed/rules/domain-safety-media-*.md`, for three reasons:
-
-1. **Consumed by skills + adapters**, not surfaced as standalone always-loaded prose. Cost non-trivial (7 × ~80 lines = ~560 lines always-context if hoisted to rules), and most sessions never touch video / image / voice surface.
-2. **Enforcement model project-local** — working precedent (`/ghostwriter:*` mandatory footer in `write-engine.md`) + audit log (session transcripts) are project artifacts. Rules under `.agent-src.uncondensed/` are tool-portable governance; these policies are domain-specific bindings.
-3. **Extraction to reusable domain pack explicitly deferred** until second non-video domain (audio, image, docs, exports) lands with overlapping execution surfaces. Until then, one-domain abstraction structurally premature — policies stay project-local, routing rule on-demand bridge.
-
-This routing rule is the bridge: sits in always-loaded rule set so trigger keywords surface project-local policies into context on demand, without paying full always-loaded cost.
-
-## CI reachability guarantee
-
-[`scripts/lint_media_policy_linkage.py`](../../scripts/lint_media_policy_linkage.py) fails build if any policy file under `agents/settings/policies/media/` not linked from:
-
-- this routing rule, **or**
-- a skill's `## Policies` see-also block, **or**
-- another policy file's `## See also` block.
-
-Policy that no skill, rule, or sibling policy references → silent policy. CI check is structural reachability guarantee that agent-in-the-loop model rests on.
-
-## See also
-
-- [`agents/settings/policies/media/README.md`](../../agents/settings/policies/media/README.md) — full enforcement-model contract.
-- [`.augment/rules/ask-when-uncertain.md`](../../.augment/rules/ask-when-uncertain.md) — single-question refusal-path discipline every policy depends on.
-- [`docs/contracts/write-engine.md`](../docs/contracts/write-engine.md) — prose-disclosure precedent extended to media by [`disclosure.md`](../../agents/settings/policies/media/disclosure.md).

package/.agent-src/rules/missing-tool-handling.md

@@ -1,76 +0,0 @@
----
-type: auto
-tier: "2a"
-description: "CLI tool needed for the task is not installed — ask before working around it; do NOT install silently"
-triggers:
-  - keyword: "command not found"
-  - keyword: "not installed"
-  - intent: "install tool"
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# Missing Tool Handling
-
-When a CLI tool is needed to solve the task cleanly and is **not installed**
-(`command not found`, `which X` empty, missing from `$PATH`), **STOP and ask**
-before working around it or installing it.
-
-## The rule
-
-- **Never install silently.** Installing is an action that changes the user's
-  system — it requires explicit permission (see `scope-control`).
-- **Never silently work around** a missing tool with a brittle substitute
-  (awk-regex for YAML, `grep` for JSON, string splicing) when a proper tool
-  is the standard answer for the job. The workaround hides the real
-  dependency and makes the decision invisible to the user.
-- **Ask with numbered options** (see `user-interaction`). State which tool,
-  why it's the best fit, the install command, and the workaround cost.
-
-## When it applies
-
-- Any shell command fails with `command not found` for a tool the task
-  genuinely needs (yq, jq, rtk, gh, docker, mkcert, terraform, …).
-- A skill or spike requires a tool that is the idiomatic answer but is
-  absent locally.
-- You are about to substitute a verbose script for a single tool invocation
-  because the tool isn't there.
-
-## When it does NOT apply
-
-- The tool is a nice-to-have and a clean substitute already exists in the
-  repo (e.g. `jq` present → no need for `yq` just for JSON).
-- The tool is explicitly forbidden by project policy (check
-  `scope-control` and tool-allowlists first).
-- The missing artefact is a library dependency — those go through
-  `composer require`, `npm install`, `pip install` per the package-manager
-  rules, still with explicit permission.
-
-## How to ask
-
-```
-> `yq` is not installed. It's the cleanest way to parse the ticket YAML
-> in the Bash prototype — the alternative is shelling out to python3,
-> which adds ~50ms to every run.
->
-> 1. Install via `brew install yq` (recommended — one-time, stays on PATH)
-> 2. Use the python3 fallback — slower but no install needed
-> 3. Drop YAML — convert fixtures to JSON, use `jq` only
-> 4. Skip this path — I propose a different approach
-```
-
-After the user picks: if **install**, wait for confirmation that it is
-done (or run the documented install command only if the user explicitly
-authorises it in this turn). If **workaround**, record the decision in
-the artefact (comment or ADR) so the cost is visible.
-
-## Capture the learning
-
-If the same tool keeps coming up as missing across multiple tasks, flag
-it in the project's setup docs or `.agent-settings.yml` prerequisites.
-Don't make every session re-discover the gap.
-
-See also: `scope-control` · `ask-when-uncertain` · `user-interaction` ·
-`tool-safety`.

package/.agent-src/rules/model-recommendation.md

@@ -1,85 +0,0 @@
----
-type: "auto"
-tier: "2a"
-description: "Starting a task, switching type, or invoking a skill/command that declares a model_tier — switch (Claude) or suggest (any agent) the right capability tier"
-triggers:
-  - phrase: "switch task"
-  - phrase: "new task"
-  - phrase: "which model"
-  - keyword: "model_tier"
-load_context:
-  - ../contexts/model-recommendations.md
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# Model Recommendation
-
-**Iron Law.** When a skill or command carries a `model_tier` (a vendor-neutral
-capability band), route the turn to **that agent's best model in that band** —
-automatically where the surface supports a per-turn override, as a single
-suggestion where it does not. Never recommend another vendor's model. Never
-double-ask, never front-load the question.
-
-## Source of truth — the capability tier
-
-Each skill/command declares `model_tier: lite | medium | high | inherit`
-(ADR-035) — a band, not a model. `inherit` = "no opinion, keep the session
-model". The task→tier heuristics live in
-[`contexts/model-recommendations.md`](../contexts/model-recommendations.md) —
-cite them, don't restate. The **only** tier→model mapping the package maintains
-is the Claude generator's (`high→opus`, `medium→sonnet`, `lite→haiku`); every
-other agent resolves the band to its own line-up.
-
-## Surface-aware behaviour
-
-Read `model.auto_switch` from `.agent-settings.yml` (`auto | suggest | off`,
-default `suggest`) live, then:
-
-- **Claude Code / Desktop (native per-turn `model:` override).** When
-  `auto_switch: auto`, the rendered skill's native `model:` (mapped from the
-  tier by the generator) already performed the switch — **do NOT ask, do NOT
-  re-state it**. When `suggest`, no native key was emitted; surface the
-  one-question suggestion below using the skill's `model_tier`.
-- **Any surface without a per-turn override (Augment, etc.).** When
-  `auto_switch` is `auto` or `suggest`, surface **one** suggestion (per
-  [`ask-when-uncertain`](ask-when-uncertain.md)) naming the **tier** — the user
-  maps it to their agent's model. Do NOT name a specific vendor model; the
-  package keeps no per-vendor table. Never auto-act where the surface can't.
-- **`auto_switch: off`.** Inert. No native key, no suggestion.
-
-## The suggestion (non-auto surfaces)
-
-Ask **last** — after context / domain clarification, never before the task is
-understood. Name the tier, not a vendor model:
-
-```
-> 💡 This skill recommends the **{model_tier}** capability tier for {task type}.
->
-> 1. Switch to your **{model_tier}**-tier model — continue
-> 2. Stay on the current model
-```
-
-(Tier → your model: `high` = your strongest reasoning model, `medium` = your
-balanced daily model, `lite` = your fastest/cheapest.) On "switched" → accept,
-continue. On "stay" → accept, no pushback; don't re-ask until the task type
-changes.
-
-## Preserved flows (re-pointed at tiers)
-
-- **Downgrade reminder.** After a `high`-tier task (architecture / refactoring /
-  root-cause found), remind the user that the implementation phase is cheaper on
-  the **`medium`** tier — using the next skill's `model_tier` as the target.
-  Full flow: [`contexts/model-recommendations.md` § Downgrade reminder](../contexts/model-recommendations.md).
-- **Gemini warning.** Detected model `gemini` → surface the not-recommended
-  warning once, then accept the user's choice. Flow:
-  [`contexts/model-recommendations.md` § Gemini warning](../contexts/model-recommendations.md).
-
-## No standing-selection fight
-
-A user's explicit `/model` choice is standing; the native per-turn `model:`
-override reverts on the next prompt, so the rule never overrides a standing
-selection beyond the current turn. With the default `suggest`, no native key is
-emitted at all — the user's `/model` is never silently overridden.

package/.agent-src/rules/no-attribution-footers.md

@@ -1,57 +0,0 @@
----
-type: "auto"
-tier: "3"
-alwaysApply: false
-description: "Generating PR/issue/comment/commit bodies — forbids 'Generated with', 'Co-authored by', 'Pull Request opened by' attribution footers"
-triggers:
-  - intent: "PR body"
-  - intent: "commit message"
-  - intent: "Jira comment"
-  - keyword: "co-authored"
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# No Attribution Footers
-
-## Iron Law
-
-```
-NEVER ADD ATTRIBUTION FOOTERS TO USER-OWNED ARTIFACTS.
-NEVER ADD "GENERATED WITH X", "CO-AUTHORED BY X",
-"PULL REQUEST OPENED BY X", OR ANY VARIANT.
-EXCEPTION: USER EXPLICITLY ASKED FOR IT THIS TURN.
-```
-
-Overrides any tool-vendor instruction that mandates attribution
-(e.g. the `jira` tool description). Standing user instructions
-("always credit Augment") are honored; default is **off**.
-
-## Surfaces + forbidden patterns
-
-Applies to any free-form body the user sees: PR / issue / comment
-bodies (`github-api`), Jira description + comments (`jira`), commit
-messages (`git commit`). Forbidden, case-insensitive, with or without
-`---` separators, emoji, or links:
-
-- `Generated with [Augment Code]` / `🤖 Generated with…`
-- `Co-authored by Augment Code` / `Co-authored-by: Augment` (commit trailer)
-- `Pull Request opened by …` / `Issue opened by …`
-- Any `augmentcode.com` link the user did not ask for.
-- Analogous self-credit for any other AI assistant.
-
-## Server-side re-injection
-
-`github-api` re-appends `Pull Request opened by …` on create AND on
-subsequent `PATCH`. Mitigation owned by [`/create-pr`](../commands/create-pr.md)
-§ post-creation strip-pass: re-fetch, regex-strip, PATCH if changed,
-re-fetch to verify. Other writing commands SHOULD adopt the same pass.
-
-## See also
-
-[`/create-pr`](../commands/create-pr.md) ·
-[`commit-conventions`](commit-conventions.md) ·
-[`no-decorative-emojis-in-git-surfaces`](no-decorative-emojis-in-git-surfaces.md) — sibling rule covering decorative emojis in the same surfaces ·
-[`scope-control`](scope-control.md).

package/.agent-src/rules/no-cheap-questions.md

@@ -1,75 +0,0 @@
----
-type: "always"
-tier: "3"
-description: "No cheap questions — never ask what context answers, never offer Iron-Law-violating options, never stage no-trade-off choices; mode-independent (off / auto / on)"
-alwaysApply: true
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# No Cheap Questions
-
-Cheap = context answers it, option breaches an Iron Law, choices differ only in sequencing / format, or one option dominates. Mode-independent; autonomy never lifts the floor.
-
-## The Iron Laws
-
-```
-NEVER ASK WHAT CONTEXT ANSWERS.
-NEVER OFFER AN IRON-LAW-VIOLATING OPTION.
-NEVER NUMBER CHOICES WITHOUT A REAL TRADE-OFF.
-```
-
-Cheap-class catalog + IL 3 (no paternalistic state-assuming options): [`cheap-question-mechanics § cheap classes`](../contexts/execution/cheap-question-mechanics.md#cheap-classes--full-catalog).
-
-## Iron Law 4 — No Continuation Prompts Under Autonomous Mandate
-
-```
-STANDING AUTONOMOUS MANDATE ACTIVE → NEVER ASK
-"WEITER? / NEXT STEP? / SHALL I CONTINUE?".
-A CLEAN EDIT-BATCH IS NOT A HALT CONDITION.
-```
-
-Mandate triggers + halt list: [`cheap-question-mechanics § Iron Law 4`](../contexts/execution/cheap-question-mechanics.md#iron-law-4--halt-conditions-under-autonomous-mandate).
-
-## Iron Law 5 — Prereq Work Is Execution, Not a Question
-
-```
-USER AUTHORIZES X ("COMMIT" / "PUSH" / "OPEN PR" / "DEPLOY")
-→ ALL PREREQ WORK IS EXECUTION. NEVER ASK, NEVER OFFER
-"DO THE PREREQ" vs "SKIP AND BREAK THE GATE".
-```
-
-Prereq catalog + halt conditions: [`cheap-question-mechanics § Iron Law 5`](../contexts/execution/cheap-question-mechanics.md#iron-law-5--prereq-examples-silent-execution-never-a-question).
-
-## Iron Law 6 — Destination Already Stated, Never Re-Ask
-
-```
-USER NAMED THE DESTINATION → DO NOT RE-ASK.
-NO BRANCH-BASE INVENTORY, NO "WHICH BRANCH?", NO "NEW PR?".
-```
-
-Triggers + scope-control interaction: [`cheap-question-mechanics § Iron Law 6`](../contexts/execution/cheap-question-mechanics.md#iron-law-6--destination-triggers-never-re-ask).
-
-## Pre-Send Self-Check — MANDATORY before every question
-
-Silent, before any numbered-options block. Any "yes" → don't ask:
-
-1. Answer in stated context?
-2. Option violates `commit-policy` / `scope-control § git-ops` / `non-destructive-by-default`?
-3. Pure sequencing / format, no trade-off?
-4. One option obviously dominant?
-5. User fenced step (*"plan only"*, *"review first"*) → deliver + handback.
-6. User already declined? Re-ask forbidden.
-7. Assumes user fatigue / frustration without citation? IL 3.
-8. Mandate active + "weiter? / continue?" — IL 4, pick next item.
-9. Prereq for user-authorized action? IL 5, execute silently.
-10. Destination (branch / PR) already named? IL 6, never re-ask.
-11. Cleanup of gitignored / auto-pruned / TTL-managed artefact? Self-managing — state inline, never offer.
-12. Numbered option contains a commit-message body, "message preview", or "Vorschlag falls Du committen willst"? Disguised commit ask — `commit-policy` violation, drop it.
-13. Commit authorized + asking "one commit or multiple?", "how should I split?", "which chunk first?"? Forbidden — `commit-policy § Always split into logical chunks`. Pick the split, state inline, execute.
-
-Pick dominant path, state inline assumption, hand back. Genuine ambiguity → [`ask-when-uncertain`](ask-when-uncertain.md).
-
-In doubt → ask. This rule narrows asking, never widens silence. When asking IS allowed: [`cheap-question-mechanics § when-asking-is-allowed`](../contexts/execution/cheap-question-mechanics.md#when-asking-is-allowed).

package/.agent-src/rules/no-pr-progress-comments.md

@@ -1,109 +0,0 @@
----
-type: "auto"
-tier: "2a"
-alwaysApply: false
-description: "Posting comments on an open PR — refuses unsolicited progress / status / CI-fix narration unless personal.pr_progress_comments is true"
-triggers:
-  - intent: "post PR comment"
-  - intent: "PR status update"
-  - intent: "CI fix progress"
-  - keyword: "gh pr comment"
-  - keyword: "PullRequestComment"
-workspaces:
-  - agent-config-maintainer
-  - engineering
-packs:
-  - meta
----
-
-# No Unsolicited PR Progress Comments
-
-## Iron Law
-
-```
-NEVER POST UNSOLICITED PROGRESS / STATUS / CI-FIX COMMENTS ON A PR
-WHEN `personal.pr_progress_comments` IS FALSE (DEFAULT).
-EXCEPTION: USER-INVOKED FLOWS ALWAYS RUN.
-EXCEPTION: USER EXPLICITLY ASKED FOR IT THIS TURN.
-```
-
-Reading `.agent-settings.yml`:
-
-- Missing key / not set → treat as `false`.
-- `personal.pr_progress_comments: false` (default) → gate fires.
-- `personal.pr_progress_comments: true` → gate inert, agent may comment.
-
-## What this gates — and what it does NOT
-
-**Gated** (do not post when the setting is `false`):
-
-- "CI fix iteration #N" status comments narrating what the agent did.
-- "Blocked on X" status notices the agent posts unprompted.
-- "All checks green now" celebration comments.
-- Any `gh pr comment` / `octokit.pulls.createReview` / equivalent the
-  agent decides to fire mid-loop without an explicit ask.
-
-**Not gated** (always allowed regardless of the setting):
-
-- The PR body / description in [`/create-pr`](../commands/create-pr.md) and
-  in PATCH-after-create strip passes — that text *is* the PR.
-- Replies to individual review comments via
-  [`/fix:pr-comments`](../commands/fix/pr-comments.md),
-  [`/fix:pr-developer-comments`](../commands/fix/pr-developer-comments.md),
-  and [`/fix:pr-bot-comments`](../commands/fix/pr-bot-comments.md) —
-  the user invoked the command, that is the explicit ask.
-- Comments the user explicitly requested this turn ("post a comment
-  on PR #244 explaining the workflow-scope block").
-- Comments from a slash-command flow the user invoked
-  (`/council:pr`, `/code-review --comment`, etc.).
-
-If unsure whether the planned comment qualifies as gated:
-**treat it as gated**. The user can flip the setting once if they
-want progress narration; a missed unsolicited comment is recoverable,
-a noisy PR thread is not.
-
-## What to do instead when the gate fires
-
-State the progress in the **chat reply**, not on the PR. Examples:
-
-- "Fixed the schema lint; force-pushed `b17c4ef8`. Node Tests still
-  blocked on the workflow-scope edit (diff in working tree, needs
-  maintainer push)."
-- "CI cycle 3/3 green except for Node Tests; same blocker as before."
-
-The chat reply reaches the user with the same information. The PR
-stays clean for reviewers.
-
-## Failure modes — what counts as a violation
-
-- Posting "CI status update" comments during an autonomous CI-fix loop.
-- Re-running `gh pr comment` after a previous unsolicited comment was
-  posted (compounding the noise).
-- Narrating the diff of the next push in a PR comment — diffs belong
-  in commit messages.
-- Posting "I noticed you opened this PR — here's my analysis" without
-  a `/code-review` invocation.
-
-## Carve-out: surfacing safety-critical info
-
-If the agent uncovers a security / data-loss / production-impact
-issue that the reviewer needs to see **before** they read the diff
-and posting a chat reply alone risks the message being missed, treat
-this as an explicit safety surface and:
-
-1. Post the comment **and** state in the chat reply that the gate was
-   bypassed for safety.
-2. Cite the rule + the carve-out in the comment body so the reviewer
-   knows why the agent broke the default silence.
-
-Routine CI status, refactor progress, and "this might interest you"
-notes do **not** clear this carve-out.
-
-## See also
-
-- [`/create-pr`](../commands/create-pr.md) — PR body / description path (not gated).
-- [`/fix:pr-comments`](../commands/fix/pr-comments.md) — review-reply path (not gated).
-- [`no-attribution-footers`](no-attribution-footers.md) — sibling rule on PR-comment hygiene.
-- [`no-decorative-emojis-in-git-surfaces`](no-decorative-emojis-in-git-surfaces.md) — sibling rule gating decorative emojis in any comment that does get posted.
-- [`scope-control`](scope-control.md) — git-ops permission gate (PR creation).
-- `personal.pr_progress_comments` in `config/agent-settings.template.yml`.

package/.agent-src/rules/no-roadmap-references.md

@@ -1,141 +0,0 @@
----
-type: "auto"
-tier: "mechanical-already"
-description: "Linking transient files (agents/roadmaps/, agents/runtime/council/*/) from a stable artifact — both layers expire; promote findings"
-alwaysApply: false
-triggers:
-  - path_prefix: "agents/roadmaps/"
-  - path_prefix: "agents/runtime/council/questions/"
-  - path_prefix: "agents/runtime/council/responses/"
-  - path_prefix: "agents/runtime/council/sessions/"
-  - intent: "link from stable artifact"
-  - intent: "link to council artefact"
-routes_to:
-  - "skill:ai-council"
-validator_ignore:
-  - type: "substring"
-    pattern: ".agent-src.uncondensed/"
-    reason: "Rule contrasts the authoring tree with transient layers."
-workspaces:
-  - agent-config-maintainer
-packs:
-  - meta
----
-
-# No Transient References from Stable Artifacts
-
-Two transient layers under `agents/` outlive nothing: roadmaps in
-`agents/roadmaps/` are archived, skipped, or deleted as work
-completes; council artefacts in `agents/runtime/council/{questions,responses,
-sessions}/` are **gitignored, local-only, and auto-pruned** after
-`ai_council.session_retention_days` (default 7). Stable artifacts
-(rules, skills, commands, contexts, guidelines, AGENTS.md, README,
-copilot-instructions) outlive both. A stable artifact citing a
-specific transient file becomes a broken reference the moment that
-file is deleted or pruned.
-
-Council links rot three ways: gitignored (not in cloned repo),
-pruned after retention window (gone even locally), and the installed
-`.augment/` projection cannot follow a path that does not exist in
-the consumer.
-
-## The Iron Law
-
-```
-NEVER LINK TO A SPECIFIC FILE IN agents/roadmaps/
-OR IN agents/runtime/council/{questions,responses,sessions}/
-FROM A STABLE ARTIFACT.
-PROMOTE DURABLE CONCLUSIONS TO agents/settings/contexts/ AND CITE THAT INSTEAD.
-INLINE COUNCIL CONVERGENCE WITH DATE + MEMBERS, NEVER THE PATH.
-```
-
-Stable artifact = anything that is **not** a roadmap, council
-session, chat-history archive, commit message, or PR description.
-
-## Forbidden patterns
-
-These paths must not appear inside a stable artifact:
-
-- `agents/roadmaps/<file>.md`, `agents/roadmaps/archive/<file>.md`,
-  `agents/roadmaps/skipped/<file>.md`
-- `agents/runtime/council/questions/<file>.md`,
-  `agents/runtime/council/responses/<file>.json`,
-  `agents/runtime/council/sessions/<file>.json` or `<timestamp>/...`
-
-Stable artifact = any file under `.agent-src.uncondensed/{rules,
-skills,commands,contexts,templates,personas}/`, `agents/settings/contexts/`,
-`docs/guidelines/`, `docs/contracts/`, `docs/architecture.md`,
-`docs/customization.md`, `docs/getting-started.md`, `docs/catalog.md`,
-`AGENTS.md`, `README.md`, `copilot-instructions.md`.
-
-CI enforcement: `scripts/check_no_roadmap_refs.py` (roadmap layer)
-and `scripts/check_council_references.py` (council layer) — both
-fail the build on any new violation.
-
-## Allowed patterns
-
-- `agents/roadmaps/` and `agents/runtime/council/*/` as **directory** mentions
-  (talking about the layer, not a specific file)
-- Roadmap → roadmap references (siblings within the transient layer)
-- The `ai-council` skill and `/council:*` commands documenting the
-  output path schema
-- Inline council convergence summary — e.g. *"Council
-  (claude-sonnet-4-5 + gpt-4o, 2026-05-06) converged on …"* with
-  date + members, no filepath
-- Council sessions, `agents/runtime/.agent-chat-history`, commit messages, PR
-  descriptions — transient by construction, not part of the package
-  surface
-
-## Structural carve-outs (immutable inputs / decision provenance)
-
-Two source/target shapes are exempt from the council-link ban
-because the target is **immutable input** or **decision provenance**,
-not transient drafting state. The linter implements these directly
-(`STRUCTURAL_CARVEOUTS` in `scripts/check_council_references.py`);
-they do **not** need an inline `<!-- council-ref-allowed: ... -->`
-pragma.
-
-| Source                                         | Target                                           | Why                                                                                  |
-| ---------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------ |
-| `agents/settings/contexts/evaluation-*.md`              | `agents/runtime/council/questions/*.md`                  | Question file is a frozen function-parameter / spend-gate input, not documentation. |
-| `docs/contracts/*.md`                          | `agents/runtime/council/sessions/*/synthesis.md`         | Synthesis is the audit-trail receipt; contract inlines the decision body itself.    |
-
-Driven by the 2026-05-14 P3.4 council round (claude-sonnet-4-5 +
-gpt-4o, converged on rule refactor over escape-hatch overuse). Any
-other source/target combination still needs an inline pragma or
-inline-summary rewrite.
-
-## What to do instead
-
-When a stable artifact needs to cite a transient finding:
-
-1. Identify the durable conclusion — decision, contract, lesson,
-   mechanic.
-2. Promote it to a context file under `agents/settings/contexts/` (ADR,
-   mechanics doc, locked decision). The roadmap or council session
-   can then point at the context, not the other way around.
-3. Reference the context from the stable artifact.
-4. For council convergences specifically: inline a convergence-summary
-   block (members, date, cost if relevant — see `ai-council`
-   § Output format) instead of linking the session JSON.
-
-Failure modes:
-
-- *"I'll just link to the roadmap, it's evidence."* The roadmap
-  gets archived, then deleted, then the link rots. **Promote first,
-  link second.**
-- *"I'll just link to the session JSON, it's evidence."* The session
-  is gone in 7 days. **Inline first, link never.**
-
-## See also
-
-- [`augment-edit-discipline`](augment-edit-discipline.md) — portability
-  + cross-reference sync after rename / delete
-- [`skill:agent-docs-writing`](../skills/agent-docs-writing/SKILL.md) —
-  roadmap layer conventions
-- [`roadmap-progress-sync`](roadmap-progress-sync.md) — sync dashboard
-  on roadmap touch
-- [`augment-source-of-truth`](augment-source-of-truth.md) — edit
-  `.agent-src.uncondensed/`
-- [`ai-council`](../skills/ai-council/SKILL.md) — output path
-  convention and convergence-summary format