hatch3r 1.8.0 → 2.0.0

package/dist/content/skills/hatch3r-cost-tracking/SKILL.md

@@ -0,0 +1,164 @@
+---
+id: hatch3r-cost-tracking
+name: hatch3r-cost-tracking
+type: skill
+description: Tracks token usage and estimate costs for agent sessions. Use when monitoring spend, approaching budget limits, or generating cost reports.
+tags: [maintenance]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+# Cost Tracking Workflow
+
+## Quick Start
+
+**Applies when:** the project tracks cloud/LLM spend against a budget. On a project with no cost-accounting need, skip (per `rules/hatch3r-right-sizing.md`).
+
+```
+Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
+- [ ] Step 1: Review cost tracking configuration
+- [ ] Step 2: Estimate current session token usage
+- [ ] Step 2a: Re-fetch pricing before reporting (currency gate)
+- [ ] Step 3: Identify cost optimization opportunities
+- [ ] Step 4: Generate cost report
+```
+
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, or irreversibility. If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md`. Do not proceed under silent assumption. Default path, not an exception. Triggers for THIS skill: tracking scope (session vs issue vs epic), budget values when missing from hatch.json, hardStop authority (block vs warn), report format target, and whether to defer non-critical work over budget.
+
+## Fan-out Discipline (P8 B2)
+
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Emit `sub_agents_spawned: { count, rationale }` in your output.
+
+## Step 1: Review Configuration
+
+1. Check `hatch.json` for a `costTracking` section.
+2. Note configured budgets: `sessionBudget`, `issueBudget`, `epicBudget`.
+3. Note warning thresholds and whether `hardStop` is enabled.
+4. If no configuration exists, operate in report-only mode.
+
+## Step 2: Estimate Token Usage
+
+Estimate tokens for the current session using these rules:
+
+| Content Type | Rule | Accuracy |
+|-------------|------|----------|
+| Messages | ~4 characters per token | High -- stable ratio for English text |
+| Tool calls | JSON length / 4 (input), response length / 4 (output) | Medium -- JSON has more overhead characters |
+| File reads | Character count / 4 | High -- but large files may be truncated by the tool |
+| Web searches | ~500 tokens per search | Low -- varies widely by result length |
+| Subagent spawns | Estimate full context re-sent per spawn (~2000-5000 tokens base) | Medium -- depends on included rules/context |
+
+**Subagent cost multiplier.** Each subagent spawn carries a base cost for the agent protocol, included rules, and context. A pipeline with 8 subagents (researcher + implementer + reviewer + fixer + 4 Phase 4 specialists) has significant overhead from context re-transmission. Factor this into budget estimates.
+
+Calculate estimated cost using named-model rates tied to model IDs. Published-vendor rates drift between model releases — re-fetch before every report per Step 2a; the `accessed:` date marks when each row was last verified.
+
+| Model | Model ID | Input (per 1M) | Output (per 1M) | accessed |
+|-------|----------|---------------:|----------------:|----------|
+| Claude Haiku 4.5 | `claude-haiku-4-5` | $1.00 | $5.00 | 2026-06-05 |
+| Claude Sonnet 4.6 | `claude-sonnet-4-6` | $3.00 | $15.00 | 2026-06-05 |
+| Claude Opus 4.8 | `claude-opus-4-8` | $5.00 | $25.00 | 2026-06-05 |
+
+**Cache-read multiplier.** Cached input tokens (`cache_read_input_tokens` in the API `usage` block) bill at ~0.1× the model's base input rate; cache writes bill at 1.25× (5-minute TTL) or 2× (1-hour TTL). When a session reuses a large cached prefix, price `cache_read_input_tokens` separately at 0.1× base input — counting them at full input rate overstates spend by up to 10× on cache-heavy agent loops. Total prompt size = `input_tokens` (uncached) + `cache_creation_input_tokens` + `cache_read_input_tokens`.
+
+### Step 2a: Re-fetch Pricing Before Reporting (currency gate)
+
+Published per-token rates change between model releases. Before emitting a cost figure, verify the rate table is current:
+
+1. If any row's `accessed:` date is older than 30 days, re-fetch the vendor's current pricing (Anthropic: https://www.anthropic.com/pricing, or the live `claude-api` skill's models/pricing reference) and update the row's rates + `accessed:` date in place.
+2. Confirm the model the session actually ran on maps to a named row. If the session used a model ID absent from the table (e.g. an older or non-Anthropic model), add a row with its published rates and `accessed:` date rather than defaulting to the nearest tier.
+3. State the `accessed:` date of the rate used directly in the report (see Step 4). A cost figure with no rate-provenance date is unverifiable — never report a dollar amount without it.
+
+If pricing cannot be re-fetched (offline, vendor page unreachable), proceed with the on-file rates but flag the figure as `(rates as of <accessed-date>, not re-verified)` in the report.
+
+### Default Budgets
+
+When `hatch.json` has no `costTracking` section, apply these defaults (report-only — no hard stop unless `hardStop: true`):
+
+| Budget Type | Default |
+|------------|---------|
+| `sessionBudget` | $10.00 |
+| `issueBudget` | $5.00 |
+| `epicBudget` | $25.00 |
+| `warningThresholds` | [0.5, 0.75, 0.9] |
+| `hardStop` | false |
+
+### Enforcement
+
+| Threshold | Action |
+|-----------|--------|
+| 50% | Log warning, continue |
+| 75% | Alert user, suggest optimization |
+| 90% | Strong warning, recommend delegation or checkpoint |
+| 100% | Stop (if `hardStop: true`) or alert and continue |
+
+## Step 3: Identify Optimizations
+
+Review usage patterns for savings:
+
+- **Large file reads**: Were files read multiple times without changes? Cache instead.
+- **Model tier**: Could routine tasks (linting, formatting) use a faster/cheaper model?
+- **Context bloat**: Is irrelevant context accumulating? Summarize and trim.
+- **Batching**: Were multiple small tool calls made that could be combined?
+- **Scope creep**: Did work expand beyond the original issue? Scope back.
+
+## Step 4: Generate Report
+
+Produce a cost report in this format:
+
+```
+## Cost Report: {scope}
+
+**Period:** {session/issue/sprint}
+
+**Token Usage:**
+- Input tokens (uncached): ~{n}
+- Cache-read tokens: ~{n} (billed ~0.1x base input)
+- Cache-write tokens: ~{n} (billed 1.25x / 2x by TTL)
+- Output tokens: ~{n}
+- Total tokens: ~{n}
+
+**Estimated Cost:** ${amount} ({model-id}, rates accessed {YYYY-MM-DD})
+
+**Budget Status:** {amount} / {budget} ({percentage}%)
+
+**Breakdown:**
+
+| Phase | Tokens | Cost | % of Total |
+|-------|--------|------|-----------|
+| Planning | ~{n} | ${x} | {%} |
+| Implementation | ~{n} | ${x} | {%} |
+| Testing | ~{n} | ${x} | {%} |
+| Review | ~{n} | ${x} | {%} |
+| Sub-agents | ~{n} | ${x} | {%} |
+
+**Optimization Opportunities:**
+- {suggestions based on usage patterns}
+```
+
+Include total estimated tokens (uncached input + cache-read + cache-write + output), estimated cost at the named-model rate with its `accessed:` date, budget status (if configured), and top optimization opportunities. Always present estimated values with the `~` prefix. Never report a dollar figure without the model ID and rate-access date. Never suppress threshold alerts.
+
+## Error Handling
+
+- **Token usage data unavailable**: If the platform does not expose token metrics, use input/output character counts divided by 4 as an estimate. Note the approximation method in the report.
+- **Budget limit exceeded mid-session**: Stop non-critical operations, produce a partial cost report, and recommend which remaining tasks to defer or delegate to a lower-cost model.
+- **Cost configuration missing from hatch.json**: Operate in report-only mode and note that budget enforcement is inactive. Recommend adding cost configuration to enable guardrails.
+
+## Definition of Done
+
+- [ ] Cost configuration reviewed (or report-only mode noted)
+- [ ] Token usage estimated for current session (uncached input / cache-read / cache-write / output split)
+- [ ] Pricing rates verified current per Step 2a; report cites model ID + rate `accessed:` date
+- [ ] Optimization opportunities identified
+- [ ] Cost report generated with budget status
+
+## Related Skills & Agents
+
+- **Skill**: `hatch3r-context-health` — context health monitoring complements cost tracking for session management
+
+## References
+
+- [Anthropic API pricing](https://www.anthropic.com/pricing) — accessed 2026-06-05, official-docs (Anthropic). Source for the per-million-token input/output rates per named model (Haiku 4.5 $1/$5, Sonnet 4.6 $3/$15, Opus 4.8 $5/$25) and the cache-read 0.1x / cache-write 1.25x-2x multipliers in Step 2; these drift between model releases — re-verify per Step 2a when running a cost report.
+- [Token counting — Anthropic API docs](https://docs.anthropic.com/en/docs/build-with-claude/token-counting) — accessed 2026-06-05, official-docs (Anthropic). Source for treating the ~4-characters-per-token figure as an approximation; the documented count-tokens endpoint is authoritative when exact counts are required.

package/{skills → dist/content/skills}/hatch3r-customize/SKILL.md

@@ -1,15 +1,16 @@
 ---
 id: hatch3r-customize
-description: Create and manage customization files for any hatch3r artifact type (agents, commands, rules, skills). Supports model overrides, description changes, scope overrides, enable/disable control, and project-specific markdown instructions.
+name: hatch3r-customize
+type: skill
+description: Creates and manages customization files for any hatch3r artifact type (agents, commands, rules, skills). Supports model overrides, description changes, scope overrides, enable/disable control, and project-specific markdown instructions.
 tags: [customize]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
-canonical_for: [hatch3r-agent-customize, hatch3r-command-customize, hatch3r-rule-customize, hatch3r-skill-customize]
 ---
 # Artifact Customization Management
 
-> **Canonical entry point.** Four type-specific skills (`hatch3r-agent-customize`, `hatch3r-command-customize`, `hatch3r-rule-customize`, `hatch3r-skill-customize`) redirect here via `redirect_to: hatch3r-customize` frontmatter. Their body documents the rejected-merge alternative per `governance/audit/domains/D16-compound-system.md` SA 16.3.
+> **Canonical entry point.** This is the single skill for all per-artifact customization (agents, commands, rules, skills). The four prior type-specific skill stubs were removed in v1.9.0 per the Decision #13 Command-vs-Skill criterion; hatch3r's artifact-inventory and redundancy analysis documents the rejected-merge alternative.
 
 ## Quick Start
 
@@ -30,12 +31,7 @@ Before any work, scan the invocation for unresolved questions in scope, intent,
 
 ## Fan-out Discipline (P8 B2)
 
-This skill delegates per task size:
-- Tier 1 (trivial single-file): inline execution acceptable.
-- Tier 2 (multi-file or multi-concern): spawn parallel sub-agents per concern via the Task tool.
-- Tier 3 (multi-module / high-risk): one fresh sub-agent per independent module or gate; orchestrator integrates only.
-
-Never under-fan-out to save tokens. Token cost is dominated by quality and completeness gains. Emit `sub_agents_spawned: { count, rationale }` in your output.
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Emit `sub_agents_spawned: { count, rationale }` in your output.
 
 ## Artifact Types
 
@@ -43,10 +39,10 @@ This skill handles customization for all artifact types. The `type` parameter de
 
 | Type | Source Directory | Customization Directory | YAML Fields |
 |------|-----------------|------------------------|-------------|
-| `agent` | `.agents/agents/` | `.hatch3r/agents/` | `model`, `description`, `enabled` |
-| `command` | `.agents/commands/` | `.hatch3r/commands/` | `description`, `enabled` |
-| `rule` | `.agents/rules/` | `.hatch3r/rules/` | `scope`, `description`, `enabled` |
-| `skill` | `.agents/skills/` | `.hatch3r/skills/` | `description`, `enabled` |
+| `agent` | `agents/` | `.hatch3r/agents/` | `model`, `description`, `enabled` |
+| `command` | `commands/` | `.hatch3r/commands/` | `description`, `enabled` |
+| `rule` | `rules/` | `.hatch3r/rules/` | `scope`, `description`, `enabled` |
+| `skill` | `skills/` | `.hatch3r/skills/` | `description`, `enabled` |
 
 **Protected agents:** Some agents have `protected: true` in their canonical frontmatter. For these agents, `description` and `enabled` overrides are ignored — only `model` and markdown instructions can be customized.
 

package/{skills → dist/content/skills}/hatch3r-dep-audit/SKILL.md

@@ -1,7 +1,9 @@
 ---
 id: hatch3r-dep-audit
-description: Audit and update npm dependencies for security, freshness, and bundle impact. Use when auditing dependencies, responding to CVEs, or upgrading packages.
-tags: [maintenance, security]
+name: hatch3r-dep-audit
+type: skill
+description: Audits and updates npm dependencies for security, freshness, and bundle impact. Use when auditing dependencies, responding to CVEs, or upgrading packages.
+tags: [maintenance, floor:security]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -29,12 +31,19 @@ Before any work, scan the invocation for unresolved questions in scope, intent,
 
 ## Fan-out Discipline (P8 B2)
 
-This skill delegates per task size:
-- Tier 1 (trivial single-file): inline execution acceptable.
-- Tier 2 (multi-file or multi-concern): spawn parallel sub-agents per concern via the Task tool.
-- Tier 3 (multi-module / high-risk): one fresh sub-agent per independent module or gate; orchestrator integrates only.
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Emit `sub_agents_spawned: { count, rationale }` in your output.
 
-Never under-fan-out to save tokens. Token cost is dominated by quality and completeness gains. Emit `sub_agents_spawned: { count, rationale }` in your output.
+## Required Agent Delegation
+
+> **Note:** When this skill is invoked via an orchestration pipeline (a `commands/hatch3r-*.md` flow), skip this section — the orchestrator handles agent delegation.
+
+This skill realizes the two-agent dependency pattern (governance PRD Decision 13, F13.1-F04): the agent that *assesses* upgrade risk is distinct from the agent that *applies* it. Spawn these agents via the Task tool (`subagent_type: "generalPurpose"`) at the points below:
+
+- **`hatch3r-dependency-drafter`** (analysis phase, Steps 1–3) — MUST spawn to inventory the dependency surface, classify each candidate by SemVer band, cross-check advisories, and draft the per-dependency proposal (current pin → proposed pin, band, driver, risk, consumer call sites, verification gate). The drafter is read-only (its `tools.deny` forbids manifest edits and installs), so its proposal is a reviewable decision artifact, not a mutation. Skip only for a trivial single-package patch already scoped by the invocation.
+- **`hatch3r-fixer`** (apply phase, Step 4) — MUST spawn under reviewer authority to perform the manifest edit + `npm install` + per-upgrade verification the drafter's proposal names. The fixer flips each proposal from `drafted` to `applied` after its row's verification gate passes.
+- **`hatch3r-devops`** (apply phase, Step 4 — CI-wiring variant) — spawn instead of `hatch3r-fixer` when the upgrade requires CI manifest wiring (lockfile-cache keys, build-matrix version pins, Renovate/Dependabot config) rather than only a source-tree dependency bump.
+
+The drafter never applies and the fixer/devops never re-assess risk — the split keeps risk assessment separate from risk acceptance.
 
 ## Step 1: Gather Findings
 
@@ -48,7 +57,7 @@ Never under-fan-out to save tokens. Token cost is dominated by quality and compl
 For critical and high vulnerabilities:
 
 - Use **web search** to look up each CVE: exploitability, affected versions, fix version, workarounds.
-- Check npm advisories and platform-specific security tools for official guidance (check `platform` in `.agents/hatch.json`):
+- Check npm advisories and platform-specific security tools for official guidance (check `platform` in `.hatch3r/hatch.json`):
   - **GitHub:** GitHub Security Advisories (`gh api /repos/{owner}/{repo}/security-advisories`)
   - **Azure DevOps:** Azure Artifacts security scanning and Azure Boards advisory tracking
   - **GitLab:** GitLab Dependency Scanning (Security & Compliance → Vulnerability Report)
@@ -75,10 +84,12 @@ Before changing anything:
 ## Step 5: Verify
 
 ```bash
-npm run lint && npm run typecheck && npm run test
+${HATCH3R:VERIFY_GATE_ALL}
 npm run build
 ```
 
+The gate line is resolved to the project's language-aware command set at sync time (fallback when detection is unknown: `npm run lint && npm run typecheck && npm run test`); the build line is illustrative — substitute the project's build command.
+
 - Confirm bundle size within budget (if defined).
 - Run `npm audit` — no critical or high vulnerabilities remaining.
 - Verify `package-lock.json` is committed by checking `git status` for untracked or modified lockfile.
@@ -99,6 +110,10 @@ Use the project's PR template. Include:
 - **Major version upgrade breaks tests**: Roll back the upgrade, document the breaking changes encountered, and create a dedicated migration issue with the specific test failures and required code changes.
 - **Lockfile conflicts after upgrade**: Regenerate the lockfile from scratch (`rm package-lock.json && npm install`), verify all tests pass, and commit the clean lockfile.
 
+## Tracking Issues for Deferred Items
+
+For CVEs or outdated packages not addressed in this session, create a tracking issue on the project's platform (GitHub Issues, ADO Work Item, or GitLab Issue per `platform` in `.hatch3r/hatch.json`). Use severity-based priority labels: Critical/High → `priority:p0`/`priority:p1`; Medium/Low → `priority:p2`; Major outdated → `priority:p2`; Minor/patch → `priority:p3`. Include package name, current version, target version, severity, CVE ID (if applicable), and migration notes. Never close out a critical/high CVE without either a fix or a tracking issue.
+
 ## Definition of Done
 
 - [ ] No critical or high CVEs remaining
@@ -107,3 +122,8 @@ Use the project's PR template. Include:
 - [ ] `package-lock.json` committed
 - [ ] PR includes upgrade rationale and bundle impact
 - [ ] No duplicate packages; unused deps removed
+
+## References
+
+- [npm audit — npm CLI docs](https://docs.npmjs.com/cli/v10/commands/npm-audit) — accessed 2026-05-31, official-docs (npm, Inc.). Source for the `npm audit` severity buckets (critical/high/moderate/low) and `npm outdated` semantics used in Step 1.
+- [GitHub security advisories REST API](https://docs.github.com/en/rest/security-advisories/repository-advisories) — accessed 2026-05-31, official-docs (GitHub). Source for the `gh api /repos/{owner}/{repo}/security-advisories` CVE-research path in Step 2.

package/{skills → dist/content/skills}/hatch3r-design-system-detect/SKILL.md

@@ -1,8 +1,9 @@
 ---
 id: hatch3r-design-system-detect
+name: hatch3r-design-system-detect
 type: skill
-description: Detect existing design tokens, component library, and theming convention in a project before authoring new UI primitives — output a concise inventory for downstream implementers
-tags: [ui, design-system, frontend]
+description: Detects existing design tokens, component library, and theming convention in a project before authoring new UI primitives — output a concise inventory for downstream implementers
+tags: [implementation, floor:ui-ux, ui, design-system, frontend]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
@@ -29,12 +30,7 @@ Before any work, scan the invocation for unresolved questions in scope, intent,
 
 ## Fan-out Discipline (P8 B2)
 
-This skill delegates per task size:
-- Tier 1 (trivial single-file): inline execution acceptable.
-- Tier 2 (multi-file or multi-concern): spawn parallel sub-agents per concern via the Task tool.
-- Tier 3 (multi-module / high-risk): one fresh sub-agent per independent module or gate; orchestrator integrates only.
-
-Never under-fan-out to save tokens. Token cost is dominated by quality and completeness gains. Emit `sub_agents_spawned: { count, rationale }` in your output.
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Emit `sub_agents_spawned: { count, rationale }` in your output.
 
 ## Step 1: Scan package.json for design-system signals
 

package/dist/content/skills/hatch3r-docs-writing/SKILL.md

@@ -0,0 +1,159 @@
+---
+id: hatch3r-docs-writing
+name: hatch3r-docs-writing
+type: skill
+description: Authors technical documentation through a repeatable workflow — audience analysis, Diátaxis-mode selection, structure, draft, review, publish. Covers READMEs, ADRs, API docs, and runbooks. Use when writing or restructuring any project documentation.
+tags: [maintenance]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+
+# Technical Documentation Workflow
+
+Companion workflow to the `hatch3r-docs-writer` agent: that agent is the Phase-4 specialist invoked to update specs after a code change; this skill is the step-by-step procedure a human or agent follows to author a documentation artifact from scratch. Use the agent when documentation must track a `src/` diff; use this skill when authoring a new doc and you need the audience-analysis-through-publish sequence.
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
+- [ ] Step 1: Classify the doc by Diátaxis mode + name the audience
+- [ ] Step 2: Pick the structure template for the chosen mode
+- [ ] Step 3: Draft to the template, one mode per document
+- [ ] Step 4: Run the review checklist (audience, accuracy, style, structure)
+- [ ] Step 5: Publish — link from an index, set owner + last-updated, verify cross-references
+```
+
+The load-bearing decision is Step 1: a document serves exactly one of four user needs. Mixing learning content into a reference table, or burying a how-to procedure inside an explanation, is the most common defect this workflow prevents (Diátaxis — see References).
+
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target audience, or irreversibility. If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md`. Do not proceed under silent assumption. Default path, not an exception. Triggers for THIS skill: which doc type is wanted (README vs ADR vs API reference vs runbook), the reader's existing competence (new user vs maintainer vs on-call), whether an existing doc is being restructured (irreversible section moves), and where the published doc is linked from.
+
+## Fan-out Discipline (P8 B2)
+
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Tier boundaries for THIS skill:
+- Tier 1 (single doc, single mode): inline.
+- Tier 2 (multi-doc set, e.g. README + API reference + runbook for one feature): spawn one sub-agent per document via the Task tool; each authors to its own Diátaxis mode.
+- Tier 3 (full docs-site restructure across many modes): one fresh sub-agent per top-level section; orchestrator integrates the index only.
+
+Emit `sub_agents_spawned: { count, rationale }` in your output.
+
+## Step 1: Classify by Diátaxis Mode and Name the Audience
+
+Every document answers exactly one of four user needs. Pick one mode before writing a single sentence; if a request spans two, split it into two documents.
+
+| Mode | User need | Reader state | Writing stance |
+|------|-----------|--------------|----------------|
+| Tutorial | Learning by doing | Newcomer, no prior context | Lesson — guarantee a working result, hide edge cases |
+| How-to guide | Achieving a stated goal | Already competent, has a task | Recipe — numbered steps to one outcome, no theory |
+| Reference | Looking up a fact | Working, needs accuracy | Description — complete, dry, structured, no narrative |
+| Explanation | Understanding why | Studying, off-task | Discussion — context, trade-offs, alternatives, rationale |
+
+Map common artifacts to modes:
+
+| Artifact | Primary mode | Note |
+|----------|--------------|------|
+| README | How-to (quickstart) + Reference (config) | Lead with the 60-second "get it running" path; link out to deep docs |
+| API docs | Reference | Endpoint, params, request/response shapes, error codes, auth — one entry per endpoint |
+| Runbook | How-to | Operational procedure: prerequisites, numbered steps, verification, rollback |
+| ADR | Explanation | A decision and its rationale — context, decision, consequences |
+
+Name the audience explicitly in one sentence (e.g., "on-call engineer mid-incident, has shell access, has not seen this service before"). Write to a US-English global-audience reader: short unambiguous sentences, active voice, direct address with "you" (Google dev-docs style — see References). The audience sentence drives every later choice — vocabulary, assumed prerequisites, depth.
+
+## Step 2: Pick the Structure Template
+
+Use the template for the mode chosen in Step 1.
+
+**README (how-to + reference):**
+1. One-line description of what the project is.
+2. Quickstart — the shortest verified path from clone to a running result.
+3. Prerequisites (versions, accounts, tools).
+4. Configuration reference (table: option, type, default, description).
+5. Links to deeper docs (tutorial, full reference, contributing).
+
+**ADR (Nygard format — see References):**
+1. Title (`NNNN-short-decision-name`).
+2. Status (proposed | accepted | rejected | deprecated | superseded by NNNN).
+3. Context (the forces and problem that motivate the decision).
+4. Decision (the change, stated as "we will…").
+5. Consequences (positive and negative effects, including new obligations).
+
+**API reference (one block per endpoint):**
+- Method + path; one-line purpose.
+- Authentication required (scheme + scope).
+- Request: path/query/body params (table: name, type, required, description).
+- Response: success shape + status, paginated where applicable.
+- Errors: status code + meaning + when it fires.
+
+**Runbook (how-to):**
+1. Trigger — what condition this runbook handles.
+2. Prerequisites — access, tools, on-call context.
+3. Numbered steps — each step one action with the exact command.
+4. Verification — the observable signal that confirms success.
+5. Rollback — how to undo if a step fails.
+6. Escalation — who to page if the runbook does not resolve it.
+
+## Step 3: Draft to the Template
+
+- Write to the one chosen mode. If you reach for "but first, some background" inside a how-to, that background belongs in a separate explanation doc — link to it instead.
+- Use a descriptive heading that matches the content type: a bare infinitive for a task heading ("Configure the database"), a noun phrase for a concept heading ("Database configuration") — Google dev-docs style.
+- Put structured facts in tables (config options, params, error codes, invariants), not prose.
+- Put acceptance criteria and operational steps in checklists or numbered lists.
+- Use stable IDs from the project glossary (event IDs, invariant IDs) so the doc survives renames.
+- Every code example uses a current, non-deprecated API — verify against the library's docs at draft time.
+- State confidence on any claim you could not verify against source: mark it `[unverified]` and recommend a maintainer check before publish (quality charter — confidence levels).
+
+## Step 4: Review Checklist
+
+Run all four lenses before publishing. A failure on any line is a blocker.
+
+**Audience:**
+- [ ] The named reader can act on this doc with only the prerequisites it lists — no unstated assumed knowledge.
+- [ ] Depth matches the audience: a tutorial hides edge cases; a reference omits none.
+
+**Accuracy:**
+- [ ] Every command, code block, and config value was run or read against the current source — no copy-from-memory.
+- [ ] Cross-references resolve (no dead links, no renamed-away anchors).
+- [ ] Stable IDs match the glossary.
+
+**Style:**
+- [ ] Active voice, second person, short sentences (Google dev-docs style).
+- [ ] No filler ("it is important to note", "simply", "just"); state the fact directly.
+- [ ] Headings match content type (infinitive for task, noun phrase for concept).
+
+**Structure:**
+- [ ] One Diátaxis mode per document — no learning content in a reference, no theory in a how-to.
+- [ ] Findable from an index or parent doc.
+- [ ] README leads with a runnable quickstart; runbook ends with verification + rollback; ADR records consequences.
+
+## Step 5: Publish
+
+- Link the new doc from its index or parent (a doc no one can find does not exist).
+- Add an ownership footer: owner, reviewers, last-updated date.
+- Re-verify cross-references after the file lands at its final path (anchors shift when filenames change).
+- For docs that mirror code (API reference, config reference), note the source-of-truth file path so the next editor knows what to re-check against.
+- Lint markdown before declaring done (e.g., `npx markdownlint <path>`); a broken table or heading level is a structure defect.
+
+## Error Handling
+
+- **Source code contradicts the existing doc:** the code is the source of truth for behavior. Update the doc to match observed behavior and flag the stale section in the change summary; do not document the intended-but-absent behavior.
+- **Request spans two Diátaxis modes:** do not blend them. Split into two documents (e.g., a how-to guide plus a linked explanation) and state the split in your output.
+- **Cannot verify a code example against source:** mark the example `[unverified]`, recommend a maintainer run it, and lower the document's stated confidence to medium rather than publishing an unverified example as fact.
+- **No index or parent to link from:** create or identify the index entry as part of this work — an unlinked doc fails Step 5.
+
+## Definition of Done
+
+- [ ] Document classified to exactly one Diátaxis mode with a one-sentence named audience
+- [ ] Authored to the matching structure template
+- [ ] All four review-checklist lenses pass (audience, accuracy, style, structure)
+- [ ] Linked from an index/parent; ownership + last-updated footer present
+- [ ] Cross-references resolve and code examples verified against current source (or marked `[unverified]`)
+- [ ] No secrets, tokens, or internal-only URLs in the published text
+
+## References
+
+- Procida, Daniele. "Diátaxis — Start here." `https://diataxis.fr/start-here/` (accessed 2026-06-02, diataxis.fr, peer-reviewed-methodology). Source for the four-mode classification in Step 1 (tutorial / how-to / reference / explanation) and the one-mode-per-document discipline enforced in Steps 3–4.
+- Google. "Google developer documentation style guide — Highlights." `https://developers.google.com/style/highlights` (accessed 2026-06-02, Google for Developers, official-docs). Source for the global-audience writing stance (active voice, second person, short sentences) and the task-vs-concept heading rule (bare infinitive vs noun phrase) in Steps 1–4. Procedures guidance: `https://developers.google.com/style/procedures`.
+- Nygard, Michael. "Documenting Architecture Decisions." `https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions` (accessed 2026-06-02, Cognitect, established-library; ADR template used in 723+ open-source repositories per `https://adr.github.io/`). Source for the ADR structure template in Step 2 (Title / Status / Context / Decision / Consequences).

package/dist/content/skills/hatch3r-enhancability-verify/SKILL.md

@@ -0,0 +1,152 @@
+---
+id: hatch3r-enhancability-verify
+name: hatch3r-enhancability-verify
+type: skill
+description: Enhancability verification gate before commit/release — feature-flag adoption on behavior changes, config externalization, semver-versioned APIs, forward-compat headers, extension-point definition, startup config validation
+tags: [review, enhancability, code-standards, floor:content-quality]
+scope: conditional
+globs: "src/**,openapi.yaml,openapi.json,**/*.proto,**/schema.graphql,**/asyncapi.yaml,**/flags.yaml,**/.env*,**/config/**"
+precedence: normal
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+# Enhancability Verification Gate
+
+## Quick Start
+
+This skill defines what "done" means for any feature shipping user-visible behavior, public API changes, config schema changes, or extension-point interfaces. Run before declaring a feature complete. The 8 gates below mix automated checks (machine-checkable on every PR) with one release-cadence gate (semver bump + deprecation headers at release-cut). Skipping any gate = the feature is not done. Reviewer approval and passing tests alone do not satisfy this bar — a behavior change shipped without a flag commits the whole user base to the new path; a breaking change without a major bump breaks consumers silently.
+
+Inputs the skill expects:
+
+- A repository with `src/` source modules + a feature-flag client wired (OpenFeature, LaunchDarkly, Unleash, Flagsmith, Split, flagd).
+- A config schema file (Zod under `src/config/`, Joi, Pydantic `BaseSettings`, envalid).
+- Per-environment config files (`.env.development`, `.env.staging`, `.env.production`).
+- API spec files (`openapi.yaml`, `openapi.json`, `asyncapi.yaml`, GraphQL SDL) with `info.version` declared.
+- A flag-key inventory file (`flags.yaml` or registry-of-record).
+
+Outputs the skill produces: an 8-line verdict block written to the PR conversation, plus a JSON artifact at `.audit-workspace/enhancability-verify-<sha>.json` for downstream consumption by `hatch3r-release`.
+
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, or irreversibility. If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md`. Default path, not exception. Triggers for THIS skill: behavior change classification (new user-visible behavior vs modified API surface vs config-driven threshold change vs extension-point addition), gate selection (flag-adoption vs config-externalization vs API-versioning vs forward-compat vs full), target client audience (every consumer vs N-2 majors vs single internal caller), and irreversible-action scope (retiring a flag, dropping an endpoint, un-externalizing a previously externalized value).
+
+## Fan-out Discipline (P8 B2)
+
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Emit `sub_agents_spawned: { count, rationale }` in your output.
+
+## Invoked by
+
+This skill is the verification HARNESS — it declares HOW each enhancability gate is checked. The DISPATCHER that decides WHEN to run it is the CQ specialist agent:
+
+- `agents/hatch3r-enhancability.md` — invokes this skill as the closing enhancability gate (CQ9) on PRs modifying behavior, API surfaces, config schema, or extension-point interfaces. The agent contributes the review trigger and Phase-4 dispatch; this skill contributes the 8-gate procedure.
+
+No duplication: the agent decides WHEN, this skill defines HOW.
+
+## Gate 1: Feature-flag adoption 100% on user-visible behavior changes
+
+- Every new user-visible behavior gated behind an OpenFeature flag (or vendor-equivalent: LaunchDarkly, Flagsmith, Unleash, flagd, Split, CloudBees) with a documented default value, evaluation-context schema (`targetingKey`, plus user / org / region attributes), and rollout plan attached to the PR description.
+- Verify via `grep -rnE "OpenFeature|getBooleanValue|getStringValue|getNumberValue|getObjectValue" <src>` matched against the PR's behavior-change diff.
+- Default value matches the pre-change behavior (no surprise activations on flag-service outage); fallback path tested via `flagd --offline` or `offlineMode: true`.
+- Flag-key inventory entry present in `flags.yaml` with owner, rollout schedule, retirement date.
+- Miss → CRITICAL.
+
+## Gate 2: Configuration externalization 100% on env-dependent values
+
+- No hardcoded URLs, timeouts, retry counts, batch sizes, thresholds, or feature toggles in `src/` paths.
+- Every env-dependent value defined in a config schema (Zod / Joi / Pydantic `BaseSettings` / envalid) and overrideable via env var or config file.
+- Verify via `grep -rnE "https?://|setTimeout\([0-9]{4,}|MAX_RETRIES = [0-9]+|BATCH_SIZE = [0-9]+" <src>` against the externalization allow-list.
+- Per-environment config files (`.env.development`, `.env.staging`, `.env.production`) with parity in declared keys.
+- Hardcoded value → FINDINGS; credential, API key, or secret hardcoded → CRITICAL (cross-references `rules/hatch3r-secrets-management.md`).
+
+## Gate 3: Versioned APIs — semver 2.0.0 compliance per public surface
+
+- Each public REST / GraphQL / event surface declares its semver version in the spec (`info.version` in OpenAPI, `version:` in AsyncAPI, schema version directive in GraphQL SDL).
+- Follows semver.org rule: MAJOR on breaking change, MINOR on additive change, PATCH on bug fix.
+- Carries a deprecation policy section in the spec stating the per-tier timeline floor: 12 months notice for `team` tier, 18 months for `scaleup` / `enterprise` per 2026 industry guidance.
+- N-2 support policy declared (current major plus two previous majors supported).
+- Missing policy → FINDINGS; semver violation → CRITICAL.
+
+## Gate 4: Forward-compatibility on stable endpoints — additive only + RFC 9745 + RFC 8594 headers
+
+- Run `npx oasdiff breaking <prev-spec> <curr-spec>` (REST), `buf breaking --against` (Protobuf), `graphql-inspector diff` (GraphQL); breaking change on a stable endpoint blocks merge.
+- Retiring endpoint emits `Deprecation` header in `@<unix-time>` or IMF-fixdate form per RFC 9745 §2 AND a `Sunset` header in IMF-fixdate GMT form per RFC 8594 §3 where Sunset > Deprecation.
+- `Link: <…>; rel="deprecation"` and `Link: <…>; rel="sunset"` reference migration docs at a stable URL.
+- Verify via `curl -sI <endpoint> | grep -iE "deprecation|sunset|link"`.
+- Breaking change on stable surface → CRITICAL; missing header → FINDINGS; ordering violation → FINDINGS.
+
+## Gate 5: Extension-point definition for cross-cutting concerns
+
+- Cross-cutting concerns (auth provider, telemetry exporter, storage backend, notification channel, payment gateway, search index) ship with a named interface (`AuthProvider`, `TelemetryExporter`, `StorageBackend`, `NotificationChannel`).
+- A plugin registration mechanism (`registry.register(name, impl)` or DI-container binding) wires concrete implementations to the interface.
+- A version-stable contract documented inline as a TypeScript / Java / Python interface or in the spec with a `## Stability` block stating `stable | experimental | deprecated` plus the semver version at which the interface stabilized.
+- Missing interface or contract → FINDINGS on optional surfaces, CRITICAL on declared cross-cutting concerns.
+
+## Gate 6: Plugin architecture for pluggable behavior where applicable
+
+- Where the design declares pluggable behavior (per ADR or `rules/hatch3r-plugin-architecture.md`), the implementation ships:
+  - (a) a registry (Map / class-based with `register()` + `resolve()` methods),
+  - (b) DI wiring (NestJS providers, Spring `@Component` scanning, tsyringe containers, Apache PF4J),
+  - (c) lifecycle hooks (`onInit`, `onShutdown`, optionally `onConfigChange`, `onHealthCheck`) documented in README or spec.
+- Missing registry → CRITICAL on cross-cutting plugin surfaces, FINDINGS on optional.
+- Skip rule when no pluggable behavior is declared.
+
+## Gate 7: Config schema validated at startup; boot fails on schema violation
+
+- Run the schema validator at process boot (`loadConfig()` throws on Zod parse error, Pydantic `BaseSettings()` raises `ValidationError`, Joi `validateSync` returns error, envalid `cleanEnv` exits process).
+- Verify via `node -e "require('./dist/config').loadConfig()"` with an invalid env var injected — process must exit non-zero with a human-readable error message naming the offending field and the expected shape.
+- Silent fallback to defaults on validation error → CRITICAL.
+- Validation deferred to first request (lazy init) → FINDINGS (surfaces config errors as 5xx instead of boot failure).
+
+## Gate 8: Backward-compat tests on every API change
+
+- Consumer-driven contract tests (Pact published to broker, `pact-broker can-i-deploy --pacticipant <svc> --version <sha>` exit 0) run in CI.
+- Provider-driven spec-diff CI gate (`oasdiff breaking` / `buf breaking` / `graphql-inspector diff --rule no-breaking-changes`) blocks merge on breaking changes against the stable surface.
+- Experimental surfaces explicitly marked (`x-stability: experimental` in OpenAPI, `@experimental` directive in GraphQL SDL) and exempt; a `## Stability` block in the spec declares the path to stable.
+- Missing CI gate → CRITICAL; failing gate → CRITICAL on stable surface, FINDINGS on experimental.
+
+## Pass criteria
+
+All 8 gates pass = the feature is "done". Anything less = not done.
+
+- Feature-flag adoption: 100% on user-visible behavior changes; default = pre-change behavior; flag-key inventory entry present.
+- Config externalization: 100% of env-dependent values in schema; 0 hardcoded secrets in `src/`.
+- Semver: spec `info.version` aligned to release tag; deprecation policy 12-18 months declared.
+- Forward-compat: 0 breaking changes on stable endpoints; `Sunset` > `Deprecation` ordering on retiring endpoints.
+- Extension points: 100% of declared cross-cutting concerns have named interface + registration + stability block.
+- Plugin lifecycle: registry + DI + lifecycle hooks present when pluggable behavior declared.
+- Startup validation: process exits non-zero on invalid env var; field + expected shape in error message.
+- Backward-compat tests: Pact + spec-diff CI gates exit 0 on stable surfaces.
+
+## On fail
+
+The orchestrator running this skill emits a single-line verdict per gate (`GATE_N: PASS|FAIL <evidence-path>`) and aggregates them. One FAIL on a required gate blocks the merge regardless of reviewer approval status.
+
+Failure escalation per `agents/hatch3r-enhancability.md` status mapping: Gate 1 fail (behavior change without flag) → CRITICAL; Gate 2 credential hardcoded → CRITICAL; Gate 3 semver violation → CRITICAL; Gate 4 breaking change on stable surface → CRITICAL; Gate 7 silent fallback → CRITICAL; Gate 8 missing CI gate → CRITICAL; Gates 5/6 on optional surfaces → FINDINGS.
+
+## When this skill runs
+
+- Reviewer on any PR modifying user-visible behavior, public API surfaces (OpenAPI / GraphQL SDL / AsyncAPI), config schema, or extension-point interfaces.
+- Implementer pre-write when authoring a new user-visible behavior.
+- Verifier pre-merge gate before `gh pr merge` on protected branches touching public API or behavior-toggle surface.
+- API change audit during a `D14` or `D22` cycle, or whenever the maturity tier increases.
+- Plugin / extension-point surface review before declaring an interface stable.
+
+## Cross-References
+
+- `rules/hatch3r-feature-flags.md` — OpenFeature client wiring + flag-key inventory.
+- `rules/hatch3r-api-versioning.md` — semver bumps + deprecation timeline + Sunset header policy.
+- `rules/hatch3r-api-design.md` — RFC 9457 error format + spec-first mandate.
+- `rules/hatch3r-secrets-management.md` — hardcoded credential ban.
+- `agents/shared/quality-charter.md` §API quality + §AI feature backend.
+
+## References
+
+- Semantic Versioning 2.0.0 — `semver.org/`
+- RFC 9745 Deprecation header — `www.rfc-editor.org/rfc/rfc9745.html`
+- RFC 8594 Sunset header — `datatracker.ietf.org/doc/html/rfc8594`
+- OpenFeature Specification — `openfeature.dev/specification/`
+- Zuplo Semantic API Versioning — `zuplo.com/learning-center/semantic-api-versioning`
+- Zuplo HTTP Deprecation Header — `zuplo.com/learning-center/http-deprecation-header`
+- oasdiff — `oasdiff.com`
+- Pact — `docs.pact.io/`