release-notes-generator

• Roadmap feature: F033 On-disk spec: specs/027-release-maturity-management/ (dir 027 == F033; when the dir number and the F-number disagree, the roadmap F-number wins).
• Authority category: Maintenance Automation (the F024 enumerated declaration -- see docs/architecture/product-modules.md). NO connectivity level and NO capability level: those sub-axes belong to Execution Adapters and Product Modules; Maintenance Automation carries neither (its boundary is prose).

The kit ships in slices. Each slice changes WHAT THE KIT CAN DO, but the kit has no durable, reviewable record of "what became possible in this release, and how mature is the capability". Today that answer lives only in commit messages and the roadmap's delivered ledger. This skill is the record: it DRAFTS a per-release note (seven required blocks) and ASSESSES an evidence-gated maturity ladder. It composes evidence others already recorded; it originates none of it and owns no truth. A maturity claim is exactly where a tool is tempted to round "two worked examples" up to "production ready"; the kit's no-fake-confidence rule (hard rule #9) forbids that, so the ladder is an evidence-gated MILESTONE ladder -- not a score -- and the skill drafts-and-stops for a named release owner to approve.

Authority declaration (F024) -- Maintenance Automation (no sub-axis)

This skill declares EXACTLY ONE of the five F024 authority categories. Quoted verbatim from docs/architecture/product-modules.md, Maintenance Automation is:

a tool that runs WITHOUT a per-invocation human trigger (scheduled / CI), emits ONLY derived evidence (a report, a drift signal, a recomputed index), never creates truth, and never self-approves. This is the novel category: it is distinguished from a human-invoked Module by the absence of a per-run human trigger. The schedule itself -- and the evidence it runs on -- is a prior named-human action, so this does NOT relax Principle V.

Maintenance Automation is the ONLY non-Core category with no parallel sub-axis (a Module pins a capability level, an Adapter pins a connectivity level; "the other three categories carry no parallel sub-axis -- their boundary is prose"). So there is no module-contract / adapter-contract to fill for F033; the declaration is this prose section plus the matrix column below.

This skill's authority row, quoted verbatim from the F024 authority matrix (the Maintenance Automation column):

In short: this skill reads committed evidence, summarizes it, and writes DERIVED evidence (the release note + the maturity report). It declares NO connectivity level (it never connects to a DB or external service -- if it ever had to, the seam would make it an Adapter, not this category) and NO capability level (that axis is a Module's). It CREATES no truth and GRANTS no approval; both belong to a named human via Core Authority (Principle V). It is the conductor's product-level read AFTER a milestone, not a per-run human-triggered Module -- the prior named-human actions are the schedule and the already-committed evidence it runs on, so the category fits and Principle V is intact.

The two load-bearing boundaries (carried verbatim; do not drift)

Boundary 1 -- No fake confidence: the ladder is MILESTONES, not a score

The maturity ladder is an EVIDENCE-GATED MILESTONE ladder -- a binary "this evidence exists or it does not" test per rung, level = the HIGHEST rung whose required evidence ALL exists -- structurally the same kind of artifact as the seven numbered readiness stages (docs/readiness/readiness-model.md), which are legitimate milestones, NOT scores. The numbered rungs L0..L6 are milestone names, exactly like the numbered readiness stages; the number is an ordinal milestone, never a quantity.

This skill MUST NOT emit a percentage, a 0-100 health number, an average, or ANY number that reads as confidence (hard rule #9). A rung is reported as achieved (evidence: ...) or not achieved (missing: ...) -- never "73% mature". If asked for a numeric maturity score, the skill DECLINES, cites hard rule #9, and returns the rung verdicts + cited evidence instead.

A rung is BINARY -- achieved or not achieved. Partial evidence (one worked example complete, the second mid-build) is "not achieved" with the missing piece named; it is never rounded up. The ladder does NOT use the four readiness statuses (not_started/blocked/warning/pass) -- those are the per-table readiness spine's vocabulary; a rung is a two-valued milestone verdict.

Boundary 2 -- Consume, never re-measure; never self-approve

This skill READS the F028 evidence pack, the F032 compatibility matrix, the committed roadmap ledger + commit refs, the worked-example docs, and the on-disk presence of adapters/projects. It DRAFTS the note and ASSESSES the rung from that committed evidence. It NEVER:

• runs seshat check / retail validate, profiles a source, opens a DB connection, or reads powerbi/ (it consumes recorded results; it re-measures nothing). A missing input is recorded as "evidence not available", never fabricated.
• self-approves a release (draft -> approved is a named release owner recorded in approvals[]), self-confirms a level, or publishes (tags / GitHub releases / registry pushes are out of scope -- release execution stays a human action).
• moves any readiness stage to pass or adds any gate / seshat check rule / CLI verb / validator. Release & maturity is a product-level process orthogonal to the per-table readiness spine; it advances no stage.

Inputs it CONSUMES (referenced by role; never re-measured)

It IMPORTS none of these; it READS them. If an input is missing, the rule is "evidence not available -- cannot assert capability", never a fabricated claim or row.

The two output artifacts (two files, two purposes -- never merged)

A "release" is one shipped roadmap F-slice keyed by its roadmap F-number. Filled, approved sets live under docs/releases/<F-number>/ (e.g. docs/releases/F033/), one set per release -- the per-release record (parallel to docs/roadmap/ the delivered ledger). A batch (e.g. F024-F033) is recorded as a GROUP of per-slice notes, never one merged note. docs/releases/ is the DESCRIBED output home; this skill drafts into it and a human approves -- the skill does not create the dir or any approved instance.

The seven release-note blocks (the per-release record)

The note MUST contain all seven blocks, in order. Every "what became possible" claim MUST cite the committed evidence behind it (a file/commit, or the cited F028 pack entry); a claim with no traceable source is a defect.

Plus the note's status (draft / approved) and approvals[] (named release owner + date). The skill produces it as status: draft -- awaiting release-owner approval; it has approved nothing.

The seven-rung evidence-gated maturity ladder (the honesty core)

Exactly seven rungs, each with a BINARY evidence test. The reported level is the HIGHEST rung whose required evidence ALL exists; rungs above that are reported NOT achieved with the exact missing artifact named. Rung order is a capability-evidence milestone narrative, independent of the roadmap's F-sequence: it does NOT imply F016 is the sequencing apex -- F016 remains the deliberately-last, bottom-of-stack execution-only adapter that no readiness stage depends on.

L3's caveat -- "generic repeatability BEYOND the worked tables is the NEXT evidence" -- is a FORWARD scope-note reserved for once L3's binary test is satisfied, NOT license to round an unmet L2/L3 up early. Until >= 2 worked tables exist on disk, L3's binary test (silver + gold proven repeatable across the >= 2 worked tables L2 requires) is NOT satisfied, and L3 is reported NOT ACHIEVED with the missing second worked table named -- never rounded up on the strength of the first table alone.

Worked assessment against today's repo (the honest current state)

Run against the repo as of this authoring, the assessment yields (verify against the repo, never assert from memory):

Reported level today: L1 (the highest rung whose required evidence ALL exists). The kit makes NO production / GA / enterprise-grade claim: no rung backs one. No rung is reported as a number.

Procedure (numbered; do not reorder)

1. Identify the release and read the inputs

Resolve the release (one shipped roadmap F-slice, keyed by its F-number). READ the F028 evidence pack for the slice, the F032 compatibility matrix (by role; "consumed input not yet available" if absent), the delivered roadmap ledger row + commit refs, and the on-disk presence of adapters/projects. This is read-only; it re-measures nothing.

2. Draft the seven release-note blocks with citations

Fill templates/release-notes.md: each of the seven blocks, every "what became possible" line citing its committed evidence. A capability with no supporting evidence is NOT listed under "what became possible" -- it is omitted, or listed under "known limitations -- not yet evidenced", never asserted. Set status: draft -- awaiting release-owner approval.

3. Assess each rung by its binary test

Fill templates/maturity-report.md: for each rung L0..L6, run its binary evidence test against the committed evidence / on-disk presence, record achieved (evidence: ...) or not achieved (missing: ...). Record L3's repeatability caveat as a forward scope-note on its achieved verdict.

4. Report the level (no number)

The reported level = the highest rung whose required evidence ALL exists. Name the rungs above it as not achieved with the missing artifact. Emit NO percentage / score / average.

5. Surface conflicts; never resolve them

When inputs disagree (e.g. the matrix asserts an adapter version interoperates but no adapter exists in-repo), record the conflict as a FINDING and do NOT pick a side (Principle V). The skill recommends; the human decides.

6. STOP for the named release owner

Leave the note status: draft. Approval (draft -> approved) and level confirmation are a named release owner's act recorded in approvals[] -- Core-Authority, truth-creating, which this skill cannot perform. After a run, git status shows only the drafted derived artifacts; no release self-approved, no level self-confirmed, no stage moved to pass, no validator run, no DB opened.

Refusal behaviors (the honesty guard -- testable)

What the agent must NOT do

• Do NOT emit a numeric maturity score / percentage / averaged confidence (hard rule #9).
• Do NOT claim a capability, "production ready", "GA", or "enterprise grade" with no backing evidence rung.
• Do NOT report a level above the highest all-evidence-present rung; do NOT round a partial rung up.
• Do NOT self-approve a release, self-confirm a level, or publish (Core Authority).
• Do NOT re-measure: no seshat check / retail validate, no source profiling, no DB connection, no powerbi/ read.
• Do NOT add a seshat check rule, a CLI verb, a validator, or any new gate; do NOT move any readiness stage to pass.
• Do NOT bake C086 / retail_store_sales specifics into the two generic templates (they are cited as track record in a FILLED instance, never inlined into the blank templates).
• Do NOT create docs/releases/ content or any approved instance -- the skill drafts; a human approves.

See also

• The two output templates: ../../../templates/release-notes.md, ../../../templates/maturity-report.md.
• The authority contract: ../../../docs/architecture/product-modules.md (the five categories + the matrix + the absence of a Maintenance Automation sub-axis), ../../../docs/architecture/core-vs-modules-and-adapters.md (the prose + the seam).
• The consumed inputs (by id + role): ../../../docs/tools/evidence-pack-generator.md (F028, built), ../../../specs/026-adapter-compatibility-matrix/spec.md (F032, the compatibility matrix -- referenced by role).
• The release history of record: ../../../docs/roadmap/roadmap.md (delivered ledger).
• The four-status / no-fake-confidence model the ladder mirrors structurally: ../../../docs/readiness/readiness-model.md; hard rule #9.
• The read-and-present sibling it mirrors: ../retail-control-room/SKILL.md. The conductor it plugs into: ../retail-orchestrate/SKILL.md.
• The worked example that grounds the ladder: ../../../docs/worked-examples/retail-store-sales.md; mappings/retail_store_sales/.
• The spec: ../../../specs/027-release-maturity-management/spec.md.

Orchestration

When a milestone ships, the retail-orchestrate conductor may invoke this generator as the product-level read AFTER the milestone: it reads the committed evidence (F028 pack + F032 matrix + roadmap ledger), DRAFTS the seven release-note blocks, ASSESSES the maturity rung, reports the level, and STOPS for the named release owner. It advances no readiness stage -- the per-table spine and the product-level release record are orthogonal. Release approval, level confirmation, and any publish are the named release owner's acts via Core Authority, never this skill's.