aligndev 0.28.1 → 0.30.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.
Files changed (50) hide show
  1. package/README.md +16 -6
  2. package/dist/alignfirst-cli.js +22 -10
  3. package/dist/cli.d.ts +2 -0
  4. package/dist/cli.js +14 -12
  5. package/dist/code/claude-agent.js +1 -1
  6. package/dist/code/code-cli.js +3 -5
  7. package/dist/code/codex-agent.js +1 -1
  8. package/dist/code/machine-id.js +14 -3
  9. package/dist/code/pi-agent.js +1 -1
  10. package/dist/code/run-agent.js +37 -1
  11. package/dist/command-form.d.ts +5 -2
  12. package/dist/command-form.js +15 -6
  13. package/dist/guide/code-guide.d.ts +2 -2
  14. package/dist/guide/code-guide.js +4 -8
  15. package/dist/guide/guide-cli.js +82 -30
  16. package/dist/guide/render-template.d.ts +4 -4
  17. package/dist/guide/render-template.js +42 -21
  18. package/dist/guide/topics.d.ts +8 -3
  19. package/dist/guide/topics.js +26 -7
  20. package/dist/project/discovery.js +5 -12
  21. package/dist/project/layout.d.ts +22 -9
  22. package/dist/project/layout.js +101 -28
  23. package/dist/project/plans.d.ts +1 -1
  24. package/dist/project/plans.js +1 -1
  25. package/dist/project/render.js +3 -1
  26. package/dist/project/status.d.ts +2 -2
  27. package/dist/project/status.js +2 -2
  28. package/package.json +5 -1
  29. package/templates/guide/code.md +12 -3
  30. package/templates/guide/playbook/channel-handling.md +12 -17
  31. package/templates/guide/playbook/consultation.md +27 -30
  32. package/templates/guide/playbook/dispatcher.md +18 -0
  33. package/templates/guide/playbook/{discord-message-tool.md → message-tool.md} +29 -0
  34. package/templates/guide/playbook/playbook.md +55 -25
  35. package/templates/guide/playbook/project-lifecycle.md +33 -18
  36. package/templates/guide/playbook/project-workspace-setup.md +91 -71
  37. package/templates/guide/playbook/work-files-setup.md +2 -2
  38. package/templates/guide/playbook/working-session.md +207 -158
  39. package/templates/guide/project.md +4 -4
  40. package/dist/guide/guide-file.d.ts +0 -3
  41. package/dist/guide/guide-file.js +0 -26
  42. package/dist/worktree/add.d.ts +0 -20
  43. package/dist/worktree/add.js +0 -175
  44. package/dist/worktree/git.d.ts +0 -24
  45. package/dist/worktree/git.js +0 -103
  46. package/dist/worktree/remove.d.ts +0 -8
  47. package/dist/worktree/remove.js +0 -62
  48. package/dist/worktree/worktree-cli.d.ts +0 -10
  49. package/dist/worktree/worktree-cli.js +0 -122
  50. package/templates/guide/playbook/slack-message-tool.md +0 -23
@@ -1,27 +1,40 @@
1
1
  import { PLATFORMS } from "../config.js";
2
2
  import { readTemplate } from "../templates.js";
3
- const GUIDE_FILE_CONDITIONS = ["developers", "readme", "noGuide"];
4
- // Active for both guide files: `developers` and `readme`.
5
- const HAS_GUIDE = "hasGuide";
3
+ export const SURFACES = ["slack", "discord", "app"];
4
+ // Derived facts: `thread` holds on Slack and Discord; `conversation` in an app conversation and
5
+ // under codingAgent.
6
+ const THREAD = "thread";
7
+ const CONVERSATION = "conversation";
6
8
  const MARKER = /^\{\{([#/])([A-Za-z]+)\}\}$/;
7
- // Renders `templates/guide/<name>`: the blocks first, then the placeholders — the command forms
8
- // and every key of `values`.
9
+ // Renders `templates/guide/<name>`: the blocks first, then the placeholders — the command forms,
10
+ // the guide command of the render, and every key of `values`.
9
11
  export function renderGuideTemplate(name, active, forms, values = {}) {
10
12
  const placeholders = {
11
13
  ALIGNDEV: forms.aligndev,
12
14
  ALIGNFIRST: forms.alignfirst,
15
+ ...guidePlaceholder(active, forms),
16
+ BACKGROUND_COMMAND_JSON: JSON.stringify(`${forms.aligndev} code new --message-file '/tmp/aligndev-request.txt' --quiet --meta 'a20bc7c1-c056-4d07-8cc2-90fe491a6df6'`),
13
17
  ...values,
14
18
  };
15
19
  let text = renderBlocks(readTemplate(`guide/${name}`), active, name);
16
20
  for (const [key, value] of Object.entries(placeholders)) {
17
- text = text.replaceAll(`{{${key}}}`, value);
21
+ text = text.replaceAll(`{{${key}}}`, () => value);
18
22
  }
19
23
  return text.trimEnd();
20
24
  }
21
- // A block is `{{#<name>}}` … `{{/<name>}}`, each marker alone on its line. A platform block sits
22
- // at the top level; a condition block sits directly inside a `codingAgent` block. A line
23
- // is kept when every block around it is active. The runs of empty lines that removed blocks leave
24
- // collapse to one.
25
+ // `{{GUIDE}}` carries the surface into every later guide call. An OpenClaw render without a surface
26
+ // has none.
27
+ function guidePlaceholder(active, forms) {
28
+ if (active.surface !== undefined) {
29
+ return { GUIDE: `${forms.aligndev} guide --channel ${active.surface}` };
30
+ }
31
+ return active.platform === "codingAgent" ? { GUIDE: `${forms.aligndev} guide` } : {};
32
+ }
33
+ // A block is `{{#<name>}}` … `{{/<name>}}`, each marker alone on its line, and names a fact. A
34
+ // platform block sits at the top level. A surface block and `thread` never sit inside a
35
+ // `codingAgent` block; `conversation` sits anywhere.
36
+ // A line is kept when every block around it holds. The runs of empty lines that removed blocks
37
+ // leave collapse to one.
25
38
  export function renderBlocks(text, active, templateName) {
26
39
  const kept = [];
27
40
  const open = [];
@@ -46,40 +59,48 @@ export function renderBlocks(text, active, templateName) {
46
59
  return collapseEmptyLines(kept).join("\n");
47
60
  }
48
61
  function isActive(name, active) {
49
- if (name === HAS_GUIDE)
50
- return active.guideFile === "developers" || active.guideFile === "readme";
51
- return name === active.platform || name === active.guideFile;
62
+ if (name === THREAD)
63
+ return active.surface === "slack" || active.surface === "discord";
64
+ if (name === CONVERSATION)
65
+ return active.surface === "app" || active.platform === "codingAgent";
66
+ return name === active.platform || name === active.surface;
52
67
  }
53
68
  function openBlock(name, line, open, templateName) {
54
- const outer = open.at(-1);
69
+ const insideCodingAgent = open.some((block) => block.name === "codingAgent");
55
70
  if (isPlatform(name)) {
71
+ const outer = open.at(-1);
56
72
  if (outer !== undefined) {
57
73
  throw blockError(templateName, line, `platform block "${name}" inside "${outer.name}"`);
58
74
  }
59
75
  return { name, line };
60
76
  }
61
- if (isCondition(name)) {
62
- if (outer?.name !== "codingAgent") {
63
- throw blockError(templateName, line, `condition block "${name}" outside a codingAgent block`);
77
+ if (isSurface(name) || name === THREAD) {
78
+ if (insideCodingAgent) {
79
+ const block = isSurface(name) ? `surface block "${name}"` : `block "${name}"`;
80
+ throw blockError(templateName, line, `${block} inside a codingAgent block`);
64
81
  }
65
82
  return { name, line };
66
83
  }
84
+ if (name === CONVERSATION)
85
+ return { name, line };
67
86
  throw blockError(templateName, line, `unknown block "${name}"`);
68
87
  }
69
88
  function closeBlock(name, line, open, templateName) {
70
- if (!isPlatform(name) && !isCondition(name)) {
89
+ if (!isBlockName(name))
71
90
  throw blockError(templateName, line, `unknown block "${name}"`);
72
- }
73
91
  if (open.at(-1)?.name !== name) {
74
92
  throw blockError(templateName, line, `closing marker "${name}" without its block`);
75
93
  }
76
94
  open.pop();
77
95
  }
96
+ function isBlockName(name) {
97
+ return isPlatform(name) || isSurface(name) || name === THREAD || name === CONVERSATION;
98
+ }
78
99
  function isPlatform(name) {
79
100
  return PLATFORMS.includes(name);
80
101
  }
81
- function isCondition(name) {
82
- return name === HAS_GUIDE || GUIDE_FILE_CONDITIONS.includes(name);
102
+ export function isSurface(name) {
103
+ return SURFACES.includes(name);
83
104
  }
84
105
  function blockError(templateName, line, detail) {
85
106
  return new Error(`Error: template ${templateName}, line ${line}: ${detail}.`);
@@ -1,3 +1,8 @@
1
- import type { Platform } from "../config.js";
2
- export declare const PLAYBOOK_DISPATCHER = "playbook";
3
- export declare const PLAYBOOK_TOPICS: Record<Platform, readonly string[]>;
1
+ import { type ActiveBlocks, type Surface } from "./render-template.js";
2
+ export declare const PLAYBOOK_DISPATCHER = "dispatcher";
3
+ export declare const PLAYBOOK = "playbook";
4
+ export declare const ENTRY_TOPICS: readonly string[];
5
+ export declare const PLAYBOOK_TOPICS: Record<GuideContext, readonly string[]>;
6
+ export type GuideContext = "thread" | "app" | "codingAgent";
7
+ export declare function guideContextOf(active: ActiveBlocks): GuideContext;
8
+ export declare function surfacesServing(topic: string): Surface[];
@@ -1,17 +1,36 @@
1
- // The template rendered by `aligndev guide` without a topic.
2
- export const PLAYBOOK_DISPATCHER = "playbook";
3
- // The playbook topics each platform serves. Every topic is one file of `templates/guide/playbook/`,
4
- // shared by the platforms through platform blocks.
1
+ import { SURFACES } from "./render-template.js";
2
+ // `templates/guide/playbook/dispatcher.md`, printed by `aligndev guide` without a topic.
3
+ export const PLAYBOOK_DISPATCHER = "dispatcher";
4
+ // `templates/guide/playbook/playbook.md`, the operating instructions.
5
+ export const PLAYBOOK = "playbook";
6
+ // The topics printed after the playbook.
7
+ export const ENTRY_TOPICS = ["working-session", "channel-handling"];
8
+ // The playbook topics each context serves. Every topic is one file of `templates/guide/playbook/`,
9
+ // shared by the contexts through fact blocks.
5
10
  export const PLAYBOOK_TOPICS = {
6
- openclaw: [
11
+ thread: [
7
12
  "channel-handling",
8
13
  "working-session",
9
14
  "work-files-setup",
10
15
  "project-workspace-setup",
11
16
  "project-lifecycle",
12
17
  "consultation",
13
- "slack-message-tool",
14
- "discord-message-tool",
18
+ "message-tool",
19
+ ],
20
+ app: [
21
+ "working-session",
22
+ "work-files-setup",
23
+ "project-workspace-setup",
24
+ "project-lifecycle",
25
+ "consultation",
15
26
  ],
16
27
  codingAgent: ["working-session", "work-files-setup", "project-workspace-setup", "consultation"],
17
28
  };
29
+ export function guideContextOf(active) {
30
+ if (active.platform === "codingAgent")
31
+ return "codingAgent";
32
+ return active.surface === "app" ? "app" : "thread";
33
+ }
34
+ export function surfacesServing(topic) {
35
+ return SURFACES.filter((surface) => PLAYBOOK_TOPICS[guideContextOf({ platform: "openclaw", surface })].includes(topic));
36
+ }
@@ -1,10 +1,10 @@
1
- import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
1
+ import { lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
2
2
  import { basename, dirname, join, resolve, sep } from "node:path";
3
3
  import { isNodeError } from "../errors.js";
4
4
  import { formatRange } from "./format.js";
5
5
  import { readProjectReport } from "./layout.js";
6
6
  import { containsRange, rangesOverlap, readMarker, } from "./markers.js";
7
- const PROJECT_CONFIG_FILENAME = ".alignfirst.json";
7
+ const CONFIG_FILENAMES = ["alignfirst.json", "alignfirst.jsonc"];
8
8
  export function buildInventory(root, marker, ctx) {
9
9
  const state = { directories: [], candidates: [], directoryClaims: [], issues: [] };
10
10
  walkProjectsDirectory(root, marker, undefined, state);
@@ -68,7 +68,7 @@ function classifyCandidates(state, ctx) {
68
68
  }
69
69
  function classifyCandidate(candidate, state, ctx) {
70
70
  if (mainWorktreeGitDirectory(candidate.path) === undefined) {
71
- if (existsSync(join(candidate.path, PROJECT_CONFIG_FILENAME))) {
71
+ if (CONFIG_FILENAMES.some((name) => lstatSync(join(candidate.path, name), { throwIfNoEntry: false }) !== undefined)) {
72
72
  state.issues.push({ path: candidate.path, message: "not a git main worktree" });
73
73
  }
74
74
  else {
@@ -86,21 +86,14 @@ function classifyCandidate(candidate, state, ctx) {
86
86
  path: candidate.path,
87
87
  directory: candidate.directory,
88
88
  description,
89
- ...(description.config?.portRange === undefined
89
+ ...(description.workspace.portRange === null
90
90
  ? {}
91
- : { portRange: description.config.portRange }),
91
+ : { portRange: description.workspace.portRange }),
92
92
  workspaces: [],
93
93
  };
94
94
  const enclosingRange = findEnclosingRange(candidate.enclosingRanges, project.portRange);
95
95
  if (enclosingRange?.code !== undefined)
96
96
  project.portRangeCode = enclosingRange.code;
97
- if (description.cli !== null && !description.cli.satisfied) {
98
- state.issues.push({
99
- path: candidate.path,
100
- message: `AlignFirst CLI ${description.cli.installed} does not satisfy required range ` +
101
- description.cli.range,
102
- });
103
- }
104
97
  reportOutsideRange(project.path, project.portRange, candidate.enclosingRanges, state.issues);
105
98
  return [project];
106
99
  }
@@ -1,33 +1,46 @@
1
1
  import type { PortRange } from "./markers.js";
2
- export type ItemName = ".alignfirst.json" | ".alignfirst-instructions" | "DEVELOPERS.md" | "docs" | ".plans" | "_aligndev";
2
+ export type ItemName = "alignfirst" | ".alignfirst-instructions" | "developerInstructions" | "workspaceRuntime" | "docs" | ".plans" | "_aligndev";
3
3
  export interface ProjectReport {
4
4
  source: ConfigSource | null;
5
- cli: ProjectCliReport | null;
5
+ workspace: WorkspaceConfigReport;
6
6
  config: ProjectConfigView | null;
7
7
  companion: CompanionReport | null;
8
8
  aligndev: AligndevProjectSettings | null;
9
- locations: Record<ItemName, ItemLocation>;
9
+ locations: ProjectLocations;
10
+ selectionOrigins: Record<ItemName, SelectionOrigin>;
10
11
  }
12
+ export type SelectionOrigin = "item" | "defaultLocation" | "builtin";
13
+ export type ProjectLocations = Record<Exclude<ItemName, "developerInstructions">, ItemLocation> & {
14
+ developerInstructions: ItemLocation | null;
15
+ };
11
16
  export interface AligndevProjectSettings {
12
17
  profile: string;
13
18
  }
14
19
  export type ConfigSource = "project" | "companion";
15
- export interface ProjectCliReport {
16
- installed: string;
17
- range: string;
18
- satisfied: boolean;
20
+ export interface WorkspaceConfigReport {
21
+ location: ItemLocation;
22
+ registryDir: string;
23
+ runtimeDir: string;
24
+ schemaVersion: number | null;
25
+ portRange: PortRange | null;
26
+ hasDevServer: boolean;
19
27
  }
20
28
  export interface ProjectConfigView {
21
- ticketIdPattern?: string;
29
+ conventions?: {
30
+ ticketIdPattern?: string;
31
+ };
32
+ developerInstructions?: string;
22
33
  plans?: {
23
34
  repositoryFolder?: string;
24
35
  };
25
- portRange?: PortRange;
26
36
  }
27
37
  export interface CompanionReport {
28
38
  dir: string;
29
39
  exists: boolean;
40
+ defaultLocation: "project" | "companion" | "auto";
41
+ items: Record<ItemName, ItemSetting>;
30
42
  }
43
+ export type ItemSetting = "project" | "companion" | "auto";
31
44
  export interface ItemLocation {
32
45
  path: string;
33
46
  in: "project" | "companion";
@@ -30,22 +30,32 @@ function firstLine(value) {
30
30
  function isOutdatedReport(value) {
31
31
  return (isRecord(value) &&
32
32
  (!Object.hasOwn(value, "aligndev") ||
33
- !(isRecord(value.locations) && ".alignfirst-instructions" in value.locations)));
33
+ !Object.hasOwn(value, "workspace") ||
34
+ !Object.hasOwn(value, "selectionOrigins") ||
35
+ !(isRecord(value.locations) &&
36
+ "alignfirst" in value.locations &&
37
+ ".alignfirst-instructions" in value.locations &&
38
+ "developerInstructions" in value.locations &&
39
+ "workspaceRuntime" in value.locations &&
40
+ isRecord(value.workspace) &&
41
+ "registryDir" in value.workspace &&
42
+ "runtimeDir" in value.workspace)));
34
43
  }
35
44
  function outdatedAlignfirst(path) {
36
- return (`The alignfirst CLI used in ${path} is too old: aligndev requires the profile-aware ` +
37
- 'alignfirst config --json contract (top-level "aligndev"). Upgrade alignfirst.');
45
+ return (`The alignfirst CLI used in ${path} is too old: aligndev requires the workspace-aware ` +
46
+ "alignfirst config --json contract (merged configuration, developerInstructions, workspaceRuntime and selectionOrigins). Upgrade alignfirst.");
38
47
  }
39
48
  function parseProjectReport(value, path) {
40
49
  if (!isRecord(value))
41
50
  throw invalidReport(path);
42
51
  return {
43
52
  source: parseSource(value.source, path),
44
- cli: parseCli(value.cli, path),
53
+ workspace: parseWorkspace(value.workspace, path),
45
54
  config: parseConfig(value.config, path),
46
55
  companion: parseCompanion(value.companion, path),
47
56
  aligndev: parseAligndev(value.aligndev, path),
48
57
  locations: parseLocations(value.locations, path),
58
+ selectionOrigins: parseSelectionOrigins(value.selectionOrigins, path),
49
59
  };
50
60
  }
51
61
  function parseAligndev(value, path) {
@@ -63,33 +73,54 @@ function parseSource(value, path) {
63
73
  return value;
64
74
  throw invalidReport(path);
65
75
  }
66
- function parseCli(value, path) {
67
- if (value === null)
68
- return null;
69
- if (!isRecord(value) ||
70
- typeof value.installed !== "string" ||
71
- typeof value.range !== "string" ||
72
- typeof value.satisfied !== "boolean") {
76
+ function parseWorkspace(value, path) {
77
+ if (!isRecord(value))
73
78
  throw invalidReport(path);
74
- }
75
- return { installed: value.installed, range: value.range, satisfied: value.satisfied };
79
+ const location = parseLocation(value.location, path);
80
+ if (typeof value.registryDir !== "string" ||
81
+ !value.registryDir.startsWith("/") ||
82
+ typeof value.runtimeDir !== "string" ||
83
+ !value.runtimeDir.startsWith("/") ||
84
+ (value.schemaVersion !== null && value.schemaVersion !== 1) ||
85
+ (value.portRange !== null && !isPortRange(value.portRange)) ||
86
+ typeof value.hasDevServer !== "boolean")
87
+ throw invalidReport(path);
88
+ if (!location.exists &&
89
+ (value.schemaVersion !== null || value.portRange !== null || value.hasDevServer))
90
+ throw invalidReport(path);
91
+ if (location.exists && value.schemaVersion !== 1)
92
+ throw invalidReport(path);
93
+ if (!value.hasDevServer && value.portRange !== null)
94
+ throw invalidReport(path);
95
+ return {
96
+ location,
97
+ registryDir: value.registryDir,
98
+ runtimeDir: value.runtimeDir,
99
+ schemaVersion: value.schemaVersion,
100
+ portRange: value.portRange,
101
+ hasDevServer: value.hasDevServer,
102
+ };
76
103
  }
77
104
  function parseConfig(value, path) {
78
105
  if (value === null)
79
106
  return null;
80
- if (!isRecord(value))
107
+ if (!isRecord(value) || Object.hasOwn(value, "cli") || Object.hasOwn(value, "portRange"))
108
+ throw invalidReport(path);
109
+ if (Object.hasOwn(value, "ticketIdPattern") || Object.hasOwn(value, "git"))
110
+ throw invalidReport(path);
111
+ if (value.conventions !== undefined && !isRecord(value.conventions))
112
+ throw invalidReport(path);
113
+ const ticketIdPattern = value.conventions?.ticketIdPattern;
114
+ const developerInstructions = value.developerInstructions;
115
+ if (developerInstructions !== undefined && typeof developerInstructions !== "string")
81
116
  throw invalidReport(path);
82
- const ticketIdPattern = value.ticketIdPattern;
83
117
  const plans = parsePlans(value.plans, path);
84
- const portRange = value.portRange;
85
118
  if (ticketIdPattern !== undefined && typeof ticketIdPattern !== "string")
86
119
  throw invalidReport(path);
87
- if (portRange !== undefined && !isPortRange(portRange))
88
- throw invalidReport(path);
89
120
  return {
90
- ...(ticketIdPattern === undefined ? {} : { ticketIdPattern }),
121
+ ...(ticketIdPattern === undefined ? {} : { conventions: { ticketIdPattern } }),
122
+ ...(developerInstructions === undefined ? {} : { developerInstructions }),
91
123
  ...(plans === undefined ? {} : { plans }),
92
- ...(portRange === undefined ? {} : { portRange }),
93
124
  };
94
125
  }
95
126
  function parsePlans(value, path) {
@@ -97,34 +128,69 @@ function parsePlans(value, path) {
97
128
  return;
98
129
  if (!isRecord(value))
99
130
  throw invalidReport(path);
100
- // Before alignfirst 0.12.0, the report named this key `folder`.
101
- const repositoryFolder = value.repositoryFolder ?? value.folder;
131
+ if (Object.hasOwn(value, "folder"))
132
+ throw invalidReport(path);
133
+ const repositoryFolder = value.repositoryFolder;
102
134
  if (repositoryFolder !== undefined && typeof repositoryFolder !== "string")
103
135
  throw invalidReport(path);
104
136
  return repositoryFolder === undefined ? {} : { repositoryFolder };
105
137
  }
106
- // The report's other companion fields (`key`, `items`) are alignfirst's concern.
138
+ // Registry keys remain AlignFirst's concern; carry effective placement and its origins.
107
139
  function parseCompanion(value, path) {
108
140
  if (value === null)
109
141
  return null;
110
142
  if (!isRecord(value) || typeof value.dir !== "string" || typeof value.exists !== "boolean") {
111
143
  throw invalidReport(path);
112
144
  }
113
- return { dir: value.dir, exists: value.exists };
145
+ if (value.defaultLocation !== "auto" &&
146
+ value.defaultLocation !== "project" &&
147
+ value.defaultLocation !== "companion")
148
+ throw invalidReport(path);
149
+ if (!isRecord(value.items))
150
+ throw invalidReport(path);
151
+ const items = parseItemRecord(value.items, path, (setting) => {
152
+ if (setting !== "auto" && setting !== "project" && setting !== "companion")
153
+ throw invalidReport(path);
154
+ return setting;
155
+ });
156
+ if (items._aligndev === "project")
157
+ throw invalidReport(path);
158
+ return { dir: value.dir, exists: value.exists, defaultLocation: value.defaultLocation, items };
114
159
  }
115
160
  function parseLocations(value, path) {
116
161
  if (!isRecord(value))
117
162
  throw invalidReport(path);
118
163
  const location = (name) => parseLocation(value[name], path);
119
164
  return {
120
- ".alignfirst.json": location(".alignfirst.json"),
165
+ alignfirst: location("alignfirst"),
121
166
  ".alignfirst-instructions": location(".alignfirst-instructions"),
122
- "DEVELOPERS.md": location("DEVELOPERS.md"),
167
+ developerInstructions: value.developerInstructions === null ? null : location("developerInstructions"),
168
+ workspaceRuntime: location("workspaceRuntime"),
123
169
  docs: location("docs"),
124
170
  ".plans": location(".plans"),
125
171
  _aligndev: location("_aligndev"),
126
172
  };
127
173
  }
174
+ function parseSelectionOrigins(value, path) {
175
+ return parseItemRecord(value, path, (origin) => {
176
+ if (origin !== "item" && origin !== "defaultLocation" && origin !== "builtin")
177
+ throw invalidReport(path);
178
+ return origin;
179
+ });
180
+ }
181
+ function parseItemRecord(value, path, parse) {
182
+ if (!isRecord(value))
183
+ throw invalidReport(path);
184
+ return {
185
+ alignfirst: parse(value.alignfirst),
186
+ ".alignfirst-instructions": parse(value[".alignfirst-instructions"]),
187
+ developerInstructions: parse(value.developerInstructions),
188
+ workspaceRuntime: parse(value.workspaceRuntime),
189
+ docs: parse(value.docs),
190
+ ".plans": parse(value[".plans"]),
191
+ _aligndev: parse(value._aligndev),
192
+ };
193
+ }
128
194
  function parseLocation(value, path) {
129
195
  if (!isRecord(value) ||
130
196
  typeof value.path !== "string" ||
@@ -138,7 +204,14 @@ function invalidReport(path) {
138
204
  return new Error(`Invalid alignfirst config report for ${path}`);
139
205
  }
140
206
  function isPortRange(value) {
141
- return isRecord(value) && typeof value.first === "number" && typeof value.last === "number";
207
+ return (isRecord(value) &&
208
+ typeof value.first === "number" &&
209
+ typeof value.last === "number" &&
210
+ Number.isInteger(value.first) &&
211
+ Number.isInteger(value.last) &&
212
+ value.first >= 1 &&
213
+ value.last <= 65535 &&
214
+ value.first <= value.last);
142
215
  }
143
216
  function isRecord(value) {
144
217
  return typeof value === "object" && value !== null;
@@ -147,6 +220,6 @@ function isRecord(value) {
147
220
  export function companionInUse(report, items) {
148
221
  return items.some((item) => {
149
222
  const location = report.locations[item];
150
- return location.in === "companion" && location.exists;
223
+ return location?.in === "companion" && location.exists;
151
224
  });
152
225
  }
@@ -1,5 +1,5 @@
1
1
  import type { CommandForms } from "../command-form.js";
2
- import type { GitContext } from "../worktree/git.js";
2
+ import type { GitContext } from "@alignfirst/workspace/git";
3
3
  import { type ProjectReport } from "./layout.js";
4
4
  export interface PlansContext extends GitContext {
5
5
  alignfirstCommand: string[];
@@ -26,7 +26,7 @@ export function validateEffectivePlans(ctx) {
26
26
  return value.plans.target;
27
27
  }
28
28
  catch (error) {
29
- throw new Error(`${errorMessage(error)}\nSee \`${ctx.forms.aligndev} guide work-files-setup\` for authorized preparation.`);
29
+ throw new Error(`${errorMessage(error)}\nSee the \`work-files-setup\` topic of \`${ctx.forms.aligndev} guide\` for authorized preparation.`);
30
30
  }
31
31
  }
32
32
  function isRecord(value) {
@@ -88,7 +88,7 @@ export function renderProjectStatus(details) {
88
88
  ` Config source: ${details.configSource ?? "(none)"}`,
89
89
  ` Companion: ${renderCompanion(details.companion)}`,
90
90
  ` AlignDev profile: ${renderNullableValue(details.aligndev?.profile ?? null)}`,
91
- ` DEVELOPERS.md: ${renderLocation(details.locations["DEVELOPERS.md"])}`,
91
+ ` Developer instructions: ${renderLocation(details.locations.developerInstructions)}`,
92
92
  ` Work files: ${renderLocation(details.locations[".plans"])}`,
93
93
  ` Work-files folder: ${renderNullableValue(details.plansFolder)}`,
94
94
  ` Ticket id pattern: ${renderNullableValue(details.ticketIdPattern)}`,
@@ -108,6 +108,8 @@ function renderCompanion(companion) {
108
108
  return renderPath(companion.dir, companion.exists);
109
109
  }
110
110
  function renderLocation(location) {
111
+ if (location === null)
112
+ return "(not configured)";
111
113
  return renderPath(location.path, location.exists);
112
114
  }
113
115
  function renderPath(path, exists) {
@@ -1,5 +1,5 @@
1
1
  import type { ProjectInventory } from "./discovery.js";
2
- import type { AligndevProjectSettings, CompanionReport, ConfigSource, ItemLocation, ItemName } from "./layout.js";
2
+ import type { AligndevProjectSettings, CompanionReport, ConfigSource, ProjectLocations } from "./layout.js";
3
3
  import type { PortRange } from "./markers.js";
4
4
  export interface ProjectDetails {
5
5
  name: string;
@@ -13,7 +13,7 @@ export interface ProjectDetails {
13
13
  configSource: ConfigSource | null;
14
14
  companion: CompanionReport | null;
15
15
  aligndev: AligndevProjectSettings | null;
16
- locations: Record<ItemName, ItemLocation>;
16
+ locations: ProjectLocations;
17
17
  workspaces: string[];
18
18
  worktrees: ProjectWorktree[];
19
19
  }
@@ -1,7 +1,7 @@
1
1
  import { execFileSync } from "node:child_process";
2
2
  import { realpathSync } from "node:fs";
3
3
  import { basename } from "node:path";
4
- import { readWorktrees } from "../worktree/git.js";
4
+ import { readWorktrees } from "@alignfirst/workspace/git";
5
5
  import { errorMessage, isNodeError } from "../errors.js";
6
6
  const URL_WITH_AUTHORITY = /^[A-Za-z][A-Za-z\d+.-]*:\/\//u;
7
7
  export function getProjectStatus(inventory, projectPath) {
@@ -32,7 +32,7 @@ function buildProjectDetails(project) {
32
32
  portRange: project.portRange ?? null,
33
33
  portRangeCode: project.portRangeCode ?? null,
34
34
  plansFolder: project.description.config?.plans?.repositoryFolder ?? null,
35
- ticketIdPattern: project.description.config?.ticketIdPattern ?? null,
35
+ ticketIdPattern: project.description.config?.conventions?.ticketIdPattern ?? null,
36
36
  configSource: project.description.source,
37
37
  companion: project.description.companion,
38
38
  aligndev: project.description.aligndev,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "aligndev",
3
- "version": "0.28.1",
3
+ "version": "0.30.0",
4
4
  "license": "CC0-1.0",
5
5
  "author": "Thomas MUR",
6
6
  "description": "The AlignDev CLI: the assistant's playbook, coding-agent delegation, and project inventory.",
@@ -37,6 +37,10 @@
37
37
  "publishConfig": {
38
38
  "access": "public"
39
39
  },
40
+ "dependencies": {
41
+ "@alignfirst/docmap": "~0.12.0",
42
+ "@alignfirst/workspace": "~0.42.0"
43
+ },
40
44
  "devDependencies": {
41
45
  "@types/node": "~26.6.5",
42
46
  "rimraf": "~6.1.3",
@@ -9,7 +9,7 @@ Run a coding agent through AlignFirst protocols with `{{ALIGNDEV}} code`. It wra
9
9
 
10
10
  **Never implement, investigate, or modify the codebase yourself. Your role is to delegate and guide the agent.**
11
11
 
12
- Run `{{ALIGNDEV}} code` from the root of the selected worktree, so the agent works in the right repository. The project must have usable `.plans/`, in the repository or in its companion directory: `{{ALIGNFIRST}} plans check` verifies it, and `{{ALIGNDEV}} guide work-files-setup` prepares it.
12
+ Run `{{ALIGNDEV}} code` from the root of the selected worktree, so the agent works in the right repository. The project must have usable `.plans/`, in the repository or in its companion directory: `{{ALIGNFIRST}} plans check` verifies it, and `{{GUIDE}} work-files-setup` prepares it.
13
13
 
14
14
  {{ALIGNFIRST_SETUP}}
15
15
 
@@ -29,7 +29,12 @@ Under OpenClaw, background it through the `exec` tool:
29
29
 
30
30
  `{{ALIGNDEV}} code <command> <options> ; openclaw system event --text "aligndev code run finished — read its session file and report to the user" --mode now --session-key <KEY>`
31
31
 
32
+ {{#thread}}
32
33
  Chain with `;` (never `&&`) so a failed run wakes you too, and keep the `;` on the same line as the `{{ALIGNDEV}} code` command: a line that starts with `;` is a shell syntax error, the wake command never runs, and the run's completion is lost. The wake may reach you as a bare heartbeat with the text dropped, and OpenClaw's own `Exec completed` notice may lag behind it. Never wait for either text.
34
+ {{/thread}}
35
+ {{#app}}
36
+ Chain with `;` (never `&&`) so a failed run wakes you too, and keep the `;` on the same line as the `{{ALIGNDEV}} code` command: a line that starts with `;` is a shell syntax error, the wake command never runs, and the run's completion is lost. The wake may reach you as a bare heartbeat with the text dropped. Never wait for its text.
37
+ {{/app}}
33
38
  - Pass `background: true` and `timeoutSeconds: 0` (no kill timer). Never rely on the auto-yield or a finite timeout.
34
39
  - For a run launched without `--ticket` or `--no-ticket`, pass `--meta <KEY>` with this session's key. `{{ALIGNDEV}} code status --meta <KEY>` then finds its result among concurrent runs in the shared main worktree.
35
40
  - Set the exec `workdir` to the project root as an **absolute** path (`~` is not expanded there), or `cd` into the project inside the command itself.
@@ -42,6 +47,10 @@ As soon as the run is backgrounded, tell the user — in the user's language —
42
47
  ## After a background run completes
43
48
 
44
49
  The chained wake fires when the backgrounded `{{ALIGNDEV}} code` exits. This session receives a heartbeat, often as a plain heartbeat poll with no message text. A run counts as pending while it is running **and until its outcome is reported**.
50
+ {{#app}}
51
+
52
+ In this conversation, the run's exit brings two turns, about ten seconds apart: OpenClaw's `Exec completed` notice, then the chained wake as a heartbeat. Both are completion wakes. The first finds the run pending and reports it; the second finds it reported.
53
+ {{/app}}
45
54
 
46
55
  **First, decide whether this heartbeat needs a report.** A heartbeat is a completion wake only while a run is pending. Once you have reported the outcome, later heartbeats for that run need nothing. End them with exactly `HEARTBEAT_OK`, alone.
47
56
 
@@ -54,7 +63,7 @@ Any heartbeat received while an `{{ALIGNDEV}} code` run is **still pending** ent
54
63
 
55
64
  For a consultation, answer it directly from the findings; include a failure or uncertainty when relevant. The coding-run template above is for change reports.
56
65
 
57
- The report is the plain text that ends the turn, on Slack and Discord alike. It must be the turn's **final message**: text written between tool calls may never post. Never follow it with `NO_REPLY`, `HEARTBEAT_OK`, a duplicate message-tool post, or another tool call.
66
+ The report is the plain text that ends the turn. It must be the turn's **final message**: text written between tool calls may never post. Never follow it with `NO_REPLY`, `HEARTBEAT_OK`, a duplicate message-tool post, or another tool call.
58
67
  3. **Don't reconstruct what happened.** Verifying the result is what your operating instructions prescribe; re-deriving the run's story is not: no re-running the agent, no fetch/merge, no `git` archaeology to double-check its account — the session file is authoritative for that.
59
68
 
60
69
  Reporting the run is not calling the work done: the report relays the agent's claim plus what you verified. When your verification finds a failing check, the report says so, and the fix is new work — a fresh run with its own completion wake; the wake you were answering is discharged by your report.
@@ -89,7 +98,7 @@ Retain these distinct values for each run:
89
98
  Prepare the literal delegated prompt in a UTF-8 file, then launch the ordinary quoted shell command through `background` with `action: "start"` and `cwd`. Supply `--quiet --meta <unique-run-key>` yourself; the extension never parses or appends CLI options. This example assumes `/tmp/aligndev-request.txt` already contains the request. Generate a fresh key for every actual launch; the UUID below illustrates one run:
90
99
 
91
100
  ```json
92
- {"action":"start","command":"{{ALIGNDEV}} code new --message-file '/tmp/aligndev-request.txt' --quiet --meta 'a20bc7c1-c056-4d07-8cc2-90fe491a6df6'","cwd":"/srv/projects/example","label":"coding run"}
101
+ {"action":"start","command":{{BACKGROUND_COMMAND_JSON}},"cwd":"/srv/projects/example","label":"coding run"}
93
102
  ```
94
103
 
95
104
  For resume, use `{{ALIGNDEV}} code resume <sessionId> --message-file <path> --quiet --meta <fresh-run-key>` from the original worktree. A Pi child must resume from its recorded directory. Use safe shell quoting for paths and options; never interpolate raw user text into a command. A quoted heredoc with `--message-file -` is another literal-input route.