@event4u/agent-config 8.12.0 → 9.0.0

package/dist/agent-src/skills/merge-conflicts/SKILL.md

@@ -43,6 +43,27 @@ For each conflicted file:
 3. **Understand "theirs"** — what does the incoming branch intend?
 4. **Check if both changes are needed** — often both sides added different things.
 
+### 2b. Merge Resolution Plan — mandatory before touching a conflict
+
+After reading both sides, write the plan; under `autonomous-execution` the
+approval gate applies (a standing mandate states the plan and proceeds; an
+interactive session surfaces it and waits):
+
+```
+## Merge Resolution Plan
+- Conflicts: {N files / M hunks}
+- Execution order: {dependency leaves first — a file nothing else imports
+  resolves before the files that import it}
+| file | strategy | rationale |
+|---|---|---|
+- Decisions needed from the user: {semantic/deleted-modified items, or none}
+- Validation: {targeted checks to run after resolution}
+```
+
+**Backup before resolution:** every deleted-modified file is copied to a
+temp path (`$TMPDIR/merge-backup-<ts>/<file>`) and the path noted in the
+plan BEFORE any resolution touches it.
+
 ### 3. Resolution strategies
 
 | Situation | Strategy |
@@ -54,6 +75,8 @@ For each conflicted file:
 | Migration conflicts (same timestamp) | **Rename** — adjust timestamp to avoid collision |
 | Auto-generated files (OpenAPI spec, baselines) | **Regenerate** — resolve source, then regenerate the output |
 | Formatting-only conflicts | **Accept either** — then run quality tools to normalize |
+| Import-block conflicts (both sides added imports) | **Keep both** — union the imports, drop duplicates, let the linter order them |
+| Binary files (images, archives, compiled assets) | **Pick one side whole** — never splice; regenerate from source if generated, else ask which side wins |
 
 ### 4. File-type specific rules (stack-aware)
 
@@ -104,6 +127,13 @@ For each conflicted file:
 - Import statement ordering
 - Formatting-only differences
 
+### 5b. Resolution log — one line per conflict
+
+Every resolved conflict gets a one-line explanation ("kept both — additive
+imports"; "took theirs — lockfile regenerated") collected into the final
+summary: the auditable log the reviewer reads instead of re-deriving each
+hunk decision.
+
 ### 6. Verify after resolution
 
 After resolving ALL conflicts:

package/dist/agent-src/skills/pdf-tools/SKILL.md

@@ -0,0 +1,101 @@
+---
+model_tier: medium
+name: pdf-tools
+description: "Use when creating, merging, splitting, filling, or extracting from a PDF — library-per-task, output validated. Triggers on 'merge these PDFs', 'fill this PDF form', 'split the PDF', 'create a PDF'."
+status: active
+tier: senior
+domain: process
+compatibility: "Requires consumer-installed PDF libraries: pypdf (merge/split/rotate/encrypt/extract), reportlab (create), a form library for AcroForm fill; an OCR engine (e.g. tesseract) only for the OCR task. No LibreOffice dependency. Ships zero runtime in this package."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# pdf-tools
+
+Wing-1 engineering skill for **PDF write/transform** — `markitdown` reads a PDF
+to Markdown; this creates, merges, fills, and extracts. Ships zero runtime: the
+agent drives libraries the consumer has. Pattern re-implementation only.
+
+## When to use
+
+- "Merge / split / rotate / encrypt these PDFs."
+- "Fill this PDF form (AcroForm) with these values."
+- "Create a PDF from this content."
+- "Extract the text / tables from this PDF" (structured extraction beyond `markitdown`'s Markdown).
+- "OCR this scanned PDF."
+
+Do NOT use for: PDF → Markdown ingestion (`markitdown`); Word (`docx-authoring`).
+
+## Procedure
+
+### 1. Library per task — do not force one tool
+
+| Task | Library path |
+|---|---|
+| merge / split / rotate / encrypt | pypdf — page-level operations, no rendering |
+| create from content | reportlab (canvas / platypus) |
+| form-fill (AcroForm) | a form-aware library; map field name → value, then flatten if the form must not be re-editable |
+| text / table extraction | a text-layer extractor; tables need a layout-aware pass, not naive text |
+| OCR (scanned/image PDF) | an OCR engine over rasterized pages — ONLY when there is no text layer |
+
+### 2. Decide flatten-or-keep on form fills
+
+A filled AcroForm stays editable unless flattened. Flatten when the PDF is a
+final artifact (an invoice, a signed form); keep fields when the recipient must
+edit further. State which you chose — a silently-editable "final" form is a
+correctness bug.
+
+### 3. Validate — assert output validity, do not trust the write
+
+1. Re-open the output with pypdf; assert `len(reader.pages)` matches the expected count (merge = sum; split = 1 per part).
+2. For a form-fill: read back one field value (pre-flatten) or extract the rendered text (post-flatten) and assert the value is present.
+3. For create: assert the file opens and page 1 carries expected text.
+
+## Output format
+
+1. The output PDF path(s).
+2. Validation: page count matches expected ✅, read-back value/text present ✅.
+3. For fills: flatten decision stated (flattened / kept-editable + why).
+
+## Gotcha
+
+**OCR is a last resort, not the default extraction path.** Running OCR over a
+PDF that already has a text layer produces worse output (OCR errors) than the
+existing text and burns time. Check for a text layer first; OCR only when it is
+genuinely absent.
+
+- **Editable "final" form:** a filled AcroForm left un-flattened ships as a "signed invoice" the recipient can silently alter → flatten when the artifact is final.
+
+## Do NOT
+
+- Do NOT bundle a Python toolkit in this package — drive the consumer's libraries (zero-runtime posture).
+- Do NOT OCR a PDF that has a text layer.
+- Do NOT leave a "final" filled form editable without saying so.
+- Do NOT claim success on "file written"; claim it only after the re-open + page-count assertion.
+
+## Related Skills
+
+**WHEN to use this**
+
+- The task creates, merges, splits, rotates, encrypts, or form-fills a PDF.
+- Structured text/table extraction beyond `markitdown`'s Markdown, or OCR of a scanned PDF.
+
+**WHEN NOT to use this**
+
+- PDF → Markdown ingestion → [`markitdown`](../markitdown/SKILL.md).
+- Word documents → [`docx-authoring`](../docx-authoring/SKILL.md); spreadsheets → [`spreadsheet-authoring`](../spreadsheet-authoring/SKILL.md).
+
+## When the agent should load this
+
+- "Merge / split / rotate these PDFs."
+- "Fill this PDF form."
+- "Create a PDF from this content."
+- "Extract the tables from this PDF / OCR this scan."
+
+## Output
+
+1. **Output PDF(s)** — the path(s). Cite as `pdf-output`.
+2. **Validation receipt** — page count matches expected ✅, read-back value/text present ✅. Cite as `pdf-validation`.
+3. **Fill decision** — present on form-fills: flattened / kept-editable + why. Cite as `pdf-fill-decision`.

package/dist/agent-src/skills/quality-tools/evals/evals.json

@@ -0,0 +1,15 @@
+{
+  "skill": "quality-tools",
+  "_calibration": "Seed for eval-schema v2 (ecosystem-harvest skill-quality-gates Phase 2). tool-choice + trajectory assertions are trace-gated: pass:null (manual-pending) in CI until a recorded tool-trace.json exists.",
+  "scenarios": [
+    {
+      "id": "runs-project-pinned-tools",
+      "prompt": "Fix the failing lint on the changed files.",
+      "environment": "a project whose pinned quality CLI is defined in its task runner",
+      "assertions": [
+        { "kind": "tool-choice", "must_use": ["bash"], "must_not_use": [] },
+        { "kind": "trajectory_budget", "n": 8 }
+      ]
+    }
+  ]
+}

package/dist/agent-src/skills/security-audit/SKILL.md

@@ -40,6 +40,30 @@ Do NOT use when:
 
 ## Procedure: Security audit
 
+### 0. False-positive gate — restate the claim before reporting
+
+Before any finding enters report, restate as one falsifiable sentence naming all three:
+
+1. **Privilege level** — access attacker already has (anonymous, authenticated user, tenant admin, CI runner).
+2. **Execution context** — where vulnerable code runs (request handler, queue worker, sandboxed template, build step).
+3. **Attacker precondition** — concrete state or input attacker must control to trigger it.
+
+Any of the three not concretely nameable → **not a finding yet** — trace further or drop with one-line reason.
+
+**Rationalizations to Reject:**
+
+| Rationalization | Reality |
+|---|---|
+| "It looks dangerous" | Pattern-recognition is not analysis — trace the full data flow from entry to sink first |
+| "This is clearly critical" | Complete a devil's-advocate pass — models systematically overrate severity |
+| "Report it just in case" | Over-reporting erodes trust; an unverifiable finding is noise, not diligence |
+| "Same pattern as a known CVE" | Same pattern ≠ same preconditions — verify the preconditions hold in THIS codebase |
+
+**Standard vs. Deep verification routing:**
+
+- **Standard** — traced data flow + all three claim elements named → report with normal field list.
+- **Deep** — severity High/Critical, OR precondition chain crosses trust boundary you did not trace → devil's-advocate pass first: actively try to refute finding (existing middleware? framework default? type system? config?). Report only what survives; killed findings listed one-line under *Rejected candidates* so triage is auditable.
+
 ### 1. Map attack surface
 
 Identify all entry points where untrusted data enters:
@@ -78,6 +102,9 @@ User Input → Controller → Validation → Service → DB/File/External
 | **Secret exposure** | Hardcoded credentials, secrets in logs, `.env` in public dir |
 | **Rate limiting** | Missing throttle on auth endpoints, password reset, API |
 | **Header injection** | User input in response headers, email headers |
+| **Insecure defaults / fail-open** | Guards that allow on error (`catch { return true }` in an authz check), default-allow matchers, debug mode defaulting on, permissive CORS/`verify=false` fallbacks, feature flags whose missing value grants access |
+
+Worked example (fail-open): `if (!$gate->check($user)) { … }` wrapped in `try/catch` that logs and **continues** fails open — exception in gate grants access. Finding shape: Category *Insecure defaults*, Evidence the catch block `file:line`, Fix *fail closed — rethrow or deny on gate error*.
 
 ### 4. Framework-specific checks
 
@@ -108,6 +135,8 @@ For each vulnerability:
 - **Fix:** concrete mitigation
 - **Confidence:** Low / Medium / High
 
+After findings, add **Rejected candidates** section: one line per look-dangerous-but-benign pattern the Step-0 gate killed, with traced reason ("raw SQL string is a static migration constant — no user input reaches it"). Audit that rejects nothing has usually skipped the gate.
+
 ## Integration with other skills
 
 - **analysis-autonomous-mode** — routes here when security concerns are detected

package/dist/agent-src/skills/security-maturity-assessment/SKILL.md

@@ -0,0 +1,90 @@
+---
+model_tier: high
+name: security-maturity-assessment
+description: "Use when the user wants a security-maturity scorecard / posture assessment of a module — category ratings with evidence, not a vulnerability hunt. Also on 'wie sicher ist dieses Modul aufgestellt?'"
+domain: quality
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# security-maturity-assessment
+
+Rate how mature a module's security **posture** is — category by category, every rating backed by `file:line` evidence — instead of hunting individual vulnerabilities. Output is a scorecard a maintainer can re-run and diff, not a finding list.
+
+## When to use
+
+- "How mature / well-set-up is this module's security?" — posture, not holes
+- Baseline before a hardening effort, or re-assessment after one
+- A stakeholder needs a defensible rating per category with cited evidence
+
+Do NOT use when:
+
+- Hunting concrete vulnerabilities — route to [`security-audit`](../security-audit/SKILL.md)
+- One route/action's authorization chain — route to [`authz-review`](../authz-review/SKILL.md)
+- Pre-implementation threat model for a new feature — route to [`threat-modeling`](../threat-modeling/SKILL.md)
+- Writing new secure code — route to [`security`](../security/SKILL.md)
+- AI-agent config/behaviour review — route to [`agent-security-review`](../agent-security-review/SKILL.md)
+
+## The nine categories
+
+| # | Category | Critical? | What to inspect |
+|---|---|---|---|
+| 1 | Input validation | **Yes** | Request-boundary validation primitives on every entry point; no inline ad-hoc checks |
+| 2 | Authorization | **Yes** | Per-object ownership/tenant checks, policy coverage, field-level access |
+| 3 | Secrets handling | **Yes** | No hardcoded creds; env/vault usage; secrets absent from logs and VCS |
+| 4 | Error handling | No | No swallowed exceptions; no stack traces / internals leaked to clients |
+| 5 | Logging & audit | No | Security events (auth, permission denials, admin actions) logged; no PII in logs |
+| 6 | Dependency hygiene | No | Lockfiles present; known-CVE scan wired; update cadence visible |
+| 7 | Data boundaries | No | Serializers/resources whitelist fields; exports/queues don't leak internals |
+| 8 | Tenant isolation | **Yes** (multi-tenant only; else N/A) | Tenant scoping on queries, jobs, caches; cross-tenant negative tests |
+| 9 | Security test coverage | No | Negative tests exist (401/403/404 paths, abuse cases), not only happy-path |
+
+## Rating rubric
+
+| Rating | Meaning |
+|---|---|
+| **Missing** | No control exists for the category |
+| **Weak** | Ad-hoc, inconsistent — some paths covered, most not |
+| **Moderate** | Control present and usual, with named gaps |
+| **Satisfactory** | Consistent across the surface; minor gaps only |
+| **Strong** | Consistent AND enforced (CI gate, test, linter) or negatively tested |
+
+## Procedure
+
+1. **Scope** — name the module/paths under assessment; list entry points (routes, jobs, commands, webhooks). Scorecard without stated scope is not reproducible.
+2. **Assess each category** — inspect the code the category names. Every rating cites evidence:
+   - Positive evidence: `file:line` of the control (`app/Http/Requests/…:12`).
+   - Absence evidence: the searches run that came back empty (name the grep patterns) — "not found" beats "probably missing".
+   - Multi-tenant N/A: single-tenant systems rate category 8 `N/A`; drops out of the roll-up.
+3. **Roll up deterministically** — overall rating is computed, not vibed:
+   - `overall = min( median(all rated categories), one step above the lowest critical-category rating )`
+   - Consequences: any critical category **Missing** caps overall at **Weak**; any critical **Weak** caps overall at **Moderate**. Non-critical categories move the median but never lift the cap.
+4. **Recommend** — max 3 next steps, ordered by which would raise the overall rating (fix the lowest critical category first).
+
+## Output format
+
+1. **Scope block** — module/paths + entry-point list, so the scorecard is re-runnable.
+2. **Scorecard table** — one row per category: `Category | Rating | Evidence (file:line or named empty searches) | Gap`. Every row MUST carry evidence; a rating without a citation is invalid.
+3. **Overall rating** — with the roll-up shown (`median=…, lowest critical=…, cap=… → overall=…`), never a bare verdict.
+4. **Top-3 next steps** — ordered by roll-up impact.
+
+## Gotcha
+
+- The model tends to rate from vibes ("looks well-structured") — a rating row without `file:line` or named empty searches is invalid; redo it.
+- Don't let a Strong non-critical category mask a Weak critical one — the cap rule exists precisely because a polished logging setup does not offset missing authorization.
+- A vulnerability found mid-assessment is **out of scope** for the scorecard — note it and route to [`security-audit`](../security-audit/SKILL.md) (with its false-positive gate) instead of inlining findings here.
+
+## Do NOT
+
+- Do NOT emit a rating without evidence — every row cites `file:line` or the empty searches that prove absence.
+- Do NOT average away critical categories — the deterministic cap always wins.
+- Do NOT turn the scorecard into a finding list — posture assessment and vulnerability hunting are different deliverables.
+- Do NOT assess unscoped ("the whole app") when the user named a module.
+
+## See also
+
+- [`security-audit`](../security-audit/SKILL.md) — vulnerability hunting with the false-positive gate.
+- [`defense-in-depth`](../defense-in-depth/SKILL.md) — layering controls the scorecard checks for.
+- [`ai-code-blindspots`](../ai-code-blindspots/SKILL.md) — the per-surface invisible-controls checklist.

package/dist/agent-src/skills/security-maturity-assessment/evals/triggers.json

@@ -0,0 +1,52 @@
+{
+    "skill": "security-maturity-assessment",
+    "last_eval": "2026-07-12",
+    "description": "5 should-trigger + 5 should-not-trigger queries. Should-trigger covers DE + EN posture/scorecard/baseline phrasings. Should-not-trigger covers the neighbouring security skills (vuln hunt, authz chain, threat model, secure coding, agent config) whose vocabulary overlaps.",
+    "queries": [
+        {
+            "q": "how mature is the security posture of our billing module?",
+            "trigger": true
+        },
+        {
+            "q": "give me a security scorecard for this codebase with evidence per category",
+            "trigger": true
+        },
+        {
+            "q": "wie sicher ist dieses Modul aufgestellt? Bitte pro Kategorie bewerten",
+            "trigger": true
+        },
+        {
+            "q": "baseline our security maturity before the hardening sprint",
+            "trigger": true
+        },
+        {
+            "q": "rate input validation, secrets and tenant isolation for the API package",
+            "trigger": true
+        },
+        {
+            "q": "audit this module for SQL injection and XSS vulnerabilities",
+            "trigger": false,
+            "note": "vulnerability hunt → security-audit"
+        },
+        {
+            "q": "review the authorization chain for the invoice download route",
+            "trigger": false,
+            "note": "single-route authz → authz-review"
+        },
+        {
+            "q": "threat-model the new file-upload feature before we build it",
+            "trigger": false,
+            "note": "pre-implementation → threat-modeling"
+        },
+        {
+            "q": "write a policy and gate for this new admin action",
+            "trigger": false,
+            "note": "writing secure code → security"
+        },
+        {
+            "q": "red-team my Claude agent's MCP and hook config",
+            "trigger": false,
+            "note": "agent config/behaviour → agent-security-review"
+        }
+    ]
+}

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

@@ -451,12 +451,91 @@ to every skill you author.
 4. Does the description carry filler ("comprehensive", "advanced",
    "powerful")?
 
+## Read-only-by-default scripts
+
+A script shipped inside a skill (`scripts/**`) is **side-effect-free by
+default** — inspects, computes, prints; does not mutate. Mutation (write /
+delete / rename / copy) gates behind an explicit flag named in this SKILL.md —
+`--writable` / `--apply` / `--write` / `--output` / `--fix` — so the default
+invocation is safe. A generator whose *declared purpose* is to write (emits an
+artifact to a caller-supplied path) is allowlisted with a rationale in
+`src/scripts/lint_skill_scripts_readonly_allowlist.json` instead of a redundant
+flag. `lint_skill_scripts_readonly` enforces this: an ungated, non-allowlisted
+write fails the build.
+
+## Description-optimizer loop (U1 — held-out, not vibes)
+
+Descriptions are the trigger surface; tune them like a model, not like prose:
+
+1. Draft 2-3 candidate descriptions for the skill.
+2. Ensure `evals/triggers.json` has should- AND should-not-trigger queries
+   (grow beyond the 5+5 stub when optimizing — more queries = a real test split).
+3. Run the helper: `npx tsx src/scripts/optimize_skill_description.ts
+   --skill <id> --candidate "…" [--candidate "…"] [--live]` — it splits the
+   queries deterministically into train/held-out, scores every candidate
+   (deterministic token-overlap proxy by default; `--live` = haiku judge,
+   ~$0.001 per query·candidate), and picks the best **held-out** accuracy.
+4. Adopt the pick ONLY if it beats the current description on the held-out
+   split — a train-only win is overfitting to the queries you wrote.
+
+## Self-QA loop for output-producing skills (optional pattern)
+
+For skills whose product is a rendered/structural artifact (decks, docs,
+diagrams, dashboards, generated UI): **assume there are problems** and have a
+fresh-eyes pass find them before handing back. The author-context is blind to
+its own omissions; a context-free verifier is not.
+
+1. Produce the artifact.
+2. Dispatch a fresh subagent (no authoring context) with ONLY the artifact +
+   the acceptance criteria: "list every visual/structural defect; assume at
+   least one exists."
+3. Fix what it finds; re-run once. Two clean passes → done.
+
+Worked example (deck skill): the author renders 12 slides; the fresh-eyes
+pass gets the PDF + "check overflow, contrast, orphaned bullets, broken
+images" — it flags a clipped title on slide 7 the author never re-read.
+One fix, one re-check, done.
+
+Scope: complements `verify-before-complete` (which gates the completion
+claim); this pattern is HOW to get the fresh evidence for artifacts where no
+deterministic checker exists. Skip it when a real validator covers the
+surface (linter, schema, test) — deterministic checks beat judge passes.
+
+## Known-pitfalls section (optional pattern, tool skills)
+
+Tool/integration skills teach the happy path; the recurring support burden is
+the *silent* failures — the ones that cost money, corrupt state, or fail with no
+error. For a high-support-burden tool skill, add a `## Known pitfalls` section
+in this micro-format:
+
+1. **A Symptom → Root cause → Fix table.** Each row starts from the *observable
+   symptom* (what the user sees), not the internal cause — the user greps for
+   the symptom, not the fix.
+
+   | Symptom | Root cause | Fix |
+   |---|---|---|
+   | `<what the user observes>` | `<why it happens>` | `<the concrete action>` |
+
+2. **Optionally, a quick-reference anti-pattern checklist** (Anti-pattern ·
+   cost/impact · fix difficulty) for traps worth scanning before shipping — add
+   it only when it does not restate the skill's existing `## Gotcha` / `## Do
+   NOT`; the table is the load-bearing part.
+
+Sourcing floor — **real, not invented**: every entry names a genuinely common
+failure (a high-vote community question, a documented incident class), never a
+hypothetical. **≤ 5 entries per skill.** The value is a short, sourced,
+high-signal list; a long one is noise. A pitfall is a *section on the existing
+tool skill*, **never** a new skill per pitfall and never a generated grid (see
+[`size-enforcement`](../../rules/size-enforcement.md) § Per-tool pitfall
+content).
+
 ## Do NOT
 
 * Write documentation-style, pointer-only, or too-broad skills ("Laravel skill")
 * Skip Procedure or use vague validation
 * Exceed size limits (see `docs/guidelines/agent-infra/size-and-scope.md`)
 * Duplicate rules
+* Ship a skill script that mutates the filesystem on its default invocation — gate it behind a flag or allowlist it with a rationale
 
 ## Encode usage policy in the description
 

package/dist/agent-src/skills/spreadsheet-authoring/SKILL.md

@@ -41,9 +41,17 @@ prose document/table (that is the document surface, `doc-coauthoring`).
 2. **Formulas over hardcoded values.** Any computed cell holds a **formula**
    (`=SUM(...)`, `=B2*C2`), never the typed-in result. Hardcoding a computed
    value is the cardinal spreadsheet defect — it does not recalculate.
-3. **Read back after every write.** After writing a formula, read the cell back
-   and confirm no formula error (`#REF!`, `#DIV/0!`, `#VALUE!`). The read-back is
-   the spreadsheet's verification truth source.
+3. **Read back after every write, and RECALCULATE first.** After writing a
+   formula, force a recalculation, then read the cell back — a library that
+   writes formulas without recalculating leaves the cached value stale, so a
+   read-back before recalc proves nothing. The **zero-formula-error contract**:
+   any of `#REF!` / `#DIV/0!` / `#VALUE!` / `#N/A` / `#NAME?` in a written cell
+   is a **failure**, not a warning — reject the output and fix the formula. The
+   recalc'd read-back is the spreadsheet's verification truth source.
+   **Formulas, never hardcoded computed values** — a library that writes the
+   Python-computed number into the cell instead of the `=` formula has produced
+   a dead spreadsheet that will not update when inputs change; write the formula
+   string and let the recalc compute it.
 4. **Source-comment web-sourced cells.** Any figure taken from the web carries a
    cell comment with its source. Financial figures follow the
    [`spreadsheet-source-quality`](../../rules/spreadsheet-source-quality.md) rule

package/dist/agent-src/skills/subagent-orchestration/schemas/team-review-status.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$id": "https://event4u.dev/agent-config/schemas/team-review-status.json",
+  "title": "Team Review Status Envelope",
+  "description": "Wire format for every /team:review return — plugin path and multi-host fallback alike. Extends the subagent-status.json frame (same status enum, same NEEDS_CONTEXT/BLOCKED semantics) with review findings, the reviewed ref, and quota visibility. Emitted by src/scripts/ai_team/team_dispatch.ts; contract prose in docs/contracts/ai-team-config.md.",
+  "type": "object",
+  "required": ["status", "findings", "reviewed_ref", "model", "quota"],
+  "additionalProperties": false,
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"],
+      "description": "DONE = review ran, no findings above info. DONE_WITH_CONCERNS = review ran and findings[] needs the caller's attention, OR the model output was unparseable (raw carries the verbatim text — never silently dropped). NEEDS_CONTEXT = reviewer lacks context beyond the bundle; blocking_question must be answered. BLOCKED = no review was produced (auth, quota, transport); blocking_reason describes why."
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1,
+      "description": "One- or two-sentence review outcome."
+    },
+    "findings": {
+      "type": "array",
+      "description": "Review findings. Empty for a clean DONE and for BLOCKED (no review happened).",
+      "items": {
+        "type": "object",
+        "required": ["severity", "evidence", "suggested_fix"],
+        "additionalProperties": false,
+        "properties": {
+          "severity": {
+            "type": "string",
+            "enum": ["critical", "major", "minor", "info"],
+            "description": "critical = data loss / security / correctness on the main path. major = real defect, wrong under realistic input. minor = defect on an edge path or maintainability trap. info = observation, no action required."
+          },
+          "evidence": {
+            "type": "string",
+            "minLength": 1,
+            "description": "What is wrong, citing the exact hunk/line from the reviewed diff — never invented code."
+          },
+          "suggested_fix": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Concrete, minimal fix proposal."
+          },
+          "location": {
+            "type": "string",
+            "description": "file[:line] when known."
+          }
+        }
+      }
+    },
+    "reviewed_ref": {
+      "type": "string",
+      "minLength": 1,
+      "description": "HEAD sha the repo-context bundle was built from — pins what was actually reviewed."
+    },
+    "model": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Reviewer model id, or the literal 'auto' when the codex CLI default was used (no --model flag passed)."
+    },
+    "quota": {
+      "type": "object",
+      "required": ["used", "ceiling"],
+      "additionalProperties": false,
+      "description": "Shared cli_call_budget openai-bucket visibility after this run.",
+      "properties": {
+        "used": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Today's openai-bucket call count (UTC-day, shared with the council)."
+        },
+        "ceiling": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "ai_team.max_calls_per_day — the team-side ceiling on the shared bucket."
+        }
+      }
+    },
+    "raw": {
+      "type": "string",
+      "description": "Verbatim model output, present ONLY when the findings contract could not be parsed (status is then DONE_WITH_CONCERNS). Preserved so a malformed review is loud, never dropped."
+    },
+    "blocking_question": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Single specific question whose answer would unblock. Required when status = NEEDS_CONTEXT."
+    },
+    "blocking_reason": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Why no review was produced (auth_expired → codex login, cli_quota_exhausted, transport error). Required when status = BLOCKED."
+    }
+  },
+  "allOf": [
+    {
+      "if": {"properties": {"status": {"const": "NEEDS_CONTEXT"}}, "required": ["status"]},
+      "then": {"required": ["blocking_question"]}
+    },
+    {
+      "if": {"properties": {"status": {"const": "BLOCKED"}}, "required": ["status"]},
+      "then": {"required": ["blocking_reason"]}
+    }
+  ]
+}

package/dist/agent-src/skills/terraform/SKILL.md

@@ -128,6 +128,16 @@ Each env has a GitHub IAM role with:
 - resources
 - state management
 
+## Known pitfalls
+
+| Symptom | Root cause | Fix |
+|---|---|---|
+| `Error acquiring the state lock` blocks every command | A prior `apply` crashed / was killed and left the lock held (DynamoDB / backend lock) | Confirm no apply is actually running, then `terraform force-unlock <lock-id>` — never delete the lock table |
+| `plan` wants to destroy+recreate a resource after a rename | Renaming a resource block changes its address; Terraform sees the old address gone and a new one added | `terraform state mv <old.addr> <new.addr>` (or a `moved {}` block) so it tracks the same object |
+| `count`/`for_each` errors with "value depends on resource attributes that cannot be determined until apply" | The count/for_each expression reads an unknown (not-yet-created) value | Key `for_each` off a static/known map, or split into a two-stage apply with `-target` |
+| A change applies but the next `plan` shows the same diff again (perpetual diff) | The provider normalizes/computes the attribute differently than written (ordering, defaults, case) | Match the provider's canonical form, or `ignore_changes` on that attribute in `lifecycle` |
+| `plan` shows a resource as tainted/replaced after a manual console change | Out-of-band drift — someone edited the resource outside Terraform | `terraform apply -refresh-only` to reconcile state, then decide code-vs-cloud; stop the manual edits |
+
 ## Gotcha
 
 - `terraform apply` without `-auto-approve` requires interactive confirmation — don't use in CI without the flag.

package/dist/agent-src/skills/test-driven-development/SKILL.md

@@ -83,6 +83,37 @@ talked-around. Externalized to
 [`testing-anti-patterns/process-anti-patterns.md`](../testing-anti-patterns/process-anti-patterns.md)
 to keep this skill under the 400-line sunset trigger.
 
+## Mode contracts — Goal / Activities / Forbidden / Output
+
+The flow runs as four modes. Each Forbidden item names **how a reviewer
+checks it from the diff** — an unverifiable prohibition does not ship.
+
+| Mode | Goal | Activities | Forbidden (diff check) | Output contract |
+|---|---|---|---|---|
+| **Design** | One-sentence behavior + enumerated cases | Steps 1–2 | **No production code** (diff touches no `src/**` production path) · no test bodies yet | Case list (happy/boundary/error) |
+| **Test-Red** | A failing test that fails RIGHT | Steps 3–4 | **No production edits** (diff = `tests/**` only) · test must fail at an **assertion, not an import/setup error** (failure output cites the assertion line) | Failing test + its observed failure reason |
+| **Implement** | Minimum code to green | Steps 5–6 | **No test edits** (no `tests/**` paths in Implement-phase diffs — changing the assertion to fit the code is the canonical violation; genuinely-wrong test → STOP and ask, never silently edit) · no scope beyond the one case | Green run output |
+| **Debug** | Fix a defect found later | (re-enter at 3) | **No bugfix before a reproducing regression test exists** (the fix commit contains a `tests/**` addition that fails without the fix) | Regression test + fix, verified red→green |
+
+### Mode inference on resume
+
+Step 0 of any resume: if `agents/runtime/state/HANDOFF.md` exists, resume
+from its Mode + Contract-owed fields (see `/agent-handoff` file mode) instead
+of re-deriving. Otherwise infer the mode from observable state — never
+assume Design:
+
+| Observed state | Resume in |
+|---|---|
+| No test for the target behavior | Design |
+| Test exists, currently failing at an assertion | Implement |
+| Test exists + passing, defect reported | Debug |
+| Test failing at import/collection error | Test-Red (fix the test, not the code) |
+
+At every mode transition, one consent-checkpoint sentence (per
+`ask-when-uncertain` / `autonomous-execution` — no new mechanism): name the
+mode you are leaving, the output contract you hand over, and the mode you
+enter; under an autonomous mandate the sentence is stated, not asked.
+
 ## Procedure
 
 ### 1. Identify the behavior to test