@litfamily/litmuse 0.1.2 → 0.1.3

package/plugin/skills/lit-adhd/references/status-taxonomy.md

@@ -1,20 +1,22 @@
 # lit-adhd status taxonomy
 
 The collector assigns every session exactly one status. The brief renders it in the user's language
-with the words below and never invents a fifth.
+with the words below and never invents another.
 
 | Status | Set when | English | 한국어 |
 | --- | --- | --- | --- |
 | `waiting-on-user` | The last transcript entry is the assistant asking something (a closing `?`, `lit approve`, `확인해 주세요`, `할까요`…), or the session holds a paused workflow frame or a start-work boundary | waiting on you | 나를 기다림 |
 | `active` | A transcript write within the last 15 minutes and not waiting | active | 진행 중 |
-| `ended` | Quiet for longer than 15 minutes | ended | 끝남 |
+| `idle` | Another session, otherwise active, whose last hook event is a Stop no older than its last log line | idle | 쉬는 중 |
+| `done` | Another session, otherwise active, whose start-work plan was fully ticked after its last log line | done | 완료 |
+| `ended` | Quiet for longer than 15 minutes, or its last hook event was SessionEnd | ended | 끝남 |
 | `unknown` | The transcript held no timestamp | unknown | 모름 |
 
 `waitingReason` says why a session waits: `asked the user`, `paused workflow` or
 `start-work boundary`. Name it in the card's status cell when present: `waiting on you (paused
 workflow)` / `나를 기다림 (멈춘 워크플로)`.
 
-Order in the brief: waiting sessions first, then active ones as full cards, newest first inside each group; ended sessions collapse into one short row each after the cards.
+Order in the brief: waiting sessions first, then active, idle and done ones as full cards, newest first inside each group; ended sessions collapse into one short row each after the cards. A done card's next line names the plan its run finished (`start-work finished plans/a.md` / `plans/a.md start-work 완료`).
 
 ## Sources
 
@@ -29,7 +31,7 @@ line and never filled in from memory.
 | `handoffs` | `HANDOFF*.md` and `.litmuse/handoff/latest.md` headings |
 | `git` | `git log --since` |
 | `workflowStack` | `.litmuse/workflow-stack/*.json` |
-| `startWork` | the session's own stage record |
+| `startWork` | the stage records: this session's live run, any session's completed run |
 | `herdr` | `herdr agent list`, only with `HERDR_ENV=1` |
 
 ## Next-step kinds

package/plugin/skills/lit-plan/SKILL.md

@@ -169,6 +169,17 @@ Detail earns its place when it removes executor judgment, protects a boundary or
 8. The final verification wave.
 9. Commit strategy, success criteria, DoneClaim, risks and open questions.
 
+### Scope roots for outside folders
+
+When a todo names an absolute path outside the project (a shared notes folder, a sibling checkout, a temp area), the plan grants it before the work starts, with one line per folder anywhere outside a code fence:
+
+```text
+Scope roots: /abs/path/to/folder (read)
+Scope roots: /abs/path/to/scratch (read, write, execute)
+```
+
+Grant the narrowest existing folder and only the actions the todos need. Paths inside the project need no line. A command quoted in a fence or an inline code span (it holds a space) is data and needs no line; a code span that is one bare path counts. Before saving, search the Todos for `/` paths and add the missing lines. `start-work` runs `node scripts/check-plan.mjs --check plans/<slug>.md`, which fails on an uncovered folder and prints the exact line to add; a filesystem-root, top-level or home folder is never suggested, so name a narrower one.
+
 A task that builds or changes a user-facing web interface names `frontend-ui-ux` in its verification (the interface probe across the responsive matrix, with no HIGH finding left) and hands the acceptance verdict to `visual-qa`. A CLI, library or backend-only task names neither.
 
 ### Plan-row grammar (machine-checkable)
@@ -337,7 +348,7 @@ Refused on this route: `create_goal`, `update_goal`, `write_todos`, `add_memory`
 
 Stop when the plan file is written and passes the checklist, or when a missing answer blocks every useful task (then the plan carries the question as row 1 and the reply says `BLOCKED: <question>`). After two failed attempts at one section, surface what you tried and ask.
 
-Reply in reader form: the plan path, the TL;DR, the number of tasks, any assumption the user should confirm, and the next action: run `/start-work` (or `/litmuse:start-work`) to execute it. Approval covers plan generation; implementation, commit, push, versioning and publishing each need their own go-ahead. Keep logs, lane verdicts and command lists in the draft and ledger unless the user asks for them.
+Reply in reader form: the plan path, the TL;DR, the number of tasks, any assumption the user should confirm, and the next action. End the reply with this line, plan name filled in: "Type `go` within 30 minutes to start `plans/<slug>.md` with start-work, or run `/start-work` later." The Stop hook records the saved plan for this session only, so `go` from another session, or after 30 minutes, starts nothing. Approval covers plan generation; implementation, commit, push, versioning and publishing each need their own go-ahead. Keep logs, lane verdicts and command lists in the draft and ledger unless the user asks for them.
 
 ## Pitfalls
 

package/plugin/skills/lit-plan/scripts/check-plan.mjs

@@ -10,8 +10,9 @@
 // Exit 0 = pass, 1 = findings, 2 = usage. A planning turn cannot run this (the route policy refuses node);
 // start-work, a terminal and the test suite do.
 
-import { existsSync, lstatSync, readFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 export const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
@@ -56,7 +57,67 @@ export function visibleLines(text) {
   return out;
 }
 
-export function checkPlan(text, { complete = false } = {}) {
+// `Scope roots: <path> (<action>, <action>)`: an outside folder the plan's todos reach, granted up front.
+export const SCOPE_ROOT_LINE = /^Scope roots?:[ \t]*(\S+)[ \t]*\(([a-z, -]+)\)[ \t]*$/u;
+// An absolute path with at least two segments. Inside an inline code span only a span that is one bare
+// path counts; a span holding spaces is a quoted command, which is data rather than a folder.
+const ABSOLUTE_PATH = /(?<![\w.~/-])\/[\w.@+%,=~-]+(?:\/[\w.@+%,=~-]+)+\/?/gu;
+const pathsIn = (line) => line
+  .replace(/`([^`]*)`/gu, (_, span) => (/\s/u.test(span.trim()) ? ' ' : ` ${span.trim()} `))
+  .match(ABSOLUTE_PATH) ?? [];
+
+const realOr = (path) => {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+};
+const within = (root, path) => {
+  const rel = relative(root, path);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+};
+const existingFolder = (path) => {
+  for (let at = path; ; at = dirname(at)) {
+    try {
+      if (statSync(at).isDirectory()) return at;
+    } catch { /* not there: climb */ }
+    if (dirname(at) === at) return at;
+  }
+};
+
+/**
+ * Absolute paths named under `## Todos` (up to `## Final verification wave`, fences skipped) that lie
+ * outside `projectRoot` and outside every `Scope roots:` line, one entry per folder: `{path, suggestion}`
+ * with the line to add, or `{path, problem}` when the nearest existing folder is too broad to grant.
+ */
+export function uncoveredScopePaths(text, projectRoot) {
+  const project = realOr(resolve(projectRoot));
+  const lines = visibleLines(text);
+  const granted = lines.map(({ line }) => SCOPE_ROOT_LINE.exec(line.trim())).filter(Boolean)
+    .map(([, path]) => realOr(isAbsolute(path) ? path : resolve(project, path)));
+  const found = new Map();
+  let todos = false;
+  for (const { line } of lines) {
+    const heading = line.trimEnd();
+    if (heading === '## Todos') todos = true;
+    else if (/^## /u.test(heading)) todos = false;
+    if (!todos) continue;
+    for (const raw of pathsIn(line)) {
+      const path = raw.replace(/[.,:;)]+$/u, '');
+      const folder = realOr(existingFolder(path));
+      const covered = [realOr(path), folder].some((p) => within(project, p) || granted.some((root) => within(root, p)));
+      if (covered || found.has(folder)) continue;
+      const tooBroad = dirname(folder) === dirname(dirname(folder)) || folder === realOr(homedir());
+      found.set(folder, tooBroad
+        ? { path, problem: `${path} is outside the project; name a narrower existing folder on a Scope roots line` }
+        : { path, suggestion: `Scope roots: ${folder} (read)` });
+    }
+  }
+  return [...found.values()];
+}
+
+export function checkPlan(text, { complete = false, projectRoot = null } = {}) {
   const problems = [];
   const lines = visibleLines(text);
 
@@ -115,6 +176,10 @@ export function checkPlan(text, { complete = false } = {}) {
 
   if (/<fill\b/u.test(text)) problems.push('unfilled <fill ...> placeholders remain: the plan is not decision-complete');
 
+  if (projectRoot) {
+    for (const entry of uncoveredScopePaths(text, projectRoot)) problems.push(entry.problem ?? `${entry.path} is outside the project and no Scope roots line covers it; add: ${entry.suggestion}`);
+  }
+
   if (complete) {
     for (const { line } of marked) {
       if (/^- \[ \] /u.test(line)) problems.push(`row still open: ${line.trim()}`);
@@ -138,7 +203,9 @@ function checkFile(planPath, options) {
   }
   if (stat.isSymbolicLink() || !stat.isFile()) return fail(`FAIL PLAN_UNSAFE: ${path} must be a regular file`);
   if (stat.size > MAX_PLAN_BYTES) return fail(`FAIL PLAN_TOO_LARGE: ${path}`);
-  const result = checkPlan(readFileSync(path, 'utf8'), options);
+  // The project is the folder holding plans/; a plan kept elsewhere is checked against the cwd.
+  const projectRoot = basename(dirname(path)) === 'plans' ? dirname(dirname(path)) : process.cwd();
+  const result = checkPlan(readFileSync(path, 'utf8'), { ...options, projectRoot });
   if (!result.ok) {
     for (const problem of result.problems) process.stderr.write(`FAIL ${problem}\n`);
     return 1;

package/plugin/skills/lit-team/scripts/state-root.mjs

@@ -1,27 +1,14 @@
 // state-root.mjs: where LitMuse keeps project-local working state.
 // State belongs at the outermost Git root (or the start directory when there is no repository), so a nested
-// package never grows its own .litmuse folder. Node builtins only.
+// package never grows its own .litmuse folder; a linked worktree keeps its own. The rule lives once, in the
+// hooks' workflow-stack module, so team state lands where the hooks and the status card look.
 
-import { closeSync, constants, existsSync, lstatSync, openSync, writeSync } from "node:fs";
+import { closeSync, constants, lstatSync, openSync, writeSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 
-export const PROJECT_STATE_DIR = ".litmuse";
-
-const outermostGitRoot = (startDir) => {
-  let root = null;
-  let current = startDir;
-  for (;;) {
-    if (existsSync(join(current, ".git"))) root = current;
-    const parent = dirname(current);
-    if (parent === current) return root;
-    current = parent;
-  }
-};
+export { resolveProjectStateRoot } from "../../../hooks/lib/workflow-stack.mjs";
 
-export const resolveProjectStateRoot = (startDir = process.cwd()) => {
-  const start = resolve(startDir);
-  return outermostGitRoot(start) ?? start;
-};
+export const PROJECT_STATE_DIR = ".litmuse";
 
 const STATE_GITIGNORE = "# Created by LitMuse: local working state, not for commits.\n*\n";
 

package/plugin/skills/start-work/SKILL.md

@@ -74,7 +74,10 @@ okay. When the two disagree, ask.
 
 ### Authority envelope
 
-The envelope is the plan's Scope plus the user's messages. Work inside it freely:
+The envelope is the plan's Scope, its `Scope roots: <path> (<actions>)` lines and the user's messages. A
+`Scope roots` line grants exactly its listed actions under that folder outside the workspace; a todo that reaches
+an uncovered outside folder fails the structure check (`check-plan.mjs --check` prints the line to add), so ask
+the user before treating that folder as in scope. Work inside the envelope freely:
 
 - read: any file in the workspace;
 - write: the paths on the current row's Files line, new test files for that row, `.litmuse/` records, and the one