@event4u/agent-config 5.10.1 → 6.0.0

package/dist/agent-src/skills/code-review/SKILL.md

@@ -0,0 +1,224 @@
+---
+model_tier: high
+name: code-review
+description: "Use when the user says \"review this\", \"check my code\", or wants feedback on changes. Reviews for correctness, quality, security, and coding standards."
+domain: quality
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# code-review
+
+## When to use
+
+Use this skill when:
+- Reviewing a PR (own or someone else's)
+- Self-reviewing local changes before creating a PR
+- Responding to review feedback on your PR
+- The user asks to "review", "check", or "look at" code changes
+
+## Procedure: Review code
+
+### Mindset
+
+- **Be thorough but pragmatic** — catch real bugs, not style nitpicks that tools handle.
+- **Understand intent first** — read the PR description, linked ticket, and commit messages before looking at code.
+- **Check the full picture** — a change in a service may require changes in tests, migrations, docs.
+- **Assume good intent** — suggest improvements, don't criticize.
+
+### Review order
+
+1. **Understand the goal** — what is this change trying to achieve?
+2. **Architecture** — does the approach make sense? Right layer? Right pattern?
+3. **Correctness** — does it actually work? Edge cases? Error handling?
+4. **Quality** — types, naming, readability, DRY, SOLID?
+5. **Security** — input validation, authorization, injection?
+6. **Performance** — N+1 queries, missing indexes, unbounded queries?
+7. **Tests** — are new paths covered? Are existing tests still valid?
+8. **Conventions** — does it follow project standards?
+
+## Review checklist
+
+The checks below are stack-agnostic. For framework-specific conventions (PSR-12 + `declare(strict_types=1)`, FormRequest, single-action `__invoke`, API Resources, Pest, Blade escaping, Eloquent N+1) defer to the carve-outs:
+- PHP / Laravel → [`laravel`](../laravel/SKILL.md), [`laravel-validation`](../laravel-validation/SKILL.md), [`eloquent`](../eloquent/SKILL.md), [`pest-testing`](../pest-testing/SKILL.md), [`blade-ui`](../blade-ui/SKILL.md), [`php-coder`](../php-coder/SKILL.md)
+- Symfony → [`symfony-workflow`](../symfony-workflow/SKILL.md)
+- Next.js / TS → [`nextjs-patterns`](../nextjs-patterns/SKILL.md), [`react-shadcn-ui`](../react-shadcn-ui/SKILL.md)
+
+### Code quality
+
+| Check | What to look for |
+|---|---|
+| **Type discipline** | New code is fully typed in the project's idiom (PHP typed properties + `declare(strict_types=1)`, TS strict, Python type hints, Go / Rust by construction). |
+| **Style conformance** | Matches the project's formatter / linter output — no reformatting battles, no out-of-band style. |
+| **Naming** | Clear, descriptive names; matches the dominant casing in the surrounding code (camelCase / snake_case / PascalCase per the language's idiom). |
+| **Early returns** | No deep nesting. Guard clauses at the top. |
+| **Single responsibility** | Each class / module / function does one thing. HTTP handlers stay thin. |
+| **No magic** | No reach-through to globals (`app()`, `$_GET`, ambient context). No untyped data shapes leaking out of the I/O boundary. |
+| **Doc comments** | Only where the type system is insufficient (generics, complex shapes). No redundant docblocks. |
+
+### Architecture
+
+| Check | What to look for |
+|---|---|
+| **Layer separation** | Business logic in services / use-cases, not in HTTP handlers. Domain models stay I/O-free. |
+| **Handler shape** | New handlers follow the framework's recommended shape (Laravel single-action `__invoke`, Next.js route handler, Express handler-per-route). See the stack carve-out. |
+| **Input validation** | Validated at the request boundary via the framework's primitive (Laravel `FormRequest`, Zod / class-validator, Pydantic, struct-tag validators). No ad-hoc inline `if` checks. |
+| **Response shaping** | Returns through a transformer / serializer / DTO. Never returns raw ORM entities. |
+| **DTOs / value objects** | Structured data between layers, not raw associative arrays / `any` / `dict[str, Any]`. |
+| **Dependency injection** | Constructor injection (or framework-idiomatic equivalent). No service-locator calls in business logic. |
+
+### Database & Performance
+
+| Check | What to look for |
+|---|---|
+| **N+1 queries** | Relationship / association access in loops without eager / batch loading. |
+| **Missing indexes** | New columns used in `WHERE` / `JOIN` without a supporting index. |
+| **Unbounded queries** | Full-table reads (`Model::all()`, `SELECT *` without `LIMIT`, unpaged list endpoints). |
+| **Raw SQL** | Parameterised queries only. No string concatenation with user input. |
+| **Migrations** | Reversible. Targets the right connection / schema. Idempotent where the platform supports it. |
+| **Money / precision** | Uses an exact-precision type (PHP `decimal` / `Math` helper, TS bigint / decimal lib, Python `Decimal`), never `float`. |
+
+### Security
+
+| Check | What to look for |
+|---|---|
+| **Authorization** | Authz check at every state-changing endpoint (Laravel Policy, Symfony voter, NestJS guard, framework middleware). No unprotected mutating routes. |
+| **Input validation** | All user input validated at the boundary via the framework's primitive. |
+| **Mass assignment** | No bulk-binding raw request payloads to ORM entities without an explicit allow-list (`$fillable` / `$guarded` in Laravel, DTO mapping in TS / Python). |
+| **Injection** | No raw queries / command lines / template strings with unescaped user input. |
+| **Output encoding** | Template output is escaped by default; raw / unescaped output is intentional and reviewed (Blade `{{ }}` vs `{!! !!}`, React `dangerouslySetInnerHTML`, Jinja `\|safe`). |
+| **Sensitive data** | No secrets, tokens, or passwords in code, logs, or error responses. |
+
+### Tests
+
+| Check | What to look for |
+|---|---|
+| **Coverage** | New code paths have tests. Bug fixes have regression tests (RED → GREEN). |
+| **Test quality** | Tests verify behaviour, not implementation details. |
+| **Framework idiom** | Correct conventions for the project's test framework (Pest / PHPUnit, Jest / Vitest, pytest, `go test`, `cargo test`) — see the stack carve-out for specifics. |
+| **Test data** | Provisioned via the project's idiom (seeders, factories, fixtures, builders). |
+| **Assertions** | Meaningful assertions. Not just "no exception thrown". |
+| **Flaky risks** | Time-dependent tests freeze the clock (`travel()`, `jest.useFakeTimers()`, `freezegun`). No reliance on execution speed. |
+
+## Before creating a PR
+
+1. Run the project's quality pipeline (see the stack carve-out for the exact commands — PHP: `quality-tools`).
+2. Run tests via the project's runner (`make test`, `npm test`, `pytest`, `go test ./...`, or the project's wrapper script).
+3. Ensure CI passes on the branch.
+4. Self-review the diff: `git diff origin/main..HEAD`.
+
+## Receiving feedback
+
+### The response pattern
+
+When receiving code review feedback, follow this sequence:
+
+1. **READ** — Complete feedback without reacting.
+2. **UNDERSTAND** — Restate the requirement in your own words (or ask if unclear).
+3. **VERIFY** — Check the suggestion against codebase reality.
+4. **EVALUATE** — Is it technically sound for THIS codebase?
+5. **RESPOND** — Technical acknowledgment or reasoned pushback.
+6. **IMPLEMENT** — One item at a time, test each.
+
+If **any item is unclear**, STOP — do not implement anything yet. Items may be related;
+partial understanding leads to wrong implementation.
+
+### No performative agreement
+
+- **Do NOT** reply with "Great point!", "You're absolutely right!", "Excellent catch!" or similar.
+- **Instead:** Just fix it. "Fixed." or "Updated — [brief description of what changed]."
+- Actions speak louder than words — the code itself shows you heard the feedback.
+
+### Source-specific handling
+
+**Internal team feedback** (trusted colleagues):
+- Implement after understanding — no need for deep skepticism.
+- Still ask if scope is unclear.
+- Skip to action or technical acknowledgment.
+
+**External / Copilot / bot feedback** (less context):
+- Check: Technically correct for THIS codebase?
+- Check: Does it break existing functionality?
+- Check: Is there a reason for the current implementation?
+- Check: Does the reviewer understand the full context?
+- **YAGNI check:** If the reviewer suggests "implementing properly", grep the codebase
+  for actual usage. If unused → suggest removing (YAGNI).
+- If it conflicts with existing architectural decisions → discuss with the team first.
+
+### When to push back
+
+Push back when:
+- Suggestion breaks existing functionality.
+- Reviewer lacks full context.
+- Violates YAGNI (unused feature).
+- Technically incorrect for this stack.
+- Legacy/compatibility reasons exist.
+- Conflicts with architectural decisions.
+
+How: Use technical reasoning, not defensiveness. Reference working tests/code.
+
+### Addressing PR comments systematically
+
+When working through review comments on a PR:
+
+1. **List** all comments and review threads (`gh pr view --comments`).
+2. **Categorize**: blocking → simple fixes → complex fixes.
+3. **Clarify** anything unclear BEFORE implementing.
+4. **Fix** one at a time, test each.
+5. **Reply in the thread** — not as a top-level PR comment.
+
+```bash
+# Reply to a specific review comment thread
+gh api repos/{owner}/{repo}/pulls/comments/{comment_id}/replies \
+  -f body="Fixed in latest commit."
+```
+
+## Output format
+
+When reviewing code, structure feedback by severity:
+
+```
+🔴 **Blocker** — must fix before merge
+Description of the issue and why it's critical.
+
+🟡 **Suggestion** — should fix, improves quality
+Description and suggested improvement.
+
+🟢 **Nit** — optional, minor improvement
+Description.
+```
+
+Group related findings. Don't repeat what the project's linter / type-checker already catches — focus on
+logic, architecture, and things tools can't detect.
+
+## Adversarial review
+
+Before creating a PR or presenting code changes, run the **`adversarial-review`** skill.
+Focus on the "Code changes / Refactoring" attack questions.
+
+## Auto-trigger keywords
+
+- code review
+- PR review
+- pull request
+- review checklist
+- review feedback
+- review changes
+- check my code
+
+## Gotcha
+
+- Don't rewrite code that works and is tested just because you'd write it differently.
+- The model tends to suggest changes that are out of scope — stay focused on the PR's intent.
+- "I would prefer X" is not a valid review comment unless X prevents a bug or violates a rule.
+- Always check if the PR has tests — missing tests is always worth flagging.
+
+## Do NOT
+
+- Do NOT approve without actually reading the code.
+- Do NOT agree with review comments without verifying them against the codebase.
+- Do NOT use performative language when responding to feedback ("Great point!", "Excellent catch!").
+- Do NOT nitpick style issues the project's formatter / auto-refactor (ECS, Prettier, Ruff, gofmt) handles automatically.
+- Do NOT merge without CI passing and quality checks green.

package/dist/agent-src/skills/command-writing/SKILL.md

@@ -0,0 +1,301 @@
+---
+model_tier: inherit
+name: command-writing
+description: "Use when creating or editing a slash command in src/agent-src/commands/ — frontmatter, numbered steps, safety gates — even when the user just says 'add a /command for X'."
+domain: process
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+<!-- cloud_safe: degrade -->
+
+# command-writing
+
+## When to use
+
+* Creating a new slash command in `src/agent-src/commands/{name}.md`
+* Rewriting an existing command (not a typo fix)
+* Deciding whether a request should be a command at all
+* Splitting an oversized command into smaller ones
+
+Do NOT use this skill when:
+
+* The content is a constraint the agent must always honor → use `rule-writing`
+* The content is reference knowledge agents cite → use `guideline-writing`
+* The content is a triggered workflow invoked by the model → use `skill-writing`
+
+## Command vs skill — critical test
+
+| Intent | Artifact |
+|---|---|
+| "User types `/foo` to explicitly run this" | **Command** |
+| "Agent picks this up from description match" | **Skill** |
+
+A command is **user-invoked** and carries `disable-model-invocation: true`.
+A skill is model-invoked via description routing. If both audiences apply,
+author as a skill and add a thin command that delegates to it.
+
+**A command must EARN a top-level slot** — only three justifications:
+**flow-entry**, **state-query**, **product-surface**. Else it's a skill.
+Check first: [`command-clusters` § Command justification](../../../docs/contracts/command-clusters.md#command-justification--a-command-must-earn-a-top-level-slot)
+([ADR-048](../../../docs/decisions/ADR-048-command-justification-rule.md)).
+
+**Categorize at creation (checklist).** New top-level command → declare
+`category:` (schema enum `flow-entry | state-query | product-surface`):
+
+- [ ] **flow-entry** — daily work start (`work`, `git-commit`, `review-changes`).
+- [ ] **state-query** — read-only check (`agent-status`, `project-health`, `profile`).
+- [ ] **product-surface** — deliberately-started feature (`council`, `research`, `roadmap`).
+- [ ] **fits none → it's a skill.** Don't add the command.
+- [ ] **ambiguous?** Omit `category:` + note why — OPTIONAL (validate-when-present);
+  deferring is intentional.
+
+Sub-commands inherit the parent cluster's category — leave `category:` off them.
+Why optional + not yet blocking, + the upgrade trigger:
+[`command-category-governance`](../../../docs/contracts/command-category-governance.md).
+
+## Commands ARE Claude skills (projection reality)
+
+Every `src/agent-src/commands/{name}.md` projects to
+`.claude/skills/{slug}/SKILL.md` via `scripts/condense.py`
+(`generate_claude_commands`). Nested commands flatten with `-`
+(`council/default.md` → `council-default`). Skills + commands share the
+**same `.claude/skills/` namespace** — Claude does not distinguish them.
+
+Authoring consequences:
+
+* Frontmatter `description` is Claude's **routing surface**. Generic
+  phrasing → undertriggering even with `disable-model-invocation: true`,
+  because the in-host suggester, fuzzy search, and any tooling that
+  scans `.claude/skills/` ranks by description match.
+* `disable-model-invocation: true` blocks **automatic** invocation only.
+  It does NOT remove the command from discovery surfaces. Weak
+  description = invisible to the suggester even when intent matches.
+* Trigger phrasing follows the same Iron Law as skill descriptions:
+  name 2+ trigger classes (domains, symptoms, user phrasing), end with
+  the `... even when the user just says ...` tail, ≤ 200 chars. See
+  `skill-writing` § 1b for the canonical before/after.
+* `suggestion.trigger_description` / `suggestion.trigger_context` are
+  **separate** from frontmatter `description` — they drive the in-host
+  suggester (`command-suggestion-policy`), not Claude's skill router.
+  Both matter, both must be precise.
+
+Bottom line: write the command's `description` as if a skill router
+will read it — because one will.
+
+## Procedure
+
+### 0. Run the Drafting Protocol
+
+Creating or materially rewriting a command **must** go through Understand →
+Research → Draft from the
+[`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) rule.
+
+* **Understand** — what user-facing problem does `/{name}` solve in one
+  session? What are the inputs, outputs, side effects?
+* **Research** — **inspect** `src/agent-src/templates/command.md`,
+  grep `commands/` for overlap, and **analyze** 1–2 peer commands
+  (e.g. `create-pr`, `commit`).
+* **Draft** — propose frontmatter (`name`, `description`) first, then the
+  step skeleton. Only fill bodies after both are confirmed.
+
+### 1. Use the template
+
+Canonical source: `src/agent-src/templates/command.md`.
+
+Minimum frontmatter:
+
+```yaml
+---
+name: {command-name}          # must match filename without .md
+description: "Short human-readable summary of what /{name} does"
+disable-model-invocation: true
+skills: [optional-skill-1]    # optional — skills this command delegates to
+suggestion:                   # required (road-to-context-aware-command-suggestion Phase 2)
+  eligible: true              # default; set false to opt out of auto-surfacing
+  trigger_description: "natural-language pattern, comma-separated examples"
+  trigger_context: "concrete signal — branch name, file pattern, recent tool output"
+---
+```
+
+Or, when opting out:
+
+```yaml
+suggestion:
+  eligible: false
+  rationale: "one-line reason this command must be invoked deliberately"
+```
+
+Suggestion-block rules (linter-enforced):
+
+* `eligible` is **required** and must be `true` or `false`.
+* `eligible: true` → both `trigger_description` and `trigger_context` must be
+  non-empty (≥ 10 chars each); the linter rejects empty or overly generic
+  patterns. The suggestion layer never auto-executes; the user always picks.
+* `eligible: false` → `rationale` must be non-empty. Use the opt-out for
+  intentional-only invocations (settings mutations, destructive actions,
+  package-internal tools, niche maintenance).
+* Optional `confidence_floor` (0.0–1.0) and `cooldown` (e.g. `10m`)
+  override the global settings per command.
+
+Eligibility decisions are tracked in
+[`agents/settings/contexts/command-suggestion-eligibility.md`](../../../agents/settings/contexts/command-suggestion-eligibility.md).
+Add or revise entries there before changing a command's `suggestion` block.
+
+When iterating on the description, delegate to the
+[`description-assist`](../description-assist/SKILL.md) skill — approval-gated,
+no silent edits, max two rounds.
+
+### 2. Structure the body
+
+Required sections in this order:
+
+1. `# /{name}` heading + one-line summary
+2. **Source of truth note** — works on `src/`, never on
+   generated directories
+3. `## Steps` — numbered sub-headings `### 1.`, `### 2.`, ...
+4. Final step **presents findings** and asks the user before destructive
+   changes (numbered options per `user-interaction` rule)
+5. Optional `## Rules` — short, command-specific constraints
+
+### 3. Enforce safety gates
+
+* No auto-apply of destructive actions without user confirmation.
+* Every step with side effects (git push, file delete, PR merge) asks first.
+* If the command calls external APIs, list required keys / permissions.
+* If the command edits agent files, target `src/` only.
+
+### 3b. Path conventions in command body
+
+Body links to guidelines / contracts use the verbatim relative form
+(`../../docs/guidelines/...`, `../../docs/contracts/...`); the
+condense-time rewriter handles depth. Do not pre-rewrite in source. Do
+not write `src/` in any markdown link target — the
+file ships into `.augment/commands/` and the prefix breaks consumer
+resolution. The only legitimate `src/` strings in a
+command file are prose mentions and step instructions about where to
+edit (per § 2 above). Canonical reference: `rule-writing` § 3b.
+
+### 4. Enforce the size budget
+
+Normative source: [`size-enforcement`](../../rules/size-enforcement.md) +
+`docs/guidelines/agent-infra/size-and-scope.md`.
+
+| Category | Target |
+|---|---|
+| Ideal | ≤ 120 lines |
+| Acceptable | ≤ 200 lines |
+| Split signal | > 250 lines |
+
+Commands orchestrate, they do not implement detail. If a step needs a
+multi-paragraph explanation, extract it into a skill and call it.
+
+### 5. Validate
+
+* Run `python3 scripts/skill_linter.py src/agent-src/commands/{name}.md`
+  → 0 FAIL.
+* Run `bash scripts/condense.sh --sync` → regenerates `dist/agent-src/commands/{name}.md`.
+* Run `python3 scripts/condense.py --generate-tools` → creates the Claude symlink at
+  `.claude/skills/{name}/SKILL.md`.
+* Run the full CI pipeline locally (see `Taskfile.yml` in this repo for
+  the script list) — must exit 0 except for tolerated warnings.
+
+### 6. Governance baseline (when introducing a new linter check)
+
+**Advisory, reviewer-checked — no CI gate.** When the same PR adds a
+new check to `scripts/skill_linter.py` (or strengthens an existing one)
+such that previously-clean commands now warn, the PR body MUST record
+the pre-existing violations on `main` in a Markdown table:
+
+```markdown
+### Pre-existing baseline (informational)
+
+| Code | Count on main | Bucket |
+|---|---:|---|
+| {new_code} | N | (a) genuine fix · (b) accept · (c) check too aggressive |
+```
+
+Forward-only: the new check applies to **the file under review** and to
+**future** edits. The baseline table is informational so reviewers can
+spot intent (fix-now vs. backlog) without diffing the full lint output.
+See `agents/evidence/analysis/lint-warning-triage.md` for the 3-bucket reference.
+
+## Output format
+
+1. Complete command file at `src/agent-src/commands/{name}.md`
+2. Frontmatter populated, `disable-model-invocation: true` present
+3. Linter output showing 0 FAIL
+4. Generated Claude symlink verified
+
+## Gotchas
+
+* Forgetting `disable-model-invocation: true` — the model will auto-invoke
+  the command as if it were a skill.
+* Numbered options without a "skip" / "no change" path.
+* Steps that silently apply destructive changes — always show summary + ask.
+* Referring to `.augment/` paths for editing — source of truth is
+  `src/`.
+* Duplicating another command's workflow instead of delegating via `skills:`.
+
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every command you author.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, command output blocks state
+  the action result, not "Now we will execute…".
+- Per the post-action summary suppression, the success path emits
+  the artifact (PR URL, commit hash) without a wrapping summary.
+- Per the cheap-question check, never offer "preview vs. execute"
+  as a numbered option when the command's role is to execute.
+
+**Pre-save self-check:**
+1. Does any command step prescribe a "Let me…" or "Found it" output
+   line?
+2. Does the command default to multi-line summaries when a one-line
+   outcome suffices?
+3. Is a confirmation gate used outside the Iron-Law / Routine /
+   Contextual taxonomy?
+4. Are template placeholders (`{{var}}`) accompanied by setup prose
+   instead of action prose?
+
+## Do NOT
+
+* Do NOT set `disable-model-invocation: false`
+* Do NOT auto-apply destructive actions
+* Do NOT inline skill-level detail — delegate
+* Do NOT edit `dist/agent-src/`, `.augment/`, or `.claude/` projections
+* Do NOT exceed the hard size limit without a waiver
+
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) the package's
+`scripts/skill_linter.py`, `scripts/condense.py`, and the `task`
+runner are not available. This skill still applies — but with
+prose-only validation:
+
+* Emit the full command file as a copyable Markdown block. Do not
+  attempt to write it to disk.
+* Self-check the frontmatter against the rules below — `name`,
+  `description`, `disable-model-invocation: true` MUST all be
+  present.
+* Self-check the body shape: numbered steps, explicit safety gates,
+  no inline skill-level detail.
+* Tell the user to save the file under
+  `src/agent-src/commands/{name}.md` and run
+  `task sync && task lint-skills` locally before committing.
+* Skip every reference to running the linter, condenseor, or
+  generators yourself — they only run on the user's machine.
+
+## Examples
+
+Good description (trigger-shaped, outcome-focused):
+
+> "Create a GitHub PR with structured description from Jira ticket and code changes"
+
+Bad description (vague, no outcome):
+
+> "PR command"

package/dist/agent-src/skills/condense-memory/SKILL.md

@@ -0,0 +1,123 @@
+---
+model_tier: inherit
+name: condense-memory
+description: "Use when shrinking always-loaded memory files (AGENTS.md, CLAUDE.md, .cursorrules) via telegraph grammar — refuses sensitive paths, round-trips via .original.md backup."
+domain: process
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: [Bash]
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# condense-memory
+
+> **Experimental.** Output-side telegraph dialect did not meet kill-criterion in [`internal/bench/reports/telegraph-v1.md`](../../../bench/reports/telegraph-v1.md) (`vs_terse` median −9.27 %). Input-side memory condensation is orthogonal use case: savings target always-loaded memory budget, not reply stream. Treat ship-criterion as **per-target measurement**, not v1 verdict.
+
+## When to use
+
+Use when:
+
+- Always-loaded memory file (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `GEMINI.md`, `.windsurfrules`) close to or above host tool's char budget and maintainer wants to recover input-token headroom.
+- Consumer-shipped `templates/AGENTS.md` failing `agents-md-thin-root` cap and pointer-extraction options exhausted.
+- Maintainer asks to "condense this memory file" or "shrink AGENTS.md" or names input-side telegraph.
+
+## Do NOT
+
+- Condense reply, commit message, PR body, ticket summary, or any deliverable written *for* human reader — those are carve-outs in [`telegraph-speak § Carve-outs`](../../rules/telegraph-speak.md) and stay verbatim.
+- Condense path matching sensitive-file denylist (`.env*`, `.netrc`, `credentials*`, `secrets*`, `id_rsa*`, `*.pem|key|p12|pfx|crt|cer|jks`, `.ssh/*`) — script refuses with `SensitivePathError` and so should you.
+- Condense generated file (`dist/agent-src/`, `.augment/`, `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules`) — edit source in `.agent-src.uncondensed/` and regenerate via package's sync + generate-tools scripts (`scripts/condense.sh --sync` + `scripts/condense.py --generate-tools`).
+- Hand-edit condensed memory file in place — run `--decondense` first; next condense pass refuses on body-hash drift (`CondensationRefused`).
+- Commit condensed file without committing matching `.original.md` backup — round-trip breaks otherwise.
+
+## Procedure
+
+1. **Analyse target first.** Before any write, **inspect** target with `view` or `wc -l` to confirm it is always-loaded memory file (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `GEMINI.md`, `.windsurfrules`), not generated, and has prose paragraphs to condense (pointer-only Thin-Root file may net near-zero). Skip rest of procedure if any check fails.
+2. **Check denylist gate.** Run `python3 scripts/condense_memory.py <path> --check` — exit 0 = safe; exit 2 = denylist hit, stop and surface refusal.
+3. **Record baseline.** `wc -c <path>` — capture pre-condensation char count for commit message.
+4. **Condense.** `python3 scripts/condense_memory.py <path>`. Script writes `<path>.original.md` (verbatim backup) and rewrites `<path>` with `original_sha256:` + `condensed_at:` frontmatter.
+5. **Inspect diff.** Eyeball every Iron-Law fence, numbered-options block, code fence, backtick span, `❌`/`⚠️`/`✅` line, and frontmatter pair — all must be byte-identical. Body prose may have lost articles (`the`/`a`/`an`) and auxiliaries (`is`/`are`/`was`/`be`/`that`/`which`).
+6. **Validate idempotency.** Re-run `python3 scripts/condense_memory.py <path>` — clean re-run is no-op (body hash matches). Non-zero exit = stop, escalate.
+7. **Commit both files together.** `<path>` and `<path>.original.md` ship as pair. Backup is rollback path; never commit one without other.
+8. **Rollback path.** If readability fails review at step 5: `python3 scripts/condense_memory.py <path> --decondense` restores backup and deletes `.original.md`.
+
+## Output format
+
+Maintainer-facing report after invoking script MUST contain, in this order:
+
+1. **Diff line** — pre/post `wc -c` as single line (`AGENTS.md: 2,891 → 2,453 chars (−15.1 %)`).
+2. **Backup path** — full path of `.original.md` backup so maintainer can verify it landed on disk.
+3. **Carve-out check** — one line confirming seven carve-out classes round-tripped (`carve-outs: 7 classes preserved · idempotent re-run: clean`).
+4. **Exit-code surface** — on failure, surface verbatim exit code and exception name (`SensitivePathError → exit 2`, `CondensationRefused → exit 3`, `FileNotFoundError → exit 4`); do not paraphrase.
+
+Do **not** narrate algorithm, grammar rules, or carve-out theory — rule and this skill document contract; output reports result.
+
+## Carve-outs — byte-for-byte preserved
+
+Mirrors seven carve-out classes in [`telegraph-speak`](../../rules/telegraph-speak.md). Condensation engine in [`scripts/condense_memory.py`](../../../scripts/condense_memory.py) preserves:
+
+1. **Triple-backtick fences** — any language, any depth.
+2. **Numbered-options lines** — `^>?\s*\d+\.\s` plus `**Recommendation:**` / `**Empfehlung:**` label.
+3. **Backtick spans** — file paths, command names, identifiers inside body prose.
+4. **Status / error markers** — lines starting with `❌`, `⚠️`, `✅`.
+5. **Iron-Law ALL-CAPS lines** — `^[A-Z][A-Z0-9 ,.\-_/']{3,}$`.
+6. **Frontmatter blocks** — `---` fence pairs at head of file.
+7. **Mode markers** per [`role-mode-adherence`](../../rules/role-mode-adherence.md).
+
+Mangling any of these breaks Iron-Law surface host tool reads. Unit tests in `tests/test_condense_memory.py` lock each carve-out class as regression case.
+
+## Idempotency contract — Step 9 guard
+
+Script is **idempotent on clean re-runs**: running it twice on same target is no-op because body hash matches recondensed hash. Script **refuses** on **body drift**:
+
+| State | Outcome |
+|---|---|
+| No frontmatter SHA marker | Condense + write backup + inject SHA. |
+| SHA marker present, body re-condenses to same hash | No-op (return target unchanged). |
+| SHA marker present, body hash diverged | **Refuse** with `CondensationRefused` exit 3. |
+
+If you need to edit condensed memory file, run `--decondense` first, edit restored `.original.md` content, then re-run condenseor. Never hand-edit condensed body — next CI run will either silently corrupt your edit (if it happens to re-condense to same shape) or hard-fail next condense pass.
+
+## Sensitive-path gate
+
+Every read path passes through [`scripts/validate_safe_paths.py`](../../../scripts/validate_safe_paths.py) `assert_safe()` before bytes leave disk. Gate is security floor for Phase 2 (input-side condensation) per `step-16-telegraph-substance.md` Phase 0; rollback of gate is rollback of this skill.
+
+CLI exit codes:
+
+- `0` — condense / decondense / check succeeded.
+- `2` — `SensitivePathError` (path matched denylist).
+- `3` — `CondensationRefused` (body hash diverged from frontmatter SHA).
+- `4` — `FileNotFoundError` (no `.original.md` backup to restore).
+
+## Gotchas
+
+- **Body-hash drift after manual edit** — hand-editing condensed body breaks `original_sha256:` invariant. Next condense pass refuses with `CondensationRefused` (exit 3). Recovery: `--decondense`, edit restored body, re-condense.
+- **`.original.md` backup missing on `--decondense`** — exit 4 (`FileNotFoundError`). Either someone deleted backup or `--decondense` already ran. Restore from git history; never regenerate backup by hand (regenerated content would not be byte-identical).
+- **Denylist false positive** — sensitive-looking filename outside denylist surface (project-specific naming) will still pass `assert_safe()`. Denylist necessary but not sufficient; maintainer responsible for never feeding secrets to condenseor.
+- **Frontmatter ordering with existing keys** — if target already has frontmatter, condenseor preserves existing keys, drops any prior `original_sha256:` / `condensed_at:` entries, and appends new pair. Other agents reading file should treat SHA + timestamp pair as canonical condensation marker, not file size.
+- **Negative savings on pointer-heavy files** — `templates/AGENTS.md` already following Thin-Root (≥ 40 % pointers, ≥ 60-char *why*-clauses) has little prose left to drop; condensation may net near-zero or even add bytes via frontmatter. Run [`agents-md-thin-root`](../agents-md-thin-root/SKILL.md) first to maximise pointer share, then measure whether this skill still pays.
+- **Generated-tree drift** — condensing `.agent-src.uncondensed/templates/AGENTS.md` does NOT propagate to `.augment/`, `.claude/`, etc. until package's sync + generate-tools scripts run (`scripts/condense.sh --sync` + `scripts/condense.py --generate-tools`). Always regenerate after condensing templated file.
+
+## Measurement — when to condense
+
+No published `telegraph-v2` baseline for input-side savings yet (Step 11 of `step-16-telegraph-substance.md` ships that). Until then, maintainer judges per-target whether condensation pays its readability cost. Suggested workflow:
+
+1. `wc -c <path>` before — record baseline char count.
+2. `python3 scripts/condense_memory.py <path>` — condense + back up.
+3. `wc -c <path>` after — record post-condensation char count.
+4. Eyeball diff: does prose stay legible? Are all Iron-Law fences intact?
+5. If yes → commit both `<path>` and `<path>.original.md`. If no → `--decondense`.
+
+Future `telegraph-v2.md` will tabulate realised input-token saving against `agents-md-thin-root` 40 % pointer-ratio constraint so maintainer has numerical floor.
+
+## Cross-references
+
+- [`telegraph-speak`](../../rules/telegraph-speak.md) — runtime rule script mirrors for input-side targets; `telegraph.speak_scope` does **not** gate this script (input-side runs regardless).
+- [`scripts/validate_safe_paths.py`](../../../scripts/validate_safe_paths.py) — Phase 0 gate; ported from upstream Telegraph `63a91ec`.
+- [`scripts/condense_memory.py`](../../../scripts/condense_memory.py) — implementation.
+- [`tests/test_condense_memory.py`](../../../tests/test_condense_memory.py) — regression locks for each carve-out + idempotency + denylist.
+- [`docs/contracts/condensation-default-kill-criterion.md`](../../../docs/contracts/condensation-default-kill-criterion.md) — v1 verdict (output-side; informs but does not gate this skill).
+- [`agents-md-thin-root`](../agents-md-thin-root/SKILL.md) — caps consumer-shipped `templates/AGENTS.md`; this skill is one tool to land under cap.