@cratis/pi 2.0.8 → 2.0.10

package/package/corpus/hooks/README.md

@@ -62,6 +62,23 @@ The two `within_type_attribute` patterns are not line greps — the scanner trac
 blocks and type scope (positional record, multi-line declaration, or braced body), so a nullable
 property is only reported when it really sits inside an `[EventType]`.
 
+### Project-specific gate configuration
+
+The shipped gates discover the repository's own solution and package, so most repositories need no
+configuration at all. A repository whose project is not where discovery lands — several packages, a
+frontend under `Source/<App>` — states only what differs in its own
+`.cratis/ai/quality-gates.project.json`, which the gate merges over the managed file by gate id:
+
+```json
+{ "gates": [ { "id": "frontend-lint", "workingDirectory": "Source/App" } ] }
+```
+
+That file is project-owned and outside the managed manifest. **Do not put project facts into
+`scripts/quality-gates.json`**: it is Cratis-managed, so the next managed update either reports it as
+drift or replaces it, and the repository silently loses its own configuration. An override naming a
+gate that does not exist is reported on stderr rather than ignored, and an unreadable override leaves
+the managed gates running unchanged.
+
 **Gated** (`Stop`, exit 2): the app-pinned commands from the Quality Gates table in
 `general.md` and the steps in [`agent-stop.md`](./agent-stop.md) — Debug build, specs, Release
 build (with `-p:CratisProxiesOutputPath=` per `general.md`, so the proxy generator does not
@@ -304,7 +321,7 @@ Each is an explicit, auditable opt-out — none of them is a default.
 | `CRATIS_HOOKS_SKIP_GATE=1` | disables the quality gate |
 | `CRATIS_HOOKS_GATE_DRYRUN=1` | prints which gates would run, and why, then exits 0 |
 | `CRATIS_HOOKS_PATTERNS=<path>` | replaces the pattern file |
-| `CRATIS_HOOKS_GATES=<path>` | replaces the gate file |
+| `CRATIS_HOOKS_GATES=<path>` | replaces the gate file (the project override still merges over it) |
 | `CRATIS_HOOKS_SUBPATH_REPORT=1` | prints every `@cratis/*` subpath reference and how it resolved, not only the failures |
 | `CRATIS_HOOKS_IMPORT_REPORT=1` | prints every `@cratis/*` named import binding and how it resolved, not only the failures |
 | `CRATIS_HOOKS_TYPE_REPORT=1` | prints every .NET type/attribute name the corpus mentions and how it resolved, not only the failures |

package/package/corpus/hooks/scripts/cratis-quality-gate.sh

@@ -40,6 +40,41 @@ jq -e . "$config" >/dev/null 2>&1 || {
     printf 'cratis-quality-gate: %s is not valid JSON — gate skipped.\n' "$config" >&2
     exit 0
 }
+
+# ── Project-owned overrides ──────────────────────────────────────────────────
+# Where a repository's own answer to "which directory does this gate build in" lives. It is
+# outside the managed tree on purpose: a repository that instead edits the managed
+# quality-gates.json mixes project facts into Cratis-owned content, so the next managed update
+# either reports drift or silently discards the repository's own configuration. The override
+# states only what differs, keyed by gate id, and nothing here needs a script fork.
+overrides="$root/.cratis/ai/quality-gates.project.json"
+if [ -f "$overrides" ]; then
+    if jq -e . "$overrides" >/dev/null 2>&1; then
+        merged="$(mktemp "${TMPDIR:-/tmp}/cratis-quality-gates.XXXXXX")"
+        if jq -s '
+            .[0] as $base | .[1] as $over
+            | ($over.gates // []) as $gates
+            | $base
+            + ($over | del(.gates))
+            + { gates: [ $base.gates[] as $gate
+                | ($gates | map(select(.id == $gate.id)) | first) as $patch
+                | if $patch == null then $gate else $gate + ($patch | del(.id)) end ] }
+        ' "$config" "$overrides" >"$merged" 2>/dev/null; then
+            unknown="$(jq -r --slurpfile base "$config" '[.gates // [] | .[].id] - [$base[0].gates[].id] | .[]' "$overrides" 2>/dev/null || true)"
+            [ -n "$unknown" ] && printf 'cratis-quality-gate: %s overrides unknown gate(s): %s\n' \
+                "${overrides#"$root"/}" "$(printf '%s' "$unknown" | tr '\n' ' ')" >&2
+            config="$merged"
+        else
+            rm -f "$merged"
+            printf 'cratis-quality-gate: %s could not be merged — managed gates used unchanged.\n' \
+                "${overrides#"$root"/}" >&2
+        fi
+    else
+        printf 'cratis-quality-gate: %s is not valid JSON — managed gates used unchanged.\n' \
+            "${overrides#"$root"/}" >&2
+    fi
+fi
+
 [ "$(jq -r '.enabled // true' "$config")" = "true" ] || exit 0
 
 # ── What changed in the working tree ─────────────────────────────────────────

package/package/corpus/hooks/scripts/hook-lib.sh

@@ -9,13 +9,18 @@ set -euo pipefail
 # ── Environment ───────────────────────────────────────────────────────────────
 
 # Root of the repository the hook is running for.
+#
+# The fallback walks up from this script, which is installed at
+# <root>/.cratis/ai/hooks/scripts/hook-lib.sh - four levels, not three. Three landed on
+# <root>/.cratis, so without CLAUDE_PROJECT_DIR every hook read a repository whose git
+# directory, tracked files and project files were all missing, and silently did nothing.
 hook_repo_root() {
     local d="${CLAUDE_PROJECT_DIR:-}"
     if [ -n "$d" ] && [ -d "$d" ]; then
         (cd "$d" && pwd)
         return 0
     fi
-    (cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)
+    (cd "$(dirname "${BASH_SOURCE[0]}")/../../../.." && pwd)
 }
 
 # True when the named command is on PATH.

package/package/corpus/hooks/scripts/quality-gates.json

@@ -29,9 +29,14 @@
     "an application repository, a framework repository, and (as nothing to run) in a corpus-only",
     "repository such as this one, which carries no .NET or Node project at all.",
     "",
-    "The override model, in order of increasing force: a repository sets workingDirectory to pin",
-    "one of several candidate projects; or it drops its own quality-gates.json in place of this",
-    "file; or it points CRATIS_HOOKS_GATES at a file anywhere. None of them requires a script fork.",
+    "The override model, in order of increasing force: a repository states only what differs in its",
+    "own .cratis/ai/quality-gates.project.json, which the runner merges over this file by gate id",
+    "(a project fact belongs there, never edited into this managed file, or the next managed update",
+    "reports drift or discards it); or it points CRATIS_HOOKS_GATES at a file anywhere. Neither",
+    "requires a script fork.",
+    "",
+    "Example .cratis/ai/quality-gates.project.json, for a repository whose frontend is not at the root:",
+    "  { \"gates\": [ { \"id\": \"frontend-lint\", \"workingDirectory\": \"Source/App\" } ] }",
     "",
     "Commands are pinned to .cratis/ai/rules/general.md 'Quality Gates' and .cratis/ai/hooks/agent-stop.md.",
     "Note the Release build passes -p:CratisProxiesOutputPath= per general.md so the proxy",

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

@@ -6,6 +6,8 @@ applyTo: "**/*"
 
 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 — 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.
+
 ## Description
 
 - Follow the repository's pull request template (`.github/pull_request_template.md`).

package/package.json

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