sisyphi 1.2.17 → 1.2.19

package/templates/orchestrator-plugin/hooks/goal-length-guard.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# PostToolUse(Write|Edit|MultiEdit) hook for the orchestrator: enforce the
+# 100-line cap on goal.md. The edit has already landed (PostToolUse runs after
+# success); if goal.md is now over the cap, emit a decision:block so the
+# orchestrator must trim it and move the detail into context/scope-*.md before
+# proceeding. Under the cap → silent passthrough.
+
+if [ -z "$SISYPHUS_SESSION_ID" ] || [ -z "$SISYPHUS_SESSION_DIR" ]; then exit 0; fi
+
+STDIN_JSON=$(cat)
+
+FP=$(printf '%s' "$STDIN_JSON" | python3 -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    print((d.get('tool_input') or {}).get('file_path') or '')
+except Exception:
+    pass
+" 2>/dev/null)
+
+[ -z "$FP" ] && exit 0
+
+GOAL_FILE="$SISYPHUS_SESSION_DIR/goal.md"
+
+SAME=$(python3 -c "
+import os, sys
+try:
+    print('1' if os.path.realpath(sys.argv[1]) == os.path.realpath(sys.argv[2]) else '0')
+except Exception:
+    print('0')
+" "$FP" "$GOAL_FILE" 2>/dev/null)
+
+[ "$SAME" = "1" ] || exit 0
+[ -f "$GOAL_FILE" ] || exit 0
+
+LINES=$(python3 -c "
+import sys
+try:
+    with open(sys.argv[1], encoding='utf-8') as f:
+        print(sum(1 for _ in f))
+except Exception:
+    print(0)
+" "$GOAL_FILE" 2>/dev/null)
+
+[ -z "$LINES" ] && exit 0
+if [ "$LINES" -le 100 ]; then exit 0; fi
+
+REASON=$(cat <<TXT
+goal.md is now ${LINES} lines — over the 100-line cap. Trim it back to the north-star paragraph plus a "## Scope" reference list before continuing.
+
+Move the detail you just added into context/scope-<topic>.md (the maintained home for one slice of the goal) and leave only a one-line pointer in goal.md:
+  - context/scope-<topic>.md — one-line description
+
+Why the cap: goal.md is inlined into every orchestrator wakeup, so length here taxes every future cycle, even ones working far from this detail. Scope files are read on demand and can be referenced from strategy.md / roadmap.md. Restructure the over-cap detail into scope files rather than deleting still-relevant scope to fit.
+TXT
+)
+
+ESCAPED=$(printf '%s' "$REASON" | python3 -c "import json,sys; print(json.dumps(sys.stdin.read()))")
+echo "{\"decision\":\"block\",\"reason\":$ESCAPED,\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUse\"}}"
+exit 0

package/templates/orchestrator-plugin/hooks/goal-read-advisory.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# PostToolUse(Read) hook for the orchestrator: when the orchestrator reads
+# goal.md, surface the scope-file convention. goal.md is inlined into every
+# wakeup, so the orchestrator only Reads it when it intends to edit — that's
+# the moment to remind it to push concrete detail into context/scope-*.md
+# rather than into the goal. Neutral guidance (additionalContext), not a block.
+
+if [ -z "$SISYPHUS_SESSION_ID" ] || [ -z "$SISYPHUS_SESSION_DIR" ]; then exit 0; fi
+
+STDIN_JSON=$(cat)
+
+FP=$(printf '%s' "$STDIN_JSON" | python3 -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    print((d.get('tool_input') or {}).get('file_path') or '')
+except Exception:
+    pass
+" 2>/dev/null)
+
+[ -z "$FP" ] && exit 0
+
+GOAL_FILE="$SISYPHUS_SESSION_DIR/goal.md"
+
+# Only fire for the session's own goal.md (compare resolved paths).
+SAME=$(python3 -c "
+import os, sys
+try:
+    print('1' if os.path.realpath(sys.argv[1]) == os.path.realpath(sys.argv[2]) else '0')
+except Exception:
+    print('0')
+" "$FP" "$GOAL_FILE" 2>/dev/null)
+
+[ "$SAME" = "1" ] || exit 0
+
+ADVISORY=$(cat <<'TXT'
+Editing goal.md? Keep it to the north-star paragraph plus a `## Scope` list of references — nothing more. Put any concrete detail about one slice of the goal (a subsystem, a workstream, a newly-authorized expansion) in `context/scope-<topic>.md`, and link it from goal.md with a one-liner:
+  - context/scope-backend.md — DB + API-layer refactors for X
+  - context/scope-frontend.md — render-path cleanup for X
+
+Why: goal.md is inlined into every orchestrator wakeup and capped at 100 lines, so per-slice detail here taxes every future cycle — even ones working far from that slice. Routing detail into scope files lets scope grow without rewriting the goal: a mid-session "let's also do the microservices" becomes a new scope file linked from goal.md, never a condensed or deleted goal. Maintain scope files like other context docs (current understanding, not history); they are read on demand, and strategy.md/roadmap.md point at whichever scope a stage is focused on.
+TXT
+)
+
+printf '%s' "$ADVISORY" | python3 -c "
+import json, sys
+print(json.dumps({
+  'hookSpecificOutput': {
+    'hookEventName': 'PostToolUse',
+    'additionalContext': sys.stdin.read(),
+  }
+}))
+"
+exit 0

package/templates/orchestrator-plugin/hooks/hooks.json

@@ -9,6 +9,26 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/goal-read-advisory.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/goal-length-guard.sh"
+          }
+        ]
+      }
     ]
   }
 }

package/templates/orchestrator-validation.md

@@ -53,6 +53,16 @@ Every claim in a validation report must have evidence behind it. The validation
 
 If a validation agent reports without evidence, their report is incomplete. Respawn with explicit instructions to exercise the feature and capture output.
 
+### Shallow checks are not proof
+
+Exit criteria and recipe steps can pass without exercising how the code actually runs in production. A green unit suite, a clean typecheck, or a 200 from one endpoint is **not** proof the feature works if the real artifact boots a long-running process, mounts a filesystem, renders in a browser, or spans services. Match validation depth to the runtime:
+
+- **Long-running process** (NestJS, a daemon, Electron): boot the actual process and exercise it. Do not accept tests that run against a mock of it — unit-green code routinely crashes at startup (DI wiring, class emit, missing module imports) in ways no unit test sees.
+- **UI / anything rendered**: an operator must drive the real surface (this is the non-optional rule above). A passing component test is not a rendered page.
+- **Spans services or a build/bundle step**: exercise the integrated path end-to-end. Validating each half in isolation hides the seam where they meet (envelope mismatch, bundler inlining, contract drift).
+
+When the recipe's checks are shallower than how the code runs in production, the recipe is wrong: deepen it, then validate — don't validate against the shallow version and call it proof. The test: *can this check fail the way production fails?* If not, it proves nothing. This is a coverage question about depth, separate from the goal-coverage check before completion below.
+
 ## Running Validation
 
 Spawn validation agents with clear, specific instructions: