@ai-agent-lead/skills 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-agent-lead/skills",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Install AI agent skills for Claude Code, Codex, Antigravity, and OpenCode",
   "main": "bin/install.js",
   "bin": {

package/skills/README.md

@@ -156,4 +156,3 @@ Used by `grill-plan`, `improve-codebase-architecture`, `system-design`, `investi
 5. Add the skill to **both** index tables above (by trigger phase AND by role).
 6. Add an entry to [TRIGGERS.md](./TRIGGERS.md) for routing.
 7. Update [WORKFLOWS.md](./WORKFLOWS.md) if the skill participates in a canonical workflow or as a cross-workflow pattern.
-. Update [WORKFLOWS.md](./WORKFLOWS.md) if the skill participates in a canonical workflow or as a cross-workflow pattern.

package/skills/WORKFLOWS.md

@@ -356,7 +356,7 @@ A few things that happen across all workflows:
 
 14. **`simplify` is the end-of-slice / end-of-round sweep.** Runs after every `tdd` slice goes green; in `tdd-rounds`, lands as its own commit per [`tdd-rounds/COMMITS.md` rule 4](./tdd-rounds/COMMITS.md). Applies the `code-hygiene` lens to the changed files, plus a test-relevance check. Distinct from `code-hygiene` (the lens) and from `improve-codebase-architecture` (the structural escalation when simplify finds bigger issues).
 
-12. **Artifacts accumulate in `docs/`:**
+15. **Artifacts accumulate in `docs/`:**
 
     | Location | Produced by | Type |
     |---|---|---|
@@ -366,13 +366,12 @@ A few things that happen across all workflows:
     | `docs/adr/<n>-<topic>.md` | `grill-plan`, `improve-codebase-architecture` | One per architectural decision |
     | `docs/CONTEXT.md` | `grill-plan`, `improve-codebase-architecture` (inline updates) | One per repo / context |
     | `docs/architecture.md` | `system-design` | One per system (the system map) |
-    | `docs/features/<name>/state/snapshot.md` | `tdd-rounds` parent | Living snapshot per feature |
-    | `docs/features/<name>/state/rounds/*.md` | `tdd-rounds` Builder | Immutable round logs |
-    | `docs/STATE.md` | `tdd-rounds` parent | Global manifest (index only) |
+    | `docs/features/<name>/state/snapshot.md` | `tdd-rounds` parent | Living snapshot per feature (target end-state per ADR-0001; not yet wired through `tdd-rounds` skill text) |
+    | `docs/features/<name>/state/rounds/*.md` | `tdd-rounds` Builder | Immutable round logs (target end-state per ADR-0001) |
+    | `docs/STATE.md` | `tdd-rounds` parent | Currently the single running summary; ADR-0001 demotes it to a global manifest after migration. |
     | `docs/security/<feature>.md` | `security-review` (high-stakes only) | One per surface-changing feature where a feature-doc section isn't enough |
     | `docs/benchmarks/<feature>.md` | `bench` | One per performance-critical feature |
-    | `docs/known-issues.md` | `verify-real-deps` | One per repo (post-mortem record) |
+    | `docs/known-issues.md` | `verify-real-deps` | One per repo (post-mortem record); also holds follow-up tracking for accepted-but-unimplemented ADRs. |
+    | `CHANGELOG.md` | `prod-ready` Section 7 | One per repo; `[Unreleased]` accumulates between releases. |
     All `docs/` files are created **lazily** — they don't have to pre-exist for a workflow to run. The skill creates them on first use.
-s/known-issues.md` | `verify-real-deps` | One per repo (post-mortem record) |
 
-    All `docs/` files are created **lazily** — they don't have to pre-exist for a workflow to run. The skill creates them on first use.

package/skills/bench/templates/benchmark-report.md

@@ -1,7 +1,16 @@
+---
+type: benchmark
+title: "Benchmark Report: <feature>"
+description: <one sentence — what was measured and the headline result>
+tags: [performance, <area>]
+timestamp: YYYY-MM-DD
+---
+
+<!-- Frontmatter is OKF per skills/formats/OKF.md (`type: benchmark`). -->
+
 # Benchmark Report
 
 **Feature:** <feature>
-**Date:** YYYY-MM-DD
 
 ## Environment
 - **Hardware:** <e.g., Apple M1 Max, 64GB RAM>

package/skills/code-hygiene/SKILL.md

@@ -9,18 +9,19 @@ expected_duration: 5 minutes
 
 Day-to-day discipline that keeps a codebase readable, navigable, and easy to change. Smaller in scope than `design` (which shapes module interfaces) — these are line-level and function-level habits.
 
-Five principles.
+Six principles.
 
 1. **Boring code beats clever code** — prefer the obvious solution over the elegant trick.
 2. **Naming is the primary refactor** — a bad name misleads longer than a bad implementation.
 3. **YAGNI** — don't build for hypothetical futures.
 4. **Rule of 3 before extracting** — duplicate twice; extract on the third occurrence, not the second.
 5. **Locality of behavior** — related code lives together; don't split by category.
+6. **Comments earn their keep** — default NONE; keep only why-comments tied to an invariant, trade-off, or provenance the next reader would otherwise miss.
 
 ## When to use
 
 - Writing new code, line by line — keep these in mind as you type.
-- Reviewing a PR — these are five common smell categories.
+- Reviewing a PR — these are six common smell categories.
 - After `tdd` reaches green, during the [`simplify`](../simplify/SKILL.md) sweep — `code-hygiene` is the lens you apply.
 - When you read code and pause to figure out what it's doing — that pause is a smell.
 
@@ -66,11 +67,7 @@ Duplicate twice; extract on the third occurrence — not the second.
 The first occurrence is unique. The second might be coincidence. The third is a pattern. Extracting at two reveals only one axis of variation; extracting at three reveals the *real* axis.
 
 **Why**: premature abstractions calcify. Once a wrong abstraction exists, callers shape themselves to it, and rewriting becomes expensive. Three concrete copies are cheap; one wrong abstraction is not.
-5. **Locality of behavior** — related code lives together; don't split by category.
-6. **Comments earn their keep** — default to none. Keep only WHY-comments: a constraint, an invariant, a trade-off, or a provenance link to an ADR / round / snapshot.
 
-## When to use
-...
 ## Principle 5: Locality of behavior
 
 Related code lives close together. Don't split a system by *type of code* (`controllers/`, `services/`, `repositories/`) — split by *responsibility* (`orders/`, `billing/`, `auth/`).
@@ -81,15 +78,11 @@ Related code lives close together. Don't split a system by *type of code* (`cont
 
 ## Principle 6: Comments earn their keep
 
-Default to none. Keep only WHY-comments: a constraint, an invariant, a trade-off, or a provenance link to an ADR / round / snapshot. Delete WHAT-comments, "used by X" / "added for Y" caller references, banner dividers, and commented-out code on sight.
+**The bar:** [`skills/formats/STYLE-comments.md`](../formats/STYLE-comments.md). Apply it *while writing*, not only during the `simplify` sweep.
 
-**Smells**:
-- A comment that restates the next line of code.
-- A comment naming a caller — that reference rots the moment someone renames or removes the caller. Use `grep`.
-- A TODO / FIXME / HACK with no owner, ticket, ADR, or date.
-- Commented-out code "in case we need it again". Git has it.
+**Default: NONE.** If you're unsure whether a comment earns its line, delete it. Keep only WHY-comments: a constraint, an invariant, a trade-off, or a provenance link to an ADR / round / snapshot — and only if the next reader would otherwise reattempt the rejected alternative.
 
-**Project-specific conventions** (package docstrings, provenance grammar) live in the repo's comment style doc — usually [`skills/formats/STYLE-comments.md`](../formats/STYLE-comments.md).
+**Delete on sight**: WHAT-comments, "used by X" / "added for Y" caller references, banner dividers, commented-out code, in-function section headers (`// validate`, `// build response`), and docstrings on exports whose contract is obvious from the signature.
 
 ## Done when
 

package/skills/design/SKILL.md

@@ -136,4 +136,4 @@ Most of the time `design` is guidance only — the shape lives in the code that
 - The interface decisions are load-bearing for downstream rounds of `tdd-rounds`.
 - A `prod-ready` reviewer will need to verify "module map / public-interface signatures / test boundaries" against something explicit (per [prod-ready Section 7](../prod-ready/SKILL.md)).
 
-When captured, save as a sibling to the feature doc: `docs/features/<feature>.design.md`. Skip when the interface is small enough that the code is the design.
+When captured, save as a sibling to the feature doc: `docs/features/<feature>.design.md`, opening with OKF frontmatter (`type: design`) per [`skills/formats/OKF.md`](../formats/OKF.md). Skip when the interface is small enough that the code is the design.

package/skills/feature-doc/SKILL.md

@@ -106,7 +106,9 @@ Once the doc is reviewed and ACs are stable:
 
 ## Done when
 
+- A feature branch (e.g. `feat/<short-name>` or `fix/<short-name>`) is checked out and the contract doc is committed on it, **not on `main`**.
 - `docs/features/<short-name>.md` exists with all four required sections.
+- The doc opens with OKF frontmatter (`type: feature`) per [`skills/formats/OKF.md`](../formats/OKF.md).
 - ACs are testable Given / When / Then statements.
 - Non-Goals is non-empty (or explicitly "none — see scope in Problem").
 - One reviewer has signed off.

package/skills/feature-doc/templates/feature-template.md

@@ -1,8 +1,20 @@
+---
+type: feature
+title: <Feature Name>
+description: <one sentence — the user pain this feature solves>
+tags: [<area>]
+timestamp: YYYY-MM-DD
+status: Draft
+owner: <name>
+---
+
+<!-- Frontmatter is OKF per skills/formats/OKF.md. `timestamp` is the canonical date;
+     `status`/`owner` mirror the human-facing lines below (OKF models neither). -->
+
 # <Feature Name>
 
 **Status:** Draft | Approved | In Progress | Shipped
 **Owner:** <name — primary author and point of contact for follow-up>
-**Date:** YYYY-MM-DD
 
 <!--
 Status values:

package/skills/formats/ADR-FORMAT.md

@@ -4,18 +4,28 @@ ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slu
 
 Create the `docs/adr/` directory lazily — only when the first ADR is needed.
 
+An ADR is a produced doc, so it opens with OKF frontmatter per [`OKF.md`](OKF.md) (`type: adr`).
+
 ## Template
 
 ```md
+---
+type: adr
+title: {Short title of the decision}
+description: {one sentence — what we decided and why}
+tags: [{area}]
+timestamp: YYYY-MM-DD
+status: accepted
+---
+
 # {Short title of the decision}
 
 **Status:** accepted
-**Date:** YYYY-MM-DD
 
 {1-3 sentences: what's the context, what did we decide, and why.}
 ```
 
-That's it. An ADR can be a single paragraph plus the two header lines. The value is in recording *that* a decision was made and *why* — not in filling out sections.
+That's it. An ADR can be a single paragraph plus the frontmatter and the `Status` line. The value is in recording *that* a decision was made and *why* — not in filling out sections. The date lives in `timestamp`; don't also keep a `**Date:**` line.
 
 ## Optional sections
 

package/skills/formats/CONTEXT-FORMAT.md

@@ -1,8 +1,18 @@
 # CONTEXT.md Format
 
+`CONTEXT.md` is a produced doc, so it opens with OKF frontmatter per [`OKF.md`](OKF.md) (`type: context`; a `CONTEXT-MAP.md` uses `type: context-map`).
+
 ## Structure
 
 ```md
+---
+type: context
+title: {Context Name}
+description: {one sentence on what this context is and why it exists}
+tags: [{area}]
+timestamp: YYYY-MM-DD
+---
+
 # {Context Name}
 
 {One or two sentence description of what this context is and why it exists.}
@@ -52,6 +62,14 @@ _Avoid_: Client, buyer, account
 The opening example uses an Ordering/Billing domain to show cross-context structure. For a smaller project a `CONTEXT.md` may be just a handful of terms and no relationships:
 
 ```md
+---
+type: context
+title: Todo App
+description: Vocabulary used across internal/auth and internal/todos.
+tags: [auth, todos]
+timestamp: 2026-05-22
+---
+
 # Todo App
 
 Vocabulary used across `internal/auth` and `internal/todos`.
@@ -85,6 +103,14 @@ An item on a User's personal list — text plus a done flag. Owned by exactly on
 **Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
 
 ```md
+---
+type: context-map
+title: Context Map
+description: Lists the bounded contexts in this repo and how they relate.
+tags: [architecture]
+timestamp: 2026-05-22
+---
+
 # Context Map
 
 ## Contexts

package/skills/formats/OKF.md

@@ -0,0 +1,82 @@
+# OKF Frontmatter for Produced Docs
+
+Every document a skill writes under `docs/` carries [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) (OKF v0.1) YAML frontmatter. That makes the whole `docs/` tree a consumable OKF **bundle** — a directory of markdown "concept" files any OKF-aware tool, agent, or static server can ingest, with no change to how we author.
+
+This is the substrate every doc-producing skill consumes (`feature-doc`, `investigate`, `bootstrap`, `grill-plan`, `bench`, `tdd-rounds`, `verify-real-deps`, …) — the way `STYLE-comments.md` is the substrate for comments. The per-skill templates carry a filled-in frontmatter block; this doc is the contract behind them.
+
+> **Why OKF and not our own scheme:** the format is vendor-neutral and additive — the only hard requirement is a non-empty `type`, and consumers preserve unknown keys. We get interop for free without giving up any of our existing structure.
+
+---
+
+## 1. The frontmatter block
+
+Every non-reserved `.md` file under `docs/` opens with a YAML frontmatter block:
+
+```yaml
+---
+type: feature
+title: Distributed State for TDD Rounds
+description: Feature-scoped state replaces the global STATE.md to cut merge conflicts.
+tags: [tdd-rounds, state, architecture]
+timestamp: 2026-05-25
+---
+```
+
+| Field | OKF status | Rule |
+| --- | --- | --- |
+| `type` | **required** | One value from the vocabulary in §2. Non-empty. This is the only field a bundle is rejected for missing. |
+| `title` | recommended | Human-readable display name. Mirror the `# H1`. Omit only if the filename already says it. |
+| `description` | recommended | One sentence. Reuse the doc's opening sentence — don't invent a second summary. |
+| `tags` | recommended | YAML list of short cross-cutting labels. Skip rather than pad. |
+| `timestamp` | recommended | ISO 8601 date (or datetime) of the last meaningful change. This is the canonical home for the date — do **not** also keep a `**Date:**` bold line. |
+| `resource` | recommended | A URI for the underlying asset. Our docs are abstract concepts, so in practice this is usually **absent** — include it only when the doc fronts a real external resource (a dashboard, a BigQuery table, an API). |
+
+**Extension keys** are allowed and encouraged where a doc kind carries status OKF doesn't model. Our kinds keep `status:` (and `owner:` on feature docs) as extension keys *in addition to* the human-facing `**Status:**` / `**Owner:**` bold lines the skills already read. OKF consumers preserve them; our skills keep working.
+
+---
+
+## 2. The `type` vocabulary
+
+OKF does not register types centrally — producers pick descriptive, self-explanatory values and consumers tolerate unknowns. These are the values this repo's skills emit:
+
+| Doc kind | `type` | Produced by | Lives in |
+| --- | --- | --- | --- |
+| Architecture decision record | `adr` | `bootstrap`, `grill-plan`, `investigate` handoff | `docs/adr/NNNN-slug.md` |
+| Feature contract | `feature` | `feature-doc` | `docs/features/<name>.md` |
+| Module / interface design note | `design` | `design` | `docs/features/<name>.design.md` |
+| Research / options note | `research` | `investigate` | `docs/research/<topic>.md` |
+| Ubiquitous-language map | `context` | `bootstrap`, `grill-plan` | `docs/CONTEXT.md` |
+| Multi-context map | `context-map` | `bootstrap` | `CONTEXT-MAP.md` |
+| Repo conventions | `convention` | `bootstrap` | `docs/CONVENTIONS.md` |
+| Accepted-but-unimplemented tracker | `known-issues` | `tdd-rounds`, `verify-real-deps` | `docs/known-issues.md` |
+| Benchmark report | `benchmark` | `bench` | `docs/bench/<name>.md` |
+| Round / feature state | `state` | `tdd-rounds` | `docs/features/<name>/state/*.md` |
+
+Pick the closest existing value before inventing a new one. A new doc kind adds a row here in the same change that first emits it.
+
+---
+
+## 3. Bundle conventions
+
+`docs/` is the bundle root. Two filenames are **reserved** by OKF and never used for a concept:
+
+- **`index.md`** — a directory listing for progressive disclosure. No frontmatter. Entries are `* [Title](relative-url) — short description`, optionally grouped under `## Section` headings. Add `docs/index.md` once the bundle has more than a couple of files; keep it current as docs are added.
+- **`log.md`** — a date-grouped changelog. Our repo's root **`CHANGELOG.md`** already plays this role (Keep-a-Changelog, newest first); treat it as the bundle's log rather than adding a second file. An OKF consumer tolerates the absence of `log.md`.
+
+**Cross-references** between docs are plain markdown links. OKF accepts two forms: **bundle-relative** (begin with `/`, resolved from the bundle root: `/adr/0001-distributed-state.md`) and **relative** (`../known-issues.md`). Bundle-relative is the more move-stable form, but this repo's docs use ordinary **relative** links by convention (they also reach files outside the bundle, like `../skills/formats/OKF.md`), and both are equally valid. A link asserts a *relationship* — the kind (supersedes, depends-on, refines) is carried by the surrounding prose, not the link. Broken links are tolerated, not malformed.
+
+**Body:** no required sections. Favor structural markdown (headings, lists, tables, fenced code) over prose — it aids both human reading and agent retrieval. The headings `# Schema`, `# Examples`, `# Citations` carry their conventional OKF meaning when present.
+
+---
+
+## 4. Conformance checklist
+
+A produced doc is OKF-conformant when:
+
+- [ ] It opens with a parseable YAML frontmatter block.
+- [ ] `type` is present and non-empty, drawn from §2 (or added there in the same change).
+- [ ] `title` mirrors the H1; `description` reuses the opening sentence; the date lives only in `timestamp`.
+- [ ] Reserved filenames (`index.md`, `log.md` / `CHANGELOG.md`) follow §3 and are **not** used for concepts.
+- [ ] Cross-links use bundle-relative (`/…`) or relative paths.
+
+This checklist is enforced at the doc-drift audits in `pr-review` (§3e) and `prod-ready` (Section 7) — a produced doc missing `type` is a finding.

package/skills/formats/STYLE-comments.md

@@ -1,59 +1,58 @@
 # Comment Style
 
-Codifies the comment discipline for this codebase. New contributors (human or agent) should match what's here, and what's already in the code, rather than re-deriving conventions per package.
+Codifies the comment discipline for this codebase. New contributors (human or agent) match what's here, rather than re-deriving conventions per package.
 
-> Default: write **no** comment. Add one only when the WHY is non-obvious.
+> **Default: write NO comment.** Add one only when the WHY is non-obvious AND a future reader is likely to make the opposite assumption.
 
-The code's identifiers, types, and structure already explain the *what*. A comment earns its line only when it captures something the reader cannot recover by reading the next ten lines: a constraint, an invariant, a trade-off, a workaround, or a pointer to the decision record.
+The code's identifiers, types, and structure explain the *what*. A comment earns its line only when it captures something the reader cannot recover by reading the next ten lines: a constraint, an invariant, a trade-off, or a pointer to the decision record. If you're unsure whether a comment earns its keep, **delete it** — git history and the next maintainer will be fine.
 
 ---
 
-## 1. Five kinds of comment we keep
+## 1. Three kinds of comment we keep
 
-### 1.1 Package docstring (required, one per package)
+### 1.1 Package docstring (one per package, only when the design needs it)
 
-Every package starts with a multi-paragraph docstring block in its primary file.
-
-Shape:
+A package whose design choice or invariant would not be obvious from reading the primary file gets a short docstring block:
 - One-line purpose.
 - One paragraph on the design choice and its rationale.
-- Round / ADR provenance for major decisions.
 - The failure mode or invariant the next reader needs to know.
 
-### 1.2 Docstrings on every exported identifier (required)
-
-- Starts with the identifier name (`// Cache stores …`, not `// Stores …`).
-- Interface methods state the **contract**, not just the action: is the call cheap, idempotent, safe under concurrency, called once per request or many times?
+A package that is what it says it is (a thin utility, a generated stub, a glue adapter) does not need a docstring. Don't pad.
 
-### 1.3 Invariant / constraint comments (encouraged)
+### 1.2 Docstrings on exported identifiers (only when the contract is non-obvious from the signature)
 
-A comment that catches a bug the next maintainer would otherwise write.
-- `// Zero means 'unknown'` (and re-stated where the bug would bite).
-- `// Selector must be cheap and side-effect-free; ServeHTTP may invoke Pick multiple times on 429 retry.`
+Skip the docstring on getters, simple constructors, and any function whose name + types already convey the contract. Write one only when:
+- The call is **not** cheap, idempotent, or safe under concurrency, and the next reader would assume it was.
+- The function may be invoked multiple times per request (e.g. retried) and that matters.
+- A parameter or return has non-obvious zero-value or nil semantics (`0 = "unknown"`, `(nil, nil) = "not found"`).
 
-### 1.4 Trade-off comments (encouraged)
+When you write one, start with the identifier name (`// Cache stores …`, not `// Stores …`).
 
-Name the alternative considered and why it lost. Cite the failure mode if the choice has one.
+### 1.3 Invariant / constraint / trade-off / provenance (only when the alternative would otherwise be reattempted)
 
-### 1.5 Provenance comments (use the grammar in §3)
+A comment whose absence would let the next maintainer write the bug, reattempt the rejected alternative, or "fix" the deliberate choice. If the next reader would just say "OK, sure" and move on, the comment is not earning its line.
 
-Anchor non-obvious behavior to its decision record (ADR, round, AC, snapshot).
+- **Invariant** — `// Zero means 'unknown'` (and re-stated where the bug would bite).
+- **Constraint** — `// Selector must be cheap and side-effect-free; ServeHTTP may invoke Pick multiple times on 429 retry.`
+- **Trade-off** — `// Cold-cache choice: an account whose (pk, model) is not yet in the cache is treated as INELIGIBLE.`
+- **Provenance** — `// Manual SQL instead of ORM — see ADR-007 §"Query shape".`
 
 ---
 
-## 2. Five kinds of comment we delete on sight
+## 2. Six kinds of comment we delete on sight
 
-1. **Restates the code.** `// increment i`, `// return the user`, `// loop over items`. The code already says it.
+1. **Restates the code.** `// increment i`, `// return the user`, `// loop over items`.
 2. **Commented-out code.** Git has it. Delete.
-3. **"Added for X" / "Used by Y" caller references.** These rot the day someone renames or removes the caller. Use `grep` instead.
+3. **"Added for X" / "Used by Y" caller references.** These rot the day someone renames or removes the caller. Use `grep`.
 4. **Banner / ASCII-art dividers.** `// =====` and `// --- section ---`. Use a function or a file boundary, not a banner.
 5. **Stale TODO / FIXME / HACK with no owner, ticket, ADR, or date.** Either link it to a decision record or fix it now.
+6. **Section-header comments inside a function.** `// validate`, `// build response`, `// compute total`. If a function needs internal section headers, extract those sections into named functions — the function name is the comment.
 
 ---
 
 ## 3. Provenance grammar (canonical forms)
 
-When a comment cites the project record, use **exactly one** of these forms. Comments that follow the canonical grammar are greppable and stable.
+When a kept comment cites the project record, use **exactly one** of these forms. Comments that follow the canonical grammar are greppable and stable.
 
 | Kind                                   | Canonical form          | Examples                                |
 | -------------------------------------- | ----------------------- | --------------------------------------- |
@@ -82,32 +81,22 @@ If the explanation needs more than **~6 lines**, the right home is an ADR or a `
 
 ---
 
-## 5. "Documented for the next reader" framing
-
-When a comment exists because a future reader is **likely to make the opposite assumption**, say so explicitly:
-
-```go
-// Cold-cache choice (documented for the next reader): an account whose
-// (pk, model) is not yet in the cache is treated as INELIGIBLE …
-```
-
----
-
-## 6. Test files
+## 5. Test files
 
-Non-trivial tests — those with fakes, harnesses, time control, channel-driven ceremonies, or unusual lifecycle — get a **5–20 line block comment at the top** of the file (or above the harness type) stating:
+Non-trivial tests — those with fakes, harnesses, time control, or unusual lifecycle — get a **5–20 line block comment** at the top of the file (or above the harness type) stating:
 - What is **faked** versus real (and why each choice).
 - Why the design (deterministic? avoid `time.Sleep`? exercise a specific retry path?).
-- Which knobs are overridden for the test and to **what value**.
+- Which knobs are overridden and to **what value**.
+
+Trivial tests get nothing. The test name carries the intent.
 
 ---
 
-## 7. Done when
+## 6. Done when
 
 Apply this checklist during the [`simplify`](../simplify/SKILL.md) sweep or in code review:
-- [ ] Every package has a docstring matching §1.1.
-- [ ] Every exported identifier has a docstring starting with its name.
-- [ ] Every comment that survived the sweep is a why, an invariant, a trade-off, or a provenance link — none restates the code.
-- [ ] No commented-out code, no `// used by X`, no banner dividers, no orphan TODOs.
+- [ ] Every surviving comment names a why, invariant, trade-off, or provenance link — none restates the code.
+- [ ] No commented-out code, no `// used by X`, no banner dividers, no orphan TODOs, no in-function section headers.
 - [ ] Every provenance citation matches the canonical grammar in §3.
+- [ ] Docstrings on exported identifiers exist only where the contract isn't obvious from the signature.
 - [ ] Test files with non-trivial harnesses have a strategy preamble; trivial ones do not.

package/skills/investigate/templates/research-note.md

@@ -1,8 +1,20 @@
+---
+type: research
+title: "Research: <topic>"
+description: <one sentence — the question this note investigates>
+tags: [<area>]
+timestamp: YYYY-MM-DD
+status: Open
+owner: <user>
+---
+
+<!-- Frontmatter is OKF per skills/formats/OKF.md. `timestamp` is the canonical date;
+     `status`/`owner` mirror the human-facing lines below (OKF models neither). -->
+
 # Research: <topic>
 
 **Status:** Open | Decided | Superseded
 **Owner:** <user>
-**Date:** YYYY-MM-DD
 
 <!--
 Status values:

package/skills/pr-review/SKILL.md

@@ -87,12 +87,14 @@ For non-surface-changing diffs: walk `prod-ready` Section 3 (defense-in-depth) b
 
 #### 3e. Doc-drift audit
 
-This is the second line of defense for `prod-ready` Section 7. Author may have missed it; reviewer catches what's left. Walk these four questions against the diff:
+This is the second line of defense for `prod-ready` Section 7. Author may have missed it; reviewer catches what's left. Walk these questions against the diff:
 
 - **New decision with viable alternatives** → does an ADR exist in `docs/adr/` for it? Does it name what it supersedes? If load-bearing, is it referenced from the code?
 - **New or changed domain term** → has [`docs/CONTEXT.md`](../../docs/CONTEXT.md) been updated? Are `_Avoid_:` aliases listed if there's risk of confusion?
 - **New / removed package, changed public interface, shifted module boundary** → is the feature's design note (`docs/features/<feature>.design.md`) updated? Module map, file layout, public-interface signatures, test boundaries.
 - **Changed acceptance criteria** → does the feature doc reflect what was actually built? Silently-dropped or silently-added behavior is the most common drift class — flag and don't accept "we'll fix in a follow-up".
+- **User-visible change** → does `CHANGELOG.md` have an entry under `[Unreleased]`, grouped by `Added / Changed / Fixed / Removed`? Skip only for formatter-only / lint-only / test-only / internal-refactor-with-no-behavior-change / dep-bump-with-no-runtime-impact diffs. Missing entry on a user-visible change = finding.
+- **New or changed produced doc under `docs/`** → does it open with OKF frontmatter carrying a non-empty `type` from [`skills/formats/OKF.md`](../formats/OKF.md) §2? A produced doc with no `type` breaks bundle conformance = finding.
 
 If any answer is "no" without `n/a + reason`, that's a finding. Severity:
 - **Blocker** — the missing doc is load-bearing for the next reader (ADR for a hard-to-reverse decision; CONTEXT.md entry for a term other PRs will use; AC drift hiding behavior).
@@ -100,11 +102,11 @@ If any answer is "no" without `n/a + reason`, that's a finding. Severity:
 
 The doc-map is small enough to walk in 2–3 minutes. Skip it and you're trading 3 minutes now for an hour of orientation in 3 months.
 
-#### 3e. Hygiene (line level)
+#### 3f. Hygiene (line level)
 
 Apply `code-hygiene` as a lens here, not as a primary phase:
 
-- **Comment churn**: new WHAT-comments, stale "used by X" references, citation grammar that doesn't match the repo's comment style doc ([`skills/formats/STYLE-comments.md`](../formats/STYLE-comments.md)). These are nits individually; in aggregate they're a signal the author didn't run `simplify`. Flag as suggestions, not blockers.
+- **Comment noise**: new WHAT-comments, docstrings on exports whose contract is obvious from the signature, in-function section headers (`// validate`, `// build response`), stale "used by X" references, citation grammar that doesn't match the repo's comment style doc ([`skills/formats/STYLE-comments.md`](../formats/STYLE-comments.md)). Flag as **nits by default**; promote to a suggestion only when cumulative comment noise obscures the diff (signal the author skipped `simplify`).
 - Names that mislead (boolean returning non-bool, `getX` that mutates, `Manager`/`Helper` suffixes hiding what the thing is).
 - Cleverness that earns its cost? Or could be boring?
 - YAGNI — "in case we need it" parameters / interfaces / classes? Strip.

package/skills/prod-ready/SKILL.md

@@ -60,6 +60,8 @@ Implementation lands → docs drift. The natural moment to catch drift is now, n
 - [ ] **New or changed domain term** → `CONTEXT.md` entry created or updated. Includes `_Avoid_:` aliases if the term is at risk of being confused with an existing one.
 - [ ] **New/removed package, changed public interface, or shifted module boundary** → the feature's design note (e.g., `docs/features/<feature>.design.md`) updated. Specifically: Module map, File layout, public-interface signatures, Test boundaries.
 - [ ] **Changed acceptance criteria** → the feature doc reflects what was actually built. Silently-dropped or silently-added behavior is the most common drift class — fix here, don't kick to a follow-up.
+- [ ] **User-visible change** → `CHANGELOG.md` has an entry under `[Unreleased]`, grouped by `Added / Changed / Fixed / Removed`. Skip only if the diff is formatter-only, lint-only, test-only, internal refactor with no behavior change, or a dependency bump with no runtime impact. (Overlaps but is **not identical** to `feature-doc`'s skip list — that one also waives the *doc* for typo fixes and one-line config tweaks. A typo fix can still merit a one-liner here.)
+- [ ] **New or changed doc under `docs/`** → it opens with OKF frontmatter carrying a non-empty `type` from [`skills/formats/OKF.md`](../formats/OKF.md) §2. A produced doc with no `type` breaks the bundle's conformance — fix here.
 
 If a doc type isn't relevant to this work, write "n/a" — explicit beats implicit.
 

package/skills/simplify/SKILL.md

@@ -49,13 +49,14 @@ Walk every changed file. Apply each lens in order. Fix what you find inline.
 - Names that read clearly out of context — would a stranger guess what `result`, `data`, `value` referred to? If not, rename.
 - Error messages that name the failing input — `"could not parse: <value>"` beats `"parse error"`.
 - Abstractions that haven't earned their keep — a base class with one subclass, an interface with one implementation. Inline.
-- Comments:
+- Comments — **default during the sweep is DELETE**:
   - Delete WHAT-comments (the code already says it).
+  - Delete docstrings on exports whose contract is obvious from the signature.
   - Delete "used by X" / "added for Y" caller references — these rot; use grep.
   - Delete commented-out code (git has it).
-  - Delete banner / ASCII-art dividers.
-  - KEEP why-comments: constraint, invariant, trade-off, provenance.
-  - If a kept comment cites a round / ADR / AC / snapshot, normalize to the project grammar in [`skills/formats/STYLE-comments.md`](../formats/STYLE-comments.md) (§3 — `ADR-007 §7`, `R6 AC-3`, `v0.3 R1b2`, `snapshot §"Invariants"`).
+  - Delete banner / ASCII-art dividers and in-function section headers (`// validate`, `// build response`).
+  - KEEP only why-comments — constraint, invariant, trade-off, provenance — and only when the next reader would otherwise reattempt the rejected alternative.
+  - If a kept comment cites a round / ADR / AC / snapshot, normalize to [`skills/formats/STYLE-comments.md`](../formats/STYLE-comments.md) §3 (`ADR-007 §7`, `R6 AC-3`, `v0.3 R1b2`, `snapshot §"Invariants"`).
 
 ### 3. Efficiency — dead code, redundant work, premature defensive checks
 

package/skills/tdd/SKILL.md

@@ -19,6 +19,11 @@ expected_duration: 20 minutes
 - Trivial getters / setters with no behavior.
 - Bug whose root cause isn't yet known — run [`debug`](../debug/SKILL.md) first; the reproduction crystallises into the failing test.
 
+## Pre-conditions
+
+- **Current branch is not `main` / `master`.** If it is, stop and run `git checkout -b feat/<short-name>` (or `fix/...`) before writing the first test. Code lands on a feature branch; `main` receives merges, not commits.
+- A feature doc (`docs/features/<short-name>.md`) exists with testable ACs — or a `debug` reproduction names the root cause.
+
 ## Philosophy
 
 Tests verify **behavior through public interfaces**, not implementation details. Code can change entirely; tests shouldn't.

package/skills/tdd-rounds/SKILL.md

@@ -22,6 +22,7 @@ Distills the pattern of a parent agent driving Builder sub-agents through a feat
 
 ## The parent's contract
 
+- **Dispatch on a feature branch, never `main`.** Verify the current branch before dispatching the first Builder; if it's `main` / `master`, create `feat/<short-name>` first. The whole multi-round delivery lives on one feature branch (or a stack of feature branches), merged to `main` only at the end.
 - **Plan once.** The plan file lists rounds, each round's ACs, the dependency order, and the skills cadence per round (which rounds need `design`; when to invoke `improve-codebase-architecture` mid-project; when to invoke `prod-ready`).
 - **Brief per round.** A self-contained brief — the Builder shouldn't need conversation history. 
   - **Briefing Sub-agent**: For complex rounds, invoke a sub-agent to autonomously generate the brief by analyzing `docs/STATE.md`, the `feature-doc`, and the results of the previous round. See `templates/builder-brief.md` for the schema.
@@ -32,6 +33,7 @@ Distills the pattern of a parent agent driving Builder sub-agents through a feat
 
 When dispatched for a round, the Builder:
 
+0. **Pre-flight.** Verifies the current branch is **not** `main` / `master`. If it is, refuses immediately and returns a blocking report — does not proceed to step 1.
 1. Reads the brief, the plan file, `docs/STATE.md`, and any ADRs / feature docs the brief cites.
 2. **Executes the listed skills sequentially in this single invocation.** When a brief says "Skills (in order): design, tdd, simplify" — that means run all three in this run, not return to the parent between them. This rule is non-obvious; the brief template makes it explicit.
 3. Commits per AC slice (or per behavior slice for refactor rounds), prefix `R<N>:`. **Read [`COMMITS.md`](COMMITS.md) before the first commit** — it captures the seven rules (`R<N>:` prefix, `#<X>` for bug fixes, per-AC slicing, separate simplify-pass commit, separate doc commits, single-commit-with-justification, honest messages) and the message-body shape. The parent reads commits as the review surface; a clean sequence is reviewable one diff at a time, a mono-commit isn't.
@@ -94,16 +96,4 @@ When the final round completes:
 1. Run `verify-real-deps`. Capture surfaced bugs into `docs/known-issues.md`.
 2. Iterate fix-rounds until clean, or document deferrals to vN.1 with rationale.
 3. Tag and publish via whatever release / distribution channel applies.
-hape the Builder returns.
 
-## Supporting docs
-
-- [`COMMITS.md`](COMMITS.md) — commit cadence and message style (per-AC slicing, `R<N>:` prefix, when single-commit is OK, honesty rule). Builders read this before the first commit.
-
-## Handoff
-
-When the final round completes:
-
-1. Run `verify-real-deps`. Capture surfaced bugs into `docs/known-issues.md`.
-2. Iterate fix-rounds until clean, or document deferrals to vN.1 with rationale.
-3. Tag and publish via whatever release / distribution channel applies.

package/skills/verify-real-deps/templates/known-issues.md

@@ -1,3 +1,14 @@
+---
+type: known-issues
+title: "Known issues — post-vN.0 smoke test findings"
+description: Bugs surfaced by the first end-to-end run against the real upstream.
+tags: [smoke-test, known-issues]
+timestamp: YYYY-MM-DD
+---
+
+<!-- Frontmatter is OKF per skills/formats/OKF.md (`type: known-issues`).
+     `timestamp` tracks the last edit; the Discovered line below pins the first run. -->
+
 # Known issues — post-vN.0 smoke test findings
 
 **Discovered:** YYYY-MM-DD (first end-to-end run against real <upstream>).