bigpowers 2.85.2 → 2.86.0

package/skills/smoke-test/SKILL.md

@@ -1,5 +1,7 @@
+# story: e80s02
 ---
 name: smoke-test
+phase: verify
 description: "Post-deploy health-check against a live URL. Validates HTTP status, response content, and critical endpoints. Runnable standalone OR as the final step of the deploy skill."
 model: sonnet
 effort: standard
@@ -11,58 +13,72 @@ effort: standard
 >
 > **HARD GATE** — A failed smoke test means the deployment is broken. Do NOT mark a deploy as successful until all smoke checks pass.
 
-Validate a deployed application is healthy by running a configurable set of HTTP checks against live URLs. Each check asserts:
-- HTTP status code (e.g., 200 for success, 404 for expected-not-found)
-- Response body content signal (regex or jq expression)
-- Response time threshold (optional)
-
-Can be run standalone for quick health checks or chained as the final step of the `deploy` skill.
+Validate a deployed application is healthy by running HTTP checks against live URLs. Each check asserts HTTP status, optional body signal (regex), and optional response-time threshold.
 
 ## Configuration
 
-Smoke checks are defined in `smoke-checks.yaml` at the project root:
-
-See [REFERENCE.md](REFERENCE.md)
+Smoke checks live in `smoke-checks.yaml` at the project root:
 
-Checks can also be specified inline via environment variables or CLI arguments for ad-hoc use.
-
-### Check Schema
+```yaml
+base_url: "https://example.com"
+checks:
+  - name: "Homepage"
+    path: "/"
+    expected_status: 200
+    content_signal: "welcome|ok"
+    max_response_time_ms: 3000
+```
 
 | Field | Required | Default | Description |
 |-------|----------|---------|-------------|
-| `name` | Yes | — | Human-readable check name (used in report) |
+| `name` | Yes | — | Human-readable check name |
 | `path` | Yes | `/` | URL path relative to base_url |
 | `method` | No | `GET` | HTTP method |
 | `expected_status` | No | `200` | Expected HTTP status code |
-| `content_signal` | No | — | Regex or string to find in response body |
-| `max_response_time_ms` | No | — | Fail if response slower than this threshold (ms) |
+| `content_signal` | No | — | Regex or string in response body |
+| `max_response_time_ms` | No | — | Fail if slower than threshold (ms) |
+
+Ad-hoc single-URL mode: `DEPLOY_URL=https://host bash scripts/run-smoke.sh`
 
 ## Process
 
-### 1. Load smoke checks
+### 1. Load checks
 
-See [REFERENCE.md](REFERENCE.md)
+```bash
+SMOKE_CHECKS_FILE="${SMOKE_CHECKS_FILE:-smoke-checks.yaml}"
+BASE_URL="${DEPLOY_URL:-$BASE_URL}"
+test -f "$SMOKE_CHECKS_FILE" || test -n "$BASE_URL" || { echo "ERROR: no checks file or URL"; exit 1; }
+```
 
 ### 2. Run each check
 
-For each check in the configuration, perform an HTTP request:
+```bash
+bash scripts/run-smoke.sh "${DEPLOY_URL:-}" "${SMOKE_CHECKS_FILE:-smoke-checks.yaml}"
+```
 
-See [REFERENCE.md](REFERENCE.md)
+The runner performs curl requests per check, records pass/fail per assertion, and prints a summary.
 
 ### 3. Assert results
 
-See [REFERENCE.md](REFERENCE.md)
+- Any HTTP status mismatch → FAIL
+- Missing `content_signal` when configured → FAIL
+- Response time over `max_response_time_ms` → FAIL
+- Exit code non-zero → deployment not healthy
 
 ### 4. Generate report
 
-See [REFERENCE.md](REFERENCE.md)
+Capture stdout from `run-smoke.sh` as evidence. Persist to `specs/verifications/smoke-<date>.log` for release-branch.
 
 ## Integration with deploy skill
 
-The `deploy` skill references `smoke-test` as its final verification step:
-
 ```bash
-# In deploy workflow — after successful deploy
 DEPLOY_URL="$DEPLOY_URL" bash scripts/run-smoke.sh
 ```
 
+## Verify arc
+
+Part of **★ VERIFY ★**: `verify-work` → `validate-contracts` → `smoke-test` → `run-evals` → `audit-code`
+
+## Verify
+
+→ verify: `test -x scripts/run-smoke.sh && grep -q 'run-smoke.sh' skills/smoke-test/SKILL.md && grep -qv 'See \[REFERENCE.md\]' skills/smoke-test/SKILL.md && echo OK`

package/skills/validate-contracts/SKILL.md

@@ -1,5 +1,7 @@
+# story: e80s02
 ---
 name: validate-contracts
+phase: verify
 description: "Assert data shape consistency across system boundaries — live API responses against JSON Schema, key-set comparison across layers, data shape validation for migrations and exports. Catches silent data corruption before deploy."
 model: sonnet
 effort: standard
@@ -11,60 +13,30 @@ effort: standard
 >
 > **HARD GATE** — Contract files MUST be version-controlled alongside code. Outdated contracts are worse than no contracts. If a contract hasn't been reviewed in 30 days, flag it as stale.
 
-Validate that data structures stay in sync across system boundaries — front-end vs
-back-end, API responses vs expected schemas, config files vs code assumptions,
-migration output vs target shape.
+Validate that data structures stay in sync across system boundaries — front-end vs back-end, API responses vs expected schemas, config files vs code assumptions, migration output vs target shape.
 
 ## Contract types
 
-Three modes of validation:
-
 | Mode | What it catches | When to use |
 |------|----------------|-------------|
-| **Schema** | API response shape mismatches (missing field, wrong type) | Before every deploy, after API changes |
+| **Schema** | API response shape mismatches | Before every deploy, after API changes |
 | **Key-set** | Missing/unexpected keys across two data sources | Translation files, configs, enum definitions |
-| **Shape** | Column type or format violations in data files | After migrations, before consuming exports |
+| **Shape** | Column type or format violations | After migrations, before consuming exports |
 
 ## Contract file convention
 
-All contract files live in `specs/contracts/` and use YAML:
-
-See [REFERENCE.md](REFERENCE.md) for examples.
-
-### 1. API Response Contracts (`--schema`)
+All contract files live in `specs/contracts/` as YAML. See [REFERENCE.md](REFERENCE.md) for extended examples.
 
-Define expected API response shapes and validate live endpoints against them:
+### Key-set example
 
-See [REFERENCE.md](REFERENCE.md) for examples.
-
-Usage:
-
-```bash
-validate-contracts --schema specs/contracts/users.schema.yaml --url https://api.example.com/users
-# → PASS: /api/users matches expected schema (3/3 fields, types ok)
-# → FAIL: /api/users — field 'email' has type null (expected string)
+```yaml
+# specs/contracts/i18n-keys.yaml
+sources:
+  reference: src/locales/en.json
+  target: src/messages/en.json
+mode: subset
 ```
 
-### 2. Key-Set Contracts (`--key-set`)
-
-Assert that two data sources share a consistent set of keys:
-
-See [REFERENCE.md](REFERENCE.md) for examples.
-
-Usage:
-
-See [REFERENCE.md](REFERENCE.md) for examples.
-
-### 3. Data Shape Contracts (`--shape`)
-
-Validate that a data file matches expected column types and constraints:
-
-See [REFERENCE.md](REFERENCE.md) for examples.
-
-Usage:
-
-See [REFERENCE.md](REFERENCE.md) for examples.
-
 ## Process
 
 ### 1. Define contract
@@ -74,29 +46,20 @@ Create a YAML file in `specs/contracts/` following the schema for the mode.
 ### 2. Run validation
 
 ```bash
-bash scripts/validate-contracts.sh <contract-file>
+bash scripts/validate-contracts.sh specs/contracts/<contract>.yaml
 ```
 
-The runner auto-detects the contract type from the file content (presence of `schema:`,
-`sources:`, or `file:` + `fields:` keys).
+The runner auto-detects key-set contracts (`sources:` block). Schema and shape modes are documented in REFERENCE.md for consumer projects.
 
 ### 3. Read the report
 
-Output is JSON Lines (one event per line) plus a human-readable summary:
-
 ```
-{"event":"pass","check":"users.schema","detail":"3/3 fields match types"}
-{"event":"warn","check":"users.schema","detail":"field 'avatar' has format: uri (unexpected)"}
-{"event":"fail","check":"i18n-keys","detail":"missing: 2 keys in target"}
+PASS: key-set contract
+# or
+FAIL: key-set — N keys in reference missing from target
 ```
 
-Final summary:
-
-```
-=== Validate Contracts Summary ===
-Schema: 3/3 pass | Key-set: 1/1 fail | Shape: 2/2 pass
-FAILED: 1 contract has divergence
-```
+JSON Lines output for CI is planned for schema/shape modes; key-set failures exit non-zero.
 
 ### 4. Fix divergence
 
@@ -107,7 +70,13 @@ FAILED: 1 contract has divergence
 ### 5. Re-validate
 
 ```bash
-bash scripts/validate-contracts.sh <contract-file>
-# → All pass → ready to deploy
+bash scripts/validate-contracts.sh specs/contracts/<contract>.yaml
 ```
 
+## Verify arc
+
+Part of **★ VERIFY ★**: `verify-work` → `validate-contracts` → `smoke-test` → `run-evals` → `audit-code`
+
+## Verify
+
+→ verify: `test -x scripts/validate-contracts.sh && bash scripts/validate-contracts.sh --self-test && grep -q 'validate-contracts.sh' skills/validate-contracts/SKILL.md && echo OK`

package/skills/validate-fix/REFERENCE-generalize-fix.md

@@ -0,0 +1,31 @@
+# Generalize-fix (e80s04 / GH #98)
+
+After local hardening in `validate-fix`, sweep the **defect class** across the codebase.
+
+## Steps
+
+1. **Classify** — name the pattern (e.g. `unscoped org query`, `fail-open verify`, `hardcoded package manager`).
+2. **Sweep** — grep for sibling instances; record `match_count` and `grep_pattern`.
+3. **Resolve** — patch all matches in this PR **or** file one tracking issue listing every remaining instance.
+4. **Artifact** — write sweep evidence before declaring done:
+
+```bash
+cat > specs/verifications/generalize-sweep-BUG-YYYY-MM-DD-slug.json <<EOF
+{
+  "defect_class": "fail-open-verify",
+  "grep_pattern": "\\\\|\\\\| echo",
+  "match_count": 0,
+  "sweep_scope": "skills/*/SKILL.md",
+  "patched_in_pr": [],
+  "tracked_issues": []
+}
+EOF
+bash scripts/verify-generalize-sweep.sh specs/verifications/generalize-sweep-*.json
+```
+
+## Security classes
+
+When the defect class is security- or gate-relevant:
+
+- Add a row to `security-review` CWE fixture table (see `skills/security-review/SKILL.md` § CWE mapping mandate).
+- If security-impact was MEDIUM+: add regression test, false-positive exclusion rule, and threat-model update (HIGH+).

package/skills/validate-fix/SKILL.md

@@ -1,3 +1,5 @@
+# story: e80s01
+# story: e80s04
 # story: e45s08
 ---
 name: validate-fix
@@ -7,7 +9,7 @@ description: Prove a fix works before declaring done — re-run the failing test
 ---
 
 # Validate Fix
-> **HARD GATE** — **HARD GATE** — Fix must not regress. Run full test suite and manual UAT before declaring success. A fix that passes tests but breaks something else is a failure.
+> **HARD GATE** — Fix must not regress. Run full test suite and manual UAT before declaring success.
 
 
 Prove the fix works. "I think it works" is not evidence. Run the suite, show the output, then harden against recurrence.
@@ -65,10 +67,13 @@ For every bug fixed, add at least one prevention layer:
 - [ ] At least one hardening mechanism added
 - [ ] Hardening mechanism is tested
 
-> **Security recurrence hardening** — If the bug's security-impact assessment (from investigate-bug) was MEDIUM or higher, additionally check:
-> - [ ] Security regression test added (covers the exploit path)
-> - [ ] False-positive exclusion rule added (if applicable)
-> - [ ] Threat model updated (if impact was HIGH+)
+### 5b. Generalize-fix (HARD GATE — e80s04 / GH #98)
+
+Sweep the **defect class** across the codebase after local hardening — see [REFERENCE-generalize-fix.md](REFERENCE-generalize-fix.md).
+
+- [ ] Defect class documented (not just the one-line root cause)
+- [ ] Grep sweep run and `match_count` recorded
+- [ ] `verify-generalize-sweep.sh` passes on the artifact
 
 ### 6. Update the bug file and registry.yaml
 
@@ -107,3 +112,7 @@ Mechanical verification (tests passing) is only half the fix. You must prove **b
 
 Suggest next skill: `audit-code` → `commit-message`.
 
+## Verify
+
+→ verify: `grep -q 'generalize-fix' skills/validate-fix/SKILL.md && test -x scripts/verify-generalize-sweep.sh && bash scripts/verify-generalize-sweep.sh --self-test && echo OK`
+

package/skills-lock.json

@@ -83,7 +83,7 @@
     },
     "develop-tdd": {
       "description": "Test-driven development with red-green-refactor loop using vertical slices. Use for features (epic tasks) or bugs (specs/bugs/BUG-*.md).",
-      "sha256": "91928da1d9757094",
+      "sha256": "8b3934e2291b863d",
       "path": "skills/develop-tddSKILL.md"
     },
     "diagnose-root": {
@@ -113,7 +113,7 @@
     },
     "enforce-first": {
       "description": "Apply the F.I.R.S.T test quality rubric (per CONVENTIONS.md §Tests) to a test suite or individual tests. Use when develop-tdd is writing tests, when test quality needs to be checked, or when user mentions F.I.R.S.T or \"test quality\".",
-      "sha256": "64cde2c5f741c77f",
+      "sha256": "1ec1183ee6377917",
       "path": "skills/enforce-firstSKILL.md"
     },
     "evolve-skill": {
@@ -143,7 +143,7 @@
     },
     "gate-trace": {
       "description": "\"Deterministic traceability quality gate — reads coverage matrix + blind-spot data, applies decision rules with oracle confidence downgrade, emits PASS/CONCERNS/FAIL/WAIVED verdict. Use before release-branch to gate merges on traceability.\"",
-      "sha256": "dd52baa85ff939e8",
+      "sha256": "87e0c49ff90ec34c",
       "path": "skills/gate-traceSKILL.md"
     },
     "generate-allure-report": {
@@ -333,7 +333,7 @@
     },
     "smoke-test": {
       "description": "\"Post-deploy health-check against a live URL. Validates HTTP status, response content, and critical endpoints. Runnable standalone OR as the final step of the deploy skill.\"",
-      "sha256": "664c11f36df51da8",
+      "sha256": "f75e9e57d4003209",
       "path": "skills/smoke-testSKILL.md"
     },
     "spike-prototype": {
@@ -368,12 +368,12 @@
     },
     "validate-contracts": {
       "description": "\"Assert data shape consistency across system boundaries — live API responses against JSON Schema, key-set comparison across layers, data shape validation for migrations and exports. Catches silent data corruption before deploy.\"",
-      "sha256": "7d944527859c3c14",
+      "sha256": "d93c9ae2953ac457",
       "path": "skills/validate-contractsSKILL.md"
     },
     "validate-fix": {
       "description": "Prove a fix works before declaring done — re-run the failing test, run the full suite, typecheck, lint, and harden against recurrence. Use after implementing a bug fix, when user says \"is this fixed?\", or before closing an investigation.",
-      "sha256": "e3a38b117a7f3b2d",
+      "sha256": "f94972af3fd48e3e",
       "path": "skills/validate-fixSKILL.md"
     },
     "verify-work": {