pi-aia-asf 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -7,6 +7,79 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-27
+
+### Added
+
+- (describe changes for 0.9.0)
+
+
+### Added
+
+- **Indexed reference structure (P-index)** — SKILL.md now carries a reference
+  index table (file → covers → read when) so the agent finds the right
+  section on demand; each reference is a small single-concern doc with a
+  "Read when / Skip when" header. Default context cost is unchanged (SKILL.md
+  only); large work reads at most the 3–4 references its phase needs.
+- **`references/06f-stability.md`** — stability patterns (timeouts, bounded
+  retries, circuit breaker, bulkheads, bounded result sets, fail fast,
+  graceful shutdown) + error-handling design rules + observability DoD for
+  service-like deliverables (health endpoint, structured logs, correlation
+  IDs, runbook) (P06, P08, P07).
+- **`references/06g-test-design.md`** — risk-based test derivation
+  (likelihood × impact, technique selection table) + determinism rules
+  (P10, P11).
+- **`references/06h-security.md`** — one-page threat model (trust boundaries,
+  STRIDE, registry), ASVS 5.0-based DoD with chapter/level selection,
+  supply-chain & secrets gates, and the agent/tool-surface chapter (P15,
+  P16, P17, P18).
+
+### Changed
+
+- **05-plan.md** — PLAN.md template extended: Decisions (ADRs, P01), Quality
+  requirements (ISO 25010 scenarios, P02), Architecture evaluation (ATAM-lite,
+  P03), optional Views (P04).
+- **04-adversarial.md** — added security lens (threat model) and architecture
+  lens (ATAM-lite) applied on every review (P15, P03).
+- **06c-code-quality.md** — deep-module principle (interface simpler than
+  implementation, P05), code smells in 5 groups (P09), characterization
+  baseline for refactoring untested code (P13).
+- **06b-testing-qa.md** — Rule 16 determinism (flaky = defect, P11), Rule 17
+  delivery report fields incl. not-tested register (P14), Rule 18
+  escaped-defect feedback loop (P21); DoD extended with delivery-report,
+  stability and security lines.
+- **06e-code-health.md** — report-only depth metric (P05) + supply-chain
+  (npm audit/osv-scanner) and secrets (gitleaks) gates with config (P17).
+- **07-release.md** — verify-first now re-runs the dependency/security check
+  before every release (P17 RV loop).
+- **06-implementation.md** — drift self-correction: named anti-patterns,
+  stop → revert → self-correct → continue, escalate only on genuine
+  conflicts (P20).
+- **06d-delegation.md** — Part 3: independent reviewer gate for large work
+  (fresh-context hostile reviewer, blockers vs suggestions, autonomous
+  triage, human only on genuine conflicts) (P19).
+- **SKILL.md** — ASF self-modification policy: facts may be updated in the
+  same change; standards change only via the review process (P22).
+- **test/test-improvements.mjs** — new suite (84 checks) verifying the
+  indexed structure and that each proposal landed in its designated file.
+- **Configurable release policy (P23)** — `.asf-release.json` at the project
+  root (optional): `when` (user-stated conditional rules: "when X is true,
+  publish automatically; when Y is true, do this…") and `how` (user-stated
+  instructions with all technical details that the ASF drives with judgment,
+  not a deterministic command list). Default with no file = current stance
+  (always send for final review); user definition takes precedence.
+  **Test on publish / in production, if applicable — always** (package →
+  clean-room registry install + observable end state; deployed app → prod
+  smoke test). The ASF's own release procedure is codified via the same
+  mechanism (repo `.asf-release.json`).
+
+## [0.8.1] - 2026-09-25
+
+### Added
+
+- (describe changes for 0.8.1)
+
+
 ## [0.8.0] - 2026-09-12
 
 ### Added

package/README.md

@@ -57,7 +57,7 @@ Then `/reload`.
 
 ## How it works
 
-- **Skill** (`skills/aia-asf/SKILL.md`) — the workflow itself, with per-phase reference guides in `references/`.
+- **Skill** (`skills/aia-asf/SKILL.md`) — the workflow itself, with per-phase reference guides in `references/`. The skill uses **progressive disclosure**: only SKILL.md (the phase flow + gates + a reference index) loads by default; each reference is a small single-concern doc the agent reads on demand when its phase needs it (the index's "Read when" column tells it which). Small work reads at most the testing + code-quality standards; large work reads the ones its phase calls for.
 - **Extension** (`index.ts`) — `/asf` commands, per-project phase state (`~/.pi/agent/skills/aia-asf/projects/<project>/state.json`), dependency checks.
 - **Specs shared with pi-vigilant** — ASF drives `capture_spec` during intake; pi-vigilant re-verifies every spec at task end and blocks "done" while MUST specs are open. One spec file, two systems.
 
@@ -86,6 +86,28 @@ Flags: `--diff` (compare vs committed `.asf-code-health-baseline.json`),
 must be project devDependencies (eslint, eslint-plugin-sonarjs, jscpd, madge,
 dependency-cruiser); the gate never installs anything.
 
+## Release policy (configurable)
+
+Publishing is the user's decision **by default** — the factory prepares the
+release and gets explicit approval. A project can define its own release
+policy in `.asf-release.json` at the project root (optional):
+
+```json
+{
+  "when": "when the full suite is green and the bump is patch/minor → publish automatically; when the bump is major → send for final review; when the suite is not green → fix first, never publish",
+  "how": "To publish: connect with npm using the credentials in ~/.npmrc (2FA token; verify with `npm whoami`), sync git (`git pull --rebase`), run `npm run release <level>`, then verify the published version from the registry in a clean install..."
+}
+```
+
+- **`when`** — user-stated conditional rules the ASF evaluates against the
+  current state (suite green, bump scope, credentials) and acts on.
+- **`how`** — user-stated instructions with all technical details; the ASF
+  drives the release with judgment, not as a deterministic command list.
+- No file → default: always send for final review; standard workflow in
+  `references/07-release.md`.
+- **Always test on publish / in production, if applicable** — verify the
+  shipped artifact from the registry (clean-room install) or smoke-test prod.
+
 ## Hygiene rules enforced
 
 - Test-first; only green commits

package/index.ts

@@ -52,6 +52,7 @@ const QA_CHECKLIST: Array<{ key: string; label: string }> = [
   { key: "browser", label: "Web surfaces exercised through a real browser (n/a if none)" },
   { key: "specs", label: "Every MUST spec 'met' with concrete evidence" },
   { key: "trace", label: "Spec-to-code traceability: every met spec has outcome → codePath → test" },
+  { key: "code-health", label: "Code Health Gate passed (or enabled:false / gate.mode:warn with the report shown)" },
   { key: "surface", label: "Every delivered feature is consumed by a surface (UI or API) — nothing dead" },
   { key: "e2e", label: "Feature specs have an end-to-end behavioral test through the real entry point" },
   { key: "honest", label: "Skipped/inconclusive checks reported explicitly" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-aia-asf",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Ai Applied Agentic Software Factory — codifies the full software development flow: intake, research, spec capture, adversarial analysis, planning with approval gates, test-first implementation, and release. Requires pi-vigilant, pi-smart-web-search, pi-smart-fetch, and pi-aia-browser.",
   "keywords": [
     "pi-package",

package/skills/aia-asf/SKILL.md

@@ -119,6 +119,13 @@ Turn the intake answers + research into the authoritative spec set.
 
 > **Small work:** skip the formal gate. Do a quick mental pass over edge cases and failure modes while implementing; if something real surfaces, fix it or capture a spec. No user checkpoint.
 
+> **Large work:** read `references/04-adversarial.md` for the full checklist
+> (per-spec, architecture, security, code-quality, traceability lenses). For
+> security, also read `references/06h-security.md` — write the one-page threat
+> model (trust boundaries + STRIDE + registry) as part of the plan. For
+> stability, ask the `references/06f-stability.md` questions about every
+> external call in the design.
+
 Challenge the plan like a hostile reviewer before committing to it. For each spec and the overall design, ask and resolve:
 
 - **Edge cases** — empty input, zero users, max load, missing data, concurrency
@@ -147,7 +154,11 @@ Write `PLAN.md` in the project root (repo root, or cwd if no repo). Structure:
 ## Goal
 ## Context
 ## Approach (from research, cited)
+## Decisions (ADRs — one per significant decision)
+## Quality requirements (ISO 25010 scenarios)
 ## Architecture / Design
+## Architecture evaluation (ATAM-lite)
+## Views (context / runtime / deployment — optional)
 ## Milestones (M1..Mn with exit criteria)
 ## Task list (per milestone, checkboxes)
 ## Dependencies (with licenses)
@@ -155,6 +166,9 @@ Write `PLAN.md` in the project root (repo root, or cwd if no repo). Structure:
 ## Definition of done (tests, deploy, release)
 ```
 
+The full template with examples is in `references/05-plan.md` — read it before
+writing the plan.
+
 Keep the plan **implementation-ready**: any competent engineer (or agent) can execute the task list without re-deriving decisions.
 
 **Gate 5 — MANDATORY user approval (large only)**: present the plan and ask explicitly:
@@ -195,6 +209,11 @@ Keep the plan **implementation-ready**: any competent engineer (or agent) can ex
 > 4 concurrent writers left only 1 of 4 edits, silently, all exiting 0 — and **exit code 0
 > does not mean success**, so always validate the returned output against what you asked for.
 
+> **Read on demand (only if they apply):** `references/06f-stability.md` if the
+> deliverable makes external calls; `references/06g-test-design.md` for the
+> test plan or non-trivial tests; `references/06h-security.md` if the
+> deliverable handles untrusted input, secrets, or agent-like tool surfaces.
+
 Execute the task list milestone by milestone. Discipline rules:
 
 1. **Test-first**: write/update tests before or with implementation; run them; only commit green.
@@ -218,8 +237,17 @@ Run the **Definition of Done checklist** in `references/06b-testing-qa.md` (Rule
 
 Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7 section): no duplicated shared logic, no hardcoded config values, every module tested standalone with the same calls it gets in the host, architecture writeup exists, existing functionality still green. **Documents too (06c Rule 9)**: no document so large that editing it is fragile — if a doc you worked on started causing edit failures/truncation, it was refactored (split by topic, parent kept as index, cross-references updated).
 
+Also check the **stability DoD** (`references/06f-stability.md`): if the deliverable makes external calls, it has timeouts and bounded retries (idempotent only). And the **security DoD** (`references/06h-security.md`): no secrets in the repo, no untrusted input reaches a shell/query/path unvalidated, no unbounded resource use on user-controlled input; for agent-like tool surfaces, every tool is least-privilege with an abuse-case test.
+
 **Large work:** run `/asf verify` — it mechanically validates the **spec-to-code traceability matrix** (M1): every `met` spec must carry `trace` (outcome → codePath → testFile + assertion), testFile must exist, assertion must appear in it. FAIL rows block delivery. **Verify ingested specs from external planning docs too** — the doc's ✅ markers are claims, not evidence.
 
+**Independent reviewer gate (large work, P19):** before delivery, run the
+independent review (fresh-context hostile reviewer, blockers vs suggestions;
+see `references/06d-delegation.md` Part 3). Triage autonomously — fix safe
+blockers, apply safe suggestions, escalate to the user **only** on genuine
+conflicts (conflicting requirements, product-level tradeoffs, scope
+conflicts). Record the review + triage in the delivery report.
+
 **Code Health Gate (large work, Gate 8):** run `/asf health` — it measures convolution objectively at function / module / architecture level (see `references/06e-code-health.md`) and fails the gate when thresholds are crossed. The gate is **on by default** with conservative thresholds; configure via `.asf-code-health.json` at the project root. **Fix the cause, not the threshold** (06e Rule 2). Small work shows the report but never blocks.
 
 1. Run the full test suite (all of it, not a subset); fix failures; re-run until green.
@@ -231,7 +259,7 @@ Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7
 3. Run `get_task_specs` and verify **every spec** with `update_spec_status` + concrete evidence (test output, build result, code inspection). Unverifiable → `partial` + ask the user. Never self-certify.
 4. **Report honestly**: never claim a check you didn't run; state explicitly anything
    skipped or inconclusive, and distinguish "tests pass" from "works for the user".
-3. If the project is a library/package that the user publishes (npm, GitHub release): **offer** to run the release (see `references/07-release.md`): version bump, CHANGELOG, git tag, push. **Publishing is always the user's decision** — never publish without explicit approval. Optionally offer to set up a CI/CD pipeline for publishing.
+3. If the project is a library/package that the user publishes (npm, GitHub release): **check the release policy** — read `.asf-release.json` at the project root if present (see `references/07-release.md`). It defines **when** (user-stated conditional rules: "when X is true, publish automatically; when Y is true, do this…") and **how** (instructions the ASF drives with judgment — credentials, git sync, publish steps). If the policy authorizes automatic publishing for the current state, drive the release per `how`; otherwise **offer** to run the release and get explicit approval (the default stance: publishing is the user's decision). **Always test on publish / in production, if applicable** — verify the shipped artifact from the registry / smoke-test prod, never assume it works. Optionally offer to set up a CI/CD pipeline for publishing.
 4. Present a completion summary: what was built, specs met, tests passing, how to use it.
 
 ---
@@ -245,7 +273,8 @@ Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7
 - ❌ Verifying a UI only via API/curl — browser testing is mandatory
 - ❌ Vague commits or CHANGELOG placeholders
 - ❌ Declaring done while specs are still `open`
-- ❌ Publishing anything without the user's explicit go-ahead
+- ❌ Publishing anything beyond the configured release policy — no `.asf-release.json` means the default: always get the user's explicit go-ahead
+- ❌ Publishing without testing the shipped artifact on publish / in production (if applicable)
 - ❌ Shipping a package without inspecting the packaged file list (`npm pack`)
 - ❌ Treating "no error" as "it worked" — malformed config is skipped **silently**
 - ❌ Verifying against a cached/stale install, or with an old duplicate still present
@@ -272,16 +301,50 @@ Also check the **modularity DoD** from `references/06c-code-quality.md` (Phase 7
 - ❌ Trusting unit tests as proof of wiring — assert the operator-facing outcome end-to-end
 - ❌ Trusting an external plan's ✅ (IMPROVEMENT-PLAN / delivery log) — ingest its items as specs and verify them
 - ❌ Implementing a spec literally when it creates product tension — challenge it and resolve with the user
-
-## References
-
-- `references/01-intake.md` — question bank and probing techniques (incl. external planning docs, M6)
-- `references/02-research.md` — research playbook with search templates
-- `references/04-adversarial.md` — adversarial checklist per area
-- `references/05-plan.md` — PLAN.md template with examples (incl. spec-to-code traceability matrix)
-- `references/06-implementation.md` — coding discipline details (incl. M4 challenge designs, M5 trace before claiming)
-- `references/06b-testing-qa.md` — **mandatory testing & QA standard** (14 rules + definition of done)
-- `references/06c-code-quality.md` — **mandatory modularity & maintainability standard** (9 rules, SSOT, testable-standalone, single escalation path, documents-are-code)
-- `references/06e-code-health.md` — **Code Health Gate** (objective convolution measurement; Gate 8 for large work)
-- `references/06d-delegation.md` — **intercom & subagents**: when to message another session, when to spawn isolated workers, the no-mutual-dependencies rule, and why exit codes lie
-- `references/07-release.md` — release workflow (versioning, CHANGELOG, tags, npm, CI/CD)
+- ❌ Shallow pass-through modules that add no abstraction; a new layer that hides nothing (06c P05)
+- ❌ Refactoring untested code without a characterization baseline (06c P13)
+- ❌ Fixing a smell instance by instance instead of the design (06c P09)
+- ❌ Drift: scope creep, approach drift, gate drift — stop, revert, self-correct (06-implementation P20)
+- ❌ Shipping a delivery summary without the report fields: spec status + evidence, test results, skipped checks, not-tested register (06b Rule 17)
+- ❌ Letting an escaped defect teach nothing — ask which gate should have caught it and close the gap (06b Rule 18)
+- ❌ Self-modifying the ASF's own rules during a task run — standards change only via the review process (P22)
+
+## Reference index (read on demand — never load all)
+
+Each reference is a small, single-concern doc. **Read only the ones your
+current phase needs** — the "Read when" column is the index. Small work
+reads at most 06b + 06c; large work reads the ones its phase calls for.
+
+| File | Covers | Read when |
+|---|---|---|
+| `01-intake.md` | question bank, probing, external planning docs (M6) | Phase 1 (large) |
+| `02-research.md` | research playbook, search templates | Phase 2 (large) |
+| `04-adversarial.md` | adversarial checklist (spec/architecture/security lenses) | Phase 4 (large) |
+| `05-plan.md` | PLAN.md template + ADRs + quality scenarios + ATAM-lite + views | Phase 5 (large) |
+| `06-implementation.md` | coding discipline, M4/M5, drift self-correction (P20) | Phase 6 |
+| `06b-testing-qa.md` | **mandatory** testing & QA standard (18 rules + DoD) | before writing tests (always) |
+| `06c-code-quality.md` | **mandatory** modularity standard (9 rules, deep modules, smells) | before structuring code |
+| `06d-delegation.md` | intercom & subagents + independent reviewer gate (P19) | before delegating; Phase 7 review (large) |
+| `06e-code-health.md` | Code Health Gate (+ depth, supply-chain, secrets metrics) | Gate 8 (large) |
+| `06f-stability.md` | stability patterns + error handling + observability (P06/P07/P08) | **if the deliverable makes external calls or is a service** |
+| `06g-test-design.md` | risk-based test derivation + determinism | Phase 6 large (test plan) / non-trivial tests |
+| `06h-security.md` | threat model, ASVS DoD, supply chain, agent tools | Phase 4/5 large; small = one line |
+| `07-release.md` | release workflow + **configurable release policy** (`.asf-release.json`: when/how) + test-on-publish | before publishing |
+
+## ASF self-modification policy (P22)
+
+The ASF's own rules, gates, and standards are **normative content** — they
+must never be self-modified during a task run (no "while I'm here, let me
+improve the rule").
+
+- **Facts may be updated in the same change**: package versions, external
+  tool behavior, SOTA findings, URLs — these are non-normative and stay
+  current.
+- **Standards change only through the review process**: propose it in
+  `docs/research/improvement-proposals.md`, review it, get approval, then
+  implement (the same flow that produced this version).
+- **Escalate, don't edit**: if a task reveals the ASF's own rules are wrong
+  or missing, that is a proposal + a user decision, not a silent edit.
+- **Rule 9 applies to the ASF too**: if SKILL.md or a reference outgrows
+  editability, split it by topic and keep the parent as an index — via the
+  review process.

package/skills/aia-asf/references/04-adversarial.md

@@ -8,6 +8,22 @@ Challenge every spec and design decision like a hostile reviewer. For each item,
 
 ## Per-spec questions
 
+> **Security lens (always applied):** for every design under review, also ask
+> the `references/06h-security.md` questions — where are the **trust
+> boundaries** (where does untrusted input cross into trusted code)? What does
+> STRIDE say about each (Spoofing, Tampering, Repudiation, Information
+> disclosure, Denial of service, Elevation of privilege)? Is there a **threat
+> registry** (threat → likelihood × impact → mitigation → status)? Any
+> High×High threat unmitigated and unrecorded blocks delivery. **Large work
+> writes the one-page threat model** (context view + STRIDE matrix + registry)
+> as part of the plan (see `references/06h-security.md`).
+
+> **Architecture lens (always applied):** for every architecture under review,
+> ask the ATAM-lite questions (`references/05-plan.md`) — which quality goals
+> matter most? Which 3–6 scenarios stress the architecture? Which decisions
+> are **sensitivity/tradeoff points** (load-bearing for one goal, harmful to
+> another)? What are the architectural risks and mitigations?
+
 > **Code-quality lens (always applied):** for every module/design under review,
 > also ask the `references/06c-code-quality.md` questions — is shared logic
 > duplicated anywhere? Is the single escalation path identifiable? Is the module

package/skills/aia-asf/references/05-plan.md

@@ -20,6 +20,57 @@ Existing system, repo layout, relevant prior work. Links to research sources.
 ## Approach
 Decided approach with rationale. Cite the research (package names, URLs).
 
+## Decisions (P01 — ADRs, one per significant decision)
+
+For every decision with alternatives (stack, architecture, protocol, library):
+
+```markdown
+### <Decision title>
+- **Decision:** <what we chose>
+- **Options considered:** <2+ real options, not strawmen>
+- **Rationale:** <why this one — cite the research>
+- **Consequence:** <what this costs / what it enables>
+```
+
+Five lines max per decision. Significant decisions live in the plan; if a
+project accumulates many, move them to `docs/decisions/NNNN-<slug>.md` and
+keep one line each in the plan. A decision with only one option is not a
+decision — skip it.
+
+## Quality requirements (P02 — ISO 25010 scenarios)
+
+Only the characteristics this work actually touches (cap ~8). For each:
+
+| Characteristic | Scenario (stimulus → response → measure) | Acceptance |
+|---|---|---|
+| e.g. Performance | 1000 concurrent users submit a report → system responds | p95 < 2s |
+| e.g. Reliability | DB restarts mid-ingest → no data loss | 0 lost records |
+| e.g. Security | unauthenticated request → rejected | 401 |
+
+Each scenario is testable: stimulus, response, measure. If you cannot write
+the measure, the requirement is not real yet.
+
+## Architecture evaluation (P03 — ATAM-lite)
+
+One page max. Before committing to the architecture:
+
+1. **Quality goals** — from the Quality requirements table (the 3–6 that
+   matter most).
+2. **Key scenarios** — the 3–6 scenarios that stress the architecture most
+   (highest risk × impact from Phase 4).
+3. **Sensitivity/tradeoff points** — which decisions are load-bearing for
+   which quality goal, and where two goals pull against each other (e.g.
+   performance vs security).
+4. **Architectural risks** — each with mitigation, or an explicit accepted
+   risk with rationale.
+
+## Views (P04 — optional, only when they earn their place)
+
+Add a view only if it communicates something the prose does not: **context**
+(external systems/interfaces), **runtime** (key flows/state), **deployment**
+(environments/topology). Each view ≤15 lines (ASCII or mermaid). No view for
+its own sake — the Architecture/Design prose is the primary artifact.
+
 ## Architecture / Design
 - Modules and their responsibilities (small, single-purpose — see `references/06c-code-quality.md`)
 - Data model / schema (if any)

package/skills/aia-asf/references/06-implementation.md

@@ -5,6 +5,11 @@
 > functionality in exactly one implementation (SSOT, single escalation path),
 > never hardcode what config should drive, and keep every module testable
 > standalone outside the host.
+>
+> **Read on demand:** `references/06f-stability.md` when the deliverable makes
+> external calls; `references/06g-test-design.md` when writing the test plan or
+> non-trivial tests; `references/06h-security.md` when the deliverable handles
+> untrusted input/secrets/agent tools.
 
 ## Test-first
 
@@ -83,3 +88,39 @@ Before marking anything ✅ (a spec, a milestone, a delivery-log item):
 A delivery log saying "IMP-006 delivered ✅" proves nothing. The code is the
 evidence. External planning docs (IMPROVEMENT-PLAN.md, PLAN.md, delivery logs)
 are inputs to spec capture — their ✅ markers are claims, never ground truth.
+
+## Drift self-correction (P20) — stop, revert, self-correct, continue
+
+**Drift** = the implementation is moving away from the approved plan/specs
+(scope creep, a different approach sneaking in, a shortcut that changes
+behavior). It is the most common silent failure of a long implementation.
+
+**Named drift anti-patterns** (if you catch yourself doing any of these, you
+are drifting):
+
+- **Scope creep** — adding features/edge cases the plan did not call for
+  ("while I'm here...").
+- **Approach drift** — quietly switching from the approved approach to a
+  different one because it "feels simpler".
+- **Spec drift** — implementing a *sensible* variant of a spec without
+  resolving the tension (M4 says: resolve it with the user first).
+- **Gate drift** — skipping a gate "just this once" (tests, adversarial,
+  browser verification).
+- **Quality drift** — accepting a shortcut that changes behavior or leaves
+  dead machinery, then marking it delivered (M5).
+
+**Self-correction loop (autonomous, no user needed):**
+
+1. **Detect** — compare what you are about to do against the plan/specs. If
+   it is not in the plan, it is drift.
+2. **Stop** — do not continue the drift; do not "finish it first".
+3. **Revert** — undo the drifted change (git checkout / undo the edit). The
+   revert is cheap; the drift is not.
+4. **Self-correct** — re-read the plan/spec, implement the approved version.
+5. **Continue** — resume the task list.
+
+**Escalate to the user only when the plan/requirements themselves are the
+problem** (a genuine conflict, a product-level tradeoff, a scope change).
+Then: stop, state the conflict plainly, propose the resolution, get the
+decision — do not silently pick a side. Everything else, self-correct and
+continue; the human decides only on genuine conflicts.

package/skills/aia-asf/references/06b-testing-qa.md

@@ -4,6 +4,10 @@ These rules are distilled from real failures in production sessions (pi-vigilant
 pi-aia-asf, pi-aia-browser, conversense, betamaxx). Each rule exists because
 skipping it **shipped a broken artifact**. They are not optional.
 
+> **Test design:** for *which* tests to write (risk-based derivation) and how
+> to keep them reliable (determinism), see `references/06g-test-design.md` —
+> read it in Phase 6 large work or when the logic under test is non-trivial.
+
 ---
 
 ## Rule 1 — Test the ARTIFACT you ship, not the source you wrote
@@ -143,11 +147,15 @@ never arrives, the wiring is dead — that is a failed test.
 - [ ] Web surfaces exercised through a real browser
 - [ ] Every MUST spec `met` with concrete evidence (`update_spec_status`)
 - [ ] **Spec-to-code traceability: every `met` spec carries `trace` (outcome → codePath → testFile + assertion); `/asf verify` mechanically validates it (large work)**
+- [ ] **Code Health Gate passed (or `enabled: false` / `gate.mode: warn` with the report shown)**
 - [ ] **Consumed by a surface: every delivered feature's output is visible in the product (UI or API) — nothing ships as dead machinery**
 - [ ] **E2E behavioral test: every feature spec has a test through the real entry point asserting the operator-facing outcome**
 - [ ] Unverifiable specs → `partial` + asked the user (never self-certified)
 - [ ] **Every long-running command ran under an explicit timeout with a stated expected duration (no unbounded waits)**
 - [ ] **No wait exceeded the 30 min (1800s) absolute ceiling — or it was explicitly waived for that single run, with a reason and a finite bound**
+- [ ] **Delivery report complete (P14): every spec with status + evidence, every test run with result, every skipped/inconclusive check listed with reason, and the not-tested register (what was deliberately not tested and why)**
+- [ ] **Stability line (06f): if the deliverable makes external calls, it has timeouts and bounded retries (idempotent only)**
+- [ ] **Security line (06h): no secrets in the repo; no untrusted input reaches a shell/query/path unvalidated; no unbounded resource use on user-controlled input**
 
 ## Rule 11 — Report honestly
 
@@ -268,3 +276,52 @@ and only for a **single run**:
 
 **Applies at both scales.** Small work is not exempt: a hang wastes the same
 time regardless of how the task was classified.
+
+## Rule 16 — Determinism: a flaky test is a defect
+
+A test that fails intermittently is a **defect in the test**, not bad luck.
+
+- Never "re-run into green" — that is hiding a broken test (Rule 11).
+- Fix it immediately (inject the clock, seed randomness, own the data, poll
+  instead of sleep, no order dependence, no real network in unit tests) — the
+  full rules are in `references/06g-test-design.md`.
+- If a test cannot be made deterministic, **delete it and say so** in the
+  delivery report (Rule 11) — a flaky test is worse than no test because it
+  erodes trust in the whole suite.
+
+## Rule 17 — Delivery report (P14): the fields that make it verifiable
+
+The completion summary is not a narrative — it is a **report with fields** a
+reviewer can check:
+
+- **Specs:** each spec → status (`met`/`partial`/`not-met`) → evidence
+  (test name + output, build result, code inspection).
+- **Tests:** each suite → command → result (pass/fail/skip) → count. State
+  which suites you ran and which you did not.
+- **Skipped/inconclusive:** every check not run or inconclusive, with the
+  reason (Rule 11).
+- **Not-tested register:** what was deliberately not tested and why (e.g.
+  "payment webhook: no sandbox credentials — covered by contract test only").
+  An honest register beats a silent gap.
+- **Artifact:** what was shipped (version, file list) and how it was verified
+  clean-room (Rule 5).
+
+## Rule 18 — Escaped-defect feedback loop (P21)
+
+When a defect escapes to the user (a bug report, a failed integration, a
+production incident), the fix is not the end — the **loop** is:
+
+1. Fix it (with a regression test, Rule 6).
+2. **Ask: which gate should have caught this?** Answer honestly — the
+   missing test technique (06g), the missing check (06b Rule 10), the
+   missing adversarial question (04-adversarial), the missing stability
+   pattern (06f), the missing security check (06h).
+3. **Close the gap** — add the check/rule/test so the same class of defect
+   cannot escape again. If the gap is in the ASF itself, that is a proposal
+   (docs/research/improvement-proposals.md), not a silent edit (P22).
+4. Record the loop in the delivery report (Rule 17) — what escaped, what
+   caught it, what changed.
+
+> **Real failure:** a package shipped with a broken `files` allowlist; the
+> fix landed but the *gap* ("no test inspects the packaged artifact") was not
+> closed until Rule 1 was added. The loop is what prevents the next one.

package/skills/aia-asf/references/06c-code-quality.md

@@ -29,6 +29,36 @@ existing functionality. Each rule below carries the lesson.
   - you cannot explain what the file does in one sentence
   - you are about to debug the same area a second time
 
+### Deep modules (P05) — interface simpler than implementation
+
+> *"A module is deep if its interface is much simpler than its
+> implementation. Shallow modules are a design flaw."* — Ousterhout, *A
+> Philosophy of Software Design*
+
+- **Depth is the goal, not size.** A deep module hides a lot behind a small
+  interface (e.g. a storage layer with one `get(key)`). A shallow module
+  exposes nearly as much interface as it implements (e.g. a "wrapper" that
+  just forwards a call with no added value).
+- **Shallow pass-through modules are defects.** A function that adds nothing
+  (forwards args, renames, calls one thing) should be inlined — it costs
+  context without hiding anything. Exception: a seam that exists for
+  testability (06c Rule 4) or a boundary that hides a *real* variation.
+- **New layer = new abstraction.** Do not add a layer unless it hides
+  something (a variation, a dependency, a policy). A layer that only passes
+  through is ceremony.
+- **Minimize voodoo constants (Rule 3 counterweight).** Config drives real
+  variation; but a constant that only this module uses and never changes
+  belongs in the module as a named constant, not in a config file. The
+  question is *who varies it* — if nobody, it is not config.
+- **Anti-patterns (P05):** temporal decomposition (functions named after
+  steps that share state and cannot be understood alone); back-door leakage
+  (a module reaches into another's internals instead of its interface);
+  information leakage (a caller knows more about a module's internals than
+  its interface should reveal).
+
+> **Depth is measured, not judged** — see `references/06e-code-health.md`
+> (report-only depth metric, no gate).
+
 ## Rule 2 — One implementation for shared functionality (single escalation path)
 
 > *"Make a separate module for ... communication and use IT instead of having
@@ -141,6 +171,24 @@ existing functionality. Each rule below carries the lesson.
 - This is the SSOT/refactor safety net: refactoring restructures *structure*,
   never *behavior*.
 
+### Characterization baseline (P13) — when refactoring code without tests
+
+If you must refactor code that has **no test coverage**, do not guess what it
+should do — **capture what it does** first:
+
+1. Write a **characterization test**: feed representative inputs, record the
+   actual outputs (including edge cases and error paths).
+2. The test asserts **current behavior** (even if it looks wrong) — it is a
+   safety net, not a spec.
+3. Refactor; the characterization test must stay green (Rule 8).
+4. Then (and only then) write the *spec* tests for the behavior you actually
+   want, and change the behavior deliberately with its own test.
+
+> **Real failure:** a refactor of untested code "fixed" behavior the author
+> believed was wrong — silently changing semantics and breaking a downstream
+> consumer that depended on it. Characterization first, then change
+> deliberately.
+
 ## Rule 9 — Documents are code: refactor them when they outgrow editability
 
 > *"Whenever documents you work on become so big that they start causing
@@ -175,18 +223,40 @@ fact of life. The same triggers that say "extract a module" for code say
 
 ---
 
+## Code smells — the 5 groups (P09)
+
+Smells are *signals*, not verdicts — each one has a standard fix. Check for
+them during Phase 4 (adversarial) and Phase 6 (implementation), and when the
+Code Health Gate flags a metric (06e).
+
+| Group | Smells | Standard fix |
+|---|---|---|
+| **Bloaters** | long method, large class, long parameter list, data clumps | Extract Method/Class, Introduce Parameter Object |
+| **Object-orientation abusers** | switch on type, temporary field, refused bequest | Replace Conditional with Polymorphism, Extract Class |
+| **Change preventers** | divergent change, shotgun surgery, parallel inheritance | Extract Class, Move Method, consolidate the variation |
+| **Dispensables** | comments as excuses, duplicate code, dead code, speculative generality | Remove Duplication, Delete Dead Code, YAGNI |
+| **Couplers** | feature envy, inappropriate intimacy, message chains, middle man | Move Method, Hide Delegate, inline the middle man |
+
+**Rule of thumb:** a smell that appears once is a code-style question; a
+smell that appears three times is a design problem — fix the design, not the
+instances.
+
 ## Where this applies in ASF
 
 - **Phase 4 (adversarial)**: challenge the design — is there duplication?
   Where is the single source of truth? Is the module testable outside the
-  host? What breaks if a config value changes?
+  host? What breaks if a config value changes? Are there **smells** (P09)?
+  Is the module **deep** (P05) or a shallow pass-through? Is any module
+  **temporally decomposed / leaking information** (P05 anti-patterns)?
 - **Phase 5 (PLAN.md)**: the Architecture/Design section must name the modules,
   their boundaries, the one-way dependencies, where shared truth lives, and
-  how each module is tested standalone.
+  how each module is tested standalone. The quality requirements table (P02)
+  and ATAM-lite evaluation (P03) live here too.
 - **Phase 6 (implementation)**: apply Rules 1–8 as you build; extract modules
   when triggers fire; write the architecture doc alongside the code. Apply
   Rule 9 to the documents you write: SKILL.md, references, PLAN.md, README —
-  split them when they outgrow editability.
+  split them when they outgrow editability. **Characterize before refactoring
+  untested code (P13)**; check for smells (P09) as you go.
 - **Phase 7 (verification)**: the DoD checklist includes: no duplicated shared
   logic (Rule 2), no hardcoded config values (Rule 3), every module tested
   standalone with the same calls (Rule 4), architecture doc written (Rule 6),
@@ -203,6 +273,12 @@ fact of life. The same triggers that say "extract a module" for code say
 - ❌ Refactoring "for fun" without the testability/debugging payoff
 - ❌ Shipping a module that cannot run outside the host
 - ❌ Skipping the architecture writeup ("the code is self-documenting")
+- ❌ Shallow pass-through modules that add no abstraction (P05)
+- ❌ A new layer that hides nothing (P05)
+- ❌ Temporal decomposition — functions named after steps, sharing state (P05)
+- ❌ Back-door leakage — reaching into another module's internals (P05)
+- ❌ Refactoring untested code without a characterization baseline (P13)
+- ❌ Fixing a smell instance by instance instead of the design (P09)
 - ❌ Letting a document grow until edits start breaking instead of splitting it
   (Rule 9)
 - ❌ A SKILL.md that is a wall of prose instead of a map to focused references

package/skills/aia-asf/references/06d-delegation.md

@@ -134,3 +134,55 @@ Delegation changes **who does the work**, never **what must be proven**:
 - The QA standard (06b) applies to delegated work identically. "A subagent did it" is not evidence.
 - Subagent findings enter the record as **claims** until verified against code or tests.
 - For LARGE work, the approval gate is unaffected: no subagent may start implementation before plan approval.
+
+---
+
+## Part 3 — Independent reviewer gate (P19, large work)
+
+Before delivery of **large** work, run an **independent review**: a second
+agent with fresh context, no exposure to your reasoning, asked to attack the
+result. It is the strongest anti-rubber-stamp check available (Part 2:
+fresh-perspective review) and it reuses the subagent machinery above.
+
+### How
+
+Spawn a subagent (Part 2, direct subprocess or extension) with a read-only
+tool set and this adversarial prompt shape:
+
+```
+You are a hostile reviewer of a delivered change. Review ONLY the diff and
+its tests. Classify every finding as:
+- BLOCKER: the change is wrong, breaks existing behavior, or violates a
+  stated spec/gate — must be fixed before delivery.
+- SUGGESTION: improvement that does not block delivery.
+- QUESTION: something you cannot determine from the diff.
+Return: findings list, nothing else. Do not fix anything.
+```
+
+Give it: the diff (or the files changed), the spec list, and the test
+results. Nothing else — no narrative, no context, no "here's what I did".
+
+### Triage (autonomous — human only on genuine conflicts)
+
+- **BLOCKER that is safe to fix** (a wrong value, a missing test, a broken
+  gate) → **fix it yourself**, add a regression test, re-run the suite. No
+  user checkpoint.
+- **SUGGESTION that is safe and clearly better** → apply it. If it is a
+  taste call, note it and move on.
+- **QUESTION / ambiguous finding** → investigate; if it resolves, resolve it.
+- **Escalate to the user ONLY on genuine conflicts** — conflicting
+  requirements, product-level tradeoffs, scope conflicts, or a finding that
+  contradicts an approved decision. State the conflict plainly and propose a
+  resolution; never silently pick a side.
+
+### Rules
+
+1. **Fresh context is the point** — the reviewer must not have seen your
+   reasoning; do not pre-answer its questions.
+2. **Read-only tools** — the reviewer never edits; it reports, you fix.
+3. **Its findings are claims** — verify each blocker against the code/test
+   before acting (M5). A reviewer can be wrong too.
+4. **Record it** — the review + triage outcome goes in the delivery report
+   (06b Rule 17): what was found, what was fixed, what was escalated.
+5. **Small work: none.** The reviewer gate is large-work only; small work
+   relies on the standard gates (06b DoD).

package/skills/aia-asf/references/06e-code-health.md

@@ -24,6 +24,21 @@ Three levels, each with objective thresholds (all configurable):
 | module | duplication | jscpd | 5% (min 5 lines / 50 tokens) |
 | module | circular imports | madge `--circular` | any cycle = fail |
 | architecture | dependency rules | dependency-cruiser | opt-in (off by default) |
+| design | module depth (interface vs implementation) | report-only heuristic | report-only (never gates) |
+| supply chain | dependency vulnerabilities | npm audit / osv-scanner | warn (high/critical fails) |
+| secrets | secrets in repo | gitleaks | warn (any finding fails) |
+
+**Depth metric (P05, report-only):** a heuristic that flags **shallow
+pass-through modules** — modules whose interface is nearly as large as their
+implementation (e.g. a wrapper that forwards every call with no added
+abstraction). It is **never a gate**: depth is a judgment call (06c Rule 1
+Deep modules), and the heuristic only *surfaces candidates* for review.
+
+**Supply chain & secrets (P17):** `npm audit`/`osv-scanner` and `gitleaks`
+run as part of the gate. They are **warn by default** (report, don't block)
+for small work; for large work a high/critical vulnerability in a runtime
+dependency or any secret finding blocks delivery. See
+`references/06h-security.md` for the full rules.
 
 Metrics for languages the project does not use are silently skipped. Metrics
 whose tool is not installed are skipped (or fail the gate when
@@ -68,6 +83,13 @@ switched on/off independently.
   "architecture": {
     "dependencyRules": { "enabled": false, "config": ".asf-code-health.rules.mjs" }
   },
+  "supplyChain": {
+    "npmAudit": { "enabled": true, "failOn": "high" },
+    "osvScanner": { "enabled": false }
+  },
+  "secrets": {
+    "gitleaks": { "enabled": true }
+  },
   "ignore": ["**/node_modules/**", "**/dist/**", "**/test/**", "**/*.test.*"]
 }
 ```

package/skills/aia-asf/references/06f-stability.md

@@ -0,0 +1,97 @@
+# 06f — Stability & Error Handling
+
+> **Read when:** the deliverable makes external calls (network, processes,
+> shared resources), is a service/daemon, or has retryable operations — large
+> work.
+> **Skip when:** small work; pure computation with no external calls; one-off
+> scripts with no retryable surface.
+>
+> **Scale note:** these are *design rules for the deliverable*, not ceremony.
+> If the deliverable has no external calls, the whole file is irrelevant — do
+> not read it.
+
+Source: Release It! (Nygard) stability patterns; Ousterhout error-handling
+philosophy; OWASP A10:2025 (Mishandling of Exceptional Conditions).
+
+---
+
+## 1. Stability patterns (apply when the deliverable makes external calls)
+
+Every external call is an integration point — the most common source of
+production failure. The patterns below are the standard set; apply the ones
+that fit, skip the rest.
+
+| Pattern | One-line rule |
+|---|---|
+| **Timeouts** | Every external call has an explicit timeout: connection, read, and total (a call that hangs is worse than a call that fails). |
+| **Bounded retries** | Retries are bounded (finite count), exponential backoff + jitter, and only for **idempotent** operations. Never retry a non-idempotent write blindly. |
+| **Circuit breaker** | At integration points: closed → open after repeated failures → half-open probe → closed. Prevents hammering a dead dependency. |
+| **Bulkheads** | Shared resources (connection pools, thread pools, rate limits) are partitioned so one consumer's exhaustion cannot starve others. |
+| **Bounded result sets** | Any query/list/stream is bounded (limit, pagination, max size). Unbounded result sets are a stability antipattern. |
+| **Fail fast** | Validate inputs at the boundary and fail immediately with a clear error — do not fail halfway through a multi-step operation. |
+| **Graceful shutdown** | On shutdown: stop accepting new work, let in-flight work finish or time out, flush state, release resources. |
+
+**DoD line (large work):** *"if the deliverable makes external calls, it has
+timeouts and bounded retries (idempotent only)."*
+
+## 2. Error-handling design rules
+
+- **Define errors out of existence** — the best error handling removes the
+  error condition (validate at the boundary, provide defaults, make the
+  impossible state unrepresentable). Only handle what cannot be prevented.
+- **Handle at the boundary** — catch at the edge (HTTP handler, CLI entry,
+  event consumer), convert to the appropriate response; do not scatter
+  try/catch through core logic.
+- **Generic to the user, detailed to the log** — user-facing errors never leak
+  internals (stack traces, SQL, paths); logs carry the full detail. (OWASP
+  A10:2025.)
+- **Idempotency is a design property** — anything retryable (webhooks, jobs,
+  writes) must be idempotent (idempotency keys, unique constraints, natural
+  keys). Retries are only safe on idempotent operations.
+- **Never use exceptions for control flow** — expected outcomes are values
+  (results, optionals, error unions); exceptions are for exceptional
+  conditions only.
+- **Fail fast** — a broken precondition is a bug; surface it immediately
+  rather than degrading silently.
+
+## 3. Observability — service-like deliverables (P07, large work)
+
+If the deliverable is a service/daemon (long-running, serves requests), the
+DoD includes:
+
+- **Health/readiness endpoint** — `/health` (or equivalent) that reports
+  liveness and readiness; a service that cannot report its own state is
+  undebuggable in production.
+- **Structured logs to stdout** — machine-parseable (JSON lines), not
+  scattered `console.log`; logs are the primary debugging surface.
+- **Correlation IDs** — one ID per request/job flows through every log line,
+  so a single user action is traceable across modules.
+- **Metrics** — where a metrics system exists (Prometheus, etc.): the
+  counters/gauges that answer "is it working?" (request rate, error rate,
+  latency). No metrics system → skip, and say so.
+- **Runbook in README** — start, stop, health check, known issues. An
+  operator should be able to run and diagnose it from the README alone.
+
+**DoD line (large work, service-like):** *"health endpoint, structured logs,
+correlation IDs, and a runbook exist."*
+
+## 4. Where this applies in ASF
+
+- **Phase 4 (adversarial):** for each external call in the design, ask — what
+  is the timeout? Is the retry bounded and idempotent? What happens when the
+  dependency is down (circuit breaker/bulkhead)? What is the max result size?
+- **Phase 5 (PLAN.md):** the Architecture/Design section names the stability
+  patterns chosen for each integration point.
+- **Phase 6 (implementation):** apply the patterns as you build; never ship an
+  unbounded wait, retry, or result set.
+- **Phase 7 (verification):** DoD includes the stability line above.
+
+## Anti-patterns
+
+- ❌ Unbounded retries on non-idempotent writes
+- ❌ No timeout on an external call ("it always returns fast")
+- ❌ Retrying a POST that creates a resource on every attempt
+- ❌ One connection pool shared by all consumers with no bulkhead
+- ❌ Loading an entire table into memory because "it's small"
+- ❌ Leaking stack traces to end users
+- ❌ try/catch around every line of core logic

package/skills/aia-asf/references/06g-test-design.md

@@ -0,0 +1,88 @@
+# 06g — Test Design: Risk-Based Derivation & Determinism
+
+> **Read when:** Phase 6 large work (writing the test plan) or when the logic
+> under test is non-trivial (branching, state, boundaries, external
+> interactions).
+> **Skip when:** small work; simple linear code where the standard test-first
+> rules in 06b suffice.
+>
+> **Scale note:** this file is about *which tests to write and how to keep
+> them reliable* — it never adds ceremony; it replaces guesswork.
+
+Source: ISTQB test design techniques; Kaner's risk-based testing; the
+determinism rules distilled from flaky-test failures.
+
+---
+
+## 1. Risk-based test derivation
+
+Test effort follows **risk = likelihood × impact**, not coverage for its own
+sake. Derive the test list from the spec's risk profile:
+
+1. **List the risks** (from Phase 4 adversarial analysis): what can break,
+   how likely, how bad.
+2. **Score each** (High/Medium/Low on both axes).
+3. **Test High × High first** — those get the most thorough technique set.
+4. **Low × Low** gets a smoke check or nothing — do not gold-plate.
+
+**Technique selection** (use when the shape matches):
+
+| Technique | Use when | Example |
+|---|---|---|
+| Equivalence partitioning | Inputs fall into classes that behave the same | age ranges, status enums |
+| Boundary value analysis | Classes have edges | min/max/just-below/just-above |
+| Decision table | Multiple conditions combine into outcomes | discount rules, permission matrix |
+| State transition | Behavior depends on state | order lifecycle, connection states |
+| All-pairs | Many parameters, few interactions | config combos, browser × OS |
+| Scenario/use-case | User journeys | end-to-end flows |
+| Error guessing | Known weak spots | empty input, unicode, huge payloads, concurrency |
+| Branch/decision coverage | High-risk logic | the gate conditions themselves |
+| MC/DC | Safety-critical conditions | anything that can cause data loss |
+
+**DoD line (large work):** *"the test list is derived from the risk profile —
+High×High risks have the strongest tests; the derivation is stated in the
+plan."*
+
+## 2. Determinism rules (flaky tests are defects)
+
+A flaky test is a **defect in the test**, not an inconvenience. Fix it
+immediately; never "re-run into green" (06b Rule 11).
+
+1. **Inject the clock** — no `Date.now()`/`new Date()` in logic under test;
+   pass time in (or a clock interface).
+2. **Seed randomness** — RNGs take an explicit seed; no `Math.random()` in
+   tested logic.
+3. **Own the data** — tests create their own fixtures/DB state; never depend
+   on pre-existing or shared data.
+4. **Poll, don't sleep** — wait for a condition with a bounded poll (with
+   timeout), never a fixed `sleep` that races.
+5. **No order dependence** — each test passes alone and in any order; no
+   shared mutable global state between tests.
+6. **No real network in unit tests** — external calls are faked at the seam
+   (06c Rule 4); integration tests are explicit and bounded.
+7. **Bound every wait** — every wait/poll carries a hard timeout (06b Rule
+   15); a test that can hang is a broken test.
+8. **Time zones / locales** — pin the environment (UTC, fixed locale) where
+   behavior depends on it.
+9. **Parallelism is opt-in** — tests that share resources run serially; only
+   independent tests run in parallel.
+
+**DoD line:** *"the suite is deterministic: no flaky test is tolerated; a
+flaky test is fixed or deleted, never retried into green."*
+
+## 3. Where this applies in ASF
+
+- **Phase 5 (PLAN.md):** the test plan states the risk-derived test list
+  (which risks, which techniques, which tests).
+- **Phase 6 (implementation):** write tests with the technique that matches
+  the shape; keep them deterministic per the rules above.
+- **Phase 7 (verification):** a flaky test blocks delivery (it is a defect).
+
+## Anti-patterns
+
+- ❌ Testing everything "for coverage" instead of what can actually break
+- ❌ `sleep(5000)` instead of polling for the condition
+- ❌ Tests that depend on the order they run in
+- ❌ Real network calls inside unit tests
+- ❌ Re-running a flaky test until it passes
+- ❌ Tests that pass only on the developer's machine (locale/timezone)

package/skills/aia-asf/references/06h-security.md

@@ -0,0 +1,134 @@
+# 06h — Security: Threat Model, ASVS DoD, Supply Chain, Agent Tools
+
+> **Read when:** Phase 4/5 for **large work**; and for any deliverable that
+> handles untrusted input, secrets, or exposes an interface.
+> **Skip when:** small work; deliverables with no untrusted input, no secrets,
+> no network exposure — the one-line DoD below is enough.
+>
+> **Scale note:** security effort is proportional to the attack surface. A CLI
+> that formats local files needs the one-liner; a service that accepts
+> untrusted input needs the full checklist. **Never skip the one-liner.**
+
+Sources: OWASP Threat Modeling, STRIDE, ASVS 5.0, OWASP Top 10 2025,
+SLSA, gitleaks/OSV best practices.
+
+---
+
+## 0. One-line DoD (applies to ALL work, both scales)
+
+> **"No secrets in the repo; no untrusted input reaches a shell/query/path
+> unvalidated; no unbounded resource use on user-controlled input."**
+
+## 1. Threat model as code (large work, Phase 4/5)
+
+A threat model is a **document in the repo**, not a meeting. Keep it to one
+page:
+
+1. **Context view** — draw the system boundary and **trust boundaries**
+   (where untrusted input crosses into trusted code: user input, webhooks,
+   file uploads, subprocess input, agent tool input).
+2. **STRIDE matrix** — for each trust boundary, walk STRIDE and record what
+   applies (Spoofing, Tampering, Repudiation, Information disclosure, Denial
+   of service, Elevation of privilege). Most rows will be N/A — that is fine.
+3. **Threat registry** — each identified threat: id, description, affected
+   boundary, likelihood, impact, mitigation, status (mitigated / accepted /
+   open). Open high-risk threats block delivery unless explicitly accepted by
+   the user.
+4. **Gate** — no High-likelihood × High-impact threat is unmitigated and
+   unrecorded. Accepted risks are recorded with rationale (Phase 4 resolution
+   rules).
+
+## 2. ASVS-based Definition of Done (large work)
+
+Use OWASP ASVS 5.0 as the checklist source. **Select the chapters that apply
+to the deliverable** — do not run the whole list:
+
+| Deliverable type | Applicable chapters (ASVS 5.0) |
+|---|---|
+| Web/API service | V1 (architecture), V2 (auth), V3 (session), V4 (access control), V5 (input validation), V6 (output encoding), V7 (crypto), V8 (errors), V14 (config), V15 (API) |
+| CLI / local tool | V1, V5, V6, V8, V14 (no session/auth chapters) |
+| Library/package | V1, V5, V6, V8, V14 (the library's own surface) |
+| Agent/tool surface | V1, V4, V5, V6, V8 + the agent chapter below |
+
+**Level selection:** L1 (baseline) for internal tools; L2 for anything
+internet-facing or holding user data; L3 only for high-value targets. Default
+is L2 for internet-facing, L1 otherwise. Record the chosen level in the plan.
+
+**DoD line (large work):** *"the applicable ASVS chapter checks pass at the
+chosen level; the level and chapter selection are recorded in the plan."*
+
+## 3. Supply chain & secrets (P17)
+
+### Dependency decision (Phase 2 research, one line)
+
+For every dependency, record in the plan: license, maintenance status, size,
+security history, and the alternative considered. A dependency with no
+maintainer or a risky license needs a recorded decision.
+
+### Automated gates (large work, via `/asf health`)
+
+| Gate | Tool | Default | Fails when |
+|---|---|---|---|
+| Dependency vulnerabilities | `npm audit` / `osv-scanner` | warn | known vuln in a runtime dep (high/critical) |
+| Secrets in repo | `gitleaks` | warn | any secret pattern in tracked files |
+
+- **Lockfile is committed** — reproducibility is a security property.
+- **RV loop (release):** re-run the dependency check **before every release**
+  (07-release.md step 1) — a vulnerability discovered after the last run must
+  not ship.
+- **Never invent credentials** — no hardcoded tokens, no `.env` in the repo,
+  no secrets in commit messages or CHANGELOGs.
+
+## 4. Agent/tool-surface chapter (P18 — only when applicable)
+
+Applies **only** when the deliverable has agent-like tool surfaces (an LLM
+agent with tools, a plugin system, an extension that exposes capabilities to
+a model). It is a chapter inside this file — not a separate reference — and
+it is **strictly proportional**: a small agent surface gets the one-liner, a
+full agent platform gets the full list.
+
+**One-liner (small surface):** *"agent tools are least-privilege: no tool can
+do more than the user asked for; tool output is validated before use."*
+
+**Full list (large surface):**
+
+1. **Least privilege** — each tool gets the minimum scope; no tool with
+   blanket shell/DB/network access unless the user explicitly granted it.
+2. **Human-in-the-loop** — destructive/irreversible actions (publish, delete,
+   pay, deploy) require explicit user confirmation; the agent never
+   self-approves.
+3. **Output validation** — tool results are validated before being used as
+   input to another tool or rendered to the user (a tool that returns
+   attacker-controlled strings must not inject into a shell or HTML).
+4. **Prompt-injection surface** — treat tool results and fetched content as
+   **untrusted input** (they can carry instructions); the agent must not
+   follow instructions found in data.
+5. **Abuse-case test** — one test that proves the agent cannot escalate
+   beyond its granted scope (e.g. asks for a tool it does not have, or
+   injects instructions via tool output).
+6. **Auditability** — tool calls are logged with inputs (redacted) so misuse
+   is traceable.
+
+**DoD line (agent surfaces):** *"every agent tool is least-privilege, and
+there is an abuse-case test proving the boundary holds."*
+
+## Where this applies in ASF
+
+- **Phase 2 (research):** dependency decision line (license, maintenance,
+  security history, alternative).
+- **Phase 4 (adversarial):** threat model (trust boundaries, STRIDE,
+  registry) for large work; the security lens questions already in
+  04-adversarial.md.
+- **Phase 5 (PLAN.md):** threat model + ASVS level/chapter selection recorded.
+- **Phase 6 (implementation):** secrets hygiene; least-privilege agent tools.
+- **Phase 7 (verification):** ASVS DoD + gates + abuse-case test.
+
+## Anti-patterns
+
+- ❌ Secrets in the repo (`.env`, tokens, keys in code or commits)
+- ❌ Unvalidated input reaching a shell/query/path
+- ❌ "It's internal, security doesn't apply"
+- ❌ An agent tool with blanket shell/DB access
+- ❌ Following instructions found in fetched content or tool output
+- ❌ Shipping a release without re-running the dependency check
+- ❌ A threat model that exists only in someone's head

package/skills/aia-asf/references/07-release.md

@@ -1,6 +1,34 @@
 # Phase 7 — Release Workflow
 
-Publishing is **always the user's decision**. The factory prepares everything; the user gives the final go.
+## Release policy (user-configurable)
+
+**Default stance:** publishing is the user's decision — the factory prepares
+everything and gets explicit approval before publishing. **A project may
+define its own release policy** in `.asf-release.json` at the project root
+(optional). The user definition takes precedence; the default is used only
+in the absence of a user definition.
+
+```json
+{
+  "when": "when the full suite is green and the bump is patch/minor → publish automatically; when the bump is major → send for final review; when the suite is not green → fix first, never publish",
+  "how": "To publish: connect with npm using the credentials in ~/.npmrc (2FA token; verify with `npm whoami`), sync git (`git pull --rebase`), run `npm run release <level>`, then verify the published version from the registry in a clean install..."
+}
+```
+
+- **`when`** — the user's **conditional rules**, in their own words: *"when X
+  is true, publish automatically; when Y is true, do this…"*. The ASF
+  evaluates them against the current state (suite green, bump scope, breaking
+  change, credentials available) and acts: publish automatically, send for
+  final review, or do something else (e.g. fix first, skip).
+- **`how`** — the user's **instructions** for driving the release, with all
+  technical details: credentials, git sync, publish steps, verification.
+  It is **not a deterministic command list** — the ASF drives the release
+  with judgment: it checks prerequisites, runs the verification gates,
+  handles failures, and applies the ASF's own discipline (06b rules) while
+  executing. A user `how` may add project-specific steps; it may not remove
+  the mandatory verification below.
+- **No file → default:** `when` = "always send for final review before
+  publishing"; `how` = the standard workflow below.
 
 ## When release applies
 
@@ -16,6 +44,10 @@ Publishing is **always the user's decision**. The factory prepares everything; t
    - test suite green
    - all MUST specs `met` in pi-vigilant
    - every long-running verification command ran under an explicit timeout with a stated expected duration (06b Rule 15) — no unbounded waits
+   - **re-run the dependency/security check (P17 RV loop):** `npm audit`
+     (or osv-scanner) + secrets scan — a vulnerability discovered after the
+     last run must not ship. The check is re-run **every release**, not
+     just when dependencies change.
 2. **Version bump** — semantic versioning:
    - `patch` (0.1.0 → 0.1.1): bug fixes
    - `minor` (0.1.0 → 0.2.0): new features, backward compatible
@@ -23,9 +55,14 @@ Publishing is **always the user's decision**. The factory prepares everything; t
 3. **CHANGELOG** — move `[Unreleased]` entries into the new version section; describe each change specifically.
 4. **Tag** — `git tag vX.Y.Z`
 5. **Push** — `git push --follow-tags`
-6. **Publish** — only with explicit user approval:
-   - npm: `npm publish` (ensure 2FA token, `npm login` state)
-   - GitHub release: via web or `gh release create` if installed
+6. **Publish** — per the release policy:
+   - default: **only with explicit user approval** (npm: `npm publish`, ensure 2FA token + `npm login` state; GitHub release: via web or `gh release create`)
+   - a `.asf-release.json` `when` rule may authorize automatic publishing for the stated conditions
+7. **Test on publish / in production — ALWAYS, if applicable** (mandatory, not optional):
+   - **Package:** install it **clean-room from the registry** (fresh dir, caches cleared, explicit version — 06b Rule 5), confirm the installed version is the one just published, and confirm the **observable end state** works (the tool/skill/extension loads and runs; any web surface exercised through `pi-aia-browser`).
+   - **Deployed app:** smoke-test in **production** (health endpoint, key user journey) — a deploy that breaks prod is not a successful release.
+   - **Not applicable** (internal-only experiment, no runtime surface): say so explicitly in the report (06b Rule 11).
+   - If the published artifact is broken: **fix forward** (new patch), never pretend the release succeeded.
 
 ## CI/CD offer
 
@@ -37,7 +74,8 @@ After a successful release (or for a new project), **offer** to set up a CI/CD p
 
 ## Hygiene rules
 
-- No auto-publish — always explicit user approval
+- No auto-publish beyond the configured policy — default is explicit user approval
 - Describe changes specifically in CHANGELOG (no placeholders)
 - The version in package.json, the git tag, and the npm release must match
 - If publishing fails partway, fix forward; never publish a second version with the same number
+- **Test on publish / in production, if applicable — always** (step 7)