djournal 0.7.0 → 0.8.0
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.
- package/.agents/adapters/shared/journal-hook.js +72 -9
- package/.agents/rules/FEAT.md +5 -3
- package/.agents/rules/STATE.md +9 -2
- package/.agents/skills/init-work/SKILL.md +3 -2
- package/.agents/skills/resume/SKILL.md +9 -2
- package/.agents/skills/switch/SKILL.md +5 -3
- package/README.md +10 -0
- package/bin/journal.js +36 -1
- package/docs/architecture.md +13 -3
- package/docs/djournal-in-practice.md +13 -0
- package/lib/installer/index.js +60 -0
- package/package.json +1 -1
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
const fs = require("node:fs");
|
|
6
6
|
const path = require("node:path");
|
|
7
7
|
const { spawnSync } = require("node:child_process");
|
|
8
|
+
const crypto = require("node:crypto");
|
|
8
9
|
|
|
9
10
|
const MARKER = /<!--\s*journal-status:\s*(closed|not-needed|off)(?:\s+([^>]*?))?\s*-->\s*$/i;
|
|
10
11
|
const PROJECT_MARKER_PATH = ".djournal.json";
|
|
@@ -47,27 +48,58 @@ function parseFrontmatter(text) {
|
|
|
47
48
|
function projectContext(root) {
|
|
48
49
|
try {
|
|
49
50
|
const markerFile = path.join(root, PROJECT_MARKER_PATH);
|
|
50
|
-
if (!fs.existsSync(markerFile)) return { root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
|
|
51
|
+
if (!fs.existsSync(markerFile)) return { root, storeRoot: root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
|
|
51
52
|
const marker = JSON.parse(fs.readFileSync(markerFile, "utf8"));
|
|
52
|
-
if (!marker.journalStore) return { root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
|
|
53
|
+
if (!marker.journalStore) return { root, storeRoot: root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
|
|
53
54
|
const store = path.resolve(marker.journalStore);
|
|
54
|
-
return { root, journalRoot: path.join(store, ".journal"), configFile: path.join(store, "config.json"), global: true };
|
|
55
|
+
return { root, storeRoot: store, journalRoot: path.join(store, ".journal"), configFile: path.join(store, "config.json"), global: true };
|
|
55
56
|
} catch {
|
|
56
|
-
return { root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
|
|
57
|
+
return { root, storeRoot: root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
|
|
57
58
|
}
|
|
58
59
|
}
|
|
59
60
|
|
|
60
|
-
function
|
|
61
|
+
function workMetadata(root, slug) {
|
|
62
|
+
const work = workBySlug(root, slug);
|
|
63
|
+
return work && work.status === "active" ? work : null;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
function sessionId(payload, env = process.env) {
|
|
67
|
+
return payload.session_id || payload.sessionId || env.DJOURNAL_SESSION_ID || "";
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
function sessionBinding(context, id) {
|
|
71
|
+
if (typeof id !== "string" || !id.trim()) return null;
|
|
72
|
+
try {
|
|
73
|
+
const file = path.join(context.storeRoot, "sessions", `${sha256(id.trim())}.json`);
|
|
74
|
+
const value = JSON.parse(fs.readFileSync(file, "utf8"));
|
|
75
|
+
return typeof value.activeWorkName === "string" ? value.activeWorkName : null;
|
|
76
|
+
} catch {
|
|
77
|
+
return null;
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
function activeWork(root, options = {}) {
|
|
61
82
|
try {
|
|
62
83
|
const context = projectContext(root);
|
|
84
|
+
const bound = sessionBinding(context, options.sessionId);
|
|
85
|
+
if (bound) {
|
|
86
|
+
const work = workMetadata(root, bound);
|
|
87
|
+
if (work) return { work, source: "session" };
|
|
88
|
+
}
|
|
89
|
+
if (options.state === false) return null;
|
|
63
90
|
const state = JSON.parse(fs.readFileSync(path.join(context.journalRoot, "state.json"), "utf8"));
|
|
64
91
|
if (typeof state.active_work_name !== "string" || !state.active_work_name) return null;
|
|
65
|
-
|
|
92
|
+
const work = workBySlug(root, state.active_work_name);
|
|
93
|
+
return work ? { work, source: "state" } : null;
|
|
66
94
|
} catch {
|
|
67
95
|
return null;
|
|
68
96
|
}
|
|
69
97
|
}
|
|
70
98
|
|
|
99
|
+
function sha256(value) {
|
|
100
|
+
return crypto.createHash("sha256").update(value).digest("hex");
|
|
101
|
+
}
|
|
102
|
+
|
|
71
103
|
function workBySlug(root, slug) {
|
|
72
104
|
try {
|
|
73
105
|
if (typeof slug !== "string" || !slug || slug.includes("/") || slug.includes("\\") || slug === "." || slug === "..") return null;
|
|
@@ -77,12 +109,44 @@ function workBySlug(root, slug) {
|
|
|
77
109
|
const metadata = parseFrontmatter(fs.readFileSync(work, "utf8"));
|
|
78
110
|
const config = readConfig(context);
|
|
79
111
|
const shared = config.sharing?.sharedWorkItems && Object.prototype.hasOwnProperty.call(config.sharing.sharedWorkItems, slug);
|
|
80
|
-
return { slug, visibility: metadata.visibility || "local_only", shared: !!shared, path: work };
|
|
112
|
+
return { slug, title: metadata.title || slug, status: metadata.status || "unknown", visibility: metadata.visibility || "local_only", shared: !!shared, path: work };
|
|
81
113
|
} catch {
|
|
82
114
|
return null;
|
|
83
115
|
}
|
|
84
116
|
}
|
|
85
117
|
|
|
118
|
+
function activeWorkItems(root) {
|
|
119
|
+
try {
|
|
120
|
+
const context = projectContext(root);
|
|
121
|
+
const workRoot = path.join(context.journalRoot, "work");
|
|
122
|
+
if (!fs.existsSync(workRoot)) return [];
|
|
123
|
+
return fs.readdirSync(workRoot, { withFileTypes: true })
|
|
124
|
+
.filter((entry) => entry.isDirectory() && !entry.isSymbolicLink())
|
|
125
|
+
.map((entry) => workBySlug(root, entry.name))
|
|
126
|
+
.filter((work) => work?.status === "active")
|
|
127
|
+
.sort((left, right) => left.slug.localeCompare(right.slug));
|
|
128
|
+
} catch {
|
|
129
|
+
return [];
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
function selectionSuffix(root, payload, env) {
|
|
134
|
+
const id = sessionId(payload, env);
|
|
135
|
+
const selected = activeWork(root, { sessionId: id, state: false });
|
|
136
|
+
if (selected?.work) {
|
|
137
|
+
return ` Session-bound active work: ${selected.work.slug}.`;
|
|
138
|
+
}
|
|
139
|
+
const candidates = activeWorkItems(root);
|
|
140
|
+
if (candidates.length > 1) {
|
|
141
|
+
const list = candidates.map((work) => `${work.slug} (${work.title})`).join("; ");
|
|
142
|
+
return ` Multiple active work items are available: ${list}. Ask the user to choose one before meaningful work, then bind this session with \`djournal work bind <slug> --session <id>\` when a session id is available.`;
|
|
143
|
+
}
|
|
144
|
+
if (candidates.length === 1) return ` Active work: ${candidates[0].slug}.`;
|
|
145
|
+
const fallback = activeWork(root, { state: true });
|
|
146
|
+
if (fallback?.work) return ` Active work: ${fallback.work.slug}.`;
|
|
147
|
+
return " No valid active work is selected.";
|
|
148
|
+
}
|
|
149
|
+
|
|
86
150
|
function readConfig(context) {
|
|
87
151
|
try {
|
|
88
152
|
if (!fs.existsSync(context.configFile)) return {};
|
|
@@ -238,8 +302,7 @@ function handle(payload, options = {}) {
|
|
|
238
302
|
const updateMessage = shouldCheckUpdates(root, env, { allowTest })
|
|
239
303
|
? updateNotice(runUpdateCheck(root, options.updateRunner))
|
|
240
304
|
: "";
|
|
241
|
-
const
|
|
242
|
-
const suffix = work ? ` Active work: ${work.slug}.` : " No valid active work is selected.";
|
|
305
|
+
const suffix = selectionSuffix(root, payload, env);
|
|
243
306
|
return context(event, `Follow AGENTS.md and .agents/rules/AUTOMATION.md.${pullMessage}${updateMessage}${suffix}`);
|
|
244
307
|
}
|
|
245
308
|
|
package/.agents/rules/FEAT.md
CHANGED
|
@@ -71,9 +71,11 @@ Allowed status values:
|
|
|
71
71
|
Status updates preserve `createdAt`, update `updatedAt`, and never alter `id` or
|
|
72
72
|
`slug`. Visibility changes require an explicit user request.
|
|
73
73
|
|
|
74
|
-
Only one work item is selected as active in
|
|
75
|
-
other work items may remain in `active` status.
|
|
76
|
-
|
|
74
|
+
Only one work item is selected as the fallback active work in
|
|
75
|
+
`<journal-root>/state.json`, but other work items may remain in `active` status.
|
|
76
|
+
Parallel sessions may bind themselves to different active work items through
|
|
77
|
+
local session state. Active selection and lifecycle status are different
|
|
78
|
+
concepts.
|
|
77
79
|
|
|
78
80
|
## Legacy work items
|
|
79
81
|
|
package/.agents/rules/STATE.md
CHANGED
|
@@ -24,15 +24,22 @@ The state file contains exactly one field:
|
|
|
24
24
|
}
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
+
This file is the global fallback selection. A session may also bind to a work
|
|
28
|
+
item through local operational session state created by `djournal work bind`.
|
|
29
|
+
Session binding does not change this file and is not durable journal history.
|
|
30
|
+
|
|
27
31
|
## Invariants
|
|
28
32
|
|
|
29
33
|
- The file MUST be valid JSON with no trailing comma.
|
|
30
34
|
- `active_work_name` MUST be a non-empty string.
|
|
31
35
|
- Its value MUST exactly match a folder under `<journal-root>/work/`.
|
|
32
36
|
- That folder SHOULD contain a `work.md` whose `slug` matches the folder name.
|
|
33
|
-
- State selects the current work item; it does not encode lifecycle
|
|
34
|
-
visibility, repository, branch, session, or user identity.
|
|
37
|
+
- State selects the fallback current work item; it does not encode lifecycle
|
|
38
|
+
status, visibility, repository, branch, session, or user identity.
|
|
35
39
|
- Update the file atomically when switching active work.
|
|
40
|
+
- When multiple work items have `status: active` and no valid session binding is
|
|
41
|
+
available, do not guess from this fallback. Prompt the user to choose the work
|
|
42
|
+
item for the session before meaningful writes.
|
|
36
43
|
|
|
37
44
|
## Missing or invalid state
|
|
38
45
|
|
|
@@ -52,8 +52,9 @@ Create one project-level work item. Work items may span repositories.
|
|
|
52
52
|
<What outcome this work item exists to achieve.>
|
|
53
53
|
```
|
|
54
54
|
|
|
55
|
-
10. Create or update `<journal-root>/state.json` to select the new slug
|
|
56
|
-
|
|
55
|
+
10. Create or update `<journal-root>/state.json` to select the new slug as the
|
|
56
|
+
global fallback work item. Preserve the exact state shape from `STATE.md`
|
|
57
|
+
and make the update safely.
|
|
57
58
|
11. Re-read `work.md` and state. Verify slug, IDs, directories, timestamps,
|
|
58
59
|
status, visibility, and JSON validity.
|
|
59
60
|
|
|
@@ -15,8 +15,15 @@ Operate read-only.
|
|
|
15
15
|
- `.agents/rules/LINKS.md`
|
|
16
16
|
- `.agents/rules/SAFETY.md`
|
|
17
17
|
- `.agents/rules/STATE.md`
|
|
18
|
-
2. Resolve the journal root according to `STATE.md`; read
|
|
19
|
-
then the
|
|
18
|
+
2. Resolve the journal root according to `STATE.md`; read active work
|
|
19
|
+
candidates under `<journal-root>/work/`, then resolve the session-bound work
|
|
20
|
+
item when the session has one, otherwise use `<journal-root>/state.json` only
|
|
21
|
+
as a fallback.
|
|
22
|
+
- If multiple work items have `status: active` and no valid session binding
|
|
23
|
+
is available, ask the user to choose one before doing meaningful writes.
|
|
24
|
+
After the user chooses, bind the session with
|
|
25
|
+
`djournal work bind <slug> --session <id>` when a session id is available,
|
|
26
|
+
or use `switch` only when the user wants to change the global fallback.
|
|
20
27
|
3. If `work.md` is legacy/missing, infer a temporary title/slug and clearly mark
|
|
21
28
|
metadata as incomplete. Do not repair it.
|
|
22
29
|
4. Index entry frontmatter under `journal/`, `_research/`, `docs/`, and
|
|
@@ -5,7 +5,9 @@ description: Change the active filesystem journal work item without changing Git
|
|
|
5
5
|
|
|
6
6
|
# Switch active work
|
|
7
7
|
|
|
8
|
-
Switch journal context only. Work items are projects and are
|
|
8
|
+
Switch the global fallback journal context only. Work items are projects and are
|
|
9
|
+
not Git branches. For parallel sessions, prefer binding the session with
|
|
10
|
+
`djournal work bind <slug> --session <id>` when a session id is available.
|
|
9
11
|
|
|
10
12
|
## Procedure
|
|
11
13
|
|
|
@@ -22,8 +24,8 @@ Switch journal context only. Work items are projects and are not Git branches.
|
|
|
22
24
|
6. If already selected, report that and stop.
|
|
23
25
|
7. Optionally inspect Git status read-only and mention uncommitted changes, but do
|
|
24
26
|
not commit, stash, switch branches, or block the journal switch.
|
|
25
|
-
8. Update `<journal-root>/state.json` atomically to the selected slug
|
|
26
|
-
exact shape in `STATE.md`.
|
|
27
|
+
8. Update `<journal-root>/state.json` atomically to the selected fallback slug
|
|
28
|
+
using the exact shape in `STATE.md`.
|
|
27
29
|
9. Re-read state and verify the target folder and `work.md` slug.
|
|
28
30
|
10. Present the selected work's latest spine summary and next steps using the
|
|
29
31
|
`resume` retrieval procedure.
|
package/README.md
CHANGED
|
@@ -238,6 +238,16 @@ three-way reconciliation. `sync` pulls first, then projects and publishes
|
|
|
238
238
|
shared work. Colocated mode leaves product-repository Git operations to the
|
|
239
239
|
user; standalone mode performs the configured Git pull and push.
|
|
240
240
|
|
|
241
|
+
Parallel sessions can bind themselves to different active work items:
|
|
242
|
+
|
|
243
|
+
```bash
|
|
244
|
+
djournal work list --active
|
|
245
|
+
djournal work bind 2026-08-14-01-example --session "$DJOURNAL_SESSION_ID"
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
If several work items are active and no session binding exists, the session-start
|
|
249
|
+
hook asks the agent to prompt for a choice instead of guessing from recency.
|
|
250
|
+
|
|
241
251
|
At session start, djournal reads a user-local npm release cache and reports a
|
|
242
252
|
known CLI or project-asset update every session until it is installed. Stale
|
|
243
253
|
release data is refreshed in the background at most once every 24 hours. Run
|
package/bin/journal.js
CHANGED
|
@@ -7,9 +7,11 @@ const { spawn } = require("node:child_process");
|
|
|
7
7
|
const {
|
|
8
8
|
InstallerError,
|
|
9
9
|
checkUpdates,
|
|
10
|
+
bindWork,
|
|
10
11
|
configure,
|
|
11
12
|
doctor,
|
|
12
13
|
install,
|
|
14
|
+
listWork,
|
|
13
15
|
pull,
|
|
14
16
|
share,
|
|
15
17
|
sync,
|
|
@@ -31,6 +33,8 @@ function usage() {
|
|
|
31
33
|
journal share [--target DIR] [--work SLUG | --all] [--dry-run] [--json]
|
|
32
34
|
journal pull [--target DIR] [--work SLUG] [--dry-run] [--json]
|
|
33
35
|
journal sync [--target DIR] [--work SLUG] [--dry-run] [--json]
|
|
36
|
+
journal work list [--target DIR] [--active] [--json]
|
|
37
|
+
journal work bind SLUG [--target DIR] [--session ID] [--dry-run] [--json]
|
|
34
38
|
journal update check [--target DIR] [--json]
|
|
35
39
|
|
|
36
40
|
Options:
|
|
@@ -38,6 +42,8 @@ Options:
|
|
|
38
42
|
--yes Disable interactive harness selection
|
|
39
43
|
--json Emit JSON
|
|
40
44
|
--work SLUG Select a journal work item instead of active state
|
|
45
|
+
--session ID Bind a journal work item to a specific session
|
|
46
|
+
--active Show only lifecycle-active work items for work list
|
|
41
47
|
--harness LIST Comma-separated codex,claude-code,pi selection
|
|
42
48
|
--all Select all work items for share, or every harness
|
|
43
49
|
--instructions-only Install core instructions without harness hooks
|
|
@@ -47,13 +53,20 @@ Options:
|
|
|
47
53
|
function parseArgs(argv) {
|
|
48
54
|
const args = [...argv];
|
|
49
55
|
const command = args.shift();
|
|
50
|
-
if (!command || !["install", "upgrade", "uninstall", "status", "doctor", "config", "share", "pull", "sync", "update"].includes(command)) {
|
|
56
|
+
if (!command || !["install", "upgrade", "uninstall", "status", "doctor", "config", "share", "pull", "sync", "update", "work"].includes(command)) {
|
|
51
57
|
throw new InstallerError(usage(), "USAGE");
|
|
52
58
|
}
|
|
53
59
|
const options = { command, harnesses: [] };
|
|
54
60
|
if (command === "update") {
|
|
55
61
|
options.subcommand = args.shift();
|
|
56
62
|
if (options.subcommand !== "check") throw new InstallerError("update requires the check subcommand", "USAGE");
|
|
63
|
+
} else if (command === "work") {
|
|
64
|
+
options.subcommand = args.shift();
|
|
65
|
+
if (!["list", "bind"].includes(options.subcommand)) throw new InstallerError("work requires the list or bind subcommand", "USAGE");
|
|
66
|
+
if (options.subcommand === "bind") {
|
|
67
|
+
if (!args.length || args[0].startsWith("-")) throw new InstallerError("work bind requires a work slug", "USAGE");
|
|
68
|
+
options.work = args.shift();
|
|
69
|
+
}
|
|
57
70
|
}
|
|
58
71
|
while (args.length) {
|
|
59
72
|
const arg = args.shift();
|
|
@@ -65,11 +78,16 @@ function parseArgs(argv) {
|
|
|
65
78
|
if (!args.length) throw new InstallerError("--work requires a value", "USAGE");
|
|
66
79
|
options.work = args.shift();
|
|
67
80
|
} else if (arg.startsWith("--work=")) options.work = arg.slice(7);
|
|
81
|
+
else if (arg === "--session") {
|
|
82
|
+
if (!args.length) throw new InstallerError("--session requires a value", "USAGE");
|
|
83
|
+
options.session = args.shift();
|
|
84
|
+
} else if (arg.startsWith("--session=")) options.session = arg.slice(10);
|
|
68
85
|
else if (arg === "--harness") {
|
|
69
86
|
if (!args.length) throw new InstallerError("--harness requires a value", "USAGE");
|
|
70
87
|
options.harnesses.push(...args.shift().split(",").filter(Boolean));
|
|
71
88
|
} else if (arg.startsWith("--harness=")) options.harnesses.push(...arg.slice(10).split(",").filter(Boolean));
|
|
72
89
|
else if (arg === "--all") options.all = true;
|
|
90
|
+
else if (arg === "--active") options.active = true;
|
|
73
91
|
else if (arg === "--instructions-only") options.instructionsOnly = true;
|
|
74
92
|
else if (arg === "--dry-run") options.dryRun = true;
|
|
75
93
|
else if (arg === "--auto") options.auto = true;
|
|
@@ -90,6 +108,9 @@ function parseArgs(argv) {
|
|
|
90
108
|
if (options.instructionsOnly && (options.all || options.harnesses.length)) {
|
|
91
109
|
throw new InstallerError("--instructions-only cannot be combined with harness selection", "USAGE");
|
|
92
110
|
}
|
|
111
|
+
if (options.active && !(command === "work" && options.subcommand === "list")) {
|
|
112
|
+
throw new InstallerError("--active is only supported for work list", "USAGE");
|
|
113
|
+
}
|
|
93
114
|
options.target = path.resolve(options.target || process.cwd());
|
|
94
115
|
options.sourceRoot = sourceRoot;
|
|
95
116
|
options.interactive = !options.yes && process.stdin.isTTY && process.stdout.isTTY;
|
|
@@ -111,6 +132,18 @@ function print(value, json) {
|
|
|
111
132
|
if (value.checkedAt) process.stdout.write(`checked: ${value.checkedAt}\n`);
|
|
112
133
|
return;
|
|
113
134
|
}
|
|
135
|
+
if (value.action === "work-list") {
|
|
136
|
+
if (value.selected) process.stdout.write(`selected: ${value.selected}\n`);
|
|
137
|
+
for (const item of value.workItems || []) {
|
|
138
|
+
const marker = item.selected ? "*" : " ";
|
|
139
|
+
process.stdout.write(`${marker} ${item.slug} [${item.status}] ${item.title}\n`);
|
|
140
|
+
}
|
|
141
|
+
return;
|
|
142
|
+
}
|
|
143
|
+
if (value.action === "work-bind") {
|
|
144
|
+
process.stdout.write(`bound ${value.work} to session ${value.sessionHash}\n`);
|
|
145
|
+
return;
|
|
146
|
+
}
|
|
114
147
|
if (value.action) process.stdout.write(`${value.action}: ${value.target}\n`);
|
|
115
148
|
else if (typeof value.installed === "boolean") process.stdout.write(value.installed ? `installed: ${value.target}\n` : `not installed: ${value.target}\n`);
|
|
116
149
|
else process.stdout.write(`${value.ok ? "ok" : "failed"}: ${value.target}\n`);
|
|
@@ -182,6 +215,8 @@ async function main() {
|
|
|
182
215
|
else if (options.command === "share") result = share(options);
|
|
183
216
|
else if (options.command === "pull") result = pull(options);
|
|
184
217
|
else if (options.command === "sync") result = sync(options);
|
|
218
|
+
else if (options.command === "work" && options.subcommand === "list") result = listWork(options);
|
|
219
|
+
else if (options.command === "work" && options.subcommand === "bind") result = bindWork(options);
|
|
185
220
|
else if (options.command === "update") {
|
|
186
221
|
result = await checkUpdates(options);
|
|
187
222
|
if (result.refreshNeeded) result.backgroundRefreshStarted = launchUpdateRefresh(options);
|
package/docs/architecture.md
CHANGED
|
@@ -10,6 +10,7 @@ The canonical journal lives in the user's djournal home, keyed by project:
|
|
|
10
10
|
```text
|
|
11
11
|
~/.djournal/projects/<project-key>/
|
|
12
12
|
config.json
|
|
13
|
+
sessions/ # local operational session bindings
|
|
13
14
|
.journal/
|
|
14
15
|
state.json
|
|
15
16
|
work/<work-item>/
|
|
@@ -47,7 +48,13 @@ Every work item has:
|
|
|
47
48
|
```
|
|
48
49
|
|
|
49
50
|
The frontmatter stores stable identity, title, status, visibility, authorship,
|
|
50
|
-
and timestamps.
|
|
51
|
+
and timestamps. Several work items may have lifecycle `status: active` at the
|
|
52
|
+
same time.
|
|
53
|
+
|
|
54
|
+
`state.json` stores the global fallback selected work item for backward
|
|
55
|
+
compatibility. Parallel sessions can bind to a different active work item using
|
|
56
|
+
local operational state under `sessions/`; those bindings are not durable
|
|
57
|
+
journal history and are not projected into shared `.journal/` content.
|
|
51
58
|
|
|
52
59
|
## Configuration
|
|
53
60
|
|
|
@@ -160,8 +167,11 @@ audit, reconciliation, and closure.
|
|
|
160
167
|
|
|
161
168
|
Hooks remind agents about the workflow, delegate configured synchronization
|
|
162
169
|
transport to the CLI, and validate final status markers. Hooks do not create
|
|
163
|
-
semantic journal entries. When `.djournal.json` exists, hooks read
|
|
164
|
-
and sync config from the global project store.
|
|
170
|
+
semantic journal entries. When `.djournal.json` exists, hooks read work context
|
|
171
|
+
and sync config from the global project store. If a session binding exists, the
|
|
172
|
+
hook reports that bound work item. If several work items are lifecycle-active and
|
|
173
|
+
no binding exists, the hook asks the agent to prompt the user before meaningful
|
|
174
|
+
work.
|
|
165
175
|
|
|
166
176
|
For Claude Code, install also injects a narrow permission grant into
|
|
167
177
|
`.claude/settings.json` for the exact global project store path and safe
|
|
@@ -18,6 +18,19 @@ At session start, the active work item gives the agent a compact context pack:
|
|
|
18
18
|
This lets future sessions start from shaped history rather than broad
|
|
19
19
|
exploration.
|
|
20
20
|
|
|
21
|
+
When several work items are still `active`, a new session should choose the one
|
|
22
|
+
it is working on before making meaningful changes. Bind a known session id to a
|
|
23
|
+
work item:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
djournal work list --active
|
|
27
|
+
djournal work bind 2026-08-14-01-example --session "$DJOURNAL_SESSION_ID"
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
If no session id is available, the agent should ask which active work item to
|
|
31
|
+
use and avoid guessing from recency. The global `state.json` selection remains a
|
|
32
|
+
fallback for older workflows.
|
|
33
|
+
|
|
21
34
|
When standalone automatic sync is enabled, session startup first pulls the
|
|
22
35
|
Git-backed journal and reconciles it into canonical storage. Work initialization
|
|
23
36
|
and switching also pull before enumerating available work, so a colleague can
|
package/lib/installer/index.js
CHANGED
|
@@ -587,6 +587,17 @@ function readActiveWork(context, requested) {
|
|
|
587
587
|
return { slug, relative, file, text, metadata, visibility: metadata.visibility || "local_only" };
|
|
588
588
|
}
|
|
589
589
|
|
|
590
|
+
function workSummary(context, slug) {
|
|
591
|
+
const work = readActiveWork(context, slug);
|
|
592
|
+
return {
|
|
593
|
+
slug: work.slug,
|
|
594
|
+
title: work.metadata.title || work.slug,
|
|
595
|
+
status: work.metadata.status || "unknown",
|
|
596
|
+
visibility: work.visibility,
|
|
597
|
+
selected: false,
|
|
598
|
+
};
|
|
599
|
+
}
|
|
600
|
+
|
|
590
601
|
function readAllWork(context) {
|
|
591
602
|
const workRoot = path.join(context.journalRoot, "work");
|
|
592
603
|
const entries = fs.existsSync(workRoot) ? fs.readdirSync(workRoot, { withFileTypes: true }) : [];
|
|
@@ -600,6 +611,53 @@ function readAllWork(context) {
|
|
|
600
611
|
return workItems;
|
|
601
612
|
}
|
|
602
613
|
|
|
614
|
+
function selectedWorkSlug(context) {
|
|
615
|
+
const state = parseJson(readOptional(path.join(context.journalRoot, "state.json")), ".journal/state.json");
|
|
616
|
+
return typeof state.active_work_name === "string" ? state.active_work_name : "";
|
|
617
|
+
}
|
|
618
|
+
|
|
619
|
+
function listWork(options) {
|
|
620
|
+
const target = checkTarget(options.target || process.cwd());
|
|
621
|
+
const context = projectContext(target, options);
|
|
622
|
+
const selected = selectedWorkSlug(context);
|
|
623
|
+
const workItems = readAllWork(context)
|
|
624
|
+
.map((work) => ({
|
|
625
|
+
slug: work.slug,
|
|
626
|
+
title: work.metadata.title || work.slug,
|
|
627
|
+
status: work.metadata.status || "unknown",
|
|
628
|
+
visibility: work.visibility,
|
|
629
|
+
selected: work.slug === selected,
|
|
630
|
+
}));
|
|
631
|
+
const filtered = options.active ? workItems.filter((work) => work.status === "active") : workItems;
|
|
632
|
+
return { action: "work-list", target, projectKey: context.projectKey, selected: selected || undefined, workItems: filtered };
|
|
633
|
+
}
|
|
634
|
+
|
|
635
|
+
function sessionId(options = {}) {
|
|
636
|
+
return options.session || process.env.DJOURNAL_SESSION_ID || "";
|
|
637
|
+
}
|
|
638
|
+
|
|
639
|
+
function sessionBindingFile(context, id) {
|
|
640
|
+
if (typeof id !== "string" || !id.trim()) throw new InstallerError("--session or DJOURNAL_SESSION_ID is required", "SESSION_REQUIRED");
|
|
641
|
+
return path.join(context.root, "sessions", `${sha256(id.trim())}.json`);
|
|
642
|
+
}
|
|
643
|
+
|
|
644
|
+
function bindWork(options) {
|
|
645
|
+
const target = checkTarget(options.target || process.cwd());
|
|
646
|
+
const context = projectContext(target, options);
|
|
647
|
+
const work = workSummary(context, options.work);
|
|
648
|
+
if (work.status !== "active") throw new InstallerError(`work item is not active: ${work.slug}`, "INVALID_WORK");
|
|
649
|
+
const id = sessionId(options);
|
|
650
|
+
const file = sessionBindingFile(context, id);
|
|
651
|
+
const binding = {
|
|
652
|
+
schemaVersion: SCHEMA_VERSION,
|
|
653
|
+
sessionHash: sha256(id.trim()),
|
|
654
|
+
activeWorkName: work.slug,
|
|
655
|
+
updatedAt: new Date().toISOString(),
|
|
656
|
+
};
|
|
657
|
+
if (!options.dryRun) writeJsonFile(file, binding);
|
|
658
|
+
return { action: "work-bind", target, projectKey: context.projectKey, work: work.slug, sessionHash: binding.sessionHash, dryRun: !!options.dryRun };
|
|
659
|
+
}
|
|
660
|
+
|
|
603
661
|
function readJournalConfig(target) {
|
|
604
662
|
const context = projectContext(target);
|
|
605
663
|
return readProjectConfig(context);
|
|
@@ -1360,12 +1418,14 @@ module.exports = {
|
|
|
1360
1418
|
SUPPORTED_HARNESSES,
|
|
1361
1419
|
applyTransaction,
|
|
1362
1420
|
checkUpdates,
|
|
1421
|
+
bindWork,
|
|
1363
1422
|
configure,
|
|
1364
1423
|
detectHarnesses,
|
|
1365
1424
|
doctor,
|
|
1366
1425
|
djournalHome,
|
|
1367
1426
|
install,
|
|
1368
1427
|
loadManifest,
|
|
1428
|
+
listWork,
|
|
1369
1429
|
pull,
|
|
1370
1430
|
projectContext,
|
|
1371
1431
|
recoverTransaction,
|