@cratis/pi 7.73.1 → 7.75.0

package/package/corpus/harnesses/pi/extensions/cratis-hooks/index.ts

@@ -332,7 +332,10 @@ export default function (pi: ExtensionAPI) {
 		label: "Cratis quality gate",
 		description:
 			"Run the Cratis quality gate (.cratis/ai/hooks/scripts/cratis-quality-gate.sh): the build, spec and lint gates the current " +
-			"working-tree changes touch, configured in quality-gates.json. Runs in the foreground with a deadline and can be cancelled. " +
+			"working-tree changes touch. Shipped defaults: .cratis/ai/hooks/scripts/quality-gates.json; project overrides: " +
+			".cratis/ai/quality-gates.project.json, shallow-merged by gate id (command without requires drops inherited packageScripts). " +
+			"CRATIS_HOOKS_GATES replaces the defaults; project overrides still merge over it. " +
+			"Runs in the foreground with a whole-tool deadline and optional per-gate timeoutSeconds; can be cancelled. " +
 			"A failure, a timeout or a cancellation is returned as an error and means the change is NOT verified. " +
 			"Run it explicitly at a verification checkpoint, not after every prompt. It selects gates for all current " +
 			"working-tree changes, not the complete CI matrix; run CI-equivalent gates before claiming completion or pushing/opening a PR. " +
@@ -378,7 +381,7 @@ export default function (pi: ExtensionAPI) {
 				const last = latestGateLog(gateLogDirectory(sessionId), started);
 				const tail = last ? tailLines(last.file, TAIL_LINES) : "";
 				throw new Error(`The Cratis quality gate TIMED OUT after ${duration(timeoutSeconds * 1000)}${last ? ` while running '${last.gate}'${last.cwd ? ` (cwd: ${last.cwd})` : ""}` : ""}. This is not a pass: nothing was verified.` +
-					(last ? `\n\nGate log: ${last.file}` : "") +
+					(last ? `\nRun a narrower command instead: ${last.gate === "backend-specs" ? "dotnet test <affected.Specs.csproj-or-Tests.csproj> --configuration Debug --no-build (replace the placeholder; repeat for affected dependents)." : "run the affected project alone using this gate's configured command."}\nConfigure it in .cratis/ai/quality-gates.project.json.\n\nGate log: ${last.file}` : "") +
 					(tail ? `\n\n--- last ${TAIL_LINES} lines ---\n${tail}\n--- end ---` : ""));
 			};
 			const reportInterrupted = () => {

package/package/corpus/hooks/README.md

@@ -277,6 +277,9 @@ their explicit consent. Slice-only scope checks do not replace the repository's
 
 ### Project-specific gate configuration
 
+Shipped defaults live in `.cratis/ai/hooks/scripts/quality-gates.json`, not `.cratis/ai/quality-gates.json`.
+Project overrides live in `.cratis/ai/quality-gates.project.json`. `CRATIS_HOOKS_GATES=<path>` replaces
+the defaults file; the project overrides still merge over that replacement by gate id.
 The shipped gates discover the repository's own solution and package, so most repositories need no
 configuration at all. An eligible root workspace or solution keeps repository-wide dispatch. Without
 one, discovery uses only each gate's matching, non-excluded changes and runs it once per affected
@@ -547,9 +550,30 @@ inapplicable gate remains a no-op. Pi preserves the script's diagnostics when pl
 The same shipped file therefore activates in application and framework repositories, and reports
 an empty plan without running gates in a repository that has no project at all.
 
-**Overriding it, in order of increasing force.** Set `workingDirectory` on a gate to pin one of
-several candidate projects; drop a `quality-gates.json` of your own in place of the shipped one; or
-point `CRATIS_HOOKS_GATES` at a file anywhere. None of them requires forking the script.
+**Overriding it.** Set `workingDirectory` on a gate in `.cratis/ai/quality-gates.project.json` to pin
+one of several candidate projects. For a replacement defaults file, point `CRATIS_HOOKS_GATES` at a
+file anywhere instead of editing the managed file. Neither requires forking the script.
+A missing defaults file reports both real configuration paths and runs no gates.
+
+**Per-gate deadlines.** `timeoutSeconds` is an optional integer from 1 to 86400, applied separately
+to each command/directory. Unset means no per-gate deadline; Pi's whole-tool deadline still applies
+and may expire first. The shipped `backend-specs` gate allows 120 seconds so a long solution-wide
+spec run stops with a named diagnostic rather than consuming the entire tool budget. On timeout,
+the script stops the command's process group (TERM, then KILL after one second), exits **2**, and
+reports **NOT VERIFIED**, the gate, its directory, log tail, and `timeoutHint` (advice, never executed).
+Commands that create separate sessions/process groups can escape this cleanup; this is not a sandbox.
+
+For a large solution, replace the placeholder below with the affected test project and repeat for
+its affected dependents. Override `command` with that narrower argv array (or a repository-owned
+runner covering all affected projects), rather than raising the timeout without diagnosing the delay:
+
+```json
+{ "gates": [{ "id": "backend-specs", "command": ["dotnet", "test", "<affected.Specs.csproj>", "--configuration", "Debug", "--no-build"], "timeoutSeconds": 120, "timeoutHint": "Run dotnet test for each affected Specs/Tests project separately." }] }
+```
+
+This is not automatic affected-project selection: imported/conditional MSBuild references and
+linked or shared sources require evaluation to establish coverage safely. The default retains
+solution-wide tests rather than silently missing dependents, and a timeout is never a pass.
 
 **Profile note.** The C# patterns are application-profile and scoped to `Source/**/*.cs`, which is
 the application source root [`../rules/general.md`](../rules/general.md) documents. A

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

@@ -35,7 +35,10 @@ here="$(cd -P "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
 config="${CRATIS_HOOKS_GATES:-$here/quality-gates.json}"
 dryrun="${CRATIS_HOOKS_GATE_DRYRUN:-0}"
 
-[ -f "$config" ] || exit 0
+[ -f "$config" ] || {
+    printf 'cratis-quality-gate: configuration not found: %s — no gates ran. Shipped defaults: .cratis/ai/hooks/scripts/quality-gates.json; project overrides: .cratis/ai/quality-gates.project.json (merged by gate id). CRATIS_HOOKS_GATES replaces the defaults.\n' "$config" >&2
+    exit 0
+}
 jq -e . "$config" >/dev/null 2>&1 || {
     printf 'cratis-quality-gate: %s is not valid JSON — gate skipped.\n' "$config" >&2
     exit 0
@@ -265,7 +268,8 @@ discover_workdirs() {
 
 gate_count="$(jq -r '.gates | length' "$config")"
 [ "${gate_count:-0}" -gt 0 ] || exit 0
-fail_fast="$(jq -r '.failFast // true' "$config")"
+# jq's // treats false as absent; failFast=false must keep running after a failed gate.
+fail_fast="$(jq -r '.failFast | if . == null then true else . end' "$config")"
 max_lines="$(jq -r '.maxOutputLines // 60' "$config")"
 
 tmp_root="$(hook_state_dir "$(hook_json "$input" '.session_id')")" || tmp_root="${TMPDIR:-/tmp}"
@@ -335,6 +339,46 @@ EOF
     return 0
 }
 
+# Bash job control gives the command and watchdog separate process groups without GNU timeout
+# or a language runtime. Keep the supervisor in the caller's group so Pi cancellation reaches
+# its trap too. Wait for escalation even if the command leader exits on TERM: its test hosts
+# may still be running. Only configured gates use this wrapper; other gates remain unchanged.
+run_timed_gate() (
+    set -m
+    local worker timer rc=0 marker="$log.timeout"
+    rm -f "$marker"
+    stop_group() {
+        kill -TERM -- "-$1" 2>/dev/null || return 0
+        sleep 1
+        kill -KILL -- "-$1" 2>/dev/null || true
+    }
+    cleanup() {
+        trap '' TERM INT
+        kill -TERM -- "-$timer" 2>/dev/null || true
+        stop_group "$worker"
+        wait "$timer" 2>/dev/null || true
+        wait "$worker" 2>/dev/null || true
+    }
+    (cd -P "$root/$wd" && exec "${cmd[@]}") </dev/null &
+    worker=$!
+    (
+        sleep "$gate_timeout"
+        printf 'timed out\n' >"$marker"
+        stop_group "$worker"
+    ) &
+    timer=$!
+    trap 'cleanup; exit 2' TERM INT
+    wait "$worker" || rc=$?
+    if [ -f "$marker" ]; then
+        wait "$timer" || true
+        rc=124
+    else
+        cleanup
+    fi
+    trap - TERM INT
+    exit "$rc"
+)
+
 idx=0
 ran=0
 planned_gates=0
@@ -383,6 +427,15 @@ while [ "$idx" -lt "$gate_count" ]; do
 $(jq -r --argjson i "$idx" '.gates[$i].command // [] | .[]' "$config")
 EOF
 
+    gate_timeout="$(jq -r --argjson i "$idx" 'if .gates[$i].timeoutSeconds == null then "" else .gates[$i].timeoutSeconds end' "$config")"
+    timeout_hint="$(jq -r --argjson i "$idx" '.gates[$i].timeoutHint // empty' "$config")"
+    if ! jq -e --argjson i "$idx" '
+        .gates[$i].timeoutSeconds | . == null or (type == "number" and . >= 1 and . <= 86400 and floor == .)
+    ' "$config" >/dev/null; then
+        printf 'cratis-quality-gate: UNVERIFIED %s — timeoutSeconds must be an integer from 1 to 86400.\n' "$id" >&2
+        exit 2
+    fi
+
     project_index=0
     gate_ran=0
     gate_noops=0
@@ -424,13 +477,23 @@ EOF
         rc=0
         {
             printf 'cratis-quality-gate: LOG %s (cwd: %s)\n' "$id" "$wd"
-            (cd -P "$root/$wd" && "${cmd[@]}") </dev/null
+            if [ -n "$gate_timeout" ]; then
+                run_timed_gate
+            else
+                (cd -P "$root/$wd" && "${cmd[@]}") </dev/null
+            fi
         } >"$log" 2>&1 || rc=$?
         ran=$((ran + 1))
 
         if [ "$rc" -ne 0 ]; then
             {
-                printf 'QUALITY GATE FAILED: %s (exit %s)\n' "$id" "$rc"
+                if [ -n "$gate_timeout" ] && [ -f "$log.timeout" ]; then
+                    printf 'QUALITY GATE TIMED OUT: %s after %ss (cwd: %s) — NOT VERIFIED.\n' "$id" "$gate_timeout" "$wd"
+                    printf 'Run a narrower command instead: %s\n' "${timeout_hint:-run the affected project with the command below, not the whole workspace/solution.}"
+                    printf 'Configure command/workingDirectory/timeoutSeconds in .cratis/ai/quality-gates.project.json.\n'
+                else
+                    printf 'QUALITY GATE FAILED: %s (exit %s)\n' "$id" "$rc"
+                fi
                 printf '  %s\n' "$desc"
                 printf '  $ %s   (cwd: %s)\n\n' "${cmd[*]}" "$wd"
                 printf -- '--- last %s lines ---\n' "$max_lines"

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

@@ -1,7 +1,8 @@
 {
   "$comment": [
     "Quality gates run by the Stop hook (cratis-quality-gate.sh).",
-    "Data, not code: a consuming repository overrides this file (or points CRATIS_HOOKS_GATES at",
+    "Shipped defaults: .cratis/ai/hooks/scripts/quality-gates.json; project overrides: .cratis/ai/quality-gates.project.json.",
+    "Data, not code: a consuming repository patches gates by id (or points CRATIS_HOOKS_GATES at",
     "its own) without touching the script. Gates run in order and stop at the first failure.",
     "",
     "A gate runs only when the working tree contains a change matching one of its \"changed\" globs,",
@@ -41,6 +42,9 @@
     "                   Mixed RUN/NO-OP directories report UNVERIFIED and exit 2, not a partial success.",
     "                   Gate commands read /dev/null so they cannot consume remaining directories.",
     "  command          argv array \u2014 executed directly, never through a shell (no eval)",
+    "  timeoutSeconds   optional integer 1..86400; deadline per command/directory, plus 1s TERM-to-KILL cleanup",
+    "                   (Pi's whole-tool deadline still applies); timeout exits 2, never a pass",
+    "  timeoutHint      narrower command to run when the gate times out; diagnostic text, never executed",
     "",
     "Managed corpus and adapter trees (.cratis/**, .pi/**, .claude/**) never count as a relevant change:",
     "a corpus update must not run a repository's application gates over files that are not its application.",
@@ -114,6 +118,8 @@
     {
       "id": "backend-specs",
       "description": "dotnet test (Debug, --no-build) \u2014 zero failures",
+      "timeoutSeconds": 120,
+      "timeoutHint": "dotnet test <affected.Specs.csproj-or-Tests.csproj> --configuration Debug --no-build (replace the placeholder with the affected test project; repeat for its affected dependents)",
       "changed": [
         "**/*.cs",
         "**/*.csproj",

package/package/corpus/rules/general.md

@@ -95,6 +95,7 @@ A claim is only as good as the signal behind it — a build result, a test run,
 
 - **Confirm "done"/"fixed"/"correct" against a fresh signal — never self-assessment.** Run the relevant gate and observe it pass *this time*.
 - **Check at the right frequency.** Run affected-project checks while iterating; a prompt ending is not task completion. Before claiming a task complete or pushing/opening a PR, run the full CI-equivalent gates required for that repository (including its Tier 1/2 policy where applicable). A change-selected hook gate is not a substitute for the repository's full CI matrix. After a fix, re-run the gate that failed. Don't argue yourself to green.
+- **Gate configuration:** shipped defaults `.cratis/ai/hooks/scripts/quality-gates.json`; project overrides `.cratis/ai/quality-gates.project.json` shallow-merge by gate id (command without requires drops inherited packageScripts). `CRATIS_HOOKS_GATES` replaces defaults; project overrides still apply.
 - **A green build is not behavioral correctness.** Compilation proves it builds, not that the slice does the right thing — that's what specs and exercising the UI are for.
 - **Report the conclusion and what you didn't verify, in a line or two.** Show the output when asked, when a claim is contested, or when the check failed — see [verification-discipline.md](./verification-discipline.md).
 

package/package.json

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