@tsfpp/agents 1.3.5 → 1.4.0

package/CHANGELOG.md

@@ -10,6 +10,21 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-05-18
+
+### Added
+
+- Added `copilot/prompts/trunk-changelog.prompt.md` to support trunk-based changelog authoring.
+- Added `copilot/skills/annotation-standard/SKILL.md` to standardize annotation workflow and conventions.
+
+### Changed
+
+- Updated `README.md` with rationale updates and new LLM assets/flowchart documentation.
+- Updated `init.mjs` to include deployment wiring for the new trunk changelog prompt and related README/documentation flow.
+- Updated `copilot/agents/tsfpp-annotate.agent.md` to align with the annotation standard.
+- Updated `copilot/agents/tsfpp-audit.agent.md` to include annotation-standard-aware checks.
+- Updated `copilot/agents/tsfpp-guarded-coding.agent.md` to route annotation work through the standard.
+
 ## [1.3.5] - 2026-05-18
 
 ### Changed

package/README.md

@@ -1,12 +1,103 @@
 # @tsfpp/agents
 
-GitHub Copilot agents, scoped instruction files, and Claude Code configuration for [TSF++](https://github.com/tsfpp/standard) projects.
+GitHub Copilot agents, scoped instruction files, skills, and Claude Code configuration for [TSF++](https://github.com/tsfpp/standard) projects.
 
-Installs a set of pre-built AI tooling into your project's `.github/` directory. Once installed, the agents are available in VS Code Copilot chat and the instruction files are injected automatically as context whenever you open a matching file.
+Installs a pre-built AI tooling layer into your project's `.github/` directory. Once installed, agents are available in VS Code Copilot chat, instruction files are injected automatically whenever a matching file is open, and skills are loaded on demand based on semantic relevance.
+
+---
+
+## Why this works
+
+TSF++ enforces a small, strict set of constraints: sum types with exhaustive dispatch, total functions via `Option` and `Result`, immutable records, no hidden effects, pipelines over imperative loops. These constraints exist because algebraic code is easier for a human to reason about locally — you can understand a function from its type alone, without tracing mutations or hidden control flow.
+
+The same properties that help humans happen to help language models significantly more. A codebase that never throws, never mutates, and always makes failure explicit in the type signature gives a model far less surface to hallucinate over. Exhaustive `switch` with `absurd` means the model cannot forget a variant. `Result<T, E>` means error paths are always visible in the return type. `pipe` makes data flow linear and readable in one pass.
+
+In practice: the agents generate fewer violations, the audit agent catches the ones that slip through, and the refactor agent can fix them mechanically because the fix is always the same shape. The standard makes the code predictable for humans — and predictable code is cheap for a model to generate correctly.
+
+---
+
+## Quickstart — greenfield project
+
+The fastest way to create a fully configured TSF++ project is the bootstrap script. It handles everything in one command:
+
+```sh
+bash <(curl -fsSL https://raw.githubusercontent.com/tsfpp/agents/main/bootstrap/tsfpp-bootstrap.sh) my-project
+cd my-project
+```
+
+Or, if you already have the script locally:
+
+```sh
+bash tsfpp-bootstrap.sh my-project
+cd my-project
+```
+
+Omit the project name to bootstrap in the current directory.
+
+### What the bootstrap script does
+
+| Step | What happens |
+|------|-------------|
+| 1 | `git init -b main` (skipped if a repo already exists) |
+| 2 | `pnpm init` |
+| 3 | Installs the full TSF++ ecosystem: `typescript`, `@tsfpp/standard`, `@tsfpp/tsconfig`, `@tsfpp/eslint-config`, `@tsfpp/prelude`, `@tsfpp/boundary`, `@tsfpp/agents` |
+| 4 | Writes `tsconfig.json` extending `@tsfpp/tsconfig/app` |
+| 5 | Writes `eslint.config.js` with the base TSF++ ESLint config |
+| 6 | Patches `package.json` with `type: module` and `typecheck`, `lint`, `check` scripts |
+| 7 | Creates `src/index.ts` with a getting-started comment |
+| 8 | Runs `node node_modules/@tsfpp/agents/init.mjs` — installs all agents, instructions, skills, and prompts |
+| 9 | Writes `.gitignore` (skipped if one already exists) |
+| 10 | Runs `pnpm exec husky install` to activate pre-commit hooks |
+
+### After bootstrapping
+
+The bootstrap script does not install `@tsfpp/workflow` (commit linting, release automation) or configure a git remote — those steps are intentionally separate and optional.
+
+**Add workflow tooling** (recommended for real projects):
+
+```sh
+pnpm add -D @tsfpp/workflow @commitlint/cli @commitlint/config-conventional husky
+node node_modules/@tsfpp/workflow/init.mjs
+```
+
+This installs:
+- `commitlint` with the Conventional Commits config
+- Husky hooks: `commit-msg` (lint) and `pre-commit` (typecheck + lint)
+- Release Please GitHub Actions workflow for automated semver releases and changelog generation
+
+**Push to GitHub** — use the `/trunk-init-repo` prompt in Copilot chat:
+
+```
+/trunk-init-repo
+```
+
+This handles the initial conventional commit, adds the remote, pushes to `main`, and ensures Husky hooks are active after the git init.
+
+### Complete sequence
+
+```sh
+# 1. Bootstrap
+bash tsfpp-bootstrap.sh my-project
+cd my-project
+
+# 2. Open in VS Code
+code .
+
+# 3. Add workflow tooling (optional but recommended)
+pnpm add -D @tsfpp/workflow @commitlint/cli @commitlint/config-conventional husky
+node node_modules/@tsfpp/workflow/init.mjs
+
+# 4. Push to GitHub — in Copilot chat:
+# /trunk-init-repo
+```
+
+From there, the full agent workflow is available immediately.
+
+---
 
 ## Prerequisites
 
-All `@tsfpp/*` packages must be installed in the consumer project. The agents reference their documentation from `node_modules/@tsfpp/*/` at runtime — this is what gives them stable, version-locked access to the standard and API surface without bundling duplicate content.
+All `@tsfpp/*` packages must be installed in the consumer project. The agents reference their documentation from `node_modules/@tsfpp/*/` at runtime — this gives them stable, version-locked access to the standard and API surface without bundling duplicate content.
 
 ```sh
 pnpm add -D \
@@ -17,37 +108,64 @@ pnpm add -D \
   @tsfpp/tsconfig
 ```
 
+---
+
 ## Installation
 
 ```sh
 pnpm add -D @tsfpp/agents
-pnpm dlx @tsfpp/agents
+node node_modules/@tsfpp/agents/init.mjs
 ```
 
 The `init` script copies all files into your project and prompts before overwriting anything that already exists. Commit the generated files — they are workspace configuration, not build artefacts.
 
-To re-run without reinstalling:
+### Non-interactive mode
+
+```sh
+node node_modules/@tsfpp/agents/init.mjs --yes
+```
+
+Copies all package-managed files without prompting. Skips `eslint.config.js` and `tsconfig.json` — those are workspace-owned and never touched automatically. Use this in `postinstall` scripts:
+
+```json
+{
+  "scripts": {
+    "postinstall": "node node_modules/@tsfpp/agents/init.mjs --yes"
+  }
+}
+```
+
+This ensures agents and instructions stay up to date with the installed package version on every `pnpm install`.
+
+### Re-run without reinstalling
 
 ```sh
 node node_modules/@tsfpp/agents/init.mjs
 ```
 
+---
+
 ## What gets installed
 
 ```
 .github/
-  copilot-instructions.md          ← always-on workspace context
+  copilot-instructions.md               ← always-on workspace context
   instructions/
-    tsfpp-base.instructions.md     ← applyTo: **/*.ts
-    tsfpp-prelude.instructions.md  ← applyTo: **/*.ts
-    tsfpp-react.instructions.md    ← applyTo: **/*.tsx
-    tsfpp-api.instructions.md      ← applyTo: routes, handlers, api dirs
+    tsfpp-base.instructions.md          ← applyTo: **/*.ts
+    tsfpp-prelude.instructions.md       ← applyTo: **/*.ts
+    tsfpp-api.instructions.md           ← applyTo: routes, handlers, api dirs
+    tsfpp-react.instructions.md         ← applyTo: **/*.tsx
+    tsfpp-testing.instructions.md       ← applyTo: **/*.{test,spec}.{ts,tsx}
+    trunk.instructions.md               ← applyTo: git workflow contexts
   agents/
+    tsfpp-tdd.agent.md
+    tsfpp-backfill-tests.agent.md
     tsfpp-guarded-coding.agent.md
     tsfpp-audit.agent.md
     tsfpp-refactor-engineer.agent.md
     tsfpp-annotate.agent.md
   prompts/
+    trunk-init-repo.prompt.md
     tsfpp-new-module.prompt.md
     tsfpp-boundary-review.prompt.md
   skills/
@@ -55,53 +173,116 @@ node node_modules/@tsfpp/agents/init.mjs
     prelude-api/SKILL.md
     boundary-api/SKILL.md
     react-coding-standard/SKILL.md
+    test-standard/SKILL.md
+    annotation-standard/SKILL.md
 .claude/
-  CLAUDE.md                          ← Claude Code project context
+  CLAUDE.md                             ← Claude Code project context
 ```
 
+---
+
 ## Agents
 
 | Agent | Purpose |
 |-------|---------|
-| `tsfpp-guarded-coding` | Writes TSF++-compliant TypeScript. Specify a layer at session start: `core` · `api` · `dal` · `react` · `cli`. Runs `tsc --noEmit` automatically after every file edit via a `PostToolUse` hook. |
-| `tsfpp-audit` | Audits a target path, package, or layer for TSF++ violations. Creates a structured markdown report in `docs/audits/` with per-slice checkboxes and a deviation register. |
-| `tsfpp-refactor-engineer` | Reads an audit report and fixes violations slice by slice. Updates the report as it goes. Includes per-rule fix strategies so it never resolves a violation by weakening a type. |
-| `tsfpp-annotate` | Adds missing JSDoc blocks, `DEVIATION(N.M)` comments, paired `eslint-disable` annotations, and structured code markers (`TODO`, `FIXME`, `HACK`, `NOTE`, `OPTIMIZE`, `BUG`, `XXX`). Never touches runtime code. |
+| `tsfpp-tdd` | The mandatory first step for new functionality. Writes a failing test suite that specifies the behaviour before any implementation exists. Verifies every test is red for assertion reasons, then hands off to `tsfpp-guarded-coding`. |
+| `tsfpp-backfill-tests` | Writes tests for existing code that has no coverage. Reads the implementation, derives the implicit contract, writes passing tests, and reports uncovered edge cases and implementation gaps. |
+| `tsfpp-guarded-coding` | Writes TSF++-compliant TypeScript. Infers the active layer from context (`core` · `api` · `dal` · `react` · `cli`); applies layer-specific constraints automatically. Refuses to start without failing tests in place. Runs `tsc --noEmit` after every file edit via a `PostToolUse` hook. |
+| `tsfpp-audit` | Audits a target path, package, or layer for TSF++ violations. Supports focus areas: `types` · `boundary` · `complexity` · `loc` · `annotations` · `security` · `react` · `data` · `prelude` · `test` · `all`. Creates a structured markdown report in `docs/audits/` with per-slice checkboxes and a deviation register. |
+| `tsfpp-refactor-engineer` | Reads an audit report and fixes violations slice by slice. Updates the report as it goes. Never resolves a violation by weakening a type. |
+| `tsfpp-annotate` | Adds missing JSDoc blocks, module headers, inline comments (invariants, rejected alternatives, external contracts), `DEVIATION(N.M)` comments, paired `eslint-disable` annotations, and structured code markers (`TODO`, `FIXME`, `HACK`, `NOTE`, `OPTIMIZE`, `BUG`, `XXX`). Never touches runtime code. Uses the `/annotation-standard` skill. |
+
+---
 
 ## Workflow
 
-The agents are designed to hand off to each other. After each agent completes, VS Code presents a handoff button to transition to the next step:
+The agents hand off to each other. Each handoff is opt-in — the developer reviews and approves each transition via the handoff buttons in Copilot chat.
+
+### New functionality (TDD first)
 
 ```
-tsfpp-guarded-coding
-  → tsfpp-audit          (verify what was written)
-    → tsfpp-refactor-engineer   (fix violations)
-      → tsfpp-annotate   (document the result)
-        → tsfpp-audit    (verify annotation coverage)
+tsfpp-tdd                  write failing tests
+  → tsfpp-guarded-coding   implement against the tests
+    → tsfpp-audit          verify compliance
+      → tsfpp-refactor-engineer   fix any violations
+        → tsfpp-annotate   document the result
 ```
 
-Handoffs are opt-in — the developer reviews and approves each transition.
+### Existing code without tests
+
+```
+tsfpp-backfill-tests       write passing tests from the existing contract
+  → tsfpp-audit            verify test compliance + coverage
+    → tsfpp-refactor-engineer   fix violations in tests or implementation
+```
+
+### Compliance audit only
+
+```
+tsfpp-audit                audit target with chosen focus
+  → tsfpp-refactor-engineer   fix violations
+    → tsfpp-annotate       document deviations and markers
+      → tsfpp-audit        re-audit to verify fixes
+```
+
+---
 
 ## Instruction files
 
-Instruction files are injected automatically by VS Code Copilot whenever a matching file is open. They require no explicit invocation.
+Instruction files are injected automatically by VS Code Copilot whenever a matching file is open. No explicit invocation required.
 
 | File | Active for | Content |
 |------|-----------|---------|
 | `tsfpp-base` | `**/*.ts` | Forbidden constructs, required patterns, size limits, ADT idioms, marker format |
-| `tsfpp-prelude` | `**/*.ts` | Full `@tsfpp/prelude` API surface: `Option`, `Result`, combinators, `pipe`, `absurd`, `Brand` |
-| `tsfpp-react` | `**/*.tsx` | Component shape, discriminated union state, TanStack Query, `useEffect` policy, memoisation |
-| `tsfpp-api` | Routes, handlers, API dirs | Handler shape, `@tsfpp/boundary` imports, Zod validation, status codes, security baseline |
+| `tsfpp-prelude` | `**/*.ts` | Full `@tsfpp/prelude` API: `Option`, `Result`, `ReadonlyMap`, `ReadonlySet`, `List`, combinators, record decoding |
+| `tsfpp-api` | Routes, handlers, api dirs | Handler shape, `@tsfpp/boundary` imports, Zod validation, middleware composition, status codes, security baseline |
+| `tsfpp-react` | `**/*.tsx` | Component shape, discriminated union state, state elimination ladder, `useEffect` policy, TanStack Query, RHF+Zod, cva/cn styling |
+| `tsfpp-testing` | `**/*.{test,spec}.{ts,tsx}` | AAA structure, factory usage, fast-check property tests, MSW, RTL query hierarchy, forbidden patterns |
+| `trunk` | Git workflow contexts | Conventional Commits, branch naming, PR discipline, trunk-based development rules |
+
+The workspace-level `copilot-instructions.md` is always active regardless of which file is open. It establishes the TSF++ axioms, the prelude-first principle, and the absolute non-negotiables.
+
+---
+
+## Skills
+
+Skills are loaded automatically by Copilot based on semantic match with what is being discussed. Unlike instruction files, skills are not file-scoped — they are injected into the context when the model determines they are relevant.
 
-The workspace-level `copilot-instructions.md` is always active regardless of which file is open. It establishes the language rule (US technical English in all files), points to the agents, and lists the absolute non-negotiables.
+| Skill | Loaded when |
+|-------|------------|
+| `coding-standard` | Writing or reviewing TypeScript; checking rules; auditing compliance |
+| `prelude-api` | Importing from or discussing `@tsfpp/prelude`; choosing between combinators |
+| `boundary-api` | Writing handlers; discussing HTTP error mapping, pagination, or middleware |
+| `react-coding-standard` | Writing React components, hooks, forms, or stores |
+| `test-standard` | Writing or reviewing test files; discussing coverage or test structure |
+| `annotation-standard` | Writing or reviewing any comment, JSDoc block, module header, code marker, or DEVIATION; discussing what to annotate and why |
+
+Skills are distilled from the full standard documents — concise enough to fit in the model's context without crowding out code.
+
+---
+
+## Prompts
+
+Reusable slash commands available in Copilot chat.
+
+| Prompt | Purpose |
+|--------|---------|
+| `/trunk-init-repo` | Initialises a git repository with `main` branch, `.gitignore`, an initial conventional commit, optional remote, and Husky hook activation. Run once after bootstrapping. |
+| `/trunk-changelog` | Inspects the current working tree diff, derives the correct conventional commit message, and appends a matching entry to the `## [Unreleased]` section of `CHANGELOG.md`. |
+| `/tsfpp-new-module` | Scaffolds a new TSF++ module with the correct file structure, barrel export, and JSDoc stubs. |
+| `/tsfpp-boundary-review` | Reviews an HTTP handler against the full `@tsfpp/boundary` contract. |
+
+---
 
 ## How agents reference the standard
 
-Each agent reads the TSF++ standards directly from `node_modules/@tsfpp/standard/` and the prelude API from `node_modules/@tsfpp/prelude/`. This means:
+Each agent reads TSF++ standards directly from `node_modules/@tsfpp/standard/spec/` and the prelude API from `node_modules/@tsfpp/prelude/` at runtime. This means:
+
+- The agent always enforces the version of the standard your project has installed.
+- Upgrading `@tsfpp/standard` automatically updates what the agents enforce — no changes to agent files required.
+- The agent files contain workflow logic, checklist structure, and layer-specific patterns — not rule content. Rule content lives in the standard packages.
 
-- The agent always uses the version of the standard your project has installed.
-- Upgrading `@tsfpp/standard` automatically updates what the agents enforce — no changes to the agent files required.
-- The agent files themselves contain workflow logic, not rule content.
+---
 
 ## Further reading
 
@@ -111,6 +292,8 @@ Each agent reads the TSF++ standards directly from `node_modules/@tsfpp/standard
 - [`@tsfpp/eslint-config`](https://github.com/tsfpp/eslint-config) — ESLint flat config
 - [`@tsfpp/tsconfig`](https://github.com/tsfpp/tsconfig) — TypeScript compiler presets
 
+---
+
 ## Release process
 
 Releases are automated with Release Please.
@@ -119,6 +302,8 @@ Releases are automated with Release Please.
 2. Release Please opens or updates a release PR on each merge to `main`.
 3. Merging the release PR publishes to npm, creates a GitHub release, and updates `CHANGELOG.md`.
 
+---
+
 ## License
 
 MIT

package/copilot/agents/tsfpp-annotate.agent.md

@@ -1,27 +1,36 @@
 ---
-description: Adds missing JSDoc, DEVIATION comments, eslint-disable annotations, and code markers to target files. Never changes runtime behaviour.
+description: >
+  Adds missing JSDoc blocks, module headers, inline comments, DEVIATION markers,
+  eslint-disable annotations, and code markers to target files. Never changes
+  runtime behaviour.
 name: tsfpp-annotate
-argument-hint: "Path(s) to annotate, e.g. src/domain/track.ts or src/domain/"
+argument-hint: "Path(s) to annotate, e.g. src/domain/user.ts or src/domain/"
 tools:
   - edit/editFiles
   - read
-  - search/codebase
-  - search/fileSearch
-  - search/textSearch
+  - search
   - todo
   - vscode/askQuestions
 handoffs:
   - label: Re-audit annotations
     agent: tsfpp-audit
-    prompt: "Re-audit the annotated files with focus: annotations. Verify JSDoc coverage and marker format."
+    prompt: "Re-audit the annotated files for TSF++ compliance. Focus: annotations. Proceed immediately."
     send: false
 ---
 
 # TSF++ Annotate
 
-You are a code annotation specialist. Your job is to make code self-documenting and auditable by adding missing JSDoc blocks, DEVIATION markers, eslint-disable comments, and structured code notices — without changing any runtime behaviour.
+You are a code annotation specialist. Your job is to make code self-documenting
+and auditable by adding missing JSDoc blocks, module headers, inline comments,
+DEVIATION markers, eslint-disable pairings, and structured code markers —
+without changing any runtime behaviour.
 
-The canonical standard is at `node_modules/@tsfpp/standard/spec/CODING_STANDARD.md` (Rules 7–8).
+## Before starting
+
+Load and apply the `/annotation-standard` skill. Every annotation you write
+must conform to all rules in that skill.
+
+Full standard: `node_modules/@tsfpp/standard/spec/ANNOTATION_CODING_STANDARD.md`
 
 > Touch only comments and documentation. **Never alter types, logic, or imports.**
 
@@ -29,7 +38,7 @@ The canonical standard is at `node_modules/@tsfpp/standard/spec/CODING_STANDARD.
 
 ## Session start
 
-If the user has not specified a target, ask:
+If the user has not specified a target, ask once:
 
 > Which file(s) or directory should I annotate?
 
@@ -37,167 +46,138 @@ If the user has not specified a target, ask:
 
 ## What to annotate
 
-### 1. JSDoc on exported symbols (Rule 7.x — MUST)
+### 1. Module header (§1)
 
-Every exported `function`, `const`, `type`, and `interface` requires a JSDoc block.
+Required on every `.ts` file that exports public API. If absent, add it before the first import.
 
-**Function / const (callable):**
 ```ts
 /**
- * <One-sentence purpose in imperative mood.>
- *
- * <Optional: preconditions or invariants the caller must satisfy.>
- *
- * @param name - <description>
- * @returns <description of return value and its semantics>
+ * @module <module-name>
  *
- * @law identity     - mapO(identity)(x) ≡ x
- * @law associativity - ...
+ * <One-paragraph description: what this module provides, not how it works.>
+ * <Key design constraints a consumer needs to know.>
  *
- * @example
- * const result = mkUserId('abc-123')
- * // => some({ _tag: 'UserId', value: 'abc-123' })
+ * @packageDocumentation
  */
 ```
 
-**Type alias:**
-```ts
-/**
- * <What this type represents in the domain.>
- *
- * Discriminated by `kind`. Variants: `'pending'` | `'resolved'` | `'rejected'`.
- */
-```
+### 2. JSDoc on exported symbols (§2)
+
+Every exported `function`, `const` (callable or significant), `type`, and `interface`.
 
-**Module-level block** (top of every `.ts` file that exports public API):
 ```ts
 /**
- * @module <module-name>
+ * <One-sentence purpose in imperative mood.>
  *
- * <One-paragraph description of what this module provides.>
+ * <Why: invariants, constraints, domain rules, rejected alternatives,
+ * accepted limitations — anything the reader cannot derive from the code.>
  *
- * @packageDocumentation
+ * @param name - <domain constraint, not the type>
+ * @returns <meaning of the return value, not its type>
+ *
+ * @law identity — mapO(x => x)(opt) ≡ opt
+ *
+ * @example
+ * mkUserId('usr-00123') // => some(UserId('usr-00123'))
+ * mkUserId('')          // => none
  */
 ```
 
-**Rules:**
-- `@param` and `@returns` required on every exported function.
-- `@law` required on every combinator that satisfies a functor, monad, or other algebraic law.
-- `@example` required on smart constructors and non-obvious combinators.
-- Do not add `@throws` in core — core does not throw. Use `@throws` only in adapter functions that bridge a throwing third-party API.
-
----
-
-### 2. DEVIATION comments
-
-When a forbidden construct is present and intentional, place this on the line immediately before it:
+Rules:
+- `@param` and `@returns` required on every exported function
+- `@law` required on every combinator with algebraic properties
+- `@example` required on smart constructors and non-obvious combinators
+- `@deprecated` requires a replacement and a version number
+- `@throws` forbidden on functions that return `Result<T, E>`
 
-```ts
-// DEVIATION(N.M): <one-line justification>
-```
-
-**Common patterns:**
-```ts
-// DEVIATION(1.4): Framework plugin API requires an interface — type alias not accepted
-interface PluginContract { ... }
+### 3. Inline comments (§3)
 
-// DEVIATION(1.5): Third-party lib returns any — narrowed to unknown immediately below
-const raw: any = externalLib.getData()
-```
+Add inline comments only when the code contains something a reader cannot
+confidently derive from the code and types alone:
 
-Only annotate constructs that already exist and already violate a rule. Do not add DEVIATION comments to clean code.
+- **Why this approach** over the alternative the reader will naturally consider
+- **Rejected alternatives** — what was considered and why it was ruled out
+- **Non-obvious invariants** — preconditions the type cannot express
+- **External contracts** — field names / values dictated by a third party
+- **Accepted imprecision** — known limitations that are intentional
+- **Performance trade-offs** — why a non-obvious implementation was chosen
 
----
+Do not add inline comments that paraphrase the code. Do not add section dividers.
 
-### 3. eslint-disable comments
+### 4. Code markers (§4)
 
-Every lint suppression must be paired with a DEVIATION comment:
+Fix malformed markers (missing author, date, or ticket). Do not add new markers
+to code that has no existing issues.
 
+Required format:
 ```ts
-// DEVIATION(1.5): Legacy adapter — any narrowed to unknown on next line
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const payload: any = deserialise(raw)
+// MARKER(author, YYYY-MM-DD[, TICKET]): description
 ```
 
-- Never add a bare `// eslint-disable` without a DEVIATION comment.
-- Prefer `eslint-disable-next-line` over block-level `/* eslint-disable */`.
-- If a suppression already exists without a DEVIATION comment, add the DEVIATION comment above it.
+Author is the GitHub handle or initials of the person adding the marker —
+never the AI. If unknown, use `unknown` and flag it in the summary.
 
----
+### 5. DEVIATION comments (§5)
 
-### 4. Code markers
+When a forbidden construct is present and intentional:
 
-Format:
 ```ts
-// <MARKER>(<author>, <YYYY-MM-DD>[, <ticket>]): <description>
+// DEVIATION(N.M): <reason the violation could not be avoided — not a description of the violation>
 ```
 
-| Marker | When to use |
-|--------|-------------|
-| `TODO` | Work that must be done before the next release |
-| `FIXME` | Known bug or broken behaviour |
-| `HACK` | Temporary workaround — must be revisited |
-| `NOTE` | Important context a reader needs to understand the code |
-| `OPTIMIZE` | Works correctly but has a known performance concern |
-| `BUG` | Confirmed bug, not yet fixed |
-| `XXX` | Extra caution warranted — something fragile or surprising |
-
-**Examples:**
-```ts
-// TODO(alice, 2026-05-14, PROJ-421): Replace with Result-based validation once boundary refactor lands
-// FIXME(bob, 2026-05-14): Returns none for empty string — should return err('empty')
-// HACK(carol, 2026-05-14): Forced cast — third-party type definition is wrong, fixed in v3.x
-// NOTE(dave, 2026-05-14): Intentional shallow copy — deep clone would be O(n²) here
-// XXX(eve, 2026-05-14): Called before store is hydrated — ordering is load-bearing
-```
-
-**Rules:**
-- Author is the GitHub handle or initials of the person adding the marker — not the AI.
-- If the user does not supply an author, use `unknown` and flag it.
-- If the user does not supply a date, use today's date.
-- Do not add markers to code that has no existing issues. Only annotate genuinely notable constructs.
+Pair every bare `eslint-disable` with a DEVIATION comment above it.
+Only annotate constructs that already exist and already violate a rule.
 
 ---
 
 ## Execution workflow
 
 **Step 1 — Inventory**
-For each file in scope, count and list:
+
+For each file in scope, list:
 - Exported symbols missing JSDoc
-- Violations present without a `// DEVIATION(N.M)` comment
-- `eslint-disable` lines without a paired DEVIATION comment
-- Existing markers with missing author, date, or ticket
+- Files missing a module header
+- Constructs with no `DEVIATION` comment where one is needed
+- Bare `eslint-disable` lines without a paired DEVIATION comment
+- Malformed markers (missing author, date, or ticket)
+- Opportunities for inline comments (invariants, external contracts, rejected alternatives visible in the code)
 
-Report the full inventory before making any changes.
+Report the full inventory then proceed immediately — do not ask for confirmation.
 
-**Step 2 — Confirm scope**
-Present the inventory. Ask: "Shall I proceed with all files, or a subset?"
-Do not start editing until the user confirms.
+> **Do not pause between files.** Work through all files without interruption.
+> Only present handoff options after the summary is complete.
 
-**Step 3 — Annotate file by file**
-For each confirmed file:
-1. Add missing module-level JSDoc block if absent.
+**Step 2 — Annotate file by file**
+
+For each file:
+1. Add or fix the module-level JSDoc block.
 2. Add missing JSDoc blocks to each exported symbol.
-3. Add DEVIATION comments above known violations.
-4. Pair bare eslint-disable lines with DEVIATION comments.
-5. Fix malformed markers (fill missing author/date fields with `unknown` / today).
-6. Report what was added per file.
+3. Add inline comments where the code contains non-obvious reasoning.
+4. Add DEVIATION comments above known violations.
+5. Pair bare `eslint-disable` lines with DEVIATION comments.
+6. Fix malformed markers.
+7. Report what was added per file.
+
+**Step 3 — Summarise**
 
-**Step 4 — Summarise**
 Report totals:
+- Module headers added
 - JSDoc blocks added
-- Module-level blocks added
+- Inline comments added
 - DEVIATION comments added
-- eslint-disable comments paired
+- `eslint-disable` lines paired
 - Markers fixed
-- Placeholders left for the user to fill in (`unknown` authors, `DEVIATION(?)`)
+- Placeholders requiring author input (`unknown`, `DEVIATION(?)`)
 
 ---
 
 ## Hard rules
 
-- Never change types, logic, or imports — documentation only.
-- Never invent content for `@param` or `@returns` — derive strictly from the signature and implementation.
-- If a description cannot be determined, write `// TODO(unknown, <date>): Add JSDoc` as a placeholder and flag it in the summary.
-- If a DEVIATION is needed but the rule number is unclear, write `// DEVIATION(?): <description>` and flag it.
-- Never add `@throws` to a function that uses `Result` — the error is in the return type, not thrown.
+- Never change types, logic, or imports — documentation only
+- Never invent content for `@param` or `@returns` — derive strictly from the signature and implementation
+- If a description cannot be determined, write `// TODO(unknown, <date>): Add JSDoc` and flag it
+- If a DEVIATION is needed but the rule number is unclear, write `// DEVIATION(?): <description>` and flag it
+- Never add `@throws` to a function that returns `Result<T, E>`
+- Never add commented-out code
+- Never add section dividers or decorative separators
+- Never attribute comments to an AI

package/copilot/agents/tsfpp-audit.agent.md

@@ -267,25 +267,46 @@ Checklist:
 - [ ] Test files excluded from LOC limits but flagged if > 600 lines
 
 ### `annotations`
-Checklist:
-
-**JSDoc (§7)**
-- [ ] Every exported symbol has a JSDoc comment
-- [ ] `@param` present for every parameter on exported functions
-- [ ] `@returns` present on every exported function with a non-void return
-- [ ] `@law` present on every combinator with algebraic laws
-- [ ] No JSDoc on non-exported symbols (unnecessary noise)
-
-**Code markers**
-- [ ] `TODO` / `FIXME` / `HACK` / `NOTE` / `OPTIMIZE` / `BUG` / `XXX` all have format: `(author, YYYY-MM-DD[, TICKET]): description`
+Full reference: `node_modules/@tsfpp/standard/spec/ANNOTATION_CODING_STANDARD.md`
+
+**Module headers (SS1)**
+- [ ] Every file with public exports has a module-level JSDoc block
+- [ ] Module header describes the contract, not the implementation
+- [ ] `@packageDocumentation` present
+
+**JSDoc on exported symbols (SS2)**
+- [ ] Every exported function, const, type has a JSDoc block
+- [ ] First sentence states purpose in imperative mood
+- [ ] JSDoc body explains the **why** -- not a paraphrase of the code
+- [ ] `@param` describes domain constraint, not the type
+- [ ] `@returns` describes meaning of the value, not its type
+- [ ] `@law` present on every combinator with algebraic properties
+- [ ] `@example` present on smart constructors and non-obvious combinators
+- [ ] `@deprecated` includes replacement and version number where present
+- [ ] No `@throws` on functions that return `Result<T, E>`
+
+**Inline comments (SS3)**
+- [ ] No comments that paraphrase the code
+- [ ] No commented-out code
+- [ ] No section dividers or decorative separators
+- [ ] Rejected alternatives documented where a reader would naturally question the choice
+- [ ] Non-obvious invariants and external contracts documented
+- [ ] Known limitations explicitly marked as intentional
+- [ ] Performance trade-offs with scale thresholds documented where present
+
+**Code markers (SS4)**
+- [ ] All markers follow `// MARKER(author, YYYY-MM-DD[, TICKET]): description` exactly
 - [ ] No marker missing author or date
-- [ ] No stale TODO older than one release cycle without a ticket reference
-
-**Deviations**
-- [ ] Every rule violation has `// DEVIATION(N.M): <one-line justification>` immediately before the offending line
-- [ ] DEVIATION format is exact: `DEVIATION(N.M)` — not `deviation`, not `Deviation`, not `DEVIATION N.M`
+- [ ] All `HACK` markers have a ticket and a revisit condition
+- [ ] No `BUG` marker without a conversion plan
+- [ ] No stale marker surviving more than one release cycle without a ticket
+
+**Deviations (SS5)**
+- [ ] Every rule violation has `// DEVIATION(N.M): <justification>` immediately before the offending line
+- [ ] Justification explains why no alternative was feasible -- not what the violation is
+- [ ] Format is exact: `DEVIATION(N.M)` -- not `deviation`, not `Deviation`, not `DEVIATION N.M`
+- [ ] Every bare `eslint-disable` is paired with a DEVIATION comment above it
 - [ ] Project-wide deviations are documented in `DEVIATIONS.md`
-
 ### `security`
 Full reference: `node_modules/@tsfpp/standard/spec/SECURITY_CODING_STANDARD.md`
 

package/copilot/agents/tsfpp-guarded-coding.agent.md

@@ -113,6 +113,28 @@ Implement user requests with minimal safe diffs while preserving TSF++ guarantee
 
 ---
 
+
+## Annotate as you go
+
+Load and apply the `/annotation-standard` skill before writing any code.
+
+Every exported symbol you write must have a JSDoc block. Do not defer annotation
+to the annotate agent -- annotate while the reasoning is fresh.
+
+JSDoc body rules:
+- First sentence: what the function computes (imperative mood)
+- Subsequent paragraphs: **why** -- invariants, constraints, rejected alternatives,
+  domain rules, accepted limitations. Anything the reader cannot derive from the code.
+- `@param` -- domain constraint, not the type
+- `@returns` -- meaning of the return value, not its type
+- `@law` -- required on every combinator with algebraic properties
+- `@example` -- required on smart constructors and non-obvious combinators
+- Never `@throws` on a function that returns `Result<T, E>`
+
+When adding inline comments, apply the same test: does this tell the reader
+something they cannot derive from the code and types alone? If not, omit it.
+
+---
 ## Prelude-first
 
 Before writing any implementation, check `@tsfpp/prelude` for available symbols.

package/copilot/prompts/trunk-changelog.prompt.md

@@ -0,0 +1,160 @@
+# Write changelog entry
+
+Inspect the current working tree, derive the correct conventional commit message,
+and append a matching entry to the `## [Unreleased]` section of `CHANGELOG.md`.
+
+---
+
+## Step 1 — Inspect changes
+
+Run the following to see what has changed:
+
+```bash
+git diff --stat HEAD
+git status --short
+```
+
+For each changed or added file, read enough of its diff to understand **what
+changed and why** — not just which lines moved.
+
+```bash
+git diff HEAD -- <file>
+```
+
+If files are staged but not committed, use:
+
+```bash
+git diff --cached --stat
+git diff --cached -- <file>
+```
+
+---
+
+## Step 2 — Classify changes
+
+Map each change to a Conventional Commits type:
+
+| Type | Use when |
+|---|---|
+| `feat` | New behaviour or capability visible to a consumer |
+| `fix` | Corrects incorrect behaviour |
+| `perf` | Improves performance without changing behaviour |
+| `refactor` | Internal restructuring; no behaviour change, no bug fix |
+| `test` | Adds or fixes tests; no production code change |
+| `docs` | Documentation only |
+| `chore` | Tooling, config, dependencies, release machinery |
+| `build` | Build system or external dependency changes |
+| `ci` | CI configuration changes |
+
+**Breaking change:** any change that removes or renames a public export, changes
+a function signature, or alters a type in a way that requires consumer updates.
+Mark with `!` after the type (e.g. `feat!`) and add a `BREAKING CHANGE:` footer.
+
+**Scope:** the package or module affected — e.g. `prelude`, `boundary`, `agents`,
+`react`, `dal`. Omit if the change is cross-cutting.
+
+---
+
+## Step 3 — Write the commit message
+
+Produce a conventional commit message following this format exactly:
+
+```
+<type>(<scope>): <imperative summary in sentence case, ≤ 72 chars>
+
+<optional body — what changed and why, not how, wrapped at 72 chars>
+
+<optional footers>
+BREAKING CHANGE: <description if applicable>
+Closes #<issue> (if applicable)
+```
+
+Rules:
+- Summary is imperative mood: "add", "fix", "remove" — not "added", "fixes"
+- Summary does not end with a period
+- Body explains the **why**, not the **what** (the diff is the what)
+- One commit per logical change; if the diff contains multiple unrelated changes,
+  produce one message per change and say so
+
+---
+
+## Step 4 — Update CHANGELOG.md
+
+Find or create the `## [Unreleased]` section at the top of `CHANGELOG.md`.
+If `CHANGELOG.md` does not exist, create it with this header:
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+This file is maintained automatically by [release-please](https://github.com/googleapis/release-please)
+and supplemented during development via the `/trunk-changelog` prompt.
+
+<!-- do not remove this comment — release-please uses it as an anchor -->
+<!-- RELEASE-PLEASE-INSERTION-POINT -->
+
+## [Unreleased]
+```
+
+Append the new entry under `## [Unreleased]`, grouped by type in this order:
+
+```markdown
+## [Unreleased]
+
+### Breaking changes
+- `feat!(boundary)!: remove legacy `fold` export` — consumers must migrate to `map`/`flatMap`
+
+### Features
+- `feat(prelude): add ReadonlyMap combinators` — `intoMap`, `assoc`, `dissoc`, `lookup`, `entriesOfMap`
+
+### Bug fixes
+- `fix(agents): init.mjs fails with ReferenceError when run with --yes`
+
+### Performance
+- ...
+
+### Refactoring
+- ...
+
+### Tests
+- ...
+
+### Documentation
+- ...
+
+### Chores
+- ...
+```
+
+Only include sections that have entries. Do not add empty sections.
+
+Each entry is a single line:
+- Backtick-quoted commit summary
+- Em dash
+- One-sentence plain-English explanation of the user-visible impact
+
+---
+
+## Step 5 — Output
+
+Print the proposed commit message in a code block so it can be copied directly
+into the terminal or used with `git commit`:
+
+```
+git commit -m "<type>(<scope>): <summary>" \
+           -m "<body paragraph if needed>"
+```
+
+If there are multiple logical changes, list each message separately and recommend
+committing them individually with `git add -p` to stage per-change.
+
+---
+
+## Rules
+
+- Never invent changes that are not visible in the diff
+- Never write a changelog entry for a change that has no user-visible impact
+  (internal renaming, comment edits) — use `chore` or `refactor` in the commit
+  message but omit from `## [Unreleased]`
+- Do not modify any section of `CHANGELOG.md` other than `## [Unreleased]`
+- release-please owns every versioned section (`## [1.2.3]`) — never touch those

package/copilot/skills/annotation-standard/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: annotation-standard
+description: >
+  Normative TSF++ annotation rules for all comments, JSDoc blocks, module
+  headers, code markers, and deviation records. Load when writing, reviewing,
+  or adding annotations to any TypeScript file: the "why not what" principle,
+  JSDoc body content (invariants, rejected alternatives, external contracts,
+  accepted imprecision, performance trade-offs), marker taxonomy with format,
+  DEVIATION pairing, and what must never be annotated.
+---
+
+# TSF++ annotation standard
+
+Full standard: `node_modules/@tsfpp/standard/spec/ANNOTATION_CODING_STANDARD.md`
+
+---
+
+## The single deciding question
+
+> Does this tell the reader something they cannot confidently derive from the code and its types?
+
+If no — do not add the comment. If yes — write it.
+
+---
+
+## What only a comment can tell you
+
+| Category | Example |
+|---|---|
+| **Why this approach** over the natural alternative | Why linear scan instead of `Map` lookup |
+| **Rejected alternatives** | What was considered and why it was ruled out |
+| **Non-obvious invariants** | Preconditions the type cannot express |
+| **Domain knowledge** | Business rules that live in the problem space |
+| **External contracts** | Field names / values dictated by a third party |
+| **Accepted imprecision** | Known limitations that are intentional |
+| **Performance trade-offs** | Why a non-obvious implementation was chosen |
+| **Temporal context** | Why a workaround exists, when to revisit it |
+
+---
+
+## JSDoc body: the why, not the what
+
+The first sentence is the purpose. Everything after is the reasoning.
+
+```ts
+/**
+ * Constructs a validated `UserId` from a raw string.
+ *
+ * Returns `None` if the input is empty. The empty case is excluded rather
+ * than mapped to an error because an empty ID indicates a caller bug, not
+ * a domain error — the type system prevents this at compile time in
+ * internal code; this guard exists for boundary inputs only.
+ *
+ * @param raw - The raw string to validate. Must be non-empty.
+ * @returns `Some(UserId)` if valid; `None` if empty.
+ *
+ * @example
+ * mkUserId('usr-00123') // => some(UserId('usr-00123'))
+ * mkUserId('')          // => none
+ */
+```
+
+`@param` describes the domain constraint, not the type. `@returns` describes the meaning, not the type. Both are already in the signature.
+
+---
+
+## Module header
+
+Required on every file with public exports:
+
+```ts
+/**
+ * @module user-account
+ *
+ * Domain model for user accounts. Provides the `UserAccount` sum type,
+ * its smart constructors, and the combinators for working with account
+ * state and identity.
+ *
+ * All functions are pure and total. Error cases are modelled via
+ * `Option<A>` (absent value) or `Result<T, E>` (fallible computation).
+ *
+ * @packageDocumentation
+ */
+```
+
+First sentence: what the module provides. Second paragraph: key design constraints a consumer needs to know. Never describe the implementation.
+
+---
+
+## Inline comment patterns
+
+### Rejected alternative
+
+```ts
+// NOTE(rob, 2026-05-18): Linear scan rather than `ReadonlyMap` lookup.
+// The active session list is always ≤10 items per user; the allocation
+// overhead of a map outweighs the O(1) lookup benefit at this scale.
+const found = sessions.find(s => s.id === id)
+```
+
+### Non-obvious invariant
+
+```ts
+// Invariant: `handlers` must be registered before this is called.
+// The runtime guarantees registration order; do not call from a module
+// initialiser that may run before the framework bootstraps.
+```
+
+### External contract
+
+```ts
+// IMPORTANT: The field name `client_id` is specified by OAuth2 RFC 6749
+// and must not be renamed despite the camelCase convention.
+// DEVIATION(1.8): Field name required by external protocol.
+```
+
+### Accepted imprecision
+
+```ts
+// NOTE(rob, 2026-05-18): Timestamp comparison has ≤1 s imprecision due
+// to clock drift between service instances. Acceptable for audit logs;
+// not acceptable for financial ordering.
+```
+
+---
+
+## Code markers
+
+Required format — no exceptions:
+
+```ts
+// MARKER(author, YYYY-MM-DD[, TICKET]): description
+```
+
+| Marker | Use when | Blocks merge? |
+|---|---|---|
+| `TODO` | Work required before next release | Soft — needs ticket |
+| `FIXME` | Known bug the author is aware of | Yes |
+| `HACK` | Temporary workaround with a deferred correct solution | Yes — needs ticket + revisit condition |
+| `NOTE` | Context a reader needs to understand the code | No |
+| `OPTIMIZE` | Correct but with a known performance concern at scale | No — needs scale threshold |
+| `BUG` | Confirmed bug not yet in a ticket | Yes — convert to FIXME + ticket |
+| `XXX` | Fragile or load-bearing — must not be casually changed | No — use sparingly |
+
+```ts
+// TODO(rjansen, 2026-05-18, ARCH-44): Replace with Result-based validation
+//   once the boundary refactor lands in v2.0.
+// HACK(rjansen, 2026-05-18, INFRA-12): Forced cast — third-party type
+//   definition is wrong. Fixed upstream in v4.x — remove after upgrade.
+// NOTE(rjansen, 2026-05-18): Rate-limit window resets at midnight UTC,
+//   not relative to first request. Contractual requirement — do not change.
+// XXX(rjansen, 2026-05-18): Initialisation order is load-bearing. The
+//   store must be hydrated before any handler is registered.
+```
+
+Author = GitHub handle or initials. Never an AI. If unknown, use `unknown`.
+
+---
+
+## DEVIATION format
+
+```ts
+// DEVIATION(N.M): <reason the violation could not be avoided>
+```
+
+The justification explains why no alternative was feasible — not what the violation is.
+
+Every `eslint-disable` must be paired:
+
+```ts
+// DEVIATION(1.5): Legacy adapter — raw type narrowed to unknown immediately below.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const payload: any = deserialise(raw)
+```
+
+The `as` in a smart constructor body:
+
+```ts
+// eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- DEVIATION(1.6): smart-constructor body
+return some(raw as UserId)
+```
+
+---
+
+## Never annotate
+
+| Forbidden | Example |
+|---|---|
+| Paraphrasing the code | `// Check if user is admin` above `if (user.role === 'admin')` |
+| Restating the type | `// Returns a string` on `: string` |
+| Commented-out code | `// const old = legacyParse(raw)` |
+| Section dividers | `// ─────────────` with nothing meaningful |
+| Stale comments | Any comment that no longer matches the code |
+| AI attribution | `// Generated by Claude` |
+| `@throws` on Result functions | Error is in the return type, not thrown |
+| Apologetic comments | `// This is a bit hacky but...` — use `HACK` properly |

package/init.mjs

@@ -55,6 +55,7 @@ const FILES = [
 
   // Prompts
   ['copilot/prompts/trunk-init-repo.prompt.md',               '.github/prompts/trunk-init-repo.prompt.md'],
+  ['copilot/prompts/trunk-changelog.prompt.md',              '.github/prompts/trunk-changelog.prompt.md'],
   ['copilot/prompts/tsfpp-new-module.prompt.md',              '.github/prompts/tsfpp-new-module.prompt.md'],
   ['copilot/prompts/tsfpp-boundary-review.prompt.md',         '.github/prompts/tsfpp-boundary-review.prompt.md'],
 
@@ -64,6 +65,7 @@ const FILES = [
   ['copilot/skills/boundary-api/SKILL.md',                    '.github/skills/boundary-api/SKILL.md'],
   ['copilot/skills/react-coding-standard/SKILL.md',           '.github/skills/react-coding-standard/SKILL.md'],
   ['copilot/skills/test-standard/SKILL.md',                   '.github/skills/test-standard/SKILL.md'],
+  ['copilot/skills/annotation-standard/SKILL.md',          '.github/skills/annotation-standard/SKILL.md'],
 
   // Claude Code
   ['claude/CLAUDE.md',                                        '.claude/CLAUDE.md'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsfpp/agents",
-  "version": "1.3.5",
+  "version": "1.4.0",
   "description": "Workspace AI tooling for TSF++ projects: scoped instructions, coding agents, and reusable prompts",
   "keywords": [
     "tsfpp",