claude-dev-env 1.38.1 → 1.40.0

package/skills/structure-prompt/reference/canonical-case.md

@@ -0,0 +1,48 @@
+# Mark the canonical sub-bucket with ⭐
+
+When a framework has many sub-buckets, one of them usually carries the category's signature failure mode. Marking that sub-bucket with ⭐ helps the auditing agent give it extra attention.
+
+## Detection
+
+The marker fires when BOTH hold:
+
+- The framework has 5 or more sub-buckets
+- No sub-bucket already carries the ⭐ marker
+
+The third condition — whether a canonical signal exists — is determined during selection (below), not detection. When selection finds no clear canonical case, the marker pass does not mark and instead emits a gap note per the [no silent action](output-contract.md#disposition-invariants) invariant.
+
+## How to pick the canonical sub-bucket
+
+In order:
+
+1. **Rubric match.** When the calling framework provides a sibling rubric (e.g., at `../category_rubrics/<name>.md` in audit-rubric layouts) and that rubric describes a "Canonical example" or names one axis as the signature pattern, pick that sub-bucket. When no sibling rubric exists, skip this step and fall through to bullet density.
+2. **Bullet density.** When the rubric stays silent, count the concrete bullets per sub-bucket. The sub-bucket with the most bullets that cite a real identifier or line number wins.
+3. **Identifier density.** When two sub-buckets tie on bullet count, pick the one whose identifiers appear most often in the data body.
+
+## How to mark it
+
+Append `⭐ canonical <category-letter> case` after the sub-bucket title, on the same line.
+
+Derive `<category-letter>` from the leading letter of the sub-bucket id (`K3` → `K`, `A2` → `A`, `B1` → `B`). When the framework uses non-lettered sub-bucket ids or no ids at all (e.g., bullets titled `Surface 1`, `Item 1`, `Check 1`), drop the letter and write `⭐ canonical case`.
+
+Example before:
+```
+**K3. Primary path vs fallback path**
+- The file's `if resolved_skill_path is not None:` branch (line 121) is the PRIMARY path…
+```
+
+Example after:
+```
+**K3. Primary path vs fallback path** ⭐ canonical K case
+- The file's `if resolved_skill_path is not None:` branch (line 121) is the PRIMARY path…
+```
+
+## What stays put
+
+When a ⭐ marker already lives somewhere in the framework, the marker pass leaves it alone — the prompt's author already chose. The skill marks at most one sub-bucket per invocation.
+
+When research turns up no clear canonical case (the bullets are evenly weighted, no rubric guidance, no identifier-density signal), the marker pass leaves the framework unmarked AND MUST emit a gap note via the paste-mode or file-path-mode gap-report mechanism that [`output-contract.md`](output-contract.md) defines for the active emission mode. The framework reads fine without an arbitrary pick, but the deferral itself is recorded — see the [no silent action](output-contract.md#disposition-invariants) invariant.
+
+## Disposition reporting
+
+Every outcome emits an action note via the mechanism that [`output-contract.md`](output-contract.md) defines. When a sub-bucket was marked: `> Gap: ⭐ canonical <letter> case marker added to sub-bucket "<sub-bucket-id>".` When the framework has fewer than 5 sub-buckets or already carries a ⭐ marker: `> Gap: Canonical-case marker verified — <reason>.` When no clear canonical case exists: `> Gap: Canonical-case marker skipped — framework has 5+ sub-buckets but <rubric match / bullet density / identifier density> found no clear canonical case.` Silent pass is forbidden — see the [no silent action](output-contract.md#disposition-invariants) invariant.

package/skills/structure-prompt/reference/citation-depth.md

@@ -0,0 +1,70 @@
+# Add file:line citations on identifier mentions
+
+When a sub-bucket bullet names an identifier (a function, variable, cmdlet, file path) that also lives in the data body, the bullet earns more value with a `file:line` citation appended.
+
+## Detection
+
+Two separate paths, evaluated for every backtick-wrapped identifier in each bullet:
+
+**Citation-candidate path.** An identifier is a citation candidate when all three hold:
+- The bullet contains a backtick-wrapped identifier (e.g., `os.walk`, `New-ScheduledTaskTrigger`, `_log_walk_error`)
+- The identifier also appears in the data body
+- No `file:line` citation already follows that identifier within the bullet
+
+**Citation-unavailable path.** An identifier triggers the unavailable path when all three hold:
+- The bullet contains a backtick-wrapped identifier
+- The identifier does NOT appear in the data body — its file is not included in the diff or the identifier is external (e.g., a stdlib symbol, a framework API)
+- No `(citation unavailable: <reason>)` marker already follows that identifier within the bullet
+
+Both paths fire independently per identifier. A bullet can contain both citable and unciteable identifiers.
+
+## Procedure
+
+**For citation candidates:**
+1. For each citation candidate, search the data body for the identifier.
+2. Find every occurrence of the identifier in the data body. When the data body uses explicit line numbers (e.g., a code block prefixed with file:line annotations or a diff), use those. When the data body has no line numbers (e.g., a raw pasted dump), use the 1-based line index within the data-body block as `<line>`. Apply the multiple-occurrence policy below to determine which lines to cite.
+3. Append the citation in this format immediately after the backtick-wrapped identifier: `` `identifier` (`<file>:<line>`)``. When the bullet contains multiple identifiers, cite each one inline after its owning backtick span. The `<file>` value comes from the data-body block's heading or label (e.g., the filename in a `### file.py` heading, the diff header, or the code block's language tag). When the data body has no file identity at all (a raw paste with no heading or label), use `data-body:<line>`. The examples below illustrate both single-identifier and multi-identifier bullets.
+
+## Multiple occurrences
+
+When the identifier appears one or more times across the data body:
+
+- 1–3 occurrences → cite all of them: `(file_a.py:42, file_a.py:88, file_b.ps1:12)`
+- 4 or more → cite the first and last with `…` between: `(file_a.py:42, …, file_b.ps1:200)`
+
+## Examples
+
+Before:
+```
+- uses `os.walk` with `_log_walk_error` — `_log_walk_error` matches the exact signature stdlib calls.
+```
+
+After (2 occurrences: definition plus one call site):
+```
+- uses `os.walk` (`sweep_empty_dirs.py:23`) with `_log_walk_error` (`sweep_empty_dirs.py:23, sweep_empty_dirs.py:33`) — `_log_walk_error` matches the exact signature stdlib calls.
+```
+
+Before:
+```
+- `Get-ScheduledTask`, `New-ScheduledTaskTrigger`, `New-ScheduledTaskAction`, `Register-ScheduledTask`, `Unregister-ScheduledTask` — verify each call's parameter shape.
+```
+
+After (one occurrence per cmdlet):
+```
+- `Get-ScheduledTask` (`Install-SweepEmptyDirs.ps1:248`), `New-ScheduledTaskTrigger` (`Install-SweepEmptyDirs.ps1:297`), `New-ScheduledTaskAction` (`Install-SweepEmptyDirs.ps1:296`), `Register-ScheduledTask` (`Install-SweepEmptyDirs.ps1:300`), `Unregister-ScheduledTask` (`Install-SweepEmptyDirs.ps1:267`) — verify each call's parameter shape.
+```
+
+## What stays put
+
+When the identifier is a generic concept (e.g., `if version`, `if FLAG`) rather than a real symbol in the data body, the bullet stays as-written. Citations apply to actual identifiers, not category-shaped placeholders.
+
+When the identifier sits in a file the data body doesn't include (e.g., the bullet mentions `os.walk` but the diff doesn't define it), the citation skips that identifier. The skipped citation MUST emit BOTH:
+
+1. An inline gap marker adjacent to the identifier: `(citation unavailable: <reason>)` — so the bullet is not visually identical to a successful citation when read in isolation.
+2. A gap note via the paste-mode or file-path-mode gap-report mechanism that [`output-contract.md`](output-contract.md) defines for the active emission mode.
+
+Both records are required by the [no silent action](output-contract.md#disposition-invariants) invariant: the reader of the bullet alone must see the gap, and the reader of the output as a whole must see the gap.
+
+## Disposition reporting
+
+Every outcome emits an action note via the mechanism that [`output-contract.md`](output-contract.md) defines. When citations were added: `> Gap: Citations added — <N> identifier(s) cited at file:line.` When no citation candidates exist: `> Gap: Citation-depth verified — no uncited identifiers found.` When a citation was unavailable: `> Gap: Citation unavailable for "<identifier>" — <reason>.` Silent pass is forbidden — see the [no silent action](output-contract.md#disposition-invariants) invariant.

package/skills/structure-prompt/reference/cleanup.md

@@ -0,0 +1,33 @@
+# Surface cleanup
+
+The optimized prompt has consistent surface formatting.
+
+## Pass list
+
+| Surface | State after cleanup |
+|---|---|
+| Typos in mission, metadata, framework, output spec, or questions | Spelled correctly |
+| Bullet style within a single section | Single style throughout (`-`) |
+| Code block language tags | Every fenced block inside the prompt artifact carries a language tag |
+| Trailing whitespace on lines | Removed |
+| Runs of 3+ blank lines | Collapsed to one blank line |
+| Heading levels | Sequential within each block (no jumps from `#` to `###`) |
+
+## Scope
+
+This pass changes surface formatting only. Identifiers, content, and ordering pass through unchanged.
+
+## Typo-correction carve-out
+
+Typo fixes apply only to plain-language prose — narrative sentences, mission statements, instructions to the agent, and similar running text. The pass leaves these surfaces untouched even when they look like typos:
+
+- Text inside backtick code spans (e.g., `` `mispelled_var` `` stays as-is)
+- Text inside fenced code blocks (any language, any content)
+- Identifiers, file paths, URLs, IDs, SHAs, ID prefixes, proper names
+- Any quoted substring the user could be referencing literally (e.g., `"recieve"` in quotes stays as-is)
+
+These surfaces are subject to the byte-for-byte preservation invariant in [`output-contract.md`](output-contract.md). When in doubt about whether a token is prose or a literal reference, leave it unchanged.
+
+## Disposition reporting
+
+Every surface-formatting change emits an action note via the mechanism that [`output-contract.md`](output-contract.md) defines (e.g., `> Gap: Typo corrected in mission line — "recieve" → "receive".`, `> Gap: Code block language tag added — python.`). When the surface pass makes zero changes, emit a single note: `> Gap: Surface cleanup verified — no formatting issues found.` Silent pass is forbidden — see the [no silent action](output-contract.md#disposition-invariants) invariant.

package/skills/structure-prompt/reference/constraints.md

@@ -0,0 +1,33 @@
+# Narrative directives → measurable criteria
+
+Every narrative directive in the optimized prompt names a measurable criterion.
+
+## Detection patterns
+
+A narrative directive opens with a soft verb:
+- "Try to `<X>`"
+- "Look at `<X>`"
+- "Make sure to `<X>`"
+- "Consider `<X>`"
+- "Be sure to `<X>`"
+- "Think about `<X>`"
+
+## Transformation
+
+Rewrite each narrative directive as a hard constraint with a measurable criterion.
+
+| Narrative input | Constraint output |
+|---|---|
+| "Try to be concise" | "Output ≤ 200 words." |
+| "Look at the security aspects" | "Inspect: input validation, auth checks, secret handling." |
+| "Make sure to verify" | "Verify each claim against the source. Cite file:line." |
+| "Consider edge cases" | "Enumerate: empty input, max-size input, concurrent input, malformed input." |
+| "Think about performance" | "Report wall-clock cost and memory cost for each candidate." |
+
+## Omission carve-out
+
+When a narrative directive resists rewriting without inventing scope the original prompt did not authorize, omit the directive from the rewritten prompt AND emit a gap note that records both the omitted directive verbatim and the reason it could not be made measurable (e.g., `> Gap: Omitted directive "Consider the edge cases" — no measurable criterion authorized by the source.`). The gap note routes through the paste-mode or file-path-mode gap-report mechanism that [`output-contract.md`](output-contract.md) defines for the active emission mode. Silent omission is forbidden — see the [no silent no-op](output-contract.md#disposition-invariants) invariant.
+
+## Cross-spoke deduplication
+
+When the [`directives.md`](directives.md) spoke has already produced identical measurable criteria (e.g., both spokes derive the same surface enumeration from overlapping input), the constraints spoke does not emit a duplicate output line. Instead it reports a merged gap note (e.g., `> Gap: Narrative directive "Try to find" merged with directives output — both derived the same measurable criteria "Inspect: SQL injection, XSS, auth issues."`). The gap note records the deduplication, satisfying the [no silent action](output-contract.md#disposition-invariants) invariant without emitting a duplicate line that the rewritten prompt would carry twice.

package/skills/structure-prompt/reference/directives.md

@@ -0,0 +1,37 @@
+# Performance directives → measurable constraints
+
+Every performance directive in the optimized prompt maps to a measurable constraint or a specific scope.
+
+## Detection patterns
+
+Common performance directives:
+- "Take a deep breath"
+- "Think step by step" / "Let's think step by step"
+- "You are an expert"
+- "Be thorough"
+- "Be comprehensive"
+- "Be careful" / "carefully"
+- "Do your best"
+- "Please"
+- "Kindly"
+
+## Transformation
+
+Each directive maps to a measurable constraint or to omission:
+
+| Directive | Replacement |
+|---|---|
+| "Be thorough" | A surface enumeration. e.g., "Inspect: input validation, auth, secret handling." |
+| "Be comprehensive" | A count target. e.g., "Produce at least 8 findings." |
+| "Be careful" / "carefully" | A locator requirement. e.g., "Cite file:line for every claim." |
+| "Think step by step" / "Let's think step by step" | omitted |
+| "Take a deep breath" | omitted |
+| "Please" / "Kindly" | omitted |
+| "You are an expert" | omitted (covered by the mission line) — unless the persona spoke's creative-writing carve-out preserved the role line intact, in which case leave "You are an expert" in place |
+| "Do your best" | omitted |
+
+Every transformation outcome — whether the directive was mapped to a measurable constraint or omitted — MUST emit an action note recording what changed via the mechanism that [`output-contract.md`](output-contract.md) defines (e.g., `> Gap: Directive "Be thorough" replaced with surface enumeration "Inspect: input validation, auth, secret handling."` or `> Gap: Directive "Take a deep breath" omitted — no measurable equivalent.`). See the [no silent action](output-contract.md#disposition-invariants) invariant.
+
+## Show-reasoning carve-out
+
+"Think step by step" stays intact when the prompt explicitly requires the agent to show its reasoning chain in the output. The carve-out MUST emit a gap note via the paste-mode or file-path-mode mechanism that [`output-contract.md`](output-contract.md) defines. See the [no silent no-op](output-contract.md#disposition-invariants) invariant.

package/skills/structure-prompt/reference/examples.md

@@ -0,0 +1,72 @@
+# Worked examples
+
+Each example shows an input prompt and the rewritten output, with a note on which spokes fire.
+
+## Example 1: Code-audit prompt with full diff
+
+**Input shape**
+- Mission, metadata, large 4-file diff, sub-bucket framework (A1-A7), cross-bucket questions, output spec — in that order.
+
+**Spokes that fire**
+- [`structure.md`](structure.md): the diff sits between metadata and framework; relocate to the end.
+
+**Rewritten ordering**
+1. Mission
+2. Metadata
+3. Framework (A1-A7)
+4. Cross-bucket questions
+5. Output spec
+6. Diff (all four files contiguous at the end)
+
+## Example 2: Persona-led generic prompt
+
+**Input**
+> You are a senior security engineer. Be thorough and review this code carefully. Try to find SQL injection, XSS, and auth issues.
+>
+> ```python
+> # ... code block ...
+> ```
+
+**Spokes that fire**
+- [`persona.md`](persona.md): "You are a senior security engineer" → mission line.
+- [`directives.md`](directives.md): "Be thorough" → surface enumeration; "carefully" → locator requirement.
+- [`constraints.md`](constraints.md): "Try to find" → measurable criteria.
+- [`structure.md`](structure.md): code block present → verifies ordering, emits gap note.
+
+**Rewritten output**
+> Audit this code for security issues.
+> Inspect: SQL injection, XSS, auth issues.
+> Cite file:line for every finding.
+> ```python
+> # ... code block ...
+> ```
+>
+> The rewritten prompt carries these `> Gap:` lines recording every spoke that fired (per the [no silent action](output-contract.md#disposition-invariants) invariant):
+> `> Gap: Persona transformed — original "You are a senior security engineer" replaced with mission "Audit this code for security issues."`
+> `> Gap: Directive "Be thorough" replaced with surface enumeration "Inspect: SQL injection, XSS, auth issues."`
+> `> Gap: Directive "carefully" replaced with locator requirement "Cite file:line for every finding."`
+> `> Gap: Narrative directive "Try to find" merged with directives output — both derived the same measurable criteria "Inspect: SQL injection, XSS, auth issues."`
+> `> Gap: Structural ordering verified — input already in canonical sequence.`
+
+## Example 3: Multi-category framework without disposition
+
+**Input shape**
+- Framework names 5 categories. No per-category requirement on emission.
+
+**Spokes that fire**
+- [`per-category.md`](per-category.md): insert canonical disposition line under the category list header.
+
+**Inserted line**
+> Each category returns either at least one finding with a locator OR exactly one proof-of-absence with at least 3 adversarial probes specific to that category. A category returning neither is a protocol gap.
+
+## Example 4: Already-optimized prompt
+
+**Input**
+- Mission first, framework before data body, persona absent, multi-category disposition present, no soft directives, code block tagged.
+
+**Spokes that fire**
+- [`structure.md`](structure.md): code block present → verifies ordering, emits `> Gap:` note recording the check.
+- [`per-category.md`](per-category.md): multi-category framework present → confirms disposition line exists, emits `> Gap:` note.
+
+**Rewritten output**
+- Identical to input save for the appended gap notes from structure and per-category.

package/skills/structure-prompt/reference/instantiation.md

@@ -0,0 +1,51 @@
+# Fill placeholders with real values
+
+Some prompts ship as templates with placeholder tokens. The skill replaces those with concrete values pulled from the rubric, the companion artifact, or the user.
+
+## Detection patterns
+
+A placeholder is any bracketed token whose content reads as instructional rather than a literal name. Common shapes:
+
+- `[REPO/ARTIFACT]`
+- `[TARGET ID]`
+- `[N]`
+- `[ARTIFACT METADATA]`
+- `[INLINE THE FULL ARTIFACT HERE — do not ask the agent to fetch.]`
+- `[List the supported …]`
+- `[Declared minimum …]`
+- `[file:line / paragraph]`
+- `[A1]–[AN]`, `[B1]–[BN]`, etc.
+
+## Procedure
+
+1. Find every placeholder in the prompt.
+2. For each placeholder, look up the value via [`research.md`](research.md).
+3. Replace the placeholder with the real value.
+4. For placeholders matching `[INLINE THE FULL ARTIFACT HERE …]` (any placeholder that opens with `INLINE THE FULL ARTIFACT`, including the long-form `[INLINE THE FULL ARTIFACT HERE — do not ask the agent to fetch.]`), the artifact's text comes from one of the sources [`research.md`](research.md) enumerates — a local file the user named when invoking in file-path mode, a sibling artifact the rubric points at, content the user pasted alongside the prompt, or a path the user supplied via AskUserQuestion. Inline that text as fenced code blocks, using each file's path as a `###` heading above its fenced block. The skill never reaches outside those sources for retrieval; when none of them yields the artifact, the spoke leaves the placeholder in place and records a gap per [`output-contract.md`](output-contract.md).
+
+## When the rubric points at a sibling prompt
+
+Rubric files often say "use category-X.md as the canonical worked example." When that happens:
+
+1. Read the sibling prompt.
+2. Copy the sibling's data body — the inlined artifact — into this prompt's data body.
+3. Sharpen this prompt's sub-bucket bullets so they cite the identifiers in the data body that match this category's axes.
+4. Keep the category-specific phrasing intact. Only the data body and the per-bucket bullets that reference data-body content change.
+
+## Sub-buckets that have nothing to find in the data body
+
+When the data body holds nothing that fits a particular sub-bucket (e.g., a SQL sub-bucket and a diff with no SQL), that sub-bucket stays as a proof-of-absence shape. Spell out three adversarial probes the agent runs to confirm zero relevant content. Use the sub-bucket bullets to name the things the agent searches for.
+
+## What stays put
+
+These elements pass through untouched:
+
+- The mission's category name (e.g., "Category B only") — derived from the file name, not the artifact
+- The per-category disposition statement
+- The cross-bucket question structure (Q1, Q2, Q3 by name)
+- The output spec's lead format (`Total: N (P0=N, P1=N, P2=N)`)
+- The adversarial-pass count and severity tier — handled by [`adversarial-tuning.md`](adversarial-tuning.md) when the noun needs sharpening; the count and tier values come from the original prompt's own adversarial phrase, not a fixed default
+
+## Disposition reporting
+
+Every outcome emits an action note via the mechanism that [`output-contract.md`](output-contract.md) defines. When placeholders were filled: `> Gap: Placeholders instantiated — <N> placeholders replaced with real values.` When no placeholders exist: `> Gap: Instantiation verified — no placeholder tokens found.` When a placeholder could not be resolved: `> Gap: Placeholder "<token>" left in place — no real value found in available sources.` Silent pass is forbidden — see the [no silent action](output-contract.md#disposition-invariants) invariant.

package/skills/structure-prompt/reference/output-contract.md

@@ -0,0 +1,72 @@
+# Output contract
+
+The skill emits exactly one artifact: the rewritten prompt. The emission shape depends on how the input arrived.
+
+## Emission modes
+
+**Paste mode** — input arrives as the user's message body or as a fenced block within it. Emit one fenced block containing the rewritten prompt. Choose a fence length that is strictly longer than the longest consecutive backtick run anywhere in the rewritten prompt (i.e., `max_backtick_run + 1`, with a minimum of four backticks). This ensures no inner fence in the rewritten prompt can prematurely close the outer fence — including cases where the input already used a 4+ backtick wrapper:
+
+``````
+`````
+<rewritten prompt, which may itself contain 4-backtick fences>
+`````
+``````
+
+**File-path mode** — input arrives as a file path argument (e.g., `/structure-prompt path/to/file.md`). File-path mode targets Markdown prompt artifacts; rewriting non-Markdown files is not supported. Rewrite the file in place. Emit a confirmation that names the file, gives the line-count delta, and lists the spokes that fired. When gaps exist, the confirmation also lists them — the output may span multiple lines.
+
+## Disposition invariants
+
+**No silent action** (also referenced as "no silent no-op"). Every spoke that fires MUST record its action. Two cases use the same `> Gap:` mechanism:
+
+- **Deferred.** The spoke elected not to apply its transformation — missing source, ambiguous detection, fallback to user input, carve-out match, or any other reason. The gap note records what was deferred and why.
+- **Applied.** The spoke successfully applied its transformation. The gap note records what changed (e.g., persona transformed, directive replaced, citation added) so the reader can detect the change.
+
+Silent omission is never the correct disposition in either case. The reader of the output must always be able to detect which spokes fired, which deferred, and why.
+
+## Preservation invariants
+
+Two clauses govern what the rewritten prompt may change.
+
+**Existing input content is preserved byte-for-byte.** The rewrite must not alter any of these values when they already appear in the input:
+
+- Identifiers (variable names, function names, file paths)
+- IDs and SHAs
+- ID prefixes
+- Proper names (people, products, services)
+- Numeric values (line numbers, thresholds, counts)
+- URLs
+- Code block contents
+
+**New numeric criteria are additive content.** When a spoke introduces a new measurable threshold (e.g., the `≥3` adversarial probes from [`per-category.md`](per-category.md), the citation-occurrence cutoffs from [`citation-depth.md`](citation-depth.md), or any new word/probe/count limit), that number is sourced per the authorized-additions list below. New numeric criteria augment the prompt; they never overwrite a numeric value the input already carries.
+
+## Idempotency
+
+Output stabilizes by the second invocation: the second and all subsequent invocations produce identical output (i.e., `f(f(x)) == f(f(f(x)))`). On the first invocation, content-mutating spokes (persona, cleanup, directives, constraints, adversarial-tuning, instantiation, citation-depth, canonical-case) apply their transformations and emit "applied" gap notes alongside situation-dependent spokes (structure, per-category) that re-fire because their input conditions still hold. On the second invocation, those mutating spokes no longer match their detection conditions (placeholders substituted, identifiers cited, markers present, noun sharpened, canonical sub-bucket marked), so their gap notes disappear and situation-dependent notes shift to "verified" wording. Combined with the gap-report block's deterministic replacement, the second invocation's output is stable: a third invocation produces identical output.
+
+## Authorized additions
+
+The skill adds content only when a spoke explicitly authorizes it. Evidence-required additions (cited values from the rubric, placeholder values from the input or user) must also pass [`research.md`](research.md) confirmation that the new content matches a real source (rubric, sibling artifact, user-pasted context, or AskUserQuestion answer). Skill-defined additions (the per-category disposition line, surface-formatting cleanup, the failure-mode noun from the adversarial-tuning built-in lookup table) are authorized by their spoke firing alone. The authorized additions are:
+
+- The mission line, when [`persona.md`](persona.md) replaces a role assignment
+- The per-category disposition line, when [`per-category.md`](per-category.md) detects an unenforced framework
+- Measurable criteria, when [`directives.md`](directives.md) or [`constraints.md`](constraints.md) replaces a soft directive
+- Real values in place of placeholders, when [`instantiation.md`](instantiation.md) fires
+- `file:line` citations on identifier mentions, when [`citation-depth.md`](citation-depth.md) fires
+- The ⭐ canonical-case marker on one sub-bucket, when [`canonical-case.md`](canonical-case.md) fires
+- A category-specific failure-mode noun in the adversarial-pass phrase, when [`adversarial-tuning.md`](adversarial-tuning.md) fires
+- Surface-formatting normalization (typo correction, single bullet style, language tags on fenced blocks, trimmed trailing whitespace, collapsed blank-line runs, sequential heading levels), when [`cleanup.md`](cleanup.md) fires
+- `(citation unavailable: <reason>)` inline markers adjacent to unciteable identifiers, when [`citation-depth.md`](citation-depth.md) fires
+
+Skill-defined additions (the per-category disposition line, surface-formatting cleanup, the failure-mode noun from [`adversarial-tuning.md`](adversarial-tuning.md)'s built-in lookup table) are authorized by their spoke firing alone — they do not need an external source. For evidence-required additions (cited values from the rubric, placeholder values from the input or user), [`research.md`](research.md) confirms the new content matches a real source. When evidence is missing for an evidence-required addition, the spoke leaves the prompt as-is and reports the gap. For a skill-defined addition, once the spoke's detection conditions are met the transformation fires and always emits an action note recording what changed — the spoke does not need external evidence beyond its own rubric, unlike evidence-required additions. (Skill-defined additions are still situation-dependent per the routing table; "fires" here means when the spoke is active, not on every invocation.) The "No silent action" invariant applies to both applied and deferred outcomes. The gap-report shape depends on emission mode:
+
+- **Paste mode.** The fenced block contains exactly the rewritten prompt — no footer follows it. Record gaps inside the fenced block as a final blockquoted note prefixed `> Gap:` (one line per gap). The note sits below the rewritten prompt's last block and remains inside the fence. On a second invocation, prior-run `> Gap:` lines are deterministically replaced (not accumulated): the current run's gap notes overwrite any prior-run gap notes, ensuring idempotent output across invocations. The passthrough rule in [`block-classification.md`](block-classification.md) step 3 still treats the prior-run gap region as inert during block tagging, but the current run's gap line emission replaces rather than appends.
+- **File-path mode.** The rewritten file on disk MUST be self-describing for gaps. Append a final HTML comment block at the bottom of the file. The block opens with `<!-- gap-report:` on its own line, contains one `> Gap:` line per gap, and closes with `-->` on its own line. The `<!-- gap-report:` block is deterministically replaced (never accumulated) to reflect the current run's gap state. When the current run has gaps, a new `<!-- gap-report:` block containing the gap lines overwrites any prior block. When the current run has no gaps, any prior block is replaced with `<!-- gap-report: none -->` — the file always carries a self-describing gap-report block so a reader can determine the latest run's gap state without external context. Example for a run with two gaps:
+
+  ```
+  <!-- gap-report:
+  > Gap: Persona transformed — original "You are an expert code reviewer" replaced with mission "Find bugs in this code."
+  > Gap: canonical-case marker skipped — framework has 5+ sub-buckets but rubric match, bullet density, and identifier density found no clear canonical case
+  -->
+  ```
+
+  The post-edit confirmation message that names the file and the spokes that fired ALSO lists the same gaps, but the file itself is now self-describing — a reader of the file alone can detect which spokes deferred and why.

package/skills/structure-prompt/reference/per-category.md

@@ -0,0 +1,23 @@
+# Per-category disposition
+
+Every multi-category framework requires each category to emit exactly one disposition:
+- At least one positive finding with a locator (file:line, section ID, line number, or equivalent) per category
+- Exactly one explicit proof-of-absence with at least 3 adversarial probes specific to that category
+
+## Detection
+
+The framework names 2+ categories, surfaces, sub-buckets, items, checks, or criteria the agent processes.
+
+## Insertion
+
+Insert this exact line directly under the category list header, substituting `<category-noun>` with whatever the prompt calls them (sub-bucket, surface, item, category, check, criterion):
+
+> Each `<category-noun>` returns either at least one finding with a locator OR exactly one proof-of-absence with at least 3 adversarial probes specific to that `<category-noun>`. A `<category-noun>` returning neither is a protocol gap.
+
+## Idempotency
+
+When the framework already states an equivalent requirement (positive finding OR proof-of-absence with ≥3 probes), leave it intact. Insert only when the requirement is absent or weaker than the canonical form.
+
+## Disposition reporting
+
+Every outcome emits an action note via the mechanism that [`output-contract.md`](output-contract.md) defines. When the disposition line was inserted: `> Gap: Per-category disposition line inserted under category list header.` When the framework already carries the canonical form: `> Gap: Per-category disposition verified — canonical form already present.` Silent omission is forbidden — see the [no silent action](output-contract.md#disposition-invariants) invariant.

package/skills/structure-prompt/reference/persona.md

@@ -0,0 +1,38 @@
+# Persona transformation
+
+Lead the optimized prompt with what the agent does, not who the agent is.
+
+## Detection patterns
+
+The persona block matches any of:
+- "You are a/an `<role>`"
+- "You are an expert in/at `<topic>`"
+- "You are a helpful assistant"
+- "Act as `<role>`"
+- "Pretend to be `<role>`"
+- "Imagine you are `<role>`"
+- "As a/an `<role>`, …"
+- "Role: `<role>`"
+
+## Transformation
+
+Replace the persona line with a single mission sentence stating the task in imperative form.
+
+| Persona input | Mission output |
+|---|---|
+| "You are a senior security engineer. Review this PR." | "Audit this PR for security issues." |
+| "Act as a code reviewer and find bugs in this code." | "Find bugs in this code." |
+| "You are an expert at SQL. Write a query that…" | "Write a SQL query that…" |
+
+## Creative-writing carve-out
+
+The persona line stays intact when the prompt explicitly references one of these output qualities: `style`, `tone`, `voice`, `fiction`, `creative writing`, `narrative`. In that case the persona shapes the output's character and the mission line follows it.
+
+## Disposition reporting
+
+The persona pass MUST emit a gap note via the paste-mode or file-path-mode gap-report mechanism that [`output-contract.md`](output-contract.md) defines, recording one of two dispositions:
+
+- `> Gap: Persona transformed — original "<persona line>" replaced with mission "<mission line>".`
+- `> Gap: Persona preserved (creative-writing carve-out matched: "<matched keyword>").`
+
+When none of the six carve-out keywords appears in the input, the persona line is always transformed. The detection is deterministic: a case-insensitive match against the six listed keywords only. No subjective "near-miss" or "intent" judgment applies. See the [no silent action](output-contract.md#disposition-invariants) invariant.

package/skills/structure-prompt/reference/research.md

@@ -0,0 +1,33 @@
+# When the skill needs information that isn't in the input
+
+Some spokes need information the input prompt doesn't include — like the line number where an identifier lives, the canonical example for a category, or the real value to put where a placeholder sits. This file describes how to find that information from real sources.
+
+## Where to look, in order
+
+1. **The sibling rubric file.** When the calling framework provides a companion rubric (typically at `../category_rubrics/<same-name>.md` in audit-rubric layouts, but the path is framework-specific), read it first. The rubric often spells out the canonical example, the instantiation recipe, and the category-specific failure-mode noun. When no sibling rubric exists for the input prompt, skip this source and proceed to the companion artifact.
+
+2. **The companion artifact.** When the rubric points at a sibling prompt as a worked example (e.g., "see `category-a-api-contracts.md` for the canonical diff"), read that sibling and use its diff or framework as the reference.
+
+3. **The user-supplied context.** When the user pasted an artifact alongside the prompt — a diff, a PR URL, a file dump — use it directly.
+
+4. **AskUserQuestion.** When the three sources above turn up nothing, ask the user via the AskUserQuestion tool. Phrase the question around the specific blocker (e.g., "Which artifact should I instantiate against?") and offer two to four concrete options.
+
+## What counts as evidence
+
+A change earns its place in the rewritten prompt when one of these is true:
+- The rubric file states it
+- The sibling artifact contains it (the line number is real, the identifier sits in the diff)
+- The user-pasted context contains it (the value sits in the prompt body the user supplied, in a fenced block within it, or in an artifact the user pasted alongside the prompt)
+- The user supplied it via an AskUserQuestion answer
+
+When none of the four holds, the spoke leaves the prompt as-is and notes the gap in the location [`output-contract.md`](output-contract.md) defines for the active emission mode. The deferral itself is mandatory — see the [no silent no-op](output-contract.md#disposition-invariants) invariant.
+
+## Tone of the AskUserQuestion
+
+Use everyday phrasing. Tell the user what's blocked and what answers would unblock it.
+
+| What the spoke needs | Question shape |
+|---|---|
+| Which PR or artifact to instantiate against | "I have placeholders in the prompt. Which artifact should I fill them with?" |
+| Which scope of source material to inline | "Should I inline the full diff, the changed files only, or specific paths?" |
+| Which sub-bucket is the canonical case | "The framework has six similarly-weighted sub-buckets. Which one is the canonical case for this category?" |

package/skills/structure-prompt/reference/structure.md

@@ -0,0 +1,28 @@
+# Structural ordering
+
+The optimized prompt presents blocks in this fixed sequence:
+
+1. Mission block
+2. Metadata block
+3. Framework block
+4. Questions block
+5. Output spec block
+6. Data body block
+
+## Procedure
+
+1. Extract each tagged block from the input. The gap-report region (prior-run `> Gap:` lines or `<!-- gap-report:` comment blocks) is excluded from block ordering — it is kept at the end during classification and reordering, then deterministically replaced during emission per [`output-contract.md`](output-contract.md).
+2. Concatenate the blocks in the sequence above.
+3. Preserve every byte of the inputs that [`output-contract.md`](output-contract.md) lists under "Preservation invariants" exactly as supplied.
+
+## Multiple data bodies
+
+When the input contains multiple data body blocks (e.g., several file diffs), group them as a contiguous final section in their original relative order.
+
+## Atomicity
+
+The framework block stays whole. The data body section sits as one contiguous region at the end.
+
+## Disposition reporting
+
+Every outcome emits an action note via the mechanism that [`output-contract.md`](output-contract.md) defines. When blocks were reordered: `> Gap: Blocks reordered to canonical sequence (mission → metadata → framework → questions → output spec → data body).` When the input already follows canonical ordering and no reorder is needed: `> Gap: Structural ordering verified — input already in canonical sequence.` Silent omission is forbidden — see the [no silent action](output-contract.md#disposition-invariants) invariant.