@cratis/pi 7.2.0 → 7.2.2

package/README.md

@@ -34,8 +34,10 @@ managed corpus.
 The packaged `cratis-path-guidance` extension attaches a path-scoped rule to the
 tool result the first time a matching file is touched, and after a successful
 `write` or `edit` adds one advisory line naming every skill whose `SKILL.md`
-`cratis-hint-paths` frontmatter matches the file. (The key is Cratis-specific
-because Claude Code gives a plain `paths` key its own meaning.) A skill is hinted at
+`metadata.cratis-hint-paths` frontmatter (one string of whitespace-separated globs)
+matches the file. (It sits under `metadata` because Agent Skills allows only a fixed set
+of top-level keys, and the key is Cratis-specific because Claude Code gives a plain
+`paths` key its own meaning.) A skill is hinted at
 most once per session and not when it is already in context: read (a shell command
 counts only when `cat`, `sed`, `head`, `tail`, `less`, `bat`, `rg` or `grep` opens
 its `SKILL.md` or a file under `references/`), preloaded by pi-subagents, or

package/package/corpus/agents/coordinator.md

@@ -128,7 +128,7 @@ For implementation, the applicable changed-lane gates must pass. Mark unrelated
 - [ ] `Documentation/verify-markdown.sh` passes when documentation is added or changed
 - [ ] `code-reviewer` finds no blocking issues
 - [ ] `security-reviewer` finds no vulnerabilities
-- [ ] PR description follows the pull request template
+- [ ] PR description follows the pull request template and the release-note contract in `pull-requests.md`; test and review notes are in a PR comment
 
 ---
 

package/package/corpus/agents/orchestrator.md

@@ -152,7 +152,7 @@ For implementation, the applicable changed-lane gates must pass. Mark unrelated
 - [ ] `code-reviewer` finds no blocking issues
 - [ ] `security-reviewer` finds no vulnerabilities
 - [ ] All documentation is complete and accurate (if required)
-- [ ] PR description follows the pull request template
+- [ ] PR description follows the pull request template and the release-note contract in `pull-requests.md`; test and review notes are in a PR comment
 
 ---
 

package/package/corpus/agents/planner.md

@@ -115,7 +115,7 @@ For an implemented application slice, require the applicable changed-lane gates
 - [ ] `Documentation/verify-markdown.sh` passes when documentation is added or changed
 - [ ] Code review by `code-reviewer` finds no blocking issues
 - [ ] Security review by `security-reviewer` finds no vulnerabilities
-- [ ] PR description follows the pull request template
+- [ ] PR description follows the pull request template and the release-note contract in `pull-requests.md`; test and review notes are in a PR comment
 
 ---
 

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/SkillTrigger.ts

@@ -8,6 +8,6 @@ export interface SkillTrigger {
     filePath: string;
     /** Directory holding `SKILL.md` and the skill's references. */
     baseDir: string;
-    /** The `cratis-hint-paths` frontmatter of the skill. Empty when the skill declares no trigger. */
+    /** The `metadata.cratis-hint-paths` frontmatter of the skill. Empty when the skill declares no trigger. */
     globs: string[];
 }

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/index.ts

@@ -66,7 +66,7 @@ function expandedSkillNames(prompt: unknown): string[] {
  *
  * Path-scoped rules are attached to the tool result the first time a matching file is touched in the session,
  * exactly as they were when `cratis-rules` delivered them. On a successful `write` or `edit`, one advisory line
- * names every skill whose `cratis-hint-paths` frontmatter matches the file and where its `SKILL.md` is. A skill
+ * names every skill whose `metadata.cratis-hint-paths` frontmatter matches the file and where its `SKILL.md` is. A skill
  * is not hinted when it is already in context: read in the session, preloaded by pi-subagents
  * (`# Preloaded Skill: <name>` followed by its text in the system prompt), or expanded by `/skill:<name>`. Hints are advisory only:
  * nothing is blocked and the system prompt is never touched.

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/skills.ts

@@ -4,9 +4,8 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { corpusRoot } from '../shared/corpusRoot.ts';
-import { frontmatter } from '../shared/frontmatter.ts';
 import { globToRegExp } from '../shared/globs.ts';
-import { skillTriggerKey } from '../shared/skillFrontmatter.ts';
+import { skillTriggerGlobs } from '../shared/skillFrontmatter.ts';
 import { selectedSkillNames } from '../shared/skillSelection.ts';
 import type { LoadedSkill } from './LoadedSkill.ts';
 import type { SkillMatch } from './SkillMatch.ts';
@@ -35,7 +34,7 @@ function repositorySkills(cwd: string): LoadedSkill[] {
 
 function triggerGlobs(filePath: string): string[] {
     try {
-        return frontmatter(readFileSync(filePath, 'utf8')).get(skillTriggerKey) ?? [];
+        return skillTriggerGlobs(readFileSync(filePath, 'utf8'));
     } catch {
         return [];
     }
@@ -48,7 +47,7 @@ function triggerGlobs(filePath: string): string[] {
  * it can be empty (a pi-subagents agent with `skills: false`, the usual setup for cheap workers), or non-empty
  * with only personal skills (an agent with `skills: true` whose `extensions:` allowlist leaves `@cratis/pi`, and
  * so its skill paths, out). The selected skills' `SKILL.md` can still be read by path, which is what the hint asks
- * for; a corpus skill the repository did not select is never added. Skills without a `cratis-hint-paths` trigger
+ * for; a corpus skill the repository did not select is never added. Skills without a `metadata.cratis-hint-paths` trigger
  * are left out.
  */
 export function skillTriggers(loaded: LoadedSkill[] | undefined, cwd: string): SkillTrigger[] {

package/package/corpus/harnesses/pi/extensions/shared/frontmatter.ts

@@ -5,17 +5,23 @@ export function unquote(value: string): string {
     return value.trim().replace(/^["']|["']$/g, '');
 }
 
+/** The text between the opening and closing `---` markers, or `undefined` when there is no terminated frontmatter. */
+export function frontmatterText(content: string): string | undefined {
+    if (!content.startsWith('---\n')) return undefined;
+    const end = content.indexOf('\n---\n', 4);
+    return end < 0 ? undefined : content.slice(4, end);
+}
+
 /**
  * Reads the YAML-ish frontmatter the corpus uses: scalar `key: value` lines and `key:` followed by
  * `  - item` lines. Anything richer is not used by the rules and skills and is deliberately not supported.
  */
 export function frontmatter(content: string): Map<string, string[]> {
     const fields = new Map<string, string[]>();
-    if (!content.startsWith('---\n')) return fields;
-    const end = content.indexOf('\n---\n', 4);
-    if (end < 0) return fields;
+    const text = frontmatterText(content);
+    if (text === undefined) return fields;
     let current: string | undefined;
-    for (const line of content.slice(4, end).split('\n')) {
+    for (const line of text.split('\n')) {
         const item = /^\s+-\s+(.*)$/.exec(line);
         if (item && current) {
             fields.get(current)!.push(unquote(item[1]));
@@ -29,3 +35,93 @@ export function frontmatter(content: string): Map<string, string[]> {
     }
     return fields;
 }
+
+/** One `key: value` line under a top-level block map such as `metadata`, as written, not interpreted. */
+export interface FrontmatterEntry {
+    /** The number of spaces the key is indented by, or -1 when the indentation contains a tab. */
+    indent: number;
+    /** The text after the colon, trimmed and otherwise untouched: quotes, a trailing comment and block scalar indicators included. */
+    raw: string;
+    /** True when more-indented lines follow the entry, so its value is a block scalar, a multi-line scalar or a nested map. */
+    continues: boolean;
+}
+
+/** The result of reading the block map under a top-level key. */
+export interface FrontmatterBlock {
+    /** The text after `name:` on the key's own line, trimmed. Non-empty for an inline value such as a flow map. */
+    inline: string;
+    /** The entries the block holds, in order. A more-indented line belongs to the entry above it and is not an entry itself. */
+    entries: Map<string, FrontmatterEntry>;
+}
+
+/**
+ * Reads the block under a top-level `name:` key without interpreting the values. Blank and comment lines are skipped.
+ * Returns `undefined` when the key is absent or the frontmatter is unterminated.
+ */
+export function frontmatterBlock(content: string, name: string): FrontmatterBlock | undefined {
+    const text = frontmatterText(content);
+    if (text === undefined) return undefined;
+    let block: FrontmatterBlock | undefined;
+    let inside = false;
+    let last: FrontmatterEntry | undefined;
+    let skipAbove: number | undefined;
+    for (const line of text.split('\n')) {
+        // Any line that starts in column 0 with something other than a comment ends the current block, whatever its
+        // spelling (a quoted key, a space before the colon). Only a real `name:` key starts this block.
+        if (/^[^\s#]/.test(line)) {
+            const top = /^([A-Za-z][\w-]*):(.*)$/.exec(line);
+            inside = top?.[1] === name;
+            last = undefined;
+            skipAbove = undefined;
+            // A comment after the key (`metadata: # note`) is not a value, so the block below it is still the block form.
+            if (inside) block ??= { inline: /^\s+#/.test(top![2]) ? '' : top![2].trim(), entries: new Map() };
+            continue;
+        }
+        if (!inside || !block || line.trim() === '' || /^\s*#/.test(line)) continue;
+        const indent = /^ *\t/.test(line) ? -1 : /^( *)/.exec(line)![1].length;
+        // Lines under a sibling key the entry pattern does not read (a quoted key, `? complex`) are not entries.
+        if (skipAbove !== undefined && indent > skipAbove) continue;
+        skipAbove = undefined;
+        const entry = /^\s+([A-Za-z][\w-]*):(.*)$/.exec(line);
+        if (entry && (!last || indent <= last.indent)) {
+            last = { indent, raw: entry[2].trim(), continues: false };
+            block.entries.set(entry[1], last);
+        } else if (last && (indent < 0 || indent > last.indent)) {
+            last.continues = true;
+        } else {
+            // At the entry's indentation or less, so a sibling key ends the entry even when its spelling is not read here.
+            last = undefined;
+            skipAbove = indent;
+        }
+    }
+    return block;
+}
+
+/**
+ * The string a raw scalar spells when it is written as one complete double-quoted or single-quoted string on one
+ * line, with nothing after the closing quote. Anything else, including a string with an escape or an embedded
+ * quote, a trailing `# comment`, an unquoted value and a block scalar, yields `undefined`: it is not guessed at.
+ */
+export function quotedScalar(raw: string): string | undefined {
+    return /^"([^"\\]*)"$/.exec(raw)?.[1] ?? /^'([^']*)'$/.exec(raw)?.[1];
+}
+
+/**
+ * Reads the nested string map under a top-level `name:` key, as Agent Skills `metadata` uses. Only the one form the
+ * corpus supports is read: an entry indented two spaces whose value is a complete one-line quoted string (see
+ * `quotedScalar`). Values stay whole strings, without comma splitting. An entry in any other form is left out of the
+ * map, so a caller never sees a guess such as `>-`; `frontmatterBlock` gives the raw entries for reporting them.
+ * Returns `undefined` when the key is absent or the frontmatter is unterminated.
+ */
+export function frontmatterMap(content: string, name: string): Map<string, string> | undefined {
+    const block = frontmatterBlock(content, name);
+    if (!block) return undefined;
+    const map = new Map<string, string>();
+    // A value on the key's own line (a flow map, even one that continues below) is not the supported block form.
+    if (block.inline !== '') return map;
+    for (const [key, entry] of block.entries) {
+        const value = entry.indent === 2 && !entry.continues ? quotedScalar(entry.raw) : undefined;
+        if (value !== undefined) map.set(key, value);
+    }
+    return map;
+}

package/package/corpus/harnesses/pi/extensions/shared/skillFrontmatter.ts

@@ -1,9 +1,31 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-/**
- * The `SKILL.md` frontmatter key that lists the globs a skill is hinted for. It is deliberately Cratis-specific:
- * Claude Code gives a plain `paths` key in `SKILL.md` a meaning of its own (a "conditional skill" that stays out
- * of the skill list until a matching file is touched), and `.claude/skills` exposes this corpus to it.
- */
+import { frontmatterMap } from './frontmatter.ts';
+
+// The key, under the `metadata` map of `SKILL.md` frontmatter, whose value lists the globs a skill is hinted for.
+// Agent Skills allows only `name`, `description`, `license`, `compatibility`, `metadata` and `allowed-tools` at the
+// top level, and `metadata` maps strings to strings, so the value is one string of whitespace-separated globs:
+//
+//     metadata:
+//       cratis-hint-paths: "**/for_*/**/*.cs **/Documentation/**/*.{md,mdx}"
+//
+// It is deliberately Cratis-specific: Claude Code gives a plain `paths` key in `SKILL.md` a meaning of its own (a
+// "conditional skill" that stays out of the skill list until a matching file is touched), and `.claude/skills`
+// exposes this corpus to it.
 export const skillTriggerKey = 'cratis-hint-paths';
+
+/** The raw `metadata.cratis-hint-paths` string of a `SKILL.md`, or `undefined` when the skill declares none. */
+export function skillTriggerValue(content: string): string | undefined {
+    return frontmatterMap(content, 'metadata')?.get(skillTriggerKey);
+}
+
+/** Splits a trigger value into its globs. Globs contain no whitespace, and brace sets keep their commas. */
+export function splitSkillTriggerGlobs(value: string): string[] {
+    return value.split(/\s+/).filter(Boolean);
+}
+
+/** The trigger globs a `SKILL.md` declares under `metadata.cratis-hint-paths`; empty when it declares none. */
+export function skillTriggerGlobs(content: string): string[] {
+    return splitSkillTriggerGlobs(skillTriggerValue(content) ?? '');
+}

package/package/corpus/prompts/ship-changes.prompt.md

@@ -2,20 +2,20 @@
 agent: agent
 description: >
   Ship local changes: create a branch, make logical commits, push, open and
-  label a PR with a proper description, merge it, prepare no-effect related
-  issue dispositions, and delete the branch.
+  label a PR with a proper description, merge it, prepare related issue
+  dispositions the request does not authorize, and delete the branch.
 ---
 
 # Ship Changes
 
 Ship the current local modifications to `main` through the standard
-branch → commits → PR → merge → no-effect issue disposition → cleanup workflow.
+branch → commits → PR → merge → issue disposition → cleanup workflow.
 
 ## Inputs
 
 - **What changed** — brief description of the work (used for branch name and PR title)
 - **Label** — `no-release`, `patch`, `minor`, or `major`, or omit entirely if no label should be applied
-- **Related issue** — optional exact repository and issue number; if unknown, search read-only first. Comment on or close it only when the user's request includes that effect.
+- **Related issue** — optional exact repository and issue number; if unknown, search read-only first. Comment on or close it only when the user's request includes that effect; otherwise prepare the disposition as a proposal. In repositories released by `cratis/release-action`, a delivered issue is closed by release-action through `(#n)` in the description, but release-action does not run for a `no-release` PR, so `(#n)` closes nothing there; elsewhere follow the repository's own release and issue-closing process.
 
 Invoking this prompt is direct authority for the standard branch, commit, push, pull-request,
 requested-label, merge, and branch-cleanup effects. Do not pause to ask for separate approval at
@@ -32,3 +32,18 @@ Every other label proceeds through merge under this prompt's ordinary authority.
 This prompt is for an explicit request to ship or land. If the user asked only to commit, only to
 push, or only to open a PR, stop after that step: the narrower request does not become authority
 for the rest of the chain because this prompt happens to be loaded.
+
+## Pull request description
+
+The description is published verbatim as the release notes, so it follows the contract in
+[`pull-requests.md`](../rules/pull-requests.md#the-description-is-the-release-note).
+
+- Before `gh pr create` or `gh pr edit`, write the body from `.github/pull_request_template.md` and
+  check it against the contract. The rules agents most often break:
+  - No development write-up: no Overview/Verification/Test plan headings (only a first `## Summary`
+    is allowed), no review, testing or provenance notes. Those go in a PR comment.
+  - `(#n)` ends the bullet that delivers an issue and `(part of #n)` marks anything that stays open;
+    never `Closes`/`Fixes`/`Refs` before a number, and never an issue reference inside an HTML comment,
+    which still closes the issue.
+  - Links are absolute `https://` URLs, never relative paths.
+- After pushing, if `verify-release-notes` fails, fix it by editing the description; it re-runs on edit.

package/package/corpus/rules/pull-requests.md

@@ -4,19 +4,81 @@ applyTo: "**/*"
 
 # How to Do Pull Requests
 
-PR descriptions serve two purposes: they help reviewers understand the change *now*, and they become the release notes that users read *later*. Write them with both audiences in mind.
+## The description is the release note
 
-**The description is the release note — it is published verbatim.** Write it as the note you want the person upgrading to read, in the repository template's sections. A generic development write-up (`## Summary`, `## Verification`, `## Testing`, a list of the files you touched, a description of how you arrived at the change) is not a release note, and shipping one makes the release history unreadable. The same applies wherever a release is produced by hand: release-notes text typed into a manual workflow run, or written straight into a published release, carries exactly the same shape and the same audience as a PR description. There is no path to a release whose notes are allowed to describe the work instead of the change.
+**The PR description is published verbatim as the GitHub release. In repositories released by `cratis/release-action`, it also closes every issue written as `(#n)`; elsewhere, follow the repository's own release and issue-closing process.** Write the note the person upgrading should read, not a development write-up. The same contract applies to release notes typed into a manual workflow run or written straight into a release. Where it is installed, the `verify-release-notes` check enforces it on every PR into the default branch that carries exactly one of `major`/`minor`/`patch` (it re-runs when the label is added); it skips `no-release` and unlabelled PRs, which should still be written this way because any of them may become releasable. `release-action` does not run for a `no-release` PR, so `(#n)` closes nothing there. Editing the description re-runs the check. HTML comments are not shown on the release page and the check ignores them for headings, keywords and placeholders, but a `(#n)` inside a comment still closes the issue (`release-action` skips only fenced and inline code) and the check fails it, so never put an issue reference in a comment. The template's own comment can stay: its `(#123)` examples are inline code.
 
-## Description
+### Allowed shape
 
-- Follow the repository's pull request template (`.github/pull_request_template.md`).
-- Focus on the **Added**, **Changed**, **Fixed**, **Removed**, **Security**, and **Deprecated** sections. Remove sections that are empty — don't leave blank headings.
-- Each bullet should be short, self-contained, and release-note ready.
-- **Write for users of the framework, not for internal developers.** Only include changes that have an impact on anyone using what we build — new APIs, changed behavior, fixed bugs, removed features. Do not list internal implementation details like storage changes, converter updates, gRPC contract internals, or spec additions. If a change is purely internal plumbing, it does not belong in the PR description. For a user-visible fix, a brief root cause and what now prevents a regression, stated as observable behavior rather than a list of specs, are user-facing and may be included: they tell the upgrader whether to trust the fix. Credit an external contributor by name or handle, unless they asked not to be named.
-- Add the associated issue reference at the end of a bullet when there is a real GitHub issue for the change (e.g. `(#351)`). Keep it a bare reference — **no closing keywords** (`Closes #351`, `Fixes #351`) anywhere in the body, because the published release notes are the PR description verbatim. If there is no associated issue, omit the reference entirely. Never use a placeholder like `(#issue)` or leave the example number `(#123)` literally, and never invent a random issue number. **Always verify the issue number read-only using the repository source — never guess or invent a number.** Comment on or close an issue when the user's request includes that effect; otherwise prepare a bounded post-merge disposition without performing it.
-- Include a summary only if there is a cohesive theme across the changes. If you find yourself restating individual bullets in slightly different words, the summary adds no value — remove it.
-- Never include Copilot prompt content in the PR description. Remove any "Original prompt" / coding agent transcript blocks before publishing.
+- Follow the repository's pull request template (`.github/pull_request_template.md`) within this contract.
+- An optional summary, first, only when one cohesive theme spans the bullets: **either** a `## Summary` section (short, user-facing prose) **or** one unheaded lead paragraph (1–3 sentences), never both. `Summary` is a level-2 heading; `# Summary` is the wrong level. No bullets before the first section.
+- Then only these `##` sections, each at most once, in this order after any `## Summary`: `## Added`, `## Changed`, `## Fixed`, `## Removed`, `## Security`, `## Deprecated`. Keep only the sections that have bullets: a section holding only prose, a code example or `None.` fails the check, so delete it. `###` sub-headings inside a section are fine unless they use a forbidden name; inside a section even `### Added` is only a sub-heading, and a section itself is always level 2.
+- A `major`/`minor`/`patch` PR needs at least one bullet under an allowed section.
+- Bullets are short, self-contained and user-facing: what a consumer compiles against, runs or observes. A user-visible fix may add one sentence of root cause or regression guard, stated as observable behavior. Credit an external contributor by name or handle, unless they asked not to be named.
+- Breaking changes and upgrade actions are bullets in `## Changed` or `## Removed` that state the action. A longer migration story goes in the docs, linked by absolute URL.
+- Do not list internal plumbing (storage, converters, gRPC internals, specs, file lists, refactor narration).
+
+### Issue references
+
+| Write | Meaning |
+| --- | --- |
+| `(#351)` at the **end of the bullet that delivers it** | Delivered: in a repository released by `cratis/release-action`, it closes it at release |
+| `(part of #351)` or prose `see #351` | Related, partial or follow-up: never closes |
+| `Cratis/Repo#351` | Other repository: never closed |
+| one `(#351)` per issue, never `(#351, #352)` | `(#351, #352)` closes nothing: write `(#351) (#352)` |
+
+- Nothing but more issue references (also `(part of #n)`, `(see #n)` and `(Cratis/Repo#n)`), closing emphasis, `<br>` and sentence punctuation (a `:` may introduce nested bullets) may follow the delivering `(#n)`. Write one `(#n)` per issue: release-action only matches `(#n)`, so `(#56, #57)` closes nothing; write `(#56) (#57)`.
+- Never use a linking or closing keyword before a number, anywhere: `Close`, `Closes`, `Closed`, `Fix`, `Fixes`, `Fixed`, `Resolve`, `Resolves`, `Resolved`, `Refs`, `Ref`, `References`, also as `Keyword: #n`, with `owner/repo#n`, followed by an issue URL, and wrapped in bold, italics or a link (`**Closes** #n`, `Closes [#n](url)`, `[Closes #n](url)`, and `[Closes](url)` where the link starts a clause). A `Refs #93` line closes nothing and is not a delivery marker: write `(#93)` at the end of the delivering bullet, or `(part of #93)` if it must stay open.
+- Comment on or close an issue when the user's request includes that effect; otherwise prepare a bounded post-merge disposition without performing it. In repositories released by `cratis/release-action`, a delivered `(#n)` is closed by release-action at release, so do not close it by hand; for a `no-release` PR release-action does not run, so any disposition follows this same rule. Elsewhere, follow the repository's own release and issue-closing process.
+- Use a bare `(#n)` only for an issue this PR fully delivers. No issue means no reference. Never use a placeholder such as `(#issue)` or the template's `(#123)`, and verify every number exists in the right repository; never guess.
+
+### Forbidden anywhere outside code
+
+- **Headings** (any level, also written as HTML `<h2>`, `<b>`, `<i>` or a possibly multi-line `<summary>`, or as an `*italic*` line; a heading line is checked like any other, so a keyword, relative link or `(#n)` in one fails too) other than a first `## Summary`, such as Overview, Description, What, Why, How, Context, Changes, What changed, Test plan, Testing, Tests, Verification, Verified, Validation, Quality, Review, Notes, Notes for reviewers, Limitations, Known follow-up, Acceptance, Details, and any `#`/`##` heading not in the allowed list.
+- **Review, verification, testing and provenance notes**: `Review:`, `Reviewed:`, a stand-alone `Reviewed by` line, `Verification:`, `Tested:`, `Testing:`, `Validation:` lines that stand alone or report a result (`Tests: 400 passed`, `Review: approved`); same-provider, cross-provider, Opus-only or Anthropic-only review remarks; the review workflow having passed, returned or run; CI or gate results (`CI green`, `all tests passed`); and a line stating which agent or model wrote the description (`Generated with Claude Code`, `Co-Authored-By:`). A bullet that describes a product change and only mentions review, validation, tests or an AI model (`- Validation: rules now apply to commands (#3)`, `- Reviewed by status is now shown on the dashboard (#4)`) is fine: inside a bullet, a summary or the lead paragraph the check reads a note only when it ends the clause (`- Cross-provider review pending`).
+- **Internal state** that is not a consumer change (for example "npm publication remains disabled").
+- **Relative links** (`](Documentation/x.md)`, `](./x)`, `](Source/...)`): they 404 on the release page. Use `https://github.com/Cratis/<Repo>/blob/main/<path>`, a `#anchor` or `mailto:`.
+- **Placeholders and transcripts**: template text, empty sections, Copilot "Original prompt" blocks, agent transcripts.
+
+Reviewer-facing information (test plan, verification, review provenance, notes for reviewers) goes in a **PR comment**, never the description.
+
+### Bad to good
+
+Bad (Cratis/Arc.TypeScript v0.48.0 as first published, bullets abridged):
+
+```markdown
+Arc can now construct Chronicle reactors and reducers through its own dependency injection, one scope per delivered batch, as an opt-in preview. npm publication remains disabled.
+
+## Added
+
+- Preview option `withChronicle({ ..., activateArtifactsInScopes: true })` ... (#93)
+
+See [Activate reactors and reducers in Arc scopes](Documentation/chronicle/reactors/scoped-activation.md).
+
+Review: Opus-only (same-provider) review.
+
+Refs #93
+```
+
+Good (as corrected):
+
+```markdown
+Arc can now construct Chronicle reactors and reducers through its own dependency injection, one scope per delivered batch, as an opt-in preview.
+
+## Added
+
+- Preview option `withChronicle({ ..., activateArtifactsInScopes: true })` ... See [Activate reactors and reducers in Arc scopes](https://github.com/Cratis/Arc.TypeScript/blob/main/Documentation/chronicle/reactors/scoped-activation.md). (part of #93)
+```
+
+"npm publication remains disabled" is internal status, the link was relative (it 404s on the release page), the review line is provenance for reviewers, and `Refs #93` is a keyword line. #93 was only partly delivered by this release, so its bullets say `(part of #93)`; `(#93)` would have closed it.
+
+### Before you create or edit a PR
+
+1. Read the body against the forbidden list and the issue table above; delete every hit and verify every issue number.
+2. Sections in order, none empty, at most one summary form; every bullet user-facing.
+3. Test plan, verification and review notes are in a PR comment.
+
+If `verify-release-notes` fails, fix it by editing the description, not by pushing code.
 
 ## Commits
 

package/package/corpus/skills/cratis-application-react-specifications/SKILL.md

@@ -2,9 +2,8 @@
 name: cratis-application-react-specifications
 description: Write specifications for the React and TypeScript surface of a Cratis application slice — view models, helpers, command orchestration, and narrow component behavior — using Vitest with Mocha-style describe/it, Sinon, and the Chai should interface. Use when adding or changing frontend behavior in an application that consumes Cratis. Do not use for backend scenarios or for specifications inside a Cratis framework package.
 license: MIT
-cratis-hint-paths:
-  - "**/for_*/**/*.ts"
-  - "**/for_*/**/*.tsx"
+metadata:
+  cratis-hint-paths: "**/for_*/**/*.ts **/for_*/**/*.tsx"
 ---
 
 # Cratis application React specifications

package/package/corpus/skills/cratis-application-slice-specifications/SKILL.md

@@ -2,9 +2,8 @@
 name: cratis-application-slice-specifications
 description: Specify the backend behavior of an event-sourced Cratis application slice with the in-process scenario family — CommandScenario, EventScenario, ReadModelScenario and ReactorScenario — including what to cover for each slice type and where the specification files live. Use when adding or changing backend behavior in an application built on Cratis. Do not use for framework library specifications and do not use for frontend behavior.
 license: MIT
-cratis-hint-paths:
-  - "**/when_*/**/*.cs"
-  - "**/for_*/**/*.cs"
+metadata:
+  cratis-hint-paths: "**/when_*/**/*.cs **/for_*/**/*.cs"
 ---
 
 # Cratis application slice specifications

package/package/corpus/skills/cratis-documentation-writing/SKILL.md

@@ -2,8 +2,8 @@
 name: cratis-documentation-writing
 description: Plan, write, and improve user-centered Cratis documentation with a clear reader journey and one primary Diátaxis purpose per page. Use for product docs, tutorials, how-to guides, reference, explanations, and documentation reviews. For executable examples use cratis-technical-examples; for release notes use cratis-release-notes. Do not invent APIs or publish content.
 license: MIT
-cratis-hint-paths:
-  - "**/Documentation/**/*.{md,mdx}"
+metadata:
+  cratis-hint-paths: "**/Documentation/**/*.{md,mdx}"
 ---
 
 # Documentation writing
@@ -136,9 +136,9 @@ An AI-drafted narrative is a first draft, not a finished page. Give the model
 the reader, the scenario, the terminology and the source evidence up front;
 then revise the result against that evidence and the
 **cratis-writing-voice-and-cadence** constructions before it ships. Tell the
-reviewer the narrative was AI-drafted (in the review request or commit
-message, not in a PR description's release-note sections) so they read it as
-prose, not only as a diff.
+reviewer the narrative was AI-drafted (in the review request, a PR comment or
+the commit message, never in the PR description, which is published as the
+release note) so they read it as prose, not only as a diff.
 
 For machine-readable delivery and retrieval checks, use
 **cratis-llm-friendly-documentation**; publishing `llms-full.txt` alone does

package/package/corpus/skills/cratis-engineering-docs-authoring/SKILL.md

@@ -2,8 +2,8 @@
 name: cratis-engineering-docs-authoring
 description: Draft accurate Cratis product or engineering documentation once the reader's goal, owning source, and product evidence are known. Use for tutorials, how-to guides, explanations, and references; use the owning repository's navigation and visual QA workflows for placement and rendering.
 license: LICENSE
-cratis-hint-paths:
-  - "**/Documentation/**/*.{md,mdx}"
+metadata:
+  cratis-hint-paths: "**/Documentation/**/*.{md,mdx}"
 ---
 
 # Cratis documentation authoring

package/package/corpus/skills/cratis-release-notes/SKILL.md

@@ -20,10 +20,10 @@ required to draft notes.
 Before writing, identify product, tag or candidate version, previous version,
 artifact/package names, supported platforms, and the audience. Inventory
 observable changes from the diff, specs, linked issues/PRs, and authoritative
-product source at that revision. A PR description may be published verbatim as
-release notes in a Cratis repository; follow its current template and confirm
-that behavior before drafting. Do not turn an unreleased draft into a claim
-about shipped behavior.
+product source at that revision. A PR description is published verbatim as
+release notes in a Cratis repository; follow its current template and the
+pull-request contract, and confirm that behavior before drafting. Do not turn
+an unreleased draft into a claim about shipped behavior.
 
 For each change, ask: who uses this path, what happened before, what happens
 now, is action required, and how would they notice? Check changed defaults,
@@ -42,15 +42,29 @@ one to add weight.
 
 ## Write for the right channel
 
-- **Exact-version release note (GitHub/PR):** start with changes requiring
-  action and affected workflows, then new capabilities and fixes. State impact
-  and the user's next action in plain language. Include an issue reference only
-  when verified, and follow the owning repository's closing-keyword policy.
-  Do not list internal refactors or specs that change nothing users observe.
-  For a user-visible fix, a sentence of root cause and of what now guards
-  against a regression, stated as observable behavior rather than a list of
-  specs, is user-facing: it tells the reader whether to trust the fix. Credit an external contributor by name or handle and say what
-  they did, unless they asked not to be named.
+- **Exact-version release note (GitHub/PR):** in a Cratis repository this is
+  the merged PR description, published verbatim, so it follows the contract in
+  [pull-requests.md](../../rules/pull-requests.md), which holds the full
+  rules. The ones most often broken: no development write-up (no Overview,
+  Verification or Test plan headings, no review or provenance notes; those go
+  in a PR comment); `(#n)` at the end of the bullet that delivers an issue and
+  `(part of #n)` for anything that stays open (in repositories released by
+  `cratis/release-action`, `(#n)` is what closes the issue), never `Closes`, `Fixes` or
+  `Refs` before a number (also in bold or a link), and no issue reference
+  inside an HTML comment, which still closes the issue; and absolute
+  `https://` links only. Sections are in
+  a fixed order (Added, Changed, Fixed, Removed, Security, Deprecated); within
+  a section, put changes requiring action first, then new capabilities and
+  fixes. State impact and the user's next action in plain language: state an
+  upgrade action in its `## Changed` or `## Removed` bullet (a first
+  `## Summary` section or an unheaded lead paragraph, not both, may mention it
+  too). Do not list internal
+  refactors or specs that change nothing users observe. For a
+  user-visible fix, a sentence of root cause and of what now guards against a
+  regression, stated as observable behavior rather than a list of specs, is
+  user-facing: it tells the reader whether to trust the fix. Credit an
+  external contributor by name or handle and say what they did, unless they
+  asked not to be named.
 - **Migration guide (durable product docs):** a compact *old behavior → new
   behavior → required action* table for each affected upgrade path, followed
   by source-verified before/after code or commands. Distinguish required
@@ -75,6 +89,23 @@ boundary that makes a change safe to adopt. One item can follow this shape:
 That is a checklist for facts, not a template to repeat word-for-word across
 items. Use descriptive headings, meaningful links, and natural sentence rhythm.
 
+## Repair an already-published release
+
+Only when asked to fix a release that violates the contract:
+
+1. Read the published body (`gh release view TAG --json body`) and the merged
+   PR. Keep the facts; remove headings, review and verification lines,
+   internal status and closing keywords, and turn relative links into
+   `https://` URLs. Do not invent changes, versions or issue numbers.
+2. Publish the corrected text with `gh release edit TAG --notes-file FILE`,
+   only when the request authorizes editing that release.
+3. In a repository released by `cratis/release-action`, editing a release
+   does not re-run release-action, so an issue that a `(#n)` would have
+   closed stays open. For each one, confirm the release
+   actually delivered it. Close it by hand with a comment naming the release
+   only when the request covers closing issues; otherwise list the issues as a
+   proposal. Leave an issue open when the release only partly delivered it.
+
 ## Verify before handing over
 
 1. Reconcile every version, affected range, capability and API against the

package/package/corpus/skills/cratis-release-notes/verification.json

@@ -6,6 +6,9 @@
     { "kind": "skill-contains", "value": "Exact-version release note" },
     { "kind": "skill-contains", "value": "old behavior → new" },
     { "kind": "skill-contains", "value": "migration from optional cleanup" },
-    { "kind": "skill-contains", "value": "drafting never authorizes publishing" }
+    { "kind": "skill-contains", "value": "drafting never authorizes publishing" },
+    { "kind": "skill-contains", "value": "`(part of #n)`" },
+    { "kind": "skill-contains", "value": "gh release edit TAG --notes-file" },
+    { "kind": "skill-contains", "value": "does not re-run release-action" }
   ]
 }

package/package/corpus/skills/cratis-specifications-csharp/SKILL.md

@@ -2,8 +2,8 @@
 name: cratis-specifications-csharp
 description: Write C# specifications with Cratis.Specifications using the Establish/Because/should_ pattern and the for_/when_/and_ folder hierarchy. Use when adding or restructuring C# specs in any Cratis repository, choosing between an isolated unit spec and an in-process scenario spec, or building reusable given/ contexts. Do not use for TypeScript or React specs, and do not use it to decide what a command, projection, or reactor should do.
 license: MIT
-cratis-hint-paths:
-  - "**/for_*/**/*.cs"
+metadata:
+  cratis-hint-paths: "**/for_*/**/*.cs"
 ---
 
 # Cratis C# specifications

package/package/corpus/skills/cratis-specifications-typescript/SKILL.md

@@ -2,9 +2,8 @@
 name: cratis-specifications-typescript
 description: Write TypeScript specifications in the Cratis BDD style using the given() helper, reusable context classes, Sinon stubbing, and the Chai .should fluent interface. Use when adding or restructuring TypeScript specifications, building a given/ context class, or laying out a for_/when_ specification folder. Do not use for C# specifications, and do not use it to decide what the code under specification should do.
 license: MIT
-cratis-hint-paths:
-  - "**/for_*/**/*.ts"
-  - "**/for_*/**/*.tsx"
+metadata:
+  cratis-hint-paths: "**/for_*/**/*.ts **/for_*/**/*.tsx"
 ---
 
 # Cratis TypeScript specifications

package/package/corpus/skills/cratis-technical-examples/SKILL.md

@@ -2,8 +2,8 @@
 name: cratis-technical-examples
 description: Design and verify developer-facing code samples, tutorial projects, and documentation snippets against real Cratis APIs. Use when adding or reviewing a runnable example, multi-client snippet, sample app, command/output pair, or migration before/after code. Do not invent API shapes or treat rendering as a compilation check.
 license: MIT
-cratis-hint-paths:
-  - "**/Samples/**/*.{cs,ts,tsx}"
+metadata:
+  cratis-hint-paths: "**/Samples/**/*.{cs,ts,tsx}"
 ---
 
 # Technical examples readers can trust

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.2.0",
+  "version": "7.2.2",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [