hatch3r 1.9.0 → 2.0.0

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

@@ -1,23 +1,34 @@
 ---
 id: hatch3r-report
-type: command
-orchestrator: false
-description: Generate an in-chat session report from the active or named transcript — every tool call, sub-agent delegation, and file edit, with diagnostics for missed parallelism, redundant work, and over-serialization.
+name: hatch3r-report
+type: skill
+description: Generates an in-chat session report from the active or named transcript — every tool call, sub-agent delegation, and file edit, with diagnostics for missed parallelism, redundant work, and over-serialization. Default = current session, executive summary, in-chat.
 tags: [maintenance]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
-parallel_tool_default: true
 ---
-## Agent Pipeline
-
-This command runs inline and does not spawn sub-agents. Parsing is driven by Bash + jq over the on-disk session transcript; the LLM only sees aggregated counts and triggered-heuristic evidence, never the raw JSONL. This keeps the command efficient (P7) even on 1000+ record sessions.
 
 # Session Report — Agentic Action Replay
 
 Render an in-chat report of what happened in a Claude Code session: every tool call, every sub-agent `Agent` delegation, every file edit, every hook event. Default = current session, executive summary, in-chat. Flags extend scope and depth. Two audiences: (a) users who want to understand the session end-to-end; (b) maintainers investigating runtime shape for framework-level optimizations.
 
----
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1) — only if invocation arguments are ambiguous
+- [ ] Step 1: Discover the session
+- [ ] Step 2: Aggregate via jq
+- [ ] Step 3: Compute diagnostics
+- [ ] Step 4: Render executive summary
+- [ ] Step 5: Render verbose timeline (--verbose only)
+- [ ] Step 6: Save to disk (--save only)
+```
+
+## Step 0 — Detect Ambiguity (P8 B1)
+
+This skill is read-only over local transcripts and produces no file mutations outside `.hatch3r/reports/` (and only with `--save`). The platform-native question tool is invoked only when the user's `--session <value>` argument fails to resolve to a readable file or when `--save` would overwrite an existing report — see Error Handling. Otherwise the skill runs without an ASK gate.
 
 ## Argument Parsing
 
@@ -80,8 +91,6 @@ Append `## Timeline`. For each assistant turn containing ≥1 tool_use, emit a n
 
 Create `.hatch3r/reports/` if missing. Write the rendered markdown (executive summary + timeline if `--verbose` set) to `.hatch3r/reports/{sessionId-short8}-{YYYYMMDD-HHMMSS}.md`. Append a `## Raw Counts (machine-readable)` section containing the jq-aggregated JSON in a fenced ```json``` block — this lets future tooling grep across sessions without re-parsing the source JSONL. Print the file path back to chat. The `.hatch3r/` directory is gitignored.
 
----
-
 ## Output Format
 
 ```markdown
@@ -125,8 +134,6 @@ Create `.hatch3r/reports/` if missing. Write the rendered markdown (executive su
 Re-run `/hatch3r-report --verbose` for the chronological timeline.
 ```
 
----
-
 ## Diagnostic Heuristics
 
 | ID | Heuristic | Trigger | Severity |
@@ -143,8 +150,6 @@ Re-run `/hatch3r-report --verbose` for the chronological timeline.
 
 Each fired record: `{id, severity, turns:[n,...], evidence, suggestion}`. Consolidate same-rule fires into one record per session.
 
----
-
 ## Error Handling
 
 | Condition | Action |
@@ -156,12 +161,10 @@ Each fired record: `{id, severity, turns:[n,...], evidence, suggestion}`. Consol
 | Malformed JSONL record encountered | Skip the record; increment a `skipped` counter; surface the count in the executive summary footer when non-zero. |
 | Read access denied to a transcript file | Print: "Cannot read {path}: permission denied." Exit. |
 
----
-
 ## Guardrails
 
 - **Never modify the JSONL.** Read-only access. All scratch files go to `$(mktemp)` and are deleted at end-of-run.
 - **Mask obvious secret patterns** (`sk-`, `ghp_`, `xoxb-`, `AIza`, `Bearer `) in any rendered tool_use input — substitute `{REDACTED-{prefix}}`. The transcript may contain ephemeral tokens from user pastes.
 - **Never write outside `.hatch3r/reports/`.** The `--save` target is fixed; do not honor flags or env vars that redirect output to other paths.
 - **Never abort on a malformed record.** Skip-and-count is the contract; aborting would hide the rest of the session from the operator (Silent Failure Contract — surface the skip count rather than swallowing it).
-- **Honor the iteration summary contract** (`rules/hatch3r-iteration-summary.md`) at the end of the parent assistant turn that invoked this command. The report content is not a substitute for the canonical Status / Outcome / Done block.
+- **Honor the iteration summary contract** (`rules/hatch3r-iteration-summary.md`) at the end of the parent assistant turn that invoked this skill. The report content is not a substitute for the canonical Status / Outcome / Done block.

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

@@ -0,0 +1,145 @@
+---
+id: hatch3r-scalability-verify
+name: hatch3r-scalability-verify
+type: skill
+description: Scalability verification gate before commit/release — stateless-handler ratio, back-pressure patterns, idempotency-key adoption, queue-based offloading, pool sizing, bulkheads, load-test pass at target scale
+tags: [review, scalability, floor:content-quality]
+scope: conditional
+globs: "src/handlers/**,src/routes/**,src/services/**,src/workers/**,**/k8s/**,**/manifests/**,**/k6/**,**/locust/**,**/gatling/**"
+precedence: normal
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+# Scalability Verification Gate
+
+## Quick Start
+
+This skill defines what "done" means for any feature shipping service code on horizontally-scaled tiers. Run before declaring a feature complete. The 8 gates below mix automated checks (machine-checkable on every PR) with one release-cadence gate (load test at target scale). Skipping any gate = the feature is not done. Functional tests passing alone do not satisfy this bar — a stateful handler on a horizontally-scaled tier breaks on the Nth request; a POST endpoint without `Idempotency-Key` duplicates side effects under retry storm.
+
+Inputs the skill expects:
+
+- A repository with `src/` (handlers, routes, services, workers).
+- A connection-pool config file (`pgbouncer.ini`, `knexfile.js`, `prisma.schema`, `application.yml` with HikariCP, `database.yml`).
+- A queue client configuration (SQS, Kafka, Redis Streams, Bull/BullMQ, Sidekiq, Celery).
+- A load-test script under `k6/`, `locust/`, or Gatling sims when claiming horizontal scaling.
+- A documented concurrency profile naming target RPS, peak RPS, and burst multiplier.
+
+Outputs the skill produces: an 8-line verdict block written to the PR conversation, plus a JSON artifact at `.audit-workspace/scalability-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: service / handler scope, target scale (current p99 vs 10x vs named load-test peak), gate selection (back-pressure vs idempotency vs pool-sizing vs full), concurrency envelope (steady-state RPS, peak RPS, burst multiplier), and topology (single-zone vs multi-region). Pool-size increases, queue-topology changes, and sticky-session removals are irreversible at production traffic — these MUST go through the protocol before action.
+
+## 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 scalability gate is checked. The DISPATCHER that decides WHEN to run it is the CQ specialist agent:
+
+- `agents/hatch3r-scalability.md` — invokes this skill as the closing scalability gate (CQ6) on PRs touching service code or scaling config. 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: Stateless-handler ratio ≥95%
+
+- Handler scan reports no in-memory session state, no module-level mutable globals, no sticky-session assumption on horizontally-scaled tiers.
+- Verified by AST grep against handler entry points: `req.session`, module-scope `let`/`var` mutables, in-process LRU caches keyed by `userId`.
+- Session storage externalized to Redis / JWT / signed-cookie.
+- <95% on user-facing routes → CRITICAL (load balancer round-robins break user state on every Nth request).
+
+## Gate 2: Request-coalescing + back-pressure on high-fan-out endpoints
+
+- Named pattern (semaphore via `p-limit`/`async-sem`, queue-depth limit via reverse-proxy LimitReqZone, token-bucket via Envoy `local_ratelimit`).
+- Documented rejection threshold and queue-depth telemetry.
+- Reject with HTTP 429 + `Retry-After` when threshold exceeded; never silently buffer beyond `max_inflight`.
+- Coalesce duplicate in-flight requests by request-key hash (singleflight pattern).
+
+## Gate 3: Database connection pool sizing per concurrency profile
+
+- `pool_size = ceil(expected_concurrent_requests × avg_query_time_ms / target_p99_ms)` documented in config alongside the inputs.
+- Hard cap below the database's `max_connections × 0.7` for admin sessions + replicas.
+- PgBouncer in `transaction` mode where pool-per-connection cost is the constraint.
+- Pool sized to dependency, not to handler concurrency. Mis-sizing → FINDINGS at High when pool exhaustion observed in load test.
+
+## Gate 4: Idempotency-Key on every POST/PUT/PATCH
+
+- Header acceptance + dedup-result storage per Stripe pattern.
+- Dedup window ≥24h (Stripe default), key length up to 255 chars, stored result returned on retry regardless of original success/failure.
+- Conflict semantics defined: same key + different request body → HTTP 422 with `idempotency_key_conflict`.
+- Missing on irreversible POST endpoint (payment, account creation) → CRITICAL.
+
+## Gate 5: Queue-based offloading for >1s operations
+
+- Background-job system (SQS / Kafka / Redis Streams / BullMQ / Sidekiq / Celery) with retry policy (decorrelated jitter per AWS Architecture Blog).
+- DLQ binding (max 3-5 attempts) + per-job idempotency at the handler level.
+- Enqueuer commits the database transaction before publishing (staged-jobs pattern); no synchronous >1s work on user-facing paths.
+- Visibility timeout ≥ p99 job duration × 2.
+
+## Gate 6: Bulkheading — resource pools isolated by tenant or critical path
+
+- Separate connection pools (or pool partitions) for tenant tiers (free / paid / enterprise) or critical-vs-batch paths.
+- Documented limits per pool prevent cascade failure when one tenant or one downstream dependency saturates.
+- Pattern: Netflix Hystrix-style bulkhead with `maxConcurrentExecutions` per dependency.
+- Missing bulkhead between tenant tiers → Medium FINDINGS (one large tenant's burst impacts every other tenant's p99).
+
+## Gate 7: Connection-pool exhaustion monitored (USE method)
+
+- Pool queue depth (`pool.waiting`), pool wait time (`pool.acquire_duration_p99`), and pool saturation (`active / max`) emit metrics per Google SRE USE method (Utilization, Saturation, Errors).
+- Saturation alerts wired with multi-window multi-burn-rate (2%/5%/10% per Google SRE workbook).
+- Alert when `pool.waiting > 0` for >30s OR `active/max > 0.8` for >2min.
+- Telemetry harness reuse: `skills/hatch3r-observability-verify` Gate 4 (RED+USE metrics).
+
+## Gate 8: Horizontal scaling validated via load test
+
+- k6 / Locust / Gatling run at named target RPS captures p99 latency, error rate, and pool-saturation metrics.
+- p99 within the documented budget; zero pool exhaustion events; idempotency-key dedup verified by replaying ≥10% of requests at peak.
+- Replicas auto-scale within target time (HPA / KEDA reaching target replica count within 2min on CPU > 70% or queue-depth threshold).
+- Load-test result attached to the PR or release notes.
+
+## Pass criteria
+
+All 8 gates pass = the feature is "done" enough to ship to production. Anything less = not done.
+
+- Stateless-handler ratio: ≥95% on user-facing routes.
+- Back-pressure pattern: named + documented threshold on every high-fan-out endpoint.
+- Pool sizing formula: documented + inputs visible in config.
+- Idempotency-Key adoption: 100% on POST/PUT/PATCH; dedup window ≥24h.
+- Queue offload: 100% of >1s operations; DLQ + decorrelated jitter + visibility ≥ p99 × 2.
+- Bulkhead: present on multi-tenant or critical-vs-batch surfaces.
+- Pool-saturation metrics + alerts: present per USE method.
+- Load test at target RPS: p99 within budget, 0 pool exhaustion, ≥10% dedup replay verified.
+
+## 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 functional-test status.
+
+Failure escalation per `agents/hatch3r-scalability.md` severity calibration: Gate 1 fail (stateful handler on horizontally-scaled tier without sticky-session strategy) → CRITICAL; Gate 4 fail (POST without Idempotency-Key on irreversible side effects) → CRITICAL; Gate 5 fail (>1s synchronous work on user-facing route) → High; Gates 3/6/7 → Medium; Gate 8 incomplete (no load test) → headroom-unstated Info but ship-block High when target unmet.
+
+## When this skill runs
+
+- Reviewer pass on PRs that add or modify request handlers, route definitions, queue clients, or connection-pool config.
+- Implementer pre-write for any new endpoint that performs >1s work, accepts POST/PUT/PATCH, or runs on a horizontally-scaled tier.
+- Verifier pre-merge gate for changes touching session storage, cache layers, or background-job systems.
+- Capacity-planning audit when service traffic projections change.
+- Load-test pre-release before any release claiming horizontal-scaling capability.
+
+## Cross-References
+
+- `rules/hatch3r-api-design.md` — idempotency requirement.
+- `rules/hatch3r-resilience-patterns.md` — bulkheads section.
+- `rules/hatch3r-observability-metrics.md` — USE method + burn-rate alerts.
+- `skills/hatch3r-observability-verify` — telemetry harness reuse for Gate 7.
+- `agents/shared/quality-charter.md` §Reliability quality + §API quality.
+
+## References
+
+- Stripe Idempotent Requests — `docs.stripe.com/api/idempotent_requests`
+- Stripe staged-jobs pattern — `stripe.com/blog/idempotency`
+- Brandur Leach Idempotency Keys in Postgres — `brandur.org/idempotency-keys`
+- Google SRE USE method (Brendan Gregg) — `www.brendangregg.com/usemethod.html`
+- AWS Architecture Blog decorrelated jitter — `aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/`
+- k6 documentation — `k6.io/docs/`
+- Stateless services failure modes — `medium.com/codeelevation/why-stateless-services-quietly-break-in-real-systems-and-how-to-fix-them-24fc20951046`

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

@@ -0,0 +1,144 @@
+---
+id: hatch3r-security-verify
+name: hatch3r-security-verify
+type: skill
+description: Security verification gate before commit/release — OAuth 2.1 + OIDC + DPoP + WebAuthn server-side, supply-chain floor (SBOM + provenance + SHA-pin + cosign), OWASP ASI01-10 control coverage, CVE acknowledgement
+tags: [review, security, supply-chain, floor:security, floor:content-quality]
+scope: conditional
+globs: "src/auth/**,**/.github/workflows/*.yml,**/Dockerfile,**/package.json,**/package-lock.json,**/pnpm-lock.yaml,**/yarn.lock"
+precedence: normal
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+# Security Verification Gate
+
+## Quick Start
+
+This skill defines what "done" means for any feature shipping security-sensitive code or release-touching artifacts. Run before declaring a feature complete. The 8 gates below mix automated checks (machine-checkable on every PR) with one release-cadence gate (CVE acknowledgement at release-cut). Skipping any gate = the feature is not done. Reviewer approval and passing functional tests alone do not satisfy this bar — a missing PKCE flag, an unpinned action SHA, or an `alg: none` JWT verifier ships exploitable code.
+
+Inputs the skill expects:
+
+- A repository with `src/auth/` (or equivalent path), `.github/workflows/`, lockfiles (`package-lock.json` / `pnpm-lock.yaml` / `yarn.lock`), and release manifests (`Dockerfile`, `kubernetes/*.yaml`).
+- Access to the project's CVE alert feed (`gh api repos/{owner}/{repo}/dependabot/alerts`) for Gate 8.
+- Access to the JWT verification configuration (the file or module that names `algorithms`, `audience`, `issuer`).
+
+Outputs the skill produces: an 8-line verdict block written to the PR conversation, plus a JSON artifact at `.audit-workspace/security-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: auth-flow scope (sign-in vs refresh vs step-up vs M2M), release-surface scope (workflow YAML vs container manifests vs SBOM tooling), gate selection (auth-only vs supply-chain-only vs full), threat-model assumptions (DPoP-bound browser tokens vs mTLS-bound service tokens vs bare bearer), and fix authority (fixes-in-scope vs audit-only).
+
+## 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 security gate is checked. The DISPATCHER that decides WHEN to run it is the CQ specialist agent:
+
+- `agents/hatch3r-security.md` — invokes this skill as the closing security gate (CQ3) on auth-touching PRs and release-prep flows. 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: OAuth 2.1 grant hygiene
+
+- PKCE on every public AND confidential client; `response_type=code` only; implicit grant absent; ROPC grant absent.
+- Exact-string `redirect_uri` allowlist (no wildcards); refresh-token rotation with reuse detection that revokes the entire token family on reuse.
+- Check: `rg -n "response_type=code" src/auth/ | rg -v "code_challenge"` — any match fails this gate (auth-code flow without PKCE).
+- Check: `rg -n "grant_type=(implicit|password)" src/auth/` — any match fails this gate.
+- Reference: `draft-ietf-oauth-v2-1-15`.
+
+## Gate 2: OIDC ID-token validation
+
+- Verifier validates `iss`, `aud`, `azp` (when `aud` is multi-valued), `exp`, `nonce`, and JWKS signature before session creation.
+- Clock-skew window documented (≤300s); RP-initiated logout (`end_session_endpoint`) and back-channel logout wired for SSO sessions.
+- Check: `rg -n "jwt\.(verify|decode)" src/auth/ | rg -v "audience|issuer"` — any match fails this gate (validator missing `aud` or `iss`).
+- Reference: OpenID Connect Core 1.0 §3.1.3.7.
+
+## Gate 3: Sender-constrained tokens (DPoP / mTLS)
+
+- DPoP (RFC 9449) for browser/mobile access tokens — proof JWT carrying `htm`/`htu`/`iat`/`jti` claims and access token bound via `cnf.jkt` thumbprint.
+- OR mTLS-bound tokens (RFC 8705) for service-to-service. Bare bearer tokens for browser clients fail this gate (High).
+- Check: `rg -n "Bearer " src/ | rg -v "DPoP|mTLS|cnf\.jkt"` — any browser-issued bearer without sender constraint fails the gate.
+
+## Gate 4: JWT BCP conformance
+
+- `alg` pinned per issuer; `alg: none` rejected at the verifier; `alg: HS*` rejected when verification key is asymmetric (key-confusion guard).
+- `kid` resolved against JWKS endpoint with cache TTL 1-24h; no PII in payload; revocation strategy named (introspection OR token-version table).
+- Check: `rg -n "alg.*none|jwt\.verify\([^,]+,[^,)]+\)$" src/` — any match fails this gate (`alg: none` accepted OR no `algorithms` option pinned).
+- Reference: RFC 8725.
+
+## Gate 5: Supply-chain floor (SBOM + provenance + SHA-pin + cosign)
+
+- SBOM attached to every release in CycloneDX 1.6+ (preferred per ECMA-424) or SPDX 3.0.1.
+- npm publication via OIDC trusted publishing with `--provenance`; every GitHub Action reference is a 40-char commit SHA.
+- Production container images consumed by digest and cosign-signed (keyless OIDC via sigstore).
+- Check: `rg -nE "uses: [^@]+@v?[0-9]+(\.[0-9]+)*$" .github/workflows/` — any match fails this gate (tag instead of 40-char SHA).
+- Check: `gh release view --json assets --jq '.assets[].name' | rg -i "(cyclonedx|spdx)"` — empty output on tagged release fails this gate.
+
+## Gate 6: WebAuthn server ceremony
+
+- Challenge cached server-side with TTL ≤300s and single-use marker; `origin` allowlist verified at assertion; RP-ID hash matched.
+- Signature validated against credential public key; signature counter strictly greater than stored value (replay guard); `user.id` is a server-side opaque identifier (NOT email or username).
+- Check: `rg -n "signCount" src/ | rg -v "[><]"` — any match fails this gate (counter stored without strict-monotonic check).
+- Reference: W3C WebAuthn Level 3 §7. Skip when no WebAuthn surface present.
+
+## Gate 7: Cookie security flags
+
+- Every auth cookie carries `__Host-` prefix + `HttpOnly` + `Secure` + `SameSite=Strict|Lax`.
+- `SameSite=None` paired with `Partitioned` (CHIPS) only when the cross-site context is documented.
+- Check: `rg -n "Set-Cookie" src/ | rg -v "__Host-|HttpOnly|Secure|SameSite"` — any auth cookie missing any flag fails this gate.
+- Reference: RFC 6265bis + CHIPS draft.
+
+## Gate 8: OWASP ASI01-10 + CVE acknowledgement
+
+- Every agent-produced module passes the current OWASP ASI revision check (100% control coverage).
+- CVE advisories ≤90 days old that match any project dependency are acknowledged in the finding registry with a `mitigated` OR `accepted` verdict + evidence URL.
+- Check: `gh api repos/{owner}/{repo}/dependabot/alerts --jq '.[] | select(.state=="open")'` — any unacknowledged alert ≤90 days old fails this gate.
+- Reference: OWASP Foundation + GitHub Security Advisories + OSV. Hardcoded secrets count: 0 per `rules/hatch3r-secrets-management.md`.
+
+## Pass criteria
+
+All 8 gates pass = the feature is "done". Anything less = not done.
+
+- Hardcoded secrets in `src/`: 0 (CRITICAL on any hit).
+- Supply-chain floor coverage: 100% (SBOM present + provenance + SHA-pinned actions + cosign-signed containers).
+- OWASP ASI01-10 controls: 100% coverage.
+- OAuth 2.1 PKCE: 100% of public + confidential clients.
+- JWT `alg: none` acceptance: 0 occurrences in `src/`.
+- Cookie flag coverage on auth cookies: 100% (`__Host-` + `HttpOnly` + `Secure` + `SameSite`).
+- Open CVE alerts ≤90 days unacknowledged: 0.
+
+## 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-security.md` Status discipline table: Gate 4 fail (`alg: none` accepted) → CRITICAL; Gate 1 fail (refresh-token rotation absent) → CRITICAL; Gate 5 fail (production container by tag) → CRITICAL; Gate 6/3/7/2 → High; Gate 8 → Medium escalating to High when exploitable.
+
+## When this skill runs
+
+- Reviewer pass on any PR touching `src/auth/*`, JWT verification, cookie wiring, OAuth client config, WebAuthn ceremony, or release workflow under `.github/workflows/*.yml`.
+- Verifier pre-merge gate on changes with `tags: floor:security` or `tags: floor:content-quality`.
+- Release-prep audit before publishing to confirm Gate 5 (supply-chain floor) on every release artifact.
+- CVE response when a ≤90-day advisory matches a project dependency.
+
+## Cross-References
+
+- `rules/hatch3r-auth-patterns.md`
+- `rules/hatch3r-passkey-server.md`
+- `rules/hatch3r-security-patterns.md`
+- `rules/hatch3r-secrets-management.md`
+- `rules/hatch3r-dependency-management.md`
+- `rules/hatch3r-container-hardening.md`
+
+## References
+
+- OAuth 2.1 (`draft-ietf-oauth-v2-1-15`) — `datatracker.ietf.org/doc/draft-ietf-oauth-v2-1/`
+- OpenID Connect Core 1.0 — `openid.net/specs/openid-connect-core-1_0.html`
+- RFC 9449 DPoP — `www.rfc-editor.org/rfc/rfc9449.html`
+- RFC 8725 JWT BCP — `www.rfc-editor.org/rfc/rfc8725.html`
+- W3C WebAuthn Level 3 — `www.w3.org/TR/webauthn-3/`
+- OWASP CycloneDX (ECMA-424) — `owasp.org/www-project-cyclonedx/`
+- sigstore / cosign — `sigstore.dev`
+- OWASP ASI — `owasp.org/www-project-application-security-verification-standard/`

package/dist/content/skills/hatch3r-team-convention-author/SKILL.md

@@ -0,0 +1,126 @@
+---
+id: hatch3r-team-convention-author
+name: hatch3r-team-convention-author
+type: skill
+description: Interactive workflow to elicit, draft, align, and persist a team's coding conventions and working agreements as a versioned project rule or convention doc. Use when a team is setting up shared norms, codifying tacit practices, or reconciling conflicting style decisions.
+tags: [maintenance, board]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+
+# Team Convention Author — Elicit, Draft, Align, Persist
+
+Captures a team's tacit coding conventions and working agreements into a single versioned artifact the whole team can read and an agent can enforce. Two output shapes: a **convention doc** (`docs/process/` markdown — for human-facing working agreements: ownership, review norms, communication) and a **project rule** (`.hatch3r/overrides/rules/` — for machine-enforceable code conventions: naming, structure, lint deltas — so the rule is tracked by `hatch3r status`/`verify` and regenerated into the adapter surfaces on `sync`, not written drift-invisibly into a generated file). The load-bearing step is Step 1: a convention written FOR a team by one person decays; a convention written BY the team through elicitation holds (team-charter methodology — see References).
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
+- [ ] Step 1: Elicit the team's conventions and working agreements
+- [ ] Step 2: Classify each item — code convention (rule) vs working agreement (doc)
+- [ ] Step 3: Cross-check against existing project rules and style guides
+- [ ] Step 4: Draft to the matching template
+- [ ] Step 5: Review with the team, then persist as a versioned artifact
+```
+
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any write, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target surface, 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 convention class is wanted (machine-enforceable code rule vs human working agreement); whether an existing convention doc/rule is being amended (a section rewrite that drops prior agreements is irreversible to readers who relied on them); the authoritative style guide for the stack (a new convention that contradicts an adopted style guide needs an explicit override decision); and who ratifies (one maintainer's preference is not a team agreement — see Step 5).
+
+## 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 convention class, one stack): inline.
+- Tier 2 (both a code-rule set AND a working-agreement doc, or conventions spanning ≥2 stacks): spawn one sub-agent per disjoint artifact via the Task tool; each drafts its own file.
+- Tier 3 (full team-handbook codification across many domains — frontend, backend, infra, review process): one fresh sub-agent per domain; orchestrator integrates the index only.
+
+Emit `sub_agents_spawned: { count, rationale }` in your output.
+
+## Step 1: Elicit the Team's Conventions and Working Agreements
+
+A convention is only adopted if the team shaped it. Elicit, do not dictate. Ask the team (or the maintainer relaying for the team) across these prompts, one focused question per turn:
+
+1. **Code conventions** — naming (files, types, functions), module/folder structure, import ordering, error-handling shape, test-file placement, comment style. Pull candidates from the existing codebase rather than from memory: a convention the code already follows in 80%+ of cases is a documented-default candidate, not a debate.
+2. **Working agreements** — review turnaround expectation, branch/PR naming, merge policy (squash vs merge-commit), required approvals, what blocks a merge, how disagreements are resolved, communication norms (where decisions are recorded).
+3. **Authority and overrides** — which published style guide is the tie-breaker for pure-style points (per Google eng-practices: the style guide is the absolute authority on style, and any style point not in the guide is personal preference — see References). Record the chosen style guide by name and URL.
+
+For each candidate, capture: the convention, one concrete example, and the rationale (why this over the alternative). A convention with no rationale is a preference, not an agreement — flag it for Step 5 ratification.
+
+## Step 2: Classify — Code Convention vs Working Agreement
+
+Route each elicited item to its output shape. The distinction drives where the artifact lands and how it is enforced.
+
+| Item type | Output shape | Lands in | Enforcement |
+|-----------|--------------|----------|-------------|
+| Machine-checkable code rule (naming, structure, import order, lint delta) | Project rule | `.hatch3r/overrides/rules/<id>.md` (+ `.mdc` companion) so `hatch3r status`/`verify` track it and `sync` regenerates it into the adapter surfaces; OR a linter config | Agent reads the rule each session; linter where expressible |
+| Human working agreement (review norms, merge policy, communication, decision-recording) | Convention doc | `docs/process/<topic>.md` | Read by humans; cited in PR templates and onboarding |
+| Pure-style point already owned by an adopted style guide | Neither — link to the style guide | The convention doc's "Authority" section | The style guide is the source of truth; do not restate it |
+
+Do not duplicate a rule the adopted style guide or an existing linter config already enforces — link to it instead (single-source-of-truth; restating drifts). A code convention that a linter can check belongs in the linter config with a one-line pointer from the rule, not as prose the agent must interpret.
+
+Write a machine rule into `.hatch3r/overrides/rules/`, not directly into a generated adapter surface such as `.cursor/rules/*.mdc` or `docs/process/`. A rule authored straight into the adapter output is invisible to `hatch3r status`/`verify` drift detection and is overwritten on the next `sync` regeneration (SA14.3-F6). The overrides subtree is the user-content surface `hatch3r` re-emits with overrides on every sync; `docs/process/` stays the home for human working agreements only.
+
+## Step 3: Cross-Check Against Existing Project Rules and Style Guides
+
+Before drafting, reconcile against what already exists:
+
+1. **Read the current rule surface** — list every existing rule file and its `description`. A new convention that overlaps an existing rule is an amendment to that rule, not a new file (per content-authoring duplication check).
+2. **Read the adopted style guide** — if a candidate convention contradicts the team's published style guide, surface the conflict to the team with both positions and a recommended resolution; do not silently override. Record the resolution as an explicit override decision with rationale.
+3. **Detect internal contradictions** — two elicited agreements that conflict (e.g., "squash all PRs" vs "preserve commit history for releases") are a Step 5 ratification blocker, not a draft-time guess.
+
+Output of this step: a reconciliation list — `{ candidate, status: new | amends:<rule-id> | conflicts:<source> | duplicate-drop }`.
+
+## Step 4: Draft to the Matching Template
+
+**Project rule** (machine-enforceable code convention):
+- Target path: `.hatch3r/overrides/rules/<id>.md` plus the `.mdc` companion (same body bytes; `scope: always` → `alwaysApply: true`, `scope: conditional` + `globs` → `globs: [...]` + `alwaysApply: false`). This is the user-content override surface `hatch3r` tracks for drift and regenerates on sync — the same path the `cursor` rule importer writes to.
+- Frontmatter: `id`, `description` (one line, what the rule enforces), scope (`always` for repo-wide, or a glob for path-scoped).
+- Body: each convention as `Convention → one concrete example → rationale`. State the passing condition concretely ("test files live next to source as `*.test.ts`", not "tests organized well").
+- Link, do not restate, anything a linter or the adopted style guide already enforces.
+
+**Convention doc** (`docs/process/<topic>.md`, working agreement):
+1. Purpose — one sentence: what this agreement governs and who it binds.
+2. Agreements — a table or numbered list, each row: the agreement, the rationale, and how it is verified or observed.
+3. Authority — the adopted style guide (name + URL) that wins on pure-style points; the decision-recording location.
+4. Review and revision — how the team amends this doc (so it stays a living agreement, not a frozen edict).
+5. Ownership footer — owner, ratifying team, last-updated date.
+
+Both shapes: every agreement carries a rationale; no agreement is stated as an unexplained mandate. Use measurable passing conditions, not subjective adjectives ("PR description states the change and the why", not "good PR descriptions").
+
+## Step 5: Review With the Team, Then Persist
+
+A convention written for a team is weaker than one written by a team; ownership is built, not delegated (team-charter methodology — see References). Before persisting:
+
+1. **Present the draft to the team for ratification** — every flagged item (no-rationale preferences, internal contradictions, style-guide overrides) is resolved by the team, not assumed. Surface them as explicit decisions.
+2. **Confirm scope** — repo-wide rule vs path-scoped; project doc vs shared-across-repos.
+3. **Persist each output to its tracked surface:**
+   - **Machine rule** → write `.hatch3r/overrides/rules/<id>.md` + its `.mdc` companion. This registers the rule in the user-content override surface, so `hatch3r status`/`verify` report drift on it and `hatch3r sync` regenerates it into the adapter outputs (`.cursor/rules/`, `CLAUDE.md`, Copilot instructions). A convention written straight into a generated adapter file instead is drift-invisible and is clobbered on the next sync (SA14.3-F6) — never persist there. If the team is instead amending an existing canonical rule rather than adding a new one, register the delta in `.hatch3r/hatch.json` `customization` (or the `.customize.md` layer) for that rule id, not a fresh override file.
+   - **Working agreement** → write the doc to `docs/process/<topic>.md` (human-facing; not a drift-tracked machine artifact).
+   Set the ownership footer (owner, ratifying team, last-updated) on each. Link the doc from the contributing guide or PR template so it is discoverable; an unlinked convention doc is not adopted.
+4. **Record the decision trail** — note which conventions were team-ratified and which are documented codebase-defaults, so a later reader knows what is negotiable.
+
+## Error Handling
+
+- **Maintainer relays for an absent team and cannot ratify:** persist the draft marked `status: proposed — pending team ratification` and list the unresolved items; do not stamp it as an adopted agreement.
+- **Candidate convention contradicts the adopted style guide:** surface both positions and a recommended resolution to the team; record the chosen override as an explicit decision with rationale. Never silently override the style guide.
+- **Two elicited agreements conflict:** stop at Step 3, present both with trade-offs, and require a team decision before drafting. Do not guess the winner.
+- **Overlap with an existing rule:** amend the existing rule rather than create a near-duplicate; cite the rule id in your output (duplication check).
+- **Convention has no rationale:** flag it as a preference at Step 5 for the team to either justify or drop; do not persist unexplained mandates.
+
+## Definition of Done
+
+- [ ] Conventions elicited from the team (or relayed) with one concrete example + rationale each
+- [ ] Each item classified to its output shape (project rule vs working-agreement doc vs style-guide link)
+- [ ] Reconciled against existing rules and the adopted style guide; conflicts and overrides resolved by the team, not assumed
+- [ ] Drafted to the matching template with measurable passing conditions and per-agreement rationale
+- [ ] Team-ratified (or marked `proposed — pending ratification`); ownership + last-updated footer present
+- [ ] Machine rules written to `.hatch3r/overrides/rules/<id>.md` (+ `.mdc`) — or registered via `.hatch3r/hatch.json` `customization` when amending a canonical rule — so `hatch3r status`/`verify` track them and `sync` regenerates them; not authored straight into a generated adapter file
+- [ ] Working agreements persisted to `docs/process/`, linked from contributing guide / PR template, and the negotiable-vs-default decision trail recorded
+- [ ] No duplication of a rule an adopted style guide or linter already enforces
+
+## References
+
+- Google. "Google's Engineering Practices documentation — The Standard of Code Review." `https://google.github.io/eng-practices/review/reviewer/standard.html` (accessed 2026-06-02, google.github.io, established-library / official-docs; CC-BY 3.0). Source for Step 1's authority principle (the style guide is the absolute authority on pure-style points; any style point not in the guide is personal preference) and the improvement-over-perfection framing applied to convention adoption. Repository: `https://github.com/google/eng-practices`.
+- Atlassian. "How to Create a Team Charter — The Workstream." `https://www.atlassian.com/work-management/project-collaboration/team-charter` (accessed 2026-06-02, atlassian.com, established-library). Source for Step 1's elicitation stance and Step 5's ratification principle (a charter written BY the team holds; one written FOR the team decays — ownership is built, not delegated) and the purpose/values/roles/communication-norm component set behind the convention-doc template. Corroborated by Easy Agile, "Team Charter, Working Agreement, & Social Contract — Template and Guide." `https://www.easyagile.com/blog/team-charter-working-agreement-social-contract-template-guide` (accessed 2026-06-02, easyagile.com, established-library).