continuous-improvement 3.8.0 → 3.9.2

package/skills/token-budget-advisor.md

@@ -1,136 +1,136 @@
----
-name: token-budget-advisor
-tier: "2"
-description: >-
-  Enforces Law 2 (Plan Is Sacred) of the 7 Laws of AI Agent Discipline by
-  making token-budget tradeoffs explicit before the response is composed.
-  Offers the user an informed choice about how much response depth to
-  consume before answering. Use this skill when the user explicitly
-  wants to control response length, depth, or token budget.
-  TRIGGER when: "token budget", "token count", "token usage", "token limit",
-  "response length", "answer depth", "short version", "brief answer",
-  "detailed answer", "exhaustive answer", "respuesta corta vs larga",
-  "cuántos tokens", "ahorrar tokens", "responde al 50%", "dame la versión
-  corta", "quiero controlar cuánto usas", or clear variants where the
-  user is explicitly asking to control answer size or depth.
-  DO NOT TRIGGER when: user has already specified a level in the current
-  session (maintain it), the request is clearly a one-word answer, or
-  "token" refers to auth/session/payment tokens rather than response size.
-origin: community
----
-
-# Token Budget Advisor (TBA)
-
-Intercept the response flow to offer the user a choice about response depth **before** the agent answers.
-
-## When to Use
-
-- User wants to control how long or detailed a response is
-- User mentions tokens, budget, depth, or response length
-- User says "short version", "tldr", "brief", "al 25%", "exhaustive", etc.
-- Any time the user wants to choose depth/detail level upfront
-
-**Do not trigger** when: user already set a level this session (maintain it silently), or the answer is trivially one line.
-
-## How It Works
-
-### Step 1 — Estimate input tokens
-
-Use the repository's canonical context-budget heuristics to estimate the prompt's token count mentally.
-
-Use the same calibration guidance as [context-budget](../context-budget/SKILL.md):
-
-- prose: `words × 1.3`
-- code-heavy or mixed/code blocks: `chars / 4`
-
-For mixed content, use the dominant content type and keep the estimate heuristic.
-
-### Step 2 — Estimate response size by complexity
-
-Classify the prompt, then apply the multiplier range to get the full response window:
-
-| Complexity   | Multiplier range | Example prompts                                      |
-|--------------|------------------|------------------------------------------------------|
-| Simple       | 3× – 8×          | "What is X?", yes/no, single fact                   |
-| Medium       | 8× – 20×         | "How does X work?"                                  |
-| Medium-High  | 10× – 25×        | Code request with context                           |
-| Complex      | 15× – 40×        | Multi-part analysis, comparisons, architecture      |
-| Creative     | 10× – 30×        | Stories, essays, narrative writing                  |
-
-Response window = `input_tokens × mult_min` to `input_tokens × mult_max` (but don’t exceed your model’s configured output-token limit).
-
-### Step 3 — Present depth options
-
-Present this block **before** answering, using the actual estimated numbers:
-
-```
-Analyzing your prompt...
-
-Input: ~[N] tokens  |  Type: [type]  |  Complexity: [level]  |  Language: [lang]
-
-Choose your depth level:
-
-[1] Essential   (25%)  ->  ~[tokens]   Direct answer only, no preamble
-[2] Moderate    (50%)  ->  ~[tokens]   Answer + context + 1 example
-[3] Detailed    (75%)  ->  ~[tokens]   Full answer with alternatives
-[4] Exhaustive (100%)  ->  ~[tokens]   Everything, no limits
-
-Which level? (1-4 or say "25% depth", "50% depth", "75% depth", "100% depth")
-
-Precision: heuristic estimate ~85-90% accuracy (±15%).
-```
-
-Level token estimates (within the response window):
-- 25%  → `min + (max - min) × 0.25`
-- 50%  → `min + (max - min) × 0.50`
-- 75%  → `min + (max - min) × 0.75`
-- 100% → `max`
-
-### Step 4 — Respond at the chosen level
-
-| Level            | Target length       | Include                                             | Omit                                              |
-|------------------|---------------------|-----------------------------------------------------|---------------------------------------------------|
-| 25% Essential    | 2-4 sentences max   | Direct answer, key conclusion                       | Context, examples, nuance, alternatives           |
-| 50% Moderate     | 1-3 paragraphs      | Answer + necessary context + 1 example              | Deep analysis, edge cases, references             |
-| 75% Detailed     | Structured response | Multiple examples, pros/cons, alternatives          | Extreme edge cases, exhaustive references         |
-| 100% Exhaustive  | No restriction      | Everything — full analysis, all code, all perspectives | Nothing                                        |
-
-## Shortcuts — skip the question
-
-If the user already signals a level, respond at that level immediately without asking:
-
-| What they say                                      | Level |
-|----------------------------------------------------|-------|
-| "1" / "25% depth" / "short version" / "brief answer" / "tldr"  | 25%   |
-| "2" / "50% depth" / "moderate depth" / "balanced answer"        | 50%   |
-| "3" / "75% depth" / "detailed answer" / "thorough answer"       | 75%   |
-| "4" / "100% depth" / "exhaustive answer" / "full deep dive"     | 100%  |
-
-If the user set a level earlier in the session, **maintain it silently** for subsequent responses unless they change it.
-
-## Precision note
-
-This skill uses heuristic estimation — no real tokenizer. Accuracy ~85-90%, variance ±15%. Always show the disclaimer.
-
-## Examples
-
-### Triggers
-
-- "Give me the short version first."
-- "How many tokens will your answer use?"
-- "Respond at 50% depth."
-- "I want the exhaustive answer, not the summary."
-- "Dame la version corta y luego la detallada."
-
-### Does Not Trigger
-
-- "What is a JWT token?"
-- "The checkout flow uses a payment token."
-- "Is this normal?"
-- "Complete the refactor."
-- Follow-up questions after the user already chose a depth for the session
-
-## Source
-
-Standalone skill from [TBA — Token Budget Advisor for Claude Code](https://github.com/Xabilimon1/Token-Budget-Advisor-Claude-Code-).
-Original project also ships a Python estimator script, but this repository keeps the skill self-contained and heuristic-only.
+---
+name: token-budget-advisor
+tier: "2"
+description: >-
+  Enforces Law 2 (Plan Is Sacred) of the 7 Laws of AI Agent Discipline by
+  making token-budget tradeoffs explicit before the response is composed.
+  Offers the user an informed choice about how much response depth to
+  consume before answering. Use this skill when the user explicitly
+  wants to control response length, depth, or token budget.
+  TRIGGER when: "token budget", "token count", "token usage", "token limit",
+  "response length", "answer depth", "short version", "brief answer",
+  "detailed answer", "exhaustive answer", "respuesta corta vs larga",
+  "cuántos tokens", "ahorrar tokens", "responde al 50%", "dame la versión
+  corta", "quiero controlar cuánto usas", or clear variants where the
+  user is explicitly asking to control answer size or depth.
+  DO NOT TRIGGER when: user has already specified a level in the current
+  session (maintain it), the request is clearly a one-word answer, or
+  "token" refers to auth/session/payment tokens rather than response size.
+origin: community
+---
+
+# Token Budget Advisor (TBA)
+
+Intercept the response flow to offer the user a choice about response depth **before** the agent answers.
+
+## When to Use
+
+- User wants to control how long or detailed a response is
+- User mentions tokens, budget, depth, or response length
+- User says "short version", "tldr", "brief", "al 25%", "exhaustive", etc.
+- Any time the user wants to choose depth/detail level upfront
+
+**Do not trigger** when: user already set a level this session (maintain it silently), or the answer is trivially one line.
+
+## How It Works
+
+### Step 1 — Estimate input tokens
+
+Use the repository's canonical context-budget heuristics to estimate the prompt's token count mentally.
+
+Use the same calibration guidance as [context-budget](../context-budget/SKILL.md):
+
+- prose: `words × 1.3`
+- code-heavy or mixed/code blocks: `chars / 4`
+
+For mixed content, use the dominant content type and keep the estimate heuristic.
+
+### Step 2 — Estimate response size by complexity
+
+Classify the prompt, then apply the multiplier range to get the full response window:
+
+| Complexity   | Multiplier range | Example prompts                                      |
+|--------------|------------------|------------------------------------------------------|
+| Simple       | 3× – 8×          | "What is X?", yes/no, single fact                   |
+| Medium       | 8× – 20×         | "How does X work?"                                  |
+| Medium-High  | 10× – 25×        | Code request with context                           |
+| Complex      | 15× – 40×        | Multi-part analysis, comparisons, architecture      |
+| Creative     | 10× – 30×        | Stories, essays, narrative writing                  |
+
+Response window = `input_tokens × mult_min` to `input_tokens × mult_max` (but don’t exceed your model’s configured output-token limit).
+
+### Step 3 — Present depth options
+
+Present this block **before** answering, using the actual estimated numbers:
+
+```
+Analyzing your prompt...
+
+Input: ~[N] tokens  |  Type: [type]  |  Complexity: [level]  |  Language: [lang]
+
+Choose your depth level:
+
+[1] Essential   (25%)  ->  ~[tokens]   Direct answer only, no preamble
+[2] Moderate    (50%)  ->  ~[tokens]   Answer + context + 1 example
+[3] Detailed    (75%)  ->  ~[tokens]   Full answer with alternatives
+[4] Exhaustive (100%)  ->  ~[tokens]   Everything, no limits
+
+Which level? (1-4 or say "25% depth", "50% depth", "75% depth", "100% depth")
+
+Precision: heuristic estimate ~85-90% accuracy (±15%).
+```
+
+Level token estimates (within the response window):
+- 25%  → `min + (max - min) × 0.25`
+- 50%  → `min + (max - min) × 0.50`
+- 75%  → `min + (max - min) × 0.75`
+- 100% → `max`
+
+### Step 4 — Respond at the chosen level
+
+| Level            | Target length       | Include                                             | Omit                                              |
+|------------------|---------------------|-----------------------------------------------------|---------------------------------------------------|
+| 25% Essential    | 2-4 sentences max   | Direct answer, key conclusion                       | Context, examples, nuance, alternatives           |
+| 50% Moderate     | 1-3 paragraphs      | Answer + necessary context + 1 example              | Deep analysis, edge cases, references             |
+| 75% Detailed     | Structured response | Multiple examples, pros/cons, alternatives          | Extreme edge cases, exhaustive references         |
+| 100% Exhaustive  | No restriction      | Everything — full analysis, all code, all perspectives | Nothing                                        |
+
+## Shortcuts — skip the question
+
+If the user already signals a level, respond at that level immediately without asking:
+
+| What they say                                      | Level |
+|----------------------------------------------------|-------|
+| "1" / "25% depth" / "short version" / "brief answer" / "tldr"  | 25%   |
+| "2" / "50% depth" / "moderate depth" / "balanced answer"        | 50%   |
+| "3" / "75% depth" / "detailed answer" / "thorough answer"       | 75%   |
+| "4" / "100% depth" / "exhaustive answer" / "full deep dive"     | 100%  |
+
+If the user set a level earlier in the session, **maintain it silently** for subsequent responses unless they change it.
+
+## Precision note
+
+This skill uses heuristic estimation — no real tokenizer. Accuracy ~85-90%, variance ±15%. Always show the disclaimer.
+
+## Examples
+
+### Triggers
+
+- "Give me the short version first."
+- "How many tokens will your answer use?"
+- "Respond at 50% depth."
+- "I want the exhaustive answer, not the summary."
+- "Dame la version corta y luego la detallada."
+
+### Does Not Trigger
+
+- "What is a JWT token?"
+- "The checkout flow uses a payment token."
+- "Is this normal?"
+- "Complete the refactor."
+- Follow-up questions after the user already chose a depth for the session
+
+## Source
+
+Standalone skill from [TBA — Token Budget Advisor for Claude Code](https://github.com/Xabilimon1/Token-Budget-Advisor-Claude-Code-).
+Original project also ships a Python estimator script, but this repository keeps the skill self-contained and heuristic-only.

package/skills/verification-loop.md

@@ -147,6 +147,36 @@ For repos whose `verify-ladder.json` declares a `deploy_receipt` field — or wh
 
 INCOMPLETE receipts move to "Immediate operator action" in the close, never to "ready". Library-only / package-published repos skip this phase entirely (no deploy seam exists).
 
+### Phase 9: Synthetic Checks (production-vs-baseline diff)
+
+Phase 8 confirms the deploy seam. Phase 9 confirms the deployed surface matches the staging baseline on the dimensions that matter — endpoint payload shape, header presence, data freshness, routing correctness. A deploy can land with a matching SHA and a 200 healthcheck and still serve broken responses (stale data sources, dropped headers, regressed payloads). Phase 9 is the gate that catches that.
+
+**When this rung runs:**
+
+- ONLY after Phase 8 reports `Receipt status: COMPLETE`. An INCOMPLETE receipt blocks Phase 9 — fix the receipt gap first, then re-run.
+- ONLY when the resolved ladder declares `synthetic_checks` as a non-null directory path (default: `synthetic-checks/`). A `null` field skips the rung silently. A missing field falls through to the directory sniff: if `synthetic-checks/` exists at the repo root with at least one `*.synthetic.*` file, the rung activates; otherwise it is recorded as "skipped — no synthetic-checks directory found".
+
+**What the runner does:**
+
+1. List every `*.synthetic.{sh,mjs,ts,py}` file in the resolved directory in lexical order.
+2. For each file, set the input env vars: `BASE_URL` (production base from project config), `BASELINE_URL` (staging baseline from project config), `EXPECTED_SHA` (the merge SHA Phase 8 reported COMPLETE), `DEPLOY_BRANCH` (the deploy branch name), `RECEIPT_TIMESTAMP` (ISO-8601 of the receipt).
+3. Invoke the file via the right interpreter (`bash` for `.sh`, `node` for `.mjs`, `tsx` for `.ts`, `python` for `.py`). Files with unrecognized extensions are skipped with a warning.
+4. Capture stdout + stderr + exit code per file. On exit 0, the check passed. On any non-zero exit, the check failed and stdout is the operator-facing diff.
+5. Aggregate: if every file exited 0, Phase 9 is `PASS`. If any file exited non-zero, Phase 9 is `FAIL — synthetic drift on <filenames>` and the captured diffs go into the verification report verbatim (no agent re-summarization).
+
+**Surfacing rule:**
+
+A failed synthetic check surfaces as `INCOMPLETE — synthetic drift` at the same severity as a failed deploy receipt. The merge moves to "Immediate operator action" with the named drift and the diff payload. Do NOT downgrade synthetic drift to "warning" — the rung exists because the report flagged exactly this gap (deploys that look healthy but serve broken responses).
+
+**Anti-patterns specific to this rung:**
+
+- **Smoke checks masquerading as synthetic checks.** A check that only verifies "endpoint returns 200" passes against a stale deploy. Synthetic checks MUST diff production against a baseline.
+- **Hardcoded baseline URLs in the check.** Baseline lives in env (`BASELINE_URL`), not in the file. Hardcoding it breaks the convention and makes per-environment use impossible.
+- **Re-summarizing the diff.** The captured stdout from a failed check is the operator-facing artifact. The agent does not re-write or shorten it.
+- **Treating an absent directory as PASS.** No synthetic-checks directory means the rung is `skipped`, not `PASS`. The operator sees the absence in the resolved ladder.
+
+See `synthetic-checks/README.md` for the file convention, the input/output contract, and a runnable sample (`example-version-endpoint.synthetic.sh`).
+
 ## Output Format
 
 After running all phases, produce a verification report:
@@ -163,6 +193,8 @@ Security:     [PASS/FAIL] (X issues)
 Diff:         [X files changed]
 Goal landed:  [YES/NO] — <one-line evidence or gap>
 All promised: [YES/NO] — <X of Y steps Done; list any Skipped>
+Deploy:       [COMPLETE/INCOMPLETE/skipped] — <SHA + health summary>
+Synthetic:    [PASS/FAIL/skipped] — <X of Y checks; failed: <filenames>>
 
 Overall:   [READY/NOT READY] for PR