@litfamily/litcodex 1.0.31 → 1.0.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/README-Ko-KR.md +11 -10
  2. package/README.md +11 -10
  3. package/TRADEMARK.md +12 -0
  4. package/marketplace/plugins/litcodex/.codex-plugin/plugin.json +1 -1
  5. package/marketplace/plugins/litcodex/components/auto-update/package.json +1 -1
  6. package/marketplace/plugins/litcodex/components/comment-checker/package.json +1 -1
  7. package/marketplace/plugins/litcodex/components/git-bash/package.json +1 -1
  8. package/marketplace/plugins/litcodex/components/lit-loop/directives/lit-adhd.md +12 -9
  9. package/marketplace/plugins/litcodex/components/lit-loop/directives/lit-plan.md +2 -1
  10. package/marketplace/plugins/litcodex/components/lit-loop/dist/card-status.d.ts +3 -0
  11. package/marketplace/plugins/litcodex/components/lit-loop/dist/card-status.js +4 -1
  12. package/marketplace/plugins/litcodex/components/lit-loop/dist/hook-cli.js +8 -2
  13. package/marketplace/plugins/litcodex/components/lit-loop/dist/plan-persistence.d.ts +1 -1
  14. package/marketplace/plugins/litcodex/components/lit-loop/dist/plan-persistence.js +28 -2
  15. package/marketplace/plugins/litcodex/components/lit-loop/dist/plan-scope-roots.d.ts +7 -0
  16. package/marketplace/plugins/litcodex/components/lit-loop/dist/plan-scope-roots.js +76 -0
  17. package/marketplace/plugins/litcodex/components/lit-loop/dist/restart-chip.d.ts +6 -0
  18. package/marketplace/plugins/litcodex/components/lit-loop/dist/restart-chip.js +59 -0
  19. package/marketplace/plugins/litcodex/components/lit-loop/dist/rewind-go.js +11 -1
  20. package/marketplace/plugins/litcodex/components/lit-loop/dist/rewind.d.ts +13 -7
  21. package/marketplace/plugins/litcodex/components/lit-loop/dist/rewind.js +143 -49
  22. package/marketplace/plugins/litcodex/components/lit-loop/dist/route-heads.js +1 -1
  23. package/marketplace/plugins/litcodex/components/lit-loop/dist/session-liveness.d.ts +16 -0
  24. package/marketplace/plugins/litcodex/components/lit-loop/dist/session-liveness.js +90 -0
  25. package/marketplace/plugins/litcodex/components/lit-loop/dist/threads.js +7 -2
  26. package/marketplace/plugins/litcodex/components/lit-loop/dist/workflow-stack.d.ts +9 -2
  27. package/marketplace/plugins/litcodex/components/lit-loop/dist/workflow-stack.js +35 -5
  28. package/marketplace/plugins/litcodex/components/lit-loop/package.json +1 -1
  29. package/marketplace/plugins/litcodex/components/lsp/package.json +1 -1
  30. package/marketplace/plugins/litcodex/components/rules/package.json +1 -1
  31. package/marketplace/plugins/litcodex/components/start-work-continuation/package.json +1 -1
  32. package/marketplace/plugins/litcodex/components/telemetry/package.json +1 -1
  33. package/marketplace/plugins/litcodex/components/wikify-knowledge/package.json +1 -1
  34. package/marketplace/plugins/litcodex/skills/lit-adhd/SKILL.md +15 -11
  35. package/marketplace/plugins/litcodex/skills/lit-adhd/references/card-examples.md +23 -7
  36. package/marketplace/plugins/litcodex/skills/lit-adhd/references/status-taxonomy.md +12 -4
  37. package/marketplace/plugins/litcodex/skills/lit-plan/SKILL.md +3 -2
  38. package/marketplace/plugins/litcodex/skills/lit-plan/references/full-workflow.md +2 -1
  39. package/marketplace/plugins/litcodex/skills/start-work/SKILL.md +1 -1
  40. package/node_modules/@litcodex/lit-loop/directives/lit-adhd.md +12 -9
  41. package/node_modules/@litcodex/lit-loop/directives/lit-plan.md +2 -1
  42. package/node_modules/@litcodex/lit-loop/dist/card-status.d.ts +3 -0
  43. package/node_modules/@litcodex/lit-loop/dist/card-status.js +4 -1
  44. package/node_modules/@litcodex/lit-loop/dist/hook-cli.js +8 -2
  45. package/node_modules/@litcodex/lit-loop/dist/plan-persistence.d.ts +1 -1
  46. package/node_modules/@litcodex/lit-loop/dist/plan-persistence.js +28 -2
  47. package/node_modules/@litcodex/lit-loop/dist/plan-scope-roots.d.ts +7 -0
  48. package/node_modules/@litcodex/lit-loop/dist/plan-scope-roots.js +76 -0
  49. package/node_modules/@litcodex/lit-loop/dist/restart-chip.d.ts +6 -0
  50. package/node_modules/@litcodex/lit-loop/dist/restart-chip.js +59 -0
  51. package/node_modules/@litcodex/lit-loop/dist/rewind-go.js +11 -1
  52. package/node_modules/@litcodex/lit-loop/dist/rewind.d.ts +13 -7
  53. package/node_modules/@litcodex/lit-loop/dist/rewind.js +143 -49
  54. package/node_modules/@litcodex/lit-loop/dist/route-heads.js +1 -1
  55. package/node_modules/@litcodex/lit-loop/dist/session-liveness.d.ts +16 -0
  56. package/node_modules/@litcodex/lit-loop/dist/session-liveness.js +90 -0
  57. package/node_modules/@litcodex/lit-loop/dist/threads.js +7 -2
  58. package/node_modules/@litcodex/lit-loop/dist/workflow-stack.d.ts +9 -2
  59. package/node_modules/@litcodex/lit-loop/dist/workflow-stack.js +35 -5
  60. package/node_modules/@litcodex/lit-loop/package.json +1 -1
  61. package/node_modules/@litcodex/lit-loop/skills/lit-adhd/SKILL.md +15 -11
  62. package/node_modules/@litcodex/lit-loop/skills/lit-plan/SKILL.md +3 -2
  63. package/node_modules/@litcodex/lit-loop/skills/start-work/SKILL.md +1 -1
  64. package/package.json +3 -2
  65. package/readme-assets/badge-version.svg +1 -1
@@ -0,0 +1,90 @@
1
+ // src/session-liveness.ts — whether each LIT session in a workspace is working, waiting or gone.
2
+ //
3
+ // One small record per session, `.litcodex/liveness/<session>.json`: `alive` from the PostToolUse live hook,
4
+ // `idle` from Stop once the turn has closed. Codex fires no hook when a session ends, so `ended` is never
5
+ // written; a reader derives it from a record left untouched for 15 minutes. A repeat of the same state within
6
+ // 30 seconds writes nothing, so a busy turn costs one write per half minute. The herdr pane id is kept only when
7
+ // `HERDR_PANE_ID` is a short plain token. Writes are atomic, refuse a symlinked folder and never throw.
8
+ import { lstatSync, mkdirSync, readdirSync } from "node:fs";
9
+ import { isAbsolute, join } from "node:path";
10
+ import { plainDirs, plainDirsOrMissing, readSmallJson, writeFileAtomic } from "./live-step.js";
11
+ import { normalizeSessionId } from "./state-paths.js";
12
+ export const LIVENESS_DIR = ".litcodex/liveness";
13
+ export const LIVENESS_THROTTLE_MS = 30_000;
14
+ export const LIVENESS_ENDED_MS = 15 * 60_000;
15
+ const PANE_ID = /^[A-Za-z0-9:_-]{1,32}$/u;
16
+ const MAX_RECORDS = 64;
17
+ function recordPath(repoRoot, sessionId) {
18
+ const id = normalizeSessionId(sessionId);
19
+ if (id === null || typeof repoRoot !== "string" || !isAbsolute(repoRoot))
20
+ return null;
21
+ return join(repoRoot, LIVENESS_DIR, `${id}.json`);
22
+ }
23
+ function parse(value, now) {
24
+ if (typeof value !== "object" || value === null || Array.isArray(value))
25
+ return null;
26
+ const record = value;
27
+ const { sessionId, state, at, herdrPane } = record;
28
+ if (record["version"] !== 1 || typeof sessionId !== "string" || typeof at !== "number" || !Number.isFinite(at))
29
+ return null;
30
+ if (state !== "alive" && state !== "idle")
31
+ return null;
32
+ return {
33
+ sessionId,
34
+ state: now - at > LIVENESS_ENDED_MS ? "ended" : state,
35
+ at,
36
+ herdrPane: typeof herdrPane === "string" && PANE_ID.test(herdrPane) ? herdrPane : null,
37
+ };
38
+ }
39
+ /** Note that `sessionId` is `alive` or `idle` now. Never throws; a failed write only leaves the old record. */
40
+ export function recordLiveness(repoRoot, sessionId, state, env, now = Date.now()) {
41
+ const path = recordPath(repoRoot, sessionId);
42
+ if (path === null)
43
+ return;
44
+ try {
45
+ if (!plainDirsOrMissing(repoRoot, LIVENESS_DIR))
46
+ return;
47
+ const last = parse(readSmallJson(path), now);
48
+ if (last !== null && last.state === state && now - last.at >= 0 && now - last.at < LIVENESS_THROTTLE_MS)
49
+ return;
50
+ const pane = env["HERDR_PANE_ID"];
51
+ mkdirSync(join(repoRoot, LIVENESS_DIR), { recursive: true });
52
+ const herdrPane = typeof pane === "string" && PANE_ID.test(pane) ? pane : null;
53
+ writeFileAtomic(path, `${JSON.stringify({ version: 1, sessionId, state, at: now, herdrPane })}\n`);
54
+ }
55
+ catch {
56
+ // Liveness is a hint for other sessions' views; the hook's own answer never depends on it.
57
+ }
58
+ }
59
+ /** This session's record with `ended` derived from its age, or null when there is none. */
60
+ export function readLiveness(repoRoot, sessionId, now = Date.now()) {
61
+ const path = recordPath(repoRoot, sessionId);
62
+ if (path === null || !plainDirs(repoRoot, LIVENESS_DIR))
63
+ return null;
64
+ return parse(readSmallJson(path), now);
65
+ }
66
+ /** Every session's record in this workspace (at most 64), `ended` derived from age. */
67
+ export function readSessionsLiveness(repoRoot, now = Date.now()) {
68
+ if (typeof repoRoot !== "string" || !isAbsolute(repoRoot) || !plainDirs(repoRoot, LIVENESS_DIR))
69
+ return [];
70
+ const dir = join(repoRoot, LIVENESS_DIR);
71
+ let names;
72
+ try {
73
+ if (!lstatSync(dir).isDirectory())
74
+ return [];
75
+ names = readdirSync(dir)
76
+ .filter((name) => name.endsWith(".json"))
77
+ .sort()
78
+ .slice(0, MAX_RECORDS);
79
+ }
80
+ catch {
81
+ return [];
82
+ }
83
+ const out = [];
84
+ for (const name of names) {
85
+ const record = parse(readSmallJson(join(dir, name)), now);
86
+ if (record !== null)
87
+ out.push(record);
88
+ }
89
+ return out;
90
+ }
@@ -1,7 +1,8 @@
1
1
  // src/threads.ts — the threads of a session as the card and the text HUD draw them.
2
2
  //
3
3
  // A thread is a frame of the session's workflow stack, a child agent (lane) running under its top frame, or
4
- // the top frame of another session of the same project that moved lately. Each takes its `k/n` from the
4
+ // the top frame of another session of the same project that moved lately or whose liveness record is fresh
5
+ // (running first, then idle; named `<skill> · <pane>` when herdr gave a pane). Each takes its `k/n` from the
5
6
  // first source that really knows it: the count the frame recorded, the start-work run it drives, the
6
7
  // checkboxes of the plan it works from, the open goal's criteria, the main thread's own `update_plan` list
7
8
  // (top frame only), and for a lane its own `update_plan`. A gauge is drawn only when both numbers are real;
@@ -95,8 +96,12 @@ export function readThreads(cwd, sessionId, now, signals) {
95
96
  const laneRows = lanes.map((lane) => laneRow(lane, now));
96
97
  const otherRows = others.map((other) => {
97
98
  const top = other.frames.at(-1);
99
+ const row = frameRow(top, `session-${other.id.slice(0, SHORT_SESSION)}`, frameCounts(top, cwd, null, null), false, false);
98
100
  return {
99
- ...frameRow(top, `session-${other.id.slice(0, SHORT_SESSION)}`, frameCounts(top, cwd, null, null), false, false),
101
+ ...row,
102
+ // A session whose turn has closed waits for its person, so it reads idle rather than running.
103
+ ...(other.liveness === "idle" && row.state === "running" ? { state: "idle" } : {}),
104
+ ...(other.pane === null ? {} : { name: `${row.name} · ${other.pane}` }),
100
105
  kind: "session",
101
106
  session: other.id.slice(0, SHORT_SESSION),
102
107
  };
@@ -98,15 +98,22 @@ export declare function recordStackEvent(cwd: string, sessionId: string, event:
98
98
  };
99
99
  /** Another session of the project counts as live while its stack was written this recently. */
100
100
  export declare const OTHER_SESSION_MS: number;
101
+ /** A finished start-work run stays on other sessions' views this long, then leaves. */
102
+ export declare const FINISHED_WORK_MS = 60000;
101
103
  export interface OtherStack {
102
104
  readonly id: string;
103
105
  readonly frames: readonly StackFrame[];
104
106
  /** The newest time any of its frames moved. */
105
107
  readonly at: number;
108
+ /** What the session's liveness record says now (`ended` records are left out), or null without one. */
109
+ readonly liveness: "alive" | "idle" | null;
110
+ readonly pane: string | null;
106
111
  }
107
112
  /**
108
- * The stacks of the project's other sessions that moved within OTHER_SESSION_MS, newest first. It only
109
- * reads: a link, an oversized or malformed file reads as empty, and an older session is simply dropped.
113
+ * The stacks of the project's other sessions that moved within OTHER_SESSION_MS, or whose liveness record is
114
+ * still fresh, running first, then idle, then the rest, newest first within each. A start-work run that
115
+ * finished leaves after FINISHED_WORK_MS. It only reads: a link, an oversized or malformed file reads as
116
+ * empty, and an older session is simply dropped.
110
117
  */
111
118
  export declare function readOtherStacks(cwd: string, selfId: string, now?: number): OtherStack[];
112
119
  /** The frame a bare `lit continue` should resume: the nearest spine below a side frame, else null. */
@@ -15,6 +15,7 @@
15
15
  import { closeSync, fstatSync, lstatSync, mkdirSync, readdirSync, readSync } from "node:fs";
16
16
  import { isAbsolute, join } from "node:path";
17
17
  import { openRegularFile, plainDirs, plainDirsOrMissing, writeFileAtomic } from "./live-step.js";
18
+ import { readSessionsLiveness } from "./session-liveness.js";
18
19
  import { normalizeSessionId } from "./state-paths.js";
19
20
  export const STACK_DIR = ".litcodex/workflow-stack";
20
21
  export const MAX_FRAMES = 3;
@@ -400,15 +401,31 @@ export function recordStackEvent(cwd, sessionId, event, now = new Date()) {
400
401
  export const OTHER_SESSION_MS = 15 * 60 * 1000;
401
402
  const MAX_OTHER_SESSIONS = 6;
402
403
  const MAX_OTHER_FILES = 24;
404
+ /** A finished start-work run stays on other sessions' views this long, then leaves. */
405
+ export const FINISHED_WORK_MS = 60_000;
406
+ /** Running first, then idle, then the rest (paused, done, or silent). */
407
+ function otherRank(other) {
408
+ const top = other.frames.at(-1);
409
+ if (other.liveness === "idle")
410
+ return 1;
411
+ if (top?.done === true || top?.status === "paused")
412
+ return 2;
413
+ return other.liveness === "alive" || other.liveness === null ? 0 : 2;
414
+ }
403
415
  /**
404
- * The stacks of the project's other sessions that moved within OTHER_SESSION_MS, newest first. It only
405
- * reads: a link, an oversized or malformed file reads as empty, and an older session is simply dropped.
416
+ * The stacks of the project's other sessions that moved within OTHER_SESSION_MS, or whose liveness record is
417
+ * still fresh, running first, then idle, then the rest, newest first within each. A start-work run that
418
+ * finished leaves after FINISHED_WORK_MS. It only reads: a link, an oversized or malformed file reads as
419
+ * empty, and an older session is simply dropped.
406
420
  */
407
421
  export function readOtherStacks(cwd, selfId, now = Date.now()) {
408
422
  try {
409
423
  const own = normalizeSessionId(selfId);
410
424
  if (!isAbsolute(cwd) || !plainDirs(cwd, STACK_DIR))
411
425
  return [];
426
+ const lives = new Map(readSessionsLiveness(cwd, now)
427
+ .filter((record) => record.state !== "ended")
428
+ .map((record) => [normalizeSessionId(record.sessionId), record]));
412
429
  const found = [];
413
430
  const names = readdirSync(join(cwd, STACK_DIR))
414
431
  .filter((name) => name.endsWith(".json"))
@@ -420,10 +437,23 @@ export function readOtherStacks(cwd, selfId, now = Date.now()) {
420
437
  continue;
421
438
  const frames = readStack(cwd, id).frames;
422
439
  const at = Math.max(0, ...frames.map((frame) => Date.parse(frame.at)));
423
- if (frames.length > 0 && now - at <= OTHER_SESSION_MS)
424
- found.push({ id, frames, at });
440
+ const live = lives.get(id);
441
+ const top = frames.at(-1);
442
+ if (top === undefined || (now - at > OTHER_SESSION_MS && live === undefined))
443
+ continue;
444
+ if (top.skill === "start-work" && top.done === true && now - at > FINISHED_WORK_MS)
445
+ continue;
446
+ found.push({
447
+ id,
448
+ frames,
449
+ at: Math.max(at, live?.at ?? 0),
450
+ liveness: live === undefined ? null : live.state,
451
+ pane: live?.herdrPane ?? null,
452
+ });
425
453
  }
426
- return found.sort((a, b) => b.at - a.at || a.id.localeCompare(b.id)).slice(0, MAX_OTHER_SESSIONS);
454
+ return found
455
+ .sort((a, b) => otherRank(a) - otherRank(b) || b.at - a.at || a.id.localeCompare(b.id))
456
+ .slice(0, MAX_OTHER_SESSIONS);
427
457
  }
428
458
  catch {
429
459
  return [];
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litcodex/lit-loop",
3
- "version": "1.0.31",
3
+ "version": "1.0.32",
4
4
  "description": "LitCodex Lit-Loop runtime: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
5
5
  "type": "module",
6
6
  "private": true,
@@ -80,19 +80,19 @@ verdicts: [PASS, FAIL, BLOCKED]
80
80
  "collector": "components/lit-loop/dist/cli.js rewind --json",
81
81
  "next_note": ".litcodex/adhd/next-<session>.json",
82
82
  "go_window_minutes": 30,
83
- "statuses": ["waiting-on-user", "active", "ended", "unknown"],
84
- "next_kinds": ["resume-frame", "approve-boundary", "continue-work", "start-plan", "none"],
83
+ "statuses": ["waiting-on-user", "active", "idle", "done", "ended", "unknown"],
84
+ "next_kinds": ["resume-frame", "approve-boundary", "continue-work", "start-plan", "handoff", "none"],
85
85
  "verdicts": ["PASS", "FAIL", "BLOCKED"]
86
86
  }
87
87
  ```
88
88
 
89
- The brief is read in ten seconds, so it has this shape, in this order. The collector's `brief` field is a finished Markdown draft of it (bold lines, a list-item card per session, a table, a boxed step); keep its structure and wording, translate it into the user's language, and add nothing it does not support. The Codex terminal draws `#` heading marks and `>` quote marks literally, so the draft uses neither: no line starts with `#` or `>`, and you add none. It draws bold, lists, inline code, tables and fenced boxes properly, in colour: the headline, the badges and the boxed step are what a tired reader's eye lands on.
89
+ The brief is read in ten seconds, so it has this shape, in this order. The collector's `brief` field is a finished Markdown draft of it (bold lines, a list-item card per session, a table, a boxed step); keep its structure and wording, translate it into the user's language, and add nothing it does not support. The Codex terminal draws `#` heading marks and `>` quote marks literally, so the draft uses neither: no line starts with `#` or `>`, and you add none. It draws bold, lists, inline code, tables and fenced boxes properly, in colour: the opener, the badges and the boxed step are what a tired reader's eye lands on.
90
90
 
91
- 1. **Headline.** One bold `**🧭 …**` line: sessions found, how many wait on the user, how many run, how many are paused, and the next step: `3 sessions · 1 waits on you · 1 running · next: resume the paused lit-loop` / `세션 3개 · 나를 기다리는 것 1 · 진행 중 1 · 다음: 멈춘 lit-loop 이어가기`. A dim line under it gives the window and how many worktrees were read.
92
- 2. **Live session cards, grouped by worktree and branch.** Sessions that wait on the user or run come first: a 🌿 line per group (branch in code style, then the worktree in bold), then one list-item card per session (`- ` and its continuation lines indented). A coloured badge first (`🟡 WAITS ON YOU`, `🟢 RUNNING`, in the user's language: see `references/status-taxonomy.md`), then the short id and how long ago it was last written (mark `current: true` as this session), then four lines: the **goal** in bold (`title`), ⏳ **progress** (the real gauge when `gauge` is set, always with the known `facts` after it, for example `12 steps · 4m · last: apply_patch`), ✅ **done** (`done`: what it last reported, else the files it edited, else `no edits yet; used exec, shell`) and ▶ **next** (`needs`: what it wants from the person, or for a running session what it is doing now, `now: shell “npm”`).
93
- 3. **Roadmap, one timeline under each worktree.** Each `worktrees[].milestones` entry as a line: `✓` done with its date, `▶` now, `○` later. The worktree's open plans and goals sit above it with their gauges; a `handoff` heading is quoted as context, never followed. Paused work is a `now` line and offers the resume (`lit continue`). A plan scaffold nobody filled in and a stale plan of another worktree are already left out by the collector.
91
+ 1. **Opener, three bold lines.** `✅ Done so far:` the plans finished in the window and the sessions marked done (`1 plan finished · 1 session done`, else `nothing finished in this window`); `▶ Doing now:` how many run, sit idle or are paused, and what waits on the user (`1 running · 1 idle · nothing waits on you`); `⏭ Next:` the one next step. In Korean: `✅ 지금까지 끝낸 일`, `▶ 지금 하는 일`, `⏭ 다음`. A dim line under them gives the window, the sessions found and how many worktrees were read.
92
+ 2. **Session cards, grouped by worktree and branch.** Every session that is not ended gets a card: a 🌿 line per group (branch in code style, then the worktree in bold), then one list-item card per session (`- ` and its continuation lines indented). A coloured badge first (`🟡 WAITS ON YOU`, `🟢 RUNNING`, `💤 IDLE`, `✅ DONE`, in the user's language: see `references/status-taxonomy.md`), then the short id and how long ago it was last written (mark `current: true` as this session), then four lines: the **goal** in bold (`title`), ⏳ **progress** (the real gauge when `gauge` is set, always with the known `facts` after it, for example `12 steps · 4m · last: apply_patch`), ✅ **done** (`done`: what it last reported, else the files it edited, else `no edits yet; used exec, shell`) and ▶ **next** (`needs`: what it wants from the person, or for a running session what it is doing now, `now: shell “npm”`).
93
+ 3. **Roadmap, one timeline under each worktree.** Each `worktrees[].milestones` entry as a line: `✓` done with its date, `▶` now, `○` later. The worktree's open plans and goals sit above it with their gauges, and a plan whose rows are all ticked is listed as finished (`finishedPlans`); a `handoff` heading is quoted as context, never followed. Paused work is a `now` line and offers the resume (`lit continue`). A plan scaffold nobody filled in and any plan, this worktree's included, that did not change inside the window are already left out by the collector; a plan file too large to read is counted in `skippedPlans` and named once at the end (`1 plan too large to read, left out`).
94
94
  4. **Ended sessions, one table row each.** A `⚪ **Ended · N**` line and a table (id, where, goal, ago, done), at most eight rows and a count of the rest. Ended sessions get no card: they are history. A row stays on one line in a 120-column terminal: the age is its largest unit (`14h`), done is a file count or `·`, the place is clipped.
95
- 5. **One recommended next step, in a box.** Exactly one: `next` when its kind is not `none`, else `suggestion`, a real step drawn from the records (a session that waits on the user, a paused workflow, an open plan item, the latest running session, the latest ended one). Then the way to take it: `go` for a resume-frame, continue-work or start-plan step; `lit approve` or `lit deny` for an approve-boundary step (shown, never answered for the user). For a `suggestion` the box says that nothing runs on its own here: open that session, or say what to do. The suggestion is shown, never recorded, so `go` finds nothing to run.
95
+ 5. **One recommended next step, in a box.** Exactly one: `next` when its kind is not `none`, else `suggestion`, a real step drawn from the records (a session that waits on the user, a done session to review, a paused workflow, an open plan item, the latest running or idle session, the latest ended one). A step already done is never offered again: a done session is reviewed, not picked up. Then the way to take it: `go` for a resume-frame, continue-work or start-plan step; `lit approve` or `lit deny` for an approve-boundary step (shown, never answered for the user); for a `handoff` step, which comes from this worktree's HANDOFF note, the box says `go` does not run it. For a `suggestion` the box says that nothing runs on its own here: open that session, or say what to do. The suggestion is shown, never recorded, so `go` finds nothing to run. The box sits in a plain fence with no language tag, so the terminal draws it as it is.
96
96
 
97
97
  **Progress gauges, required.** A gauge `[▉▉▉░░] 3/5` appears only when both numbers are real and are copied verbatim from the collector (filled `▉` done, light `░` remaining, then done/total; at most ten cells, scaled when the total is larger). When the total is unknown, no gauge is drawn and no placeholder stands in for one: write what is known in words (`12 steps · 4m · last: apply_patch`, `step 2`, `running 4m`). Never a guess, never an estimate, never a gauge of your own, and never a run of question marks in place of a number.
98
98
 
@@ -130,11 +130,12 @@ The collector (`dist/cli.js rewind` in the lit-loop component) reads, for the cu
130
130
  | Source | What it gives | Missing reads |
131
131
  | --- | --- | --- |
132
132
  | Codex session records, the rollout `.jsonl` files under the `sessions` folder of the Codex home | per session: id, folder, first ask (`title`), last ask, last assistant text, status, the tools it used most, the files it patched and what its last call was about (a program or file base name, never a command line) | `sessions: unknown` |
133
- | `.litcodex/plans/*.md` checkbox rows | open plans and done/total | none; absent means no open plan |
133
+ | `.litcodex/plans/*.md` checkbox rows | open and finished plans with done/total, held to the window; oversized files counted | none; absent means no plan |
134
+ | `.litcodex/liveness/*.json` | whether a session's turn has closed (`idle`), written by the PostToolUse and Stop hooks | none; absent means the age alone decides |
134
135
  | `.litcodex/start-work/state.json` | the active or paused start-work, its plan progress, a boundary waiting for an answer | none |
135
136
  | `.litcodex/lit-loop/goals.json` | lit-loop goals, done/total | none |
136
137
  | `.litcodex/workflow-stack/*.json` | running and paused disciplines with stage and k/n | none |
137
- | `HANDOFF*.md` | the first heading only | none |
138
+ | `HANDOFF*.md` | the first heading, and the first unticked item under `## Next` as the last-resort next step | none |
138
139
  | `git worktree list`, `git log -1` | worktrees, branches, the last commit subject | `git: unknown` |
139
140
 
140
141
  Session records are read head (256 KiB, enough for the meta line and the first ask) and tail (256 KiB, the latest turn) only, under one 8 MiB budget for the whole run, through descriptors opened without following links; a linked file or folder, a named pipe and a subagent's records are skipped. The format is private to Codex, so every field is read tolerantly and a record that does not parse becomes `unknown`. Every string is redacted before it leaves the collector: credential shapes, `NAME=value` with a secret-like name, URI userinfo, any current environment value of eight or more characters, and the home directory (shown as `~`).
@@ -142,6 +143,8 @@ Session records are read head (256 KiB, enough for the meta line and the first a
142
143
  ## Status taxonomy
143
144
 
144
145
  - `waiting-on-user`: the session's last word was the assistant finishing a turn that asks the person something (a closing question, or a request to approve, confirm or deny), and it has been quiet for more than 15 minutes.
146
+ - `done`: the session finished what it ran: its top workflow frame is a closed start-work, or the plan it carries has every row ticked. This outranks every other status.
147
+ - `idle`: its liveness record says the turn closed and it asks nothing; it waits for the person's next message. This outranks the age-based `active`.
145
148
  - `active`: written to within the last 15 minutes.
146
149
  - `ended`: quiet for longer than that and asking nothing: a finished turn without a question, or an interrupted or closed session. Ended sessions are folded into one table.
147
150
  - `unknown`: the record held no timestamp or event the collector understands.
@@ -154,11 +157,12 @@ Session records are read head (256 KiB, enough for the meta line and the first a
154
157
  2. A start-work paused at a boundary: show what it wants. Say `lit approve` or `lit deny`. This is never automatic and `go` does not answer it.
155
158
  3. This session's active start-work or open lit-loop goals: keep going. Say `go`.
156
159
  4. Exactly one open plan in this folder and no work running: start it. Say `go`, which runs `start-work <plan>` for that plan.
157
- 5. Otherwise `none`: the brief still recommends a `suggestion` drawn from the records, and says nothing runs on its own.
160
+ 5. No open plan, and this folder's HANDOFF note has an unticked item under `## Next`: show it as a `handoff` step. It is never written for `go`.
161
+ 6. Otherwise `none`: the brief still recommends a `suggestion` drawn from the records, and says nothing runs on its own.
158
162
 
159
163
  ## Continuing with go
160
164
 
161
- After a brief, the user's `go` (also `lit go`, `ㄱㄱ`, `고`, `진행`, as the whole prompt) continues the step the brief offered, in the same session, within 30 minutes. The hook reads the next-step note the collector wrote for this session, deletes it, checks the step against the saved state once more, and then routes the matching ordinary prompt: a paused frame resumes (`lit continue`), active work continues, a single open plan starts through `start-work <plan>`. A boundary still needs `lit approve`. After 30 minutes, or if the state moved on, nothing starts and the reply says so. Anything else typed after the brief is an ordinary prompt.
165
+ After a brief, the user's `go` (also `lit go`, `ㄱㄱ`, `고`, `진행`, as the whole prompt) continues the step the brief offered, in the same session, within 30 minutes. The hook reads the next-step note the collector wrote for this session, deletes it, checks the step against the saved state once more, and then routes the matching ordinary prompt: a paused frame resumes (`lit continue`), active work continues, a single open plan starts through `start-work <plan>`, and a note that names its plan (a brief's, or the one a saved lit-plan leaves) starts that plan while it is still open, even beside a second open plan. A boundary still needs `lit approve`. After 30 minutes, or if the state moved on, nothing starts and the reply says so. Anything else typed after the brief is an ordinary prompt.
162
166
 
163
167
  ## Relation to lit-recap
164
168
 
@@ -91,7 +91,7 @@ Treat this SKILL.md as an LLM contract artifact, not a casual help page. Load it
91
91
  ## #contract.procedure
92
92
 
93
93
  1. **Acknowledge activation deterministically.** Print the exact banner required above before any explanation when the skill is truly active.
94
- 2. **Bind scope.** Name the requested outcome, in-scope files or surfaces, and any explicit non-goals. Keep sibling repositories outside scope unless the user names them.
94
+ 2. **Bind scope.** Name the requested outcome, in-scope files or surfaces, and any explicit non-goals. Keep sibling repositories outside scope unless the user names them. When a todo names an absolute path outside the project, declare it on its own column-zero line, `Scope roots: <path> (<actions>)`, so start-work can grant it at init instead of pausing at the first touch. The Stop hook names any such path left undeclared, once per plan, with the exact line to paste; `/` and the bare home folder never count as a root.
95
95
  3. **Ground in Codex reality.** Prefer repo-local files, package scripts, component directives, marketplace metadata, and hook behavior over memory or generic agent habits.
96
96
  4. **Select the smallest complete path.** Reuse existing tests, scripts, components, directives, and docs before inventing new abstractions.
97
97
  5. **Execute with evidence gates.** For behavior changes, obtain a failing-first proof when a seam exists; for docs/contracts, add a guard that fails before the rewrite and passes after it.
@@ -195,7 +195,8 @@ they can press Shift+Tab and continue, or proceed with file-backed lit-plan.
195
195
  - **Planner scope only.** Prepare one Markdown plan and publish it only through the bundled
196
196
  `publish-plan` route. Write drafts under `.litcodex/drafts/*.md`. Never edit source or lifecycle
197
197
  authority state. If asked to "just do it", decline: you plan; after approval, hand the published plan
198
- to execution with `lit start work <plan-name>`.
198
+ to execution with `lit start work <plan-name>`. Saving the plan arms a one-word `go` for this session,
199
+ so close by telling the user to type `go` within 30 minutes to start it.
199
200
 
200
201
  ## Objective-achievable plan contract
201
202
 
@@ -267,7 +267,7 @@ node <plugin-root>/components/start-work-continuation/dist/cli.js init
267
267
  {"cwd":"<canonical repo>","init_id":"<stable id>","expected_revision":0,"work_id":"<work id>","plan":".litcodex/plans/<plan>.md","plan_name":"<display name>","session_id":"<raw Codex id>","worktree_path":"<canonical cwd or separate worktree>","authority":{"authority_id":"<approval id>","allowed_roots":["<canonical approved root>"],"allowed_actions":["edit","test"],"forbidden_actions":["publish"]}}
268
268
  ```
269
269
 
270
- Its JSON stdin must include `cwd`, a stable `init_id`, global-CAS `expected_revision`, `work_id`, canonical repo-relative `plan`, bounded display-only `plan_name`, raw Codex `session_id`, a live canonical absolute `worktree_path`, and an `authority` object with `authority_id`, canonical absolute `allowed_roots`, `allowed_actions`, and `forbidden_actions`. Derive that envelope only from the user's approved plan and scope. `init` atomically creates schema 3 and emits `start_work_initialized`; exact retained replay is idempotent. A terminal completed/abandoned state permits a new distinct init at the current revision while preserving bounded replay history; any nonterminal work rejects it.
270
+ Its JSON stdin must include `cwd`, a stable `init_id`, global-CAS `expected_revision`, `work_id`, canonical repo-relative `plan`, bounded display-only `plan_name`, raw Codex `session_id`, a live canonical absolute `worktree_path`, and an `authority` object with `authority_id`, canonical absolute `allowed_roots`, `allowed_actions`, and `forbidden_actions`. Derive that envelope only from the user's approved plan and scope: the project root, plus the path of every column-zero `Scope roots: <path> (<actions>)` line in the plan, made canonical and absolute, with its actions added to `allowed_actions`. Skip a declared `/` or bare home folder. `init` atomically creates schema 3 and emits `start_work_initialized`; exact retained replay is idempotent. A terminal completed/abandoned state permits a new distinct init at the current revision while preserving bounded replay history; any nonterminal work rejects it.
271
271
 
272
272
  Schema 3 has one global monotonic `revision`; `active_work_id` selects the same-keyed sole nonterminal `works[id]` or is `null` after terminal cancel/complete. Every work owns `worktree_path`; a nonterminal path must exist, be canonical, and lie within effective authority, while a terminal historical record may retain its normalized absolute path after cleanup removes the directory. Paused work must own one pending boundary matching its last canonical pause event. Every load sorts retained events by revision rather than object-key enumeration and validates unique contiguous revisions, last-transition consistency, authority, and worktree containment. Replay history is compacted to a bounded newest window with an explicit floor; terminal work records whose final events fall below that floor are compacted too, and pruned replay fails as `REPLAY_EXPIRED`. A valid schema-2 state is migrated lazily only when the first code-owned mutation supplies a valid authority envelope and the fully constructed schema-3 result validates; ambiguous nonterminal state is rejected without mutation. A historical absolute plan is normalized only when its no-follow canonical realpath proves it is directly inside `cwd/.litcodex/plans`; unsupported or unsafe state stays silent and is reported by `doctor --cwd <path> --json`.
273
273
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@litfamily/litcodex",
3
- "version": "1.0.31",
3
+ "version": "1.0.32",
4
4
  "description": "Codex CLI plugin that turns a request into a goal with checks, keeps the evidence in your project and hands unfinished work to the next session.",
5
5
  "keywords": [
6
6
  "codex",
@@ -49,10 +49,11 @@
49
49
  "README.md",
50
50
  "README-Ko-KR.md",
51
51
  "LICENSE",
52
+ "TRADEMARK.md",
52
53
  "readme-assets"
53
54
  ],
54
55
  "dependencies": {
55
- "@litcodex/lit-loop": "1.0.31"
56
+ "@litcodex/lit-loop": "1.0.32"
56
57
  },
57
58
  "bundledDependencies": [
58
59
  "@litcodex/lit-loop"
@@ -1 +1 @@
1
- <svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.31"><title>release: 1.0.31</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.31</text></g></svg>
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.32"><title>release: 1.0.32</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.32</text></g></svg>