sisyphi 1.2.18 → 1.2.19

package/dist/templates/agent-plugin/agents/review/CLAUDE.md

@@ -1,3 +1,2 @@
-- **`reuse` dismissed entries cite `existing-file:line`** (the existing utility evaluated), not `file:line` (the new code) — the validation wave parses reuse dismissals differently from all other sub-agents.
 - **No output ≠ clean**: a sub-agent that produces no output is treated as failed. The explicit clean sentence ("No X concerns — ...") is the signal the validation wave uses to skip spawning a validator.
 - **Adding a sub-agent**: create `{name}.md` with frontmatter, add `subagent_type: {name}` to the scaling table in `review.md` step 4, and update the scaling guidance table if conditionally spawned — without the registration, the sub-agent is silently never spawned.

package/dist/templates/agent-suffix.md

@@ -14,9 +14,17 @@ You are an agent in a sisyphus session.
 
 If you're blocked by ambiguity, contradictions, or unclear requirements — **don't guess**. Submit what you found instead. A clear report is more valuable than a wrong implementation.
 
+## The sis CLI
+
+You operate inside a sisyphus session driven by the `sis` CLI. Run `sis <group> -h` to drill into any command.
+
+{{HELP:.}}
+
 ## The User
 
-A human may interact with you directly in your pane — if they do, prioritize their input over your original instruction. Otherwise, communicate through the orchestrator via reports. 
+A human may interact with you directly in your pane — if they do, prioritize their input over your original instruction. Otherwise, communicate through the orchestrator via reports.
+
+**If the user complains about sisyphus itself** — a crash, a CLI that misbehaved, a confusing or broken workflow, behavior they disliked — file it with `sis feedback "<summary>"` (run `sis feedback -h`). Low-cost side-action; do it without asking. It's for the tool, not your task. 
 
 ## Context
 

package/dist/templates/orchestrator-base.md

@@ -101,6 +101,16 @@ goal.md is a plain statement of what "done" looks like — scope boundaries and
 **What belongs in goal.md:** the desired end state, what's in scope, what's out of scope.
 **What doesn't:** approach decisions, technical choices, stage plans — those belong in strategy.md and context docs.
 
+**Scope files keep goal.md lean.** goal.md is inlined into every wakeup and capped at 100 lines, so concrete detail about one slice of the goal does not belong inline — it taxes every cycle, including ones abstracted far away from that slice. When a part of the goal needs maintained detail (a subsystem, a workstream, a newly-authorized expansion), write `context/scope-<topic>.md` for it and add a one-line pointer under a `## Scope` list in goal.md:
+
+```
+## Scope
+- context/scope-backend.md — DB + API-layer refactors for X
+- context/scope-frontend.md — render-path cleanup for X
+```
+
+This is how scope *grows* 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. Scope files are maintained like other context docs (current understanding, not history) and read on demand; strategy.md and roadmap.md point at the scope file a stage is focused on rather than restating it. A hook rejects any goal.md edit that leaves the file over 100 lines and tells you to offload into scope files.
+
 ### strategy.md — Your problem-solving map
 
 strategy.md defines **how to approach this problem** — the stages, gates, backtrack edges, and behavioral style for this session. It is generated during discovery and progressively updated as the goal crystallizes or shifts.
@@ -225,6 +235,7 @@ Context dir contents are listed in your prompt each cycle. Read files when you n
 - Roadmap items should **reference** context files: `"See context/{plan-lead-agent-id}/plan-stage-1-auth.md for detail."` Copy the path from the plan lead's submission report; don't reconstruct it.
 - Agents writing requirements and designs save to the context dir with descriptive filenames: `requirements-auth.md`, `design-auth.md`. Plan agents save plans under their own subdirectory `context/{agent-id}/plan-*.md`; treat those paths as authoritative from the plan lead's report.
 - **Implementation plans belong here**, not in roadmap.md
+- **Scope files** (`context/scope-<topic>.md`) hold maintained detail for one slice of the goal, linked from goal.md's `## Scope` list — see the goal.md section. You write and maintain them directly, like strategy.md.
 
 ### Session Directory
 
@@ -284,6 +295,8 @@ You have unlimited cycles. Failed implementations, deferred issues, and skipped
 
 ## CLI Reference
 
+{{HELP:.}}
+
 {{HELP:session clone}}
 
 ## File Conflicts

package/dist/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/dist/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/dist/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sisyphi",
-  "version": "1.2.18",
+  "version": "1.2.19",
   "description": "tmux-integrated orchestration daemon for Claude Code multi-agent workflows",
   "license": "MIT",
   "repository": {

package/templates/agent-plugin/agents/review/CLAUDE.md

@@ -1,3 +1,2 @@
-- **`reuse` dismissed entries cite `existing-file:line`** (the existing utility evaluated), not `file:line` (the new code) — the validation wave parses reuse dismissals differently from all other sub-agents.
 - **No output ≠ clean**: a sub-agent that produces no output is treated as failed. The explicit clean sentence ("No X concerns — ...") is the signal the validation wave uses to skip spawning a validator.
 - **Adding a sub-agent**: create `{name}.md` with frontmatter, add `subagent_type: {name}` to the scaling table in `review.md` step 4, and update the scaling guidance table if conditionally spawned — without the registration, the sub-agent is silently never spawned.

package/templates/agent-suffix.md

@@ -14,9 +14,17 @@ You are an agent in a sisyphus session.
 
 If you're blocked by ambiguity, contradictions, or unclear requirements — **don't guess**. Submit what you found instead. A clear report is more valuable than a wrong implementation.
 
+## The sis CLI
+
+You operate inside a sisyphus session driven by the `sis` CLI. Run `sis <group> -h` to drill into any command.
+
+{{HELP:.}}
+
 ## The User
 
-A human may interact with you directly in your pane — if they do, prioritize their input over your original instruction. Otherwise, communicate through the orchestrator via reports. 
+A human may interact with you directly in your pane — if they do, prioritize their input over your original instruction. Otherwise, communicate through the orchestrator via reports.
+
+**If the user complains about sisyphus itself** — a crash, a CLI that misbehaved, a confusing or broken workflow, behavior they disliked — file it with `sis feedback "<summary>"` (run `sis feedback -h`). Low-cost side-action; do it without asking. It's for the tool, not your task. 
 
 ## Context
 

package/templates/orchestrator-base.md

@@ -101,6 +101,16 @@ goal.md is a plain statement of what "done" looks like — scope boundaries and
 **What belongs in goal.md:** the desired end state, what's in scope, what's out of scope.
 **What doesn't:** approach decisions, technical choices, stage plans — those belong in strategy.md and context docs.
 
+**Scope files keep goal.md lean.** goal.md is inlined into every wakeup and capped at 100 lines, so concrete detail about one slice of the goal does not belong inline — it taxes every cycle, including ones abstracted far away from that slice. When a part of the goal needs maintained detail (a subsystem, a workstream, a newly-authorized expansion), write `context/scope-<topic>.md` for it and add a one-line pointer under a `## Scope` list in goal.md:
+
+```
+## Scope
+- context/scope-backend.md — DB + API-layer refactors for X
+- context/scope-frontend.md — render-path cleanup for X
+```
+
+This is how scope *grows* 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. Scope files are maintained like other context docs (current understanding, not history) and read on demand; strategy.md and roadmap.md point at the scope file a stage is focused on rather than restating it. A hook rejects any goal.md edit that leaves the file over 100 lines and tells you to offload into scope files.
+
 ### strategy.md — Your problem-solving map
 
 strategy.md defines **how to approach this problem** — the stages, gates, backtrack edges, and behavioral style for this session. It is generated during discovery and progressively updated as the goal crystallizes or shifts.
@@ -225,6 +235,7 @@ Context dir contents are listed in your prompt each cycle. Read files when you n
 - Roadmap items should **reference** context files: `"See context/{plan-lead-agent-id}/plan-stage-1-auth.md for detail."` Copy the path from the plan lead's submission report; don't reconstruct it.
 - Agents writing requirements and designs save to the context dir with descriptive filenames: `requirements-auth.md`, `design-auth.md`. Plan agents save plans under their own subdirectory `context/{agent-id}/plan-*.md`; treat those paths as authoritative from the plan lead's report.
 - **Implementation plans belong here**, not in roadmap.md
+- **Scope files** (`context/scope-<topic>.md`) hold maintained detail for one slice of the goal, linked from goal.md's `## Scope` list — see the goal.md section. You write and maintain them directly, like strategy.md.
 
 ### Session Directory
 
@@ -284,6 +295,8 @@ You have unlimited cycles. Failed implementations, deferred issues, and skipped
 
 ## CLI Reference
 
+{{HELP:.}}
+
 {{HELP:session clone}}
 
 ## File Conflicts

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"
+          }
+        ]
+      }
     ]
   }
 }