@cratis/pi 7.1.5 → 7.2.1

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,6 +2,9 @@
 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"
 ---
 
 # Cratis application React specifications

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

@@ -2,6 +2,9 @@
 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"
 ---
 
 # Cratis application slice specifications

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

@@ -2,6 +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}"
 ---
 
 # Documentation writing
@@ -134,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,6 +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}"
 ---
 
 # 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,6 +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"
 ---
 
 # Cratis C# specifications

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

@@ -2,6 +2,9 @@
 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"
 ---
 
 # Cratis TypeScript specifications

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

@@ -2,6 +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}"
 ---
 
 # Technical examples readers can trust

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.1.5",
+  "version": "7.2.1",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [
@@ -41,6 +41,7 @@
       "./src/index.ts",
       "./package/corpus/harnesses/pi/extensions/cratis-hooks/index.ts",
       "./package/corpus/harnesses/pi/extensions/cratis-mcp/index.ts",
+      "./package/corpus/harnesses/pi/extensions/cratis-path-guidance/index.ts",
       "./package/corpus/harnesses/pi/extensions/subagent/index.ts"
     ]
   }

package/src/index.ts

@@ -88,6 +88,16 @@ function ruleMatchesConfiguration(path: string, content: string, configuration:
         (needsDocumentation && selectedProfiles.includes('cratis/documentation'));
 }
 
+/**
+ * A rule scoped by `applyTo` to particular files is delivered by the packaged `cratis-path-guidance`
+ * extension when such a file is touched, so it stays out of the system prompt. Only rules that apply to
+ * every file, or declare no scope, belong there.
+ */
+function isUniversalRule(content: string): boolean {
+    const applyTo = (frontmatterValue(content, 'applyTo') ?? '').split(',').map(glob => glob.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+    return applyTo.length === 0 || applyTo.some(glob => ['**', '**/*', '*'].includes(glob));
+}
+
 function rules(cwd: string): string {
     const root = join(corpusRoot, 'rules');
     const configurationPath = join(cwd, '.cratis', 'ai.json');
@@ -99,6 +109,7 @@ function rules(cwd: string): string {
         .sort()
         .map(entry => ({ path: join(root, entry), content: readFileSync(join(root, entry), 'utf8') }))
         .filter(rule => !configuration || ruleMatchesConfiguration(rule.path, rule.content, configuration))
+        .filter(rule => isUniversalRule(rule.content))
         .map(rule => rule.content)
         .join('\n\n');
 }