chore(standards): reconcile Catalog 5 v5.26.0

.agents/skills/agent-handoff/SKILL.md

@@ -43,7 +43,7 @@ Knowledge files under `docs/` belong to the consumer after creation. Preserve th
 
 The standard owns:
 
-- `.agents/skills/agent-handoff/**`;
+- `.agents/skills/agent-handoff/**` and its byte-identical copy `.claude/skills/agent-handoff/**`;
 - the optional `.agents/hooks/agent-handoff/session-start`;
 - only the exact marked blocks or semantic hook entries it installed;
 - its entries in the central `.standards/lock.toml` inventory.
@@ -63,23 +63,49 @@ For bugs, allocate the lowest unused three-digit ID and never renumber an existi
 
 ## Closeout
 
-Perform closeout when current work, current facts, or future work changed:
+Perform closeout when current work, current facts, or future work changed. Take the session-start OID from the first entry of the SessionStart `Last 5 commits` block; every `--since` below uses that OID.
 
+0. Survey the session before editing anything. Route the `delta` output instead of reconstructing the session with `grep` or `git log`: its commits become the session record, its touched handoff documents name what to update, and its issue references belong in `docs/STATUS.md` or `docs/TODO.md`.
 1. Update `docs/STATUS.md` with current outcomes that still orient the project.
 2. Preserve user-authored tasks and update the agent queue in `docs/TODO.md`.
 3. Remove completed or superseded detail from `docs/handoff/state.md`; leave only next-session focus and active incidents.
 4. Route deployment, architecture, credential-reference, convention, specification, and plan facts to their durable owners.
 5. Append a compact session record when it adds durable history.
 6. Create or update a numbered bug record when a cause, fix, or lesson should survive.
-7. Run the relevant validation commands and review the diff.
+7. Validate against the session boundary and review the diff.
 
 ```bash
-project-standards agent-handoff validate --repo .
+project-standards agent-handoff delta --repo . --since <session-start-oid>
+project-standards agent-handoff validate --repo . --since <session-start-oid>
 project-standards agent-handoff drift-check --repo .
 ```
 
+`--since` is the closeout form of validation: it suppresses warnings on lines the session did not add, so a warning this session introduced stands out instead of being buried under the pre-existing findings that append-only documents such as `docs/handoff/sessions/` accumulate. Errors are never suppressed by `--since`. Run the bare `validate --repo .` for a full repository audit.
+
 Use `size-report` or `shape-check` when eager content or document form changed.
 
+### Document caps
+
+Write to these caps the first time rather than discovering them by failing validation.
+
+| Document | Caps |
+| --- | --- |
+| `docs/handoff/state.md` | 2048 bytes hard, fatal; 1740 bytes target; 140 chars per bullet; 4 bullets per section; no paragraphs |
+| `docs/STATUS.md` | 60 lines target; 180 chars per bullet |
+| `docs/TODO.md` | 160 chars per bullet |
+| `docs/handoff/deployed.md` | 120 lines target |
+| `docs/handoff/architecture.md` | 200 lines target; 420 chars per paragraph |
+| `docs/handoff/conventions.md` | 180 chars per rule summary; 1200 chars per entry |
+| `docs/handoff/sessions/*.md` | 220 chars per table row; 20 words per row headline |
+| `docs/handoff/bugs/NNN-slug.md` | No size cap; sections Cause, Fix, and Lesson required |
+| Any other handoff document | 360 chars per paragraph; 180 chars per bullet |
+
+Caps count physical characters and bytes in the file. Visual wrapping in an editor is not a line break and does not satisfy a cap. Where this table and the installed policy could ever disagree, the validator wins: its finding reports the measured size and the applicable `max N`, and that number is authoritative.
+
+### Delegating closeout
+
+When the harness provides a dedicated closeout subagent, delegate closeout to it by default and keep the main thread on the remaining work. The brief carries the session-start OID, the `delta` output, the facts to record, and the caps above, because the subagent starts with no conversation context. The orchestrator reviews the resulting diff before the session ends; delegation moves the writing, not the responsibility. Where the harness has no such subagent, perform the same steps inline.
+
 ## Migration reconciliation
 
 Migration is a local-agent review inside the current repository, not an automated converter. Run:

.agents/skills/markdown-frontmatter/SKILL.md

@@ -5,16 +5,16 @@ compatibility: Claude Code and Codex CLI
 license: MIT
 metadata:
   author: Chris Purcell
-  version: '1.4'
+  version: '1.5'
 ---
 
 # Markdown Frontmatter
 
 ## Overview
 
-Author and fix YAML frontmatter for **managed Markdown documents** under the [project-standards Markdown Frontmatter Standard](https://github.com/L3DigitalNet/project-standards/blob/v5.19.0/standards/markdown-frontmatter/versions/1.11/README.md).
+Author and fix YAML frontmatter for **managed Markdown documents** under the [project-standards Markdown Frontmatter Standard](https://github.com/L3DigitalNet/project-standards/blob/v5.24.0/standards/markdown-frontmatter/versions/1.14/README.md).
 
-This skill ships with the standard package and is installed repo-local at `.agents/skills/markdown-frontmatter` when a repository adopts the standard. That path is deliberate: both Claude Code and Codex CLI can discover it without a global skill owner.
+This skill ships with the standard package. When a repository adopts the standard it is installed repo-local as byte-identical, digest-locked copies at **both** `.agents/skills/markdown-frontmatter` (Codex CLI) and `.claude/skills/markdown-frontmatter` (Claude Code) — each harness reads only its own tree. The duplication is deliberate; neither copy may be edited or deleted to deduplicate them.
 
 **Core principle: the schema is authoritative, not this file.** The machine contract is `markdown-frontmatter.schema.json` in project-standards, enforced by `project-standards validate`. This skill is the operating layer for the rules agents get wrong most often. On any conflict, the schema and current standard pages win.
 
@@ -24,7 +24,7 @@ This skill ships with the standard package and is installed repo-local at `.agen
 - A `project-standards validate`, `validate-frontmatter`, or `format-frontmatter --check` run failed and you need to fix the block.
 - Deciding which `doc_type` / `status` / other controlled value to set.
 
-**When NOT to use: files that must NEVER carry frontmatter.** Agent-instruction and agent-skill files are harness config, not managed documents: `CLAUDE.md`, `AGENTS.md`, and anything under `.claude/`, `.agents/`, `.codex/`. That includes this installed skill at `.agents/skills/markdown-frontmatter`. Exclude those paths through the package's `exclude` option in `.standards/config.toml` instead of adding metadata. A repo may also exclude its root `README.md` if it prefers no metadata table on its landing page.
+**When NOT to use: files that must NEVER carry frontmatter.** Agent-instruction and agent-skill files are harness config, not managed documents: `CLAUDE.md`, `AGENTS.md`, and anything under `.claude/`, `.agents/`, `.codex/`. That includes both installed copies of this skill, at `.agents/skills/markdown-frontmatter` and `.claude/skills/markdown-frontmatter`. A packaged `SKILL.md`'s own leading `---` block (`name`, `description`, `compatibility`, …) is Agent-Skills manifest metadata for the harness, not a managed-document profile, so it is not a violation of this prohibition and must not be "fixed" into one. Exclude those paths through the package's `exclude` option in `.standards/config.toml` instead of adding metadata. A repo may also exclude its root `README.md` if it prefers no metadata table on its landing page.
 
 ## Required fields (the eleven)
 
@@ -33,7 +33,7 @@ Every managed document opens with a `---` fenced YAML block carrying at least th
 ```yaml
 ---
 schema_version: '1.1'
-id: 'note-xxxxxx-human-title'
+id: 'note-XXXXXX-human-title'
 title: 'Human Title'
 description: 'One-sentence description of the document.'
 doc_type: 'note'
@@ -83,23 +83,30 @@ These fields accept only these values (the schema is the source of truth):
 
 ## The `id` field — standard-enforced format
 
-> **This is a standard rule, not a local addition.** `markdown-frontmatter@1.11` enforces the id format below via `validate-id` (run by `project-standards validate` and the V5 CI workflow). An id whose leading segment is not a valid `doc_type` **fails validation** with `prefix '<x>' is not a valid doc_type`. Earlier repo-name-prefixed ids no longer pass.
+> **This is a standard rule, not a local addition.** `markdown-frontmatter@1.14` enforces the id format below via `validate-id` (run by `project-standards validate` and the V5 CI workflow). An id whose leading segment is not a valid `doc_type` **fails validation** with `prefix '<x>' is not a valid doc_type`. Earlier repo-name-prefixed ids no longer pass.
 
 ```text
 {doc_type}-{base36-6}-{document-name}
 ```
 
 The `doc_type` (one of the controlled values above), then a random 6-character base36 token, then a readable document slug, all lower kebab-case (e.g. `runbook-0f943i-restart-netbox-after-config-change`). The token keeps the id globally unique; the slug is frozen at creation and does **not** change when the title is edited.
 
-**Generate the id with the script. Never invent the token yourself.** An LLM asked for a "random" base36 token produces low-entropy, collision-prone strings and reuses tokens already in context, defeating the uniqueness goal. `scripts/` is this skill's own directory (invoke by absolute path if your cwd is elsewhere):
+**Generate the id with the script. Never invent the token yourself.** An LLM asked for a "random" base36 token produces low-entropy, collision-prone strings and reuses tokens already in context, defeating the uniqueness goal. `scripts/` is this skill's own directory and holds `new-doc-id` and nothing else (invoke by absolute path if your cwd is elsewhere):
 
 ```bash
-scripts/new-doc-id <document-name>                        # bare id, doc_type 'note'
-scripts/new-doc-id --doc-type runbook <document-name>     # bare id, 'runbook' prefix
-scripts/new-doc-id --scaffold --doc-type runbook <name>   # full canonical frontmatter block
+# New document — the default path. Emits the whole canonical block, not just an id.
+scripts/new-doc-id --scaffold --doc-type runbook <document-name>
+
+# Existing document missing or repairing an id — bare id only.
+scripts/new-doc-id --doc-type runbook <document-name>     # 'runbook' prefix
+scripts/new-doc-id <document-name>                        # doc_type 'note'
 ```
 
-The `--doc-type` value becomes both the id prefix and (in `--scaffold`) the `doc_type` field, so the two always agree; it defaults to `note`. `--doc-type` and `--status` must be standard-controlled values. `--scaffold` emits the eleven required fields in canonical order with today's date correctly quoted. Replace the `REPLACE:` description placeholder before committing.
+`--scaffold` is the default path for a **new** document: it emits the eleven required fields in canonical order, with today's date correctly quoted and empty lists as `[]`, so none of the hand-authoring mistakes below can occur. The bare-id forms are the repair path for a document that already has a frontmatter block. **Replace the `REPLACE:` description placeholder in scaffolded output before committing.**
+
+The `--doc-type` value becomes both the id prefix and (in `--scaffold`) the `doc_type` field, so the two always agree; it defaults to `note`. `--doc-type` and `--status` must be standard-controlled values.
+
+For a batch of documents, do not loop the script per file. Write the placeholder id `{doc_type}-XXXXXX-{slug}` into each document, then make one `validate-id --fix` pass over the batch to mint the real tokens. The placeholder is uppercase deliberately: the token must match `^[0-9a-z]{6}$`, so `XXXXXX` fails validation loudly and `--fix` repairs it, whereas a lowercase placeholder is itself a valid token and would ship silently.
 
 ADRs are the exception: follow the standard's ADR id form (`adr-{NNNN}-{repo-name}-{title}`, e.g. `adr-0001-homelab-use-postgresql-for-persistent-storage`), not the `doc_type`-prefixed format. Do not use the script for ADR ids.
 
@@ -155,6 +162,8 @@ format-frontmatter --check
 
 To check or repair a single file's id: `validate-id <file>` (add `--fix` to rewrite an invalid id through the platform executor).
 
+**Where these commands come from.** `validate-id`, `format-frontmatter`, and `validate-frontmatter` are separate console scripts installed by the `project-standards` distribution — they are top-level commands on `PATH`. They are **not** `project-standards` subcommands (`project-standards validate-id` fails with `invalid choice`) and they are **not** files in this skill's `scripts/` directory, which holds `new-doc-id` alone. A repository may need its own runner prefix to reach the installed distribution; use whatever prefix its other `project-standards` invocations use.
+
 ## Common mistakes
 
 | Mistake | Fix |
@@ -169,8 +178,8 @@ To check or repair a single file's id: `validate-id <file>` (add `--fix` to rewr
 
 ## Authoritative references
 
-- [Standard README](https://github.com/L3DigitalNet/project-standards/blob/v5.19.0/standards/markdown-frontmatter/versions/1.11/README.md) — overview and adoption surface.
-- [Structure Requirements](https://github.com/L3DigitalNet/project-standards/blob/v5.19.0/standards/markdown-frontmatter/versions/1.11/structure.md) — hard fields, key order, scalar/list rules, IDs, and validation.
-- [Field Values](https://github.com/L3DigitalNet/project-standards/blob/v5.19.0/standards/markdown-frontmatter/versions/1.11/field-values.md) — lifecycle, ownership, canonical tags, aliases, relationships, sources, and extensions.
-- [Adoption guide](https://github.com/L3DigitalNet/project-standards/blob/v5.19.0/standards/markdown-frontmatter/versions/1.11/adopt.md) — unified config, CI workflow, repo-local skill install, and compliance procedure.
-- `standards/markdown-frontmatter/versions/1.11/schemas/markdown-frontmatter.schema.json` (in project-standards) — the selected package contract; wins on any conflict.
+- [Standard README](https://github.com/L3DigitalNet/project-standards/blob/v5.24.0/standards/markdown-frontmatter/versions/1.14/README.md) — overview and adoption surface.
+- [Structure Requirements](https://github.com/L3DigitalNet/project-standards/blob/v5.24.0/standards/markdown-frontmatter/versions/1.14/structure.md) — hard fields, key order, scalar/list rules, IDs, and validation.
+- [Field Values](https://github.com/L3DigitalNet/project-standards/blob/v5.24.0/standards/markdown-frontmatter/versions/1.14/field-values.md) — lifecycle, ownership, canonical tags, aliases, relationships, sources, and extensions.
+- [Adoption guide](https://github.com/L3DigitalNet/project-standards/blob/v5.24.0/standards/markdown-frontmatter/versions/1.14/adopt.md) — unified config, CI workflow, repo-local skill install, and compliance procedure.
+- `standards/markdown-frontmatter/versions/1.14/schemas/markdown-frontmatter.schema.json` (in project-standards) — the selected package contract; wins on any conflict.