self-evolving-workflow 0.0.0-stage → 0.1.3

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 (173) hide show
  1. package/LICENSE +27 -0
  2. package/README.md +90 -2
  3. package/dist/agent-memory-prompts.d.ts +13 -0
  4. package/dist/agent-memory-prompts.js +55 -0
  5. package/dist/cli.d.ts +2 -0
  6. package/dist/cli.js +6 -0
  7. package/dist/closeout.d.ts +105 -0
  8. package/dist/closeout.js +479 -0
  9. package/dist/code.d.ts +39 -0
  10. package/dist/code.js +124 -0
  11. package/dist/common.d.ts +9 -0
  12. package/dist/common.js +42 -0
  13. package/dist/context-envelope.d.ts +59 -0
  14. package/dist/context-envelope.js +23 -0
  15. package/dist/host-adapters.d.ts +34 -0
  16. package/dist/host-adapters.js +151 -0
  17. package/dist/http.d.ts +3 -0
  18. package/dist/http.js +90 -0
  19. package/dist/index.d.ts +16 -0
  20. package/dist/index.js +13 -0
  21. package/dist/knowledge-cli.d.ts +183 -0
  22. package/dist/knowledge-cli.js +654 -0
  23. package/dist/knowledge-reads.d.ts +71 -0
  24. package/dist/knowledge-reads.js +193 -0
  25. package/dist/memory.d.ts +97 -0
  26. package/dist/memory.js +250 -0
  27. package/dist/retrospective.d.ts +57 -0
  28. package/dist/retrospective.js +248 -0
  29. package/dist/search.d.ts +36 -0
  30. package/dist/search.js +112 -0
  31. package/dist/skill-addition.d.ts +25 -0
  32. package/dist/skill-addition.js +89 -0
  33. package/dist/skill-design.d.ts +96 -0
  34. package/dist/skill-design.js +226 -0
  35. package/dist/skill-replay.d.ts +55 -0
  36. package/dist/skill-replay.js +451 -0
  37. package/dist/skill-route.d.ts +30 -0
  38. package/dist/skill-route.js +75 -0
  39. package/dist/transcript-evidence.d.ts +3 -0
  40. package/dist/transcript-evidence.js +58 -0
  41. package/dist/upstream/chunker.d.ts +24 -0
  42. package/dist/upstream/chunker.js +96 -0
  43. package/dist/upstream/file-protocol.d.ts +45 -0
  44. package/dist/upstream/file-protocol.js +117 -0
  45. package/dist/upstream/frontmatter.d.ts +47 -0
  46. package/dist/upstream/frontmatter.js +86 -0
  47. package/dist/upstream/graph-search.d.ts +33 -0
  48. package/dist/upstream/graph-search.js +67 -0
  49. package/dist/upstream/l1-extraction.d.ts +26 -0
  50. package/dist/upstream/l1-extraction.js +405 -0
  51. package/dist/upstream/llm.d.ts +8 -0
  52. package/dist/upstream/llm.js +1 -0
  53. package/dist/upstream/merge.d.ts +50 -0
  54. package/dist/upstream/merge.js +153 -0
  55. package/dist/upstream/prompts.d.ts +53 -0
  56. package/dist/upstream/prompts.js +185 -0
  57. package/dist/upstream/search-utils.d.ts +34 -0
  58. package/dist/upstream/search-utils.js +55 -0
  59. package/dist/upstream/slug.d.ts +26 -0
  60. package/dist/upstream/slug.js +103 -0
  61. package/dist/upstream/template.d.ts +29 -0
  62. package/dist/upstream/template.js +80 -0
  63. package/dist/upstream/tokenize.d.ts +4 -0
  64. package/dist/upstream/tokenize.js +29 -0
  65. package/dist/wiki-change.d.ts +76 -0
  66. package/dist/wiki-change.js +299 -0
  67. package/dist/wiki-entry.d.ts +26 -0
  68. package/dist/wiki-entry.js +93 -0
  69. package/dist/wiki-ingest.d.ts +12 -0
  70. package/dist/wiki-ingest.js +126 -0
  71. package/dist/wiki-migration.d.ts +16 -0
  72. package/dist/wiki-migration.js +268 -0
  73. package/dist/wiki-tokens.d.ts +1 -0
  74. package/dist/wiki-tokens.js +46 -0
  75. package/dist/wiki.d.ts +103 -0
  76. package/dist/wiki.js +330 -0
  77. package/dist/workflow-cli.d.ts +2 -0
  78. package/dist/workflow-cli.js +258 -0
  79. package/dist/workflow-install.d.ts +36 -0
  80. package/dist/workflow-install.js +148 -0
  81. package/dist/workflow-knowledge.d.ts +16 -0
  82. package/dist/workflow-knowledge.js +24 -0
  83. package/dist/workflow-mcp.d.ts +2 -0
  84. package/dist/workflow-mcp.js +144 -0
  85. package/dist/workflow-names.d.ts +4 -0
  86. package/dist/workflow-names.js +18 -0
  87. package/dist/workflow-runtime.d.ts +622 -0
  88. package/dist/workflow-runtime.js +627 -0
  89. package/dist/workflow-skills.d.ts +48 -0
  90. package/dist/workflow-skills.js +141 -0
  91. package/package.json +76 -4
  92. package/skills/ew-odyssey/SKILL.md +237 -0
  93. package/skills/ew-odyssey/references/audit-artifacts.md +7 -0
  94. package/skills/ew-odyssey/references/odyssey-base-codex.md +3 -0
  95. package/skills/ew-odyssey/references/odyssey-base.md +278 -0
  96. package/skills/ew-odyssey/references/odyssey-debug.codex.md +305 -0
  97. package/skills/ew-odyssey/references/odyssey-debug.md +283 -0
  98. package/skills/ew-odyssey/references/odyssey-defensive.codex.md +395 -0
  99. package/skills/ew-odyssey/references/odyssey-defensive.md +369 -0
  100. package/skills/ew-odyssey/references/odyssey-improve.codex.md +270 -0
  101. package/skills/ew-odyssey/references/odyssey-improve.md +248 -0
  102. package/skills/ew-odyssey/references/odyssey-planex.codex.md +352 -0
  103. package/skills/ew-odyssey/references/odyssey-planex.md +312 -0
  104. package/skills/ew-odyssey/references/odyssey-review.codex.md +283 -0
  105. package/skills/ew-odyssey/references/odyssey-review.md +251 -0
  106. package/skills/ew-odyssey/references/odyssey-security.md +249 -0
  107. package/skills/ew-odyssey/references/odyssey-ui.codex.md +294 -0
  108. package/skills/ew-odyssey/references/odyssey-ui.md +250 -0
  109. package/skills/ew-odyssey/references/prepare/odyssey-debug.md +105 -0
  110. package/skills/ew-odyssey/references/prepare/odyssey-defensive.md +121 -0
  111. package/skills/ew-odyssey/references/prepare/odyssey-improve.md +93 -0
  112. package/skills/ew-odyssey/references/prepare/odyssey-planex.md +104 -0
  113. package/skills/ew-odyssey/references/prepare/odyssey-review.md +98 -0
  114. package/skills/ew-odyssey/references/prepare/odyssey-security.md +94 -0
  115. package/skills/ew-odyssey/references/prepare/odyssey-ui.md +87 -0
  116. package/skills/ew-orchestrate/SKILL.md +236 -0
  117. package/skills/ew-orchestrate/references/auto-policy.md +165 -0
  118. package/skills/ew-orchestrate/references/companion-route.md +52 -0
  119. package/skills/ew-orchestrate/references/ew-orchestrate.md +27 -0
  120. package/skills/ew-orchestrate/references/goal.md +53 -0
  121. package/skills/ew-orchestrate/references/knowledge-route.md +163 -0
  122. package/skills/ew-orchestrate/references/orchestrator-run-loop.md +36 -0
  123. package/skills/ew-orchestrate/references/planning.md +137 -0
  124. package/skills/ew-orchestrate/steps/ew-analyze/SKILL.md +62 -0
  125. package/skills/ew-orchestrate/steps/ew-analyze/references/boundary-grill.md +50 -0
  126. package/skills/ew-orchestrate/steps/ew-analyze/references/issue-gaps-analyze.md +59 -0
  127. package/skills/ew-orchestrate/steps/ew-analyze/references/prepare.md +42 -0
  128. package/skills/ew-orchestrate/steps/ew-analyze/references/workflow.md +401 -0
  129. package/skills/ew-orchestrate/steps/ew-brainstorm/SKILL.md +32 -0
  130. package/skills/ew-orchestrate/steps/ew-companion/SKILL.md +9 -0
  131. package/skills/ew-orchestrate/steps/ew-execute/SKILL.md +71 -0
  132. package/skills/ew-orchestrate/steps/ew-execute/references/prepare.md +69 -0
  133. package/skills/ew-orchestrate/steps/ew-execute/references/workflow.md +373 -0
  134. package/skills/ew-orchestrate/steps/ew-plan/SKILL.md +102 -0
  135. package/skills/ew-orchestrate/steps/ew-plan/references/boundary-grill.md +50 -0
  136. package/skills/ew-orchestrate/steps/ew-plan/references/prepare.md +51 -0
  137. package/skills/ew-orchestrate/steps/ew-plan/references/tdd.md +53 -0
  138. package/skills/ew-orchestrate/steps/ew-plan/references/workflow.md +278 -0
  139. package/skills/ew-orchestrate/steps/ew-review/SKILL.md +44 -0
  140. package/skills/ew-orchestrate/steps/ew-review/references/odyssey-base-codex.md +3 -0
  141. package/skills/ew-orchestrate/steps/ew-review/references/prepare.md +76 -0
  142. package/skills/ew-orchestrate/steps/ew-review/references/workflow.md +283 -0
  143. package/skills/ew-skill-design/SKILL.md +28 -0
  144. package/skills/ew-skill-design/references/package-contract.md +28 -0
  145. package/skills/ew-skill-design/references/validation.md +7 -0
  146. package/skills/team-swarm/SKILL.md +231 -0
  147. package/skills/team-swarm/references/mcp-coordination.md +10 -0
  148. package/skills/team-swarm/roles/analyst/role.md +181 -0
  149. package/skills/team-swarm/roles/ant/role.md +149 -0
  150. package/skills/team-swarm/roles/coordinator/commands/converge.md +154 -0
  151. package/skills/team-swarm/roles/coordinator/commands/init-swarm.md +134 -0
  152. package/skills/team-swarm/roles/coordinator/commands/iterate.md +202 -0
  153. package/skills/team-swarm/roles/coordinator/role.md +228 -0
  154. package/skills/team-swarm/roles/scorer/role.md +150 -0
  155. package/skills/team-swarm/scripts/aco.py +646 -0
  156. package/skills/team-swarm/scripts/pheromone.py +144 -0
  157. package/skills/team-swarm/scripts/scoring.py +111 -0
  158. package/skills/team-swarm/scripts/test_aco.py +606 -0
  159. package/skills/team-swarm/specs/ant-output-schema.md +127 -0
  160. package/skills/team-swarm/specs/convergence-criteria.md +108 -0
  161. package/skills/team-swarm/specs/pheromone-schema.md +125 -0
  162. package/skills/team-swarm/specs/swarm-config-template.json +71 -0
  163. package/skills/team-swarm/specs/swarm-protocol.md +123 -0
  164. package/skills/workflow-closeout/SKILL.md +10 -0
  165. package/skills/workflow-evolve/SKILL.md +79 -0
  166. package/skills/workflow-evolve/references/agy-gate.md +27 -0
  167. package/skills/workflow-evolve/references/auto-loop.md +20 -0
  168. package/skills/workflow-evolve/references/history-review.md +14 -0
  169. package/skills/workflow-evolve/scripts/codex-memory-replay.mjs +76 -0
  170. package/skills/workflow-evolve/scripts/codex-replay.mjs +1 -0
  171. package/skills/workflow-evolve/scripts/evolve-loop.mjs +259 -0
  172. package/skills/workflow-evolve/scripts/memory-codex-mcp.mjs +124 -0
  173. package/workflows/index.json +23 -0
@@ -0,0 +1,299 @@
1
+ import { createHash, randomUUID } from 'node:crypto';
2
+ import { linkSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
3
+ import { dirname, join } from 'node:path';
4
+ import { stringify } from 'yaml';
5
+ import { InputError, NotFoundError, openDb, requireText, transaction } from './common.js';
6
+ import { parseFrontmatter } from './upstream/frontmatter.js';
7
+ import { unionSources } from './upstream/merge.js';
8
+ import { readWikiEntryMetadata } from './wiki-entry.js';
9
+ function hash(content) {
10
+ return createHash('sha256').update(content).digest('hex');
11
+ }
12
+ function object(value, name) {
13
+ if (!value || typeof value !== 'object' || Array.isArray(value))
14
+ throw new InputError(`Invalid ${name}`);
15
+ return value;
16
+ }
17
+ function entryPath(wiki, id) {
18
+ if (!/^entries\/[a-z0-9][a-z0-9_-]*$/.test(id) || /^entries\/(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/.test(id)) {
19
+ throw new InputError('Expected an exact portable Wiki entry ID such as entries/preflight');
20
+ }
21
+ const folder = join(wiki.root, 'wiki', 'entries');
22
+ for (const directory of [join(wiki.root, 'wiki'), folder]) {
23
+ const info = lstatSync(directory, { throwIfNoEntry: false });
24
+ if (info && !info.isDirectory())
25
+ throw new InputError(`Invalid Wiki directory: ${directory}`);
26
+ }
27
+ return join(wiki.root, 'wiki', id + '.md');
28
+ }
29
+ function readEntry(path) {
30
+ const info = lstatSync(path, { throwIfNoEntry: false });
31
+ if (!info)
32
+ return null;
33
+ if (!info.isFile())
34
+ throw new InputError(`Invalid Wiki entry file: ${path}`);
35
+ return readFileSync(path, 'utf8');
36
+ }
37
+ function exactChangeId(id) {
38
+ if (!/^[a-f0-9]{64}$/.test(id))
39
+ throw new InputError('Expected an exact Wiki change ID');
40
+ return id;
41
+ }
42
+ function openChanges(wiki) {
43
+ const path = join(wiki.root, '.agent-memory', 'closeout.db');
44
+ mkdirSync(dirname(path), { recursive: true });
45
+ const db = openDb(path);
46
+ try {
47
+ db.exec(`CREATE TABLE IF NOT EXISTS wiki_changes (
48
+ id TEXT PRIMARY KEY, entry TEXT NOT NULL, payload TEXT NOT NULL,
49
+ state TEXT NOT NULL, created_at TEXT NOT NULL, applied_at TEXT
50
+ )`);
51
+ return db;
52
+ }
53
+ catch (error) {
54
+ db.close();
55
+ throw error;
56
+ }
57
+ }
58
+ function preview(id, change, state, appliedAt) {
59
+ return {
60
+ id, entry: change.entry, operation: change.operation, state, sources: change.sources,
61
+ baseline_sha256: change.before === null ? null : hash(change.before),
62
+ result_sha256: hash(change.after), before: change.before, after: change.after,
63
+ ...(change.candidate ? { candidate: change.candidate } : {}),
64
+ ...(change.review ? { review: change.review } : {}),
65
+ ...(typeof appliedAt === 'string' ? { applied_at: appliedAt } : {}),
66
+ };
67
+ }
68
+ function readChange(id, row) {
69
+ const payload = requireText(row.payload, 'Wiki change payload');
70
+ if (hash(payload) !== id)
71
+ throw new InputError(`Wiki change payload did not match its ID: ${id}`);
72
+ const change = object(JSON.parse(payload), 'Wiki change');
73
+ if (change.entry !== row.entry || !['create', 'update', 'promote', 'retire'].includes(change.operation) ||
74
+ (change.before !== null && typeof change.before !== 'string') || typeof change.after !== 'string' ||
75
+ !Array.isArray(change.sources) || !change.sources.length ||
76
+ change.sources.some(source => typeof source !== 'string')) {
77
+ throw new InputError(`Invalid stored Wiki change: ${id}`);
78
+ }
79
+ const state = row.state;
80
+ if (state !== 'pending' && state !== 'applying' && state !== 'applied') {
81
+ throw new InputError(`Invalid Wiki change state: ${id}`);
82
+ }
83
+ return { change, state, appliedAt: row.applied_at };
84
+ }
85
+ function parseDraft(value) {
86
+ const draft = object(value, 'Wiki change request');
87
+ const unknown = Object.keys(draft).filter(key => !['operation', 'entry', 'title', 'mode', 'scope', 'categories', 'repositories', 'keywords', 'body', 'review'].includes(key));
88
+ if (unknown.length)
89
+ throw new InputError(`Unknown Wiki change field: ${unknown[0]}`);
90
+ const { operation, mode } = draft;
91
+ if (operation !== 'create' && operation !== 'update' && operation !== 'promote' && operation !== 'retire') {
92
+ throw new InputError('Expected Wiki operation create, update, promote, or retire');
93
+ }
94
+ if (mode !== undefined && mode !== 'constraint' && mode !== 'reference')
95
+ throw new InputError('Invalid Wiki entry mode');
96
+ if (mode !== undefined && operation !== 'create')
97
+ throw new InputError('Use promote to change a reference into a constraint');
98
+ if (operation === 'retire' && ['title', 'scope', 'body', 'categories', 'repositories', 'keywords'].some(key => draft[key] !== undefined)) {
99
+ throw new InputError('A retirement changes status and evidence only');
100
+ }
101
+ if (draft.scope !== undefined && !Array.isArray(draft.scope))
102
+ throw new InputError('Wiki scope must be a list');
103
+ if (draft.scope?.some(item => typeof item === 'string' && item.trim().startsWith('skill:'))) {
104
+ throw new InputError('Use project, task:<kind>, or path:<glob> for Wiki scope');
105
+ }
106
+ return {
107
+ operation, mode, entry: requireText(draft.entry, 'Wiki entry ID'),
108
+ ...(draft.title !== undefined ? { title: requireText(draft.title, 'Wiki entry title') } : {}),
109
+ ...(draft.body !== undefined ? { body: requireText(draft.body, 'Wiki entry body') } : {}),
110
+ ...(draft.scope !== undefined ? { scope: draft.scope } : {}),
111
+ ...(draft.categories !== undefined ? { categories: draft.categories } : {}),
112
+ ...(draft.repositories !== undefined ? { repositories: draft.repositories } : {}),
113
+ ...(draft.keywords !== undefined ? { keywords: draft.keywords } : {}),
114
+ };
115
+ }
116
+ export function proposeWikiChange(wiki, value, evidence, candidate) {
117
+ const draft = parseDraft(value);
118
+ const related = candidate?.related ?? [];
119
+ const request = object(value, 'Wiki change request');
120
+ const review = request.review === undefined ? undefined : object(request.review, 'Wiki relationship decision');
121
+ const relationship = review?.relationship;
122
+ if (review && relationship !== 'overlap' && relationship !== 'conflict' && relationship !== 'independent') {
123
+ throw new InputError('Expected Wiki relationship overlap, conflict, or independent');
124
+ }
125
+ if (related.length && !review)
126
+ throw new InputError('A linked candidate with related entries requires a recorded relationship decision');
127
+ if (related.length && relationship !== 'independent' && !related.includes(draft.entry)) {
128
+ throw new InputError('Choose a related entry as the target, or resolve it as independent');
129
+ }
130
+ const decision = relationship === 'overlap' || relationship === 'conflict' || relationship === 'independent' ? {
131
+ relationship,
132
+ rationale: requireText(review?.rationale, 'Wiki relationship rationale'),
133
+ related: [...new Set(related)].sort(),
134
+ } : undefined;
135
+ if (evidence.some(source => source.trim().startsWith('receipt:'))) {
136
+ throw new InputError('Use --closeout and --candidate for completion receipt evidence');
137
+ }
138
+ const sources = [...new Set([...evidence, ...(candidate?.sources ?? [])]
139
+ .map(source => requireText(source, 'evidence reference')))].sort();
140
+ if (!sources.length || sources.some(source => /[\r\n]/.test(source))) {
141
+ throw new InputError('At least one single-line evidence reference is required');
142
+ }
143
+ const db = openChanges(wiki);
144
+ try {
145
+ return transaction(db, () => {
146
+ const path = entryPath(wiki, draft.entry);
147
+ const before = readEntry(path);
148
+ const original = parseFrontmatter((before ?? '').replace(/^\uFEFF/, ''));
149
+ if (draft.operation !== 'create' && before === null)
150
+ throw new NotFoundError(`Wiki entry not found: ${draft.entry}`);
151
+ if (original.frontmatter.locked === true)
152
+ throw new InputError(`Wiki entry is locked: ${draft.entry}`);
153
+ const rel = `wiki/${draft.entry}.md`;
154
+ const current = before === null || draft.operation === 'create' ? undefined : readWikiEntryMetadata(rel, original.frontmatter, original.body);
155
+ if (draft.operation === 'promote' && current?.mode !== 'reference') {
156
+ throw new InputError('Only a reference can be promoted to a constraint');
157
+ }
158
+ if (current?.status === 'deprecated') {
159
+ throw new InputError('A retired entry is immutable');
160
+ }
161
+ const scope = draft.operation === 'retire' ? current?.scope : current?.scope.filter(item => !item.startsWith('skill:'));
162
+ if ((current?.status === 'needs_review' || scope?.length === 0) && draft.operation !== 'retire' && draft.scope === undefined) {
163
+ throw new InputError('Set the reviewed scope explicitly before activating this entry');
164
+ }
165
+ const { operation } = draft;
166
+ const body = draft.body !== undefined || operation === 'create'
167
+ ? `\n${requireText(draft.body, 'Wiki entry body')}\n`
168
+ : original.body;
169
+ const metadata = {
170
+ ...(operation === 'create' ? {} : original.frontmatter),
171
+ title: draft.title ?? (operation === 'create' ? undefined : original.frontmatter.title),
172
+ mode: operation === 'promote' ? 'constraint' : draft.mode ?? current?.mode,
173
+ status: operation === 'retire' ? 'deprecated' : 'active',
174
+ scope: draft.scope ?? scope ?? ['project'],
175
+ ...(draft.categories !== undefined ? { categories: draft.categories } : {}),
176
+ ...(draft.repositories !== undefined ? { repositories: draft.repositories } : {}),
177
+ ...(draft.keywords !== undefined ? { keywords: draft.keywords } : {}),
178
+ sources: unionSources(operation === 'create' ? [] : original.frontmatter.sources ?? [], sources),
179
+ };
180
+ readWikiEntryMetadata(rel, { type: 'other', ...metadata }, body);
181
+ const after = `---\n${stringify(metadata)}---\n${body}`;
182
+ const change = {
183
+ operation, entry: draft.entry, before: operation === 'create' ? null : before, after, sources,
184
+ ...(candidate ? { candidate: { closeout: candidate.closeout, id: candidate.id } } : {}),
185
+ ...(decision ? { review: decision } : {}),
186
+ };
187
+ const payload = JSON.stringify(change);
188
+ const id = hash(payload);
189
+ const previous = db.prepare('SELECT * FROM wiki_changes WHERE id = ?').get(id);
190
+ if (previous) {
191
+ const existing = readChange(id, previous);
192
+ return preview(id, existing.change, existing.state, existing.appliedAt);
193
+ }
194
+ if (operation === 'create' && before !== null && before !== after) {
195
+ throw new InputError(`Wiki entry already exists: ${draft.entry}`);
196
+ }
197
+ if (operation !== 'create' && before === after)
198
+ throw new InputError('Wiki change has no effect');
199
+ if (operation !== 'retire')
200
+ assertUniqueContent(wiki, draft.entry, after);
201
+ db.prepare('INSERT INTO wiki_changes VALUES (?, ?, ?, ?, ?, NULL)').run(id, change.entry, payload, 'pending', new Date().toISOString());
202
+ return preview(id, change, 'pending');
203
+ });
204
+ }
205
+ finally {
206
+ db.close();
207
+ }
208
+ }
209
+ function assertUniqueContent(wiki, entry, after) {
210
+ const matches = wiki.getEntriesByExactBody(parseFrontmatter(after).body).filter(page => page.id !== entry);
211
+ if (matches.length > 0) {
212
+ throw new InputError(`Wiki content already matches ${matches.map(page => page.id).join(', ')}; review the existing entries`);
213
+ }
214
+ }
215
+ function writeChange(path, change) {
216
+ mkdirSync(dirname(path), { recursive: true });
217
+ const temporary = join(dirname(path), `.${randomUUID()}.tmp`);
218
+ try {
219
+ writeFileSync(temporary, change.after, { encoding: 'utf8', flag: 'wx' });
220
+ if (readEntry(path) !== change.before)
221
+ throw new InputError(`Wiki entry changed since review: ${change.entry}`);
222
+ if (change.before === null)
223
+ linkSync(temporary, path);
224
+ else
225
+ renameSync(temporary, path);
226
+ }
227
+ finally {
228
+ rmSync(temporary, { force: true });
229
+ }
230
+ }
231
+ export function applyWikiChange(wiki, id) {
232
+ exactChangeId(id);
233
+ const db = openChanges(wiki);
234
+ try {
235
+ const lookup = () => {
236
+ const row = db.prepare('SELECT * FROM wiki_changes WHERE id = ?').get(id);
237
+ if (!row)
238
+ throw new NotFoundError(`Wiki change not found: ${id}`);
239
+ return readChange(id, row);
240
+ };
241
+ transaction(db, () => {
242
+ const { change, state } = lookup();
243
+ if (state !== 'pending')
244
+ return;
245
+ const current = readEntry(entryPath(wiki, change.entry));
246
+ if (current !== change.before && !(change.operation === 'create' && current === change.after)) {
247
+ throw new InputError(`Wiki entry changed since review: ${change.entry}`);
248
+ }
249
+ if (change.operation !== 'retire')
250
+ assertUniqueContent(wiki, change.entry, change.after);
251
+ db.prepare("UPDATE wiki_changes SET state = 'applying' WHERE id = ?").run(id);
252
+ });
253
+ return transaction(db, () => {
254
+ const { change, state, appliedAt } = lookup();
255
+ if (state === 'applied')
256
+ return { ...preview(id, change, state, appliedAt), replayed: true };
257
+ const path = entryPath(wiki, change.entry);
258
+ const current = readEntry(path);
259
+ if (change.operation !== 'retire')
260
+ assertUniqueContent(wiki, change.entry, change.after);
261
+ if (current !== change.after) {
262
+ if (current !== change.before)
263
+ throw new InputError(`Wiki entry changed since review: ${change.entry}`);
264
+ writeChange(path, change);
265
+ }
266
+ wiki.build();
267
+ const time = new Date().toISOString();
268
+ db.prepare("UPDATE wiki_changes SET state = 'applied', applied_at = ? WHERE id = ?").run(time, id);
269
+ return { ...preview(id, change, 'applied', time), replayed: false };
270
+ });
271
+ }
272
+ finally {
273
+ db.close();
274
+ }
275
+ }
276
+ export function listWikiChanges(wiki, selection) {
277
+ if (selection?.id)
278
+ exactChangeId(selection.id);
279
+ if (selection?.entry)
280
+ entryPath(wiki, selection.entry);
281
+ const path = join(wiki.root, '.agent-memory', 'closeout.db');
282
+ if (!lstatSync(path, { throwIfNoEntry: false })?.isFile())
283
+ return [];
284
+ const db = openDb(path, true);
285
+ try {
286
+ if (!db.prepare("SELECT 1 FROM sqlite_master WHERE name = 'wiki_changes' AND type = 'table'").get())
287
+ return [];
288
+ return db.prepare(`SELECT * FROM wiki_changes
289
+ WHERE (? IS NULL OR id = ?) AND (? IS NULL OR entry = ?) ORDER BY created_at, id`)
290
+ .all(selection?.id ?? null, selection?.id ?? null, selection?.entry ?? null, selection?.entry ?? null).map(row => {
291
+ const id = requireText(row.id, 'Wiki change ID');
292
+ const { change, state, appliedAt } = readChange(id, row);
293
+ return preview(id, change, state, appliedAt);
294
+ });
295
+ }
296
+ finally {
297
+ db.close();
298
+ }
299
+ }
@@ -0,0 +1,26 @@
1
+ import type { PageFrontmatter } from './upstream/frontmatter.js';
2
+ export declare const wikiCategories: readonly ["coding", "arch", "debug", "test", "review", "learning", "ui"];
3
+ export type WikiCategory = typeof wikiCategories[number];
4
+ export interface WikiEntryMetadata {
5
+ mode: 'constraint' | 'reference';
6
+ status: 'active' | 'deprecated' | 'needs_review';
7
+ scope: string[];
8
+ aliases: string[];
9
+ categories?: WikiCategory[];
10
+ repositories?: string[];
11
+ keywords?: string[];
12
+ }
13
+ export interface WikiContext {
14
+ task?: string;
15
+ paths?: string[];
16
+ categories?: WikiCategory[];
17
+ repository?: string;
18
+ keyword?: string;
19
+ includePathScoped?: boolean;
20
+ }
21
+ export declare function isWikiCategory(value: unknown): value is WikiCategory;
22
+ export declare function isRepositoryId(value: unknown): value is string;
23
+ export declare function readWikiEntryMetadata(path: string, frontmatter: PageFrontmatter, body: string): WikiEntryMetadata | undefined;
24
+ export declare function splitLegacyKeywords(value: unknown): string[];
25
+ export declare function appliesToContext(entry: WikiEntryMetadata, context: WikiContext, body: string): boolean;
26
+ export declare function contextSpecificity(entry: WikiEntryMetadata, context: WikiContext): number;
@@ -0,0 +1,93 @@
1
+ import { posix } from 'node:path';
2
+ import { InputError } from './common.js';
3
+ export const wikiCategories = ['coding', 'arch', 'debug', 'test', 'review', 'learning', 'ui'];
4
+ const repositoryIdPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
5
+ function stringList(value, field, path) {
6
+ if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || !item.trim())) {
7
+ throw new InputError(`Wiki entry ${path} requires a list of strings in ${field}`);
8
+ }
9
+ return [...new Set(value.map(item => item.trim()))];
10
+ }
11
+ export function isWikiCategory(value) {
12
+ return wikiCategories.some(category => category === value);
13
+ }
14
+ export function isRepositoryId(value) {
15
+ return typeof value === 'string' && repositoryIdPattern.test(value);
16
+ }
17
+ export function readWikiEntryMetadata(path, frontmatter, body) {
18
+ if (!path.startsWith('wiki/entries/'))
19
+ return undefined;
20
+ if (!/^wiki\/entries\/[a-z0-9][a-z0-9_-]*\.md$/.test(path)) {
21
+ throw new InputError(`Invalid stable Wiki entry path: ${path}`);
22
+ }
23
+ const { title, mode, status } = frontmatter;
24
+ if (typeof title !== 'string' || !title.trim())
25
+ throw new InputError(`Wiki entry ${path} needs a title`);
26
+ if (mode !== 'reference' && mode !== 'constraint')
27
+ throw new InputError(`Invalid Wiki entry mode: ${path}`);
28
+ if (status !== 'active' && status !== 'deprecated' && status !== 'needs_review') {
29
+ throw new InputError(`Invalid Wiki entry status: ${path}`);
30
+ }
31
+ const scope = stringList(frontmatter.scope, 'scope', path);
32
+ if (!scope.length || scope.some(item => item !== 'project' && !/^(?:skill|task|path):\S/.test(item))) {
33
+ throw new InputError(`Invalid Wiki entry scope: ${path}`);
34
+ }
35
+ const sources = stringList(frontmatter.sources, 'sources', path);
36
+ if (!sources.length) {
37
+ throw new InputError(`Wiki entry ${path} needs at least one source`);
38
+ }
39
+ const aliases = frontmatter.aliases === undefined ? [] : stringList(frontmatter.aliases, 'aliases', path);
40
+ const categories = frontmatter.categories === undefined ? undefined : stringList(frontmatter.categories, 'categories', path);
41
+ if (categories && !categories.every(isWikiCategory))
42
+ throw new InputError(`Invalid Wiki entry category: ${path}`);
43
+ const repositories = frontmatter.repositories === undefined ? undefined : stringList(frontmatter.repositories, 'repositories', path);
44
+ if (repositories && !repositories.every(isRepositoryId))
45
+ throw new InputError(`Invalid Wiki repository ID: ${path}`);
46
+ const legacy = frontmatter.legacy;
47
+ // 旧导入保存了结构化条目的属性和行号,按原格式补读关键词。
48
+ const structuredLegacy = sources.some(source => /^legacy:[^:]+:\.workflow\/specs\/[^#]+#L\d+$/.test(source)) &&
49
+ (typeof legacy?.sid === 'string' || typeof legacy?.keywords === 'string' ||
50
+ !/^\s*###\s+(?:\[[\w-]+\]\s+)?\[\d{4}-\d{2}-\d{2}/.test(body));
51
+ const keywords = frontmatter.keywords === undefined
52
+ ? structuredLegacy ? splitLegacyKeywords(legacy?.keywords) : undefined
53
+ : stringList(frontmatter.keywords, 'keywords', path).map(keyword => keyword.toLowerCase());
54
+ return { mode, status, scope, aliases, ...(categories ? { categories } : {}), ...(repositories ? { repositories } : {}),
55
+ ...(keywords ? { keywords: [...new Set(keywords)] } : {}) };
56
+ }
57
+ export function splitLegacyKeywords(value) {
58
+ return typeof value === 'string' ? value.split(',').map(keyword => keyword.trim().toLowerCase()).filter(Boolean) : [];
59
+ }
60
+ export function appliesToContext(entry, context, body) {
61
+ if (entry.repositories && (!context.repository || !entry.repositories.includes(context.repository)))
62
+ return false;
63
+ const categories = context.categories;
64
+ const keyword = context.keyword?.toLowerCase();
65
+ const exact = keyword && entry.keywords?.includes(keyword);
66
+ if (keyword && !(entry.keywords ? exact : body.toLowerCase().includes(keyword)))
67
+ return false;
68
+ if (entry.categories && categories?.length && !exact && !entry.categories.some(category => categories.includes(category)))
69
+ return false;
70
+ return entry.scope.some(scope => {
71
+ if (scope === 'project')
72
+ return true;
73
+ if (scope.startsWith('task:'))
74
+ return scope.slice(5) === context.task;
75
+ return scope.startsWith('path:') && (context.includePathScoped ||
76
+ (context.paths ?? []).some(path => posix.matchesGlob(path.replaceAll('\\', '/'), scope.slice(5))));
77
+ });
78
+ }
79
+ export function contextSpecificity(entry, context) {
80
+ let score = 0;
81
+ if (context.task && entry.scope.includes(`task:${context.task}`))
82
+ score += 6;
83
+ if (context.paths?.length && entry.scope.some(scope => scope.startsWith('path:') &&
84
+ context.paths.some(path => posix.matchesGlob(path.replaceAll('\\', '/'), scope.slice(5)))))
85
+ score += 4;
86
+ if (context.categories?.length && entry.categories?.some(category => context.categories.includes(category)))
87
+ score += 2;
88
+ if (context.repository && entry.repositories?.includes(context.repository))
89
+ score += 2;
90
+ if (context.keyword && entry.keywords?.includes(context.keyword.toLowerCase()))
91
+ score += 1;
92
+ return score;
93
+ }
@@ -0,0 +1,12 @@
1
+ import type { LlmClient } from './upstream/llm.js';
2
+ import { type Wiki } from './wiki.js';
3
+ export interface WikiIngestOptions {
4
+ llm: LlmClient;
5
+ mode?: 'two-stage' | 'single-stage';
6
+ }
7
+ export declare function ingestWiki(wiki: Wiki, source: string, options: WikiIngestOptions): Promise<{
8
+ pages: number;
9
+ edges: number;
10
+ written: string[];
11
+ warnings: string[];
12
+ }>;
@@ -0,0 +1,126 @@
1
+ // Adapts TencentDB Agent Memory's Wiki ingest-v2 pipeline (MIT).
2
+ import { lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
3
+ import { randomUUID } from 'node:crypto';
4
+ import { basename, dirname, extname, join } from 'node:path';
5
+ import { InputError, requireText } from './common.js';
6
+ import { chunkText } from './upstream/chunker.js';
7
+ import { normalizeWikiPath, parseFileBlocks } from './upstream/file-protocol.js';
8
+ import { buildPage, parseFrontmatter, readSources } from './upstream/frontmatter.js';
9
+ import { mergePage, unionSources } from './upstream/merge.js';
10
+ import { buildAnalysisPrompt, buildAnalysisSystemPrompt, buildGenerateFromAnalysisPrompt, buildGeneratePrompt, buildSystemPrompt } from './upstream/prompts.js';
11
+ import { pageRelPath, slugify } from './upstream/slug.js';
12
+ import { loadTemplate } from './upstream/template.js';
13
+ import { readWikiPages, structuralPages } from './wiki.js';
14
+ const inProgress = new Set();
15
+ export async function ingestWiki(wiki, source, options) {
16
+ const sourceName = basename(source);
17
+ if (!['.md', '.markdown', '.txt'].includes(extname(sourceName).toLowerCase())) {
18
+ throw new InputError('Wiki ingest supports Markdown and plain text sources');
19
+ }
20
+ const sourceText = requireText(readFileSync(source, 'utf8'), 'source text');
21
+ mkdirSync(wiki.root, { recursive: true });
22
+ const root = realpathSync(wiki.root);
23
+ if (inProgress.has(root))
24
+ throw new Error('Wiki ingest is already running for this directory');
25
+ inProgress.add(root);
26
+ try {
27
+ checkedPath(root, 'wiki');
28
+ mkdirSync(join(root, 'wiki'), { recursive: true });
29
+ checkedPath(root, 'wiki/purpose.md');
30
+ checkedPath(root, 'wiki/schema.md');
31
+ const existingPages = readWikiPages(root).map(page => ({
32
+ relPath: page.path, title: page.title, type: page.type, description: page.snippet,
33
+ }));
34
+ const template = loadTemplate(root);
35
+ const chunks = sourceText.length > 28_000 ? chunkText(sourceText, { targetChars: 28_000 }) : [sourceText];
36
+ const staged = new Map();
37
+ const original = new Map();
38
+ const warnings = [];
39
+ let generated = 0;
40
+ for (const [index, text] of chunks.entries()) {
41
+ const context = {
42
+ sourceName: chunks.length === 1 ? sourceName : `${sourceName} (chunk ${index + 1}/${chunks.length})`,
43
+ sourceText: text, existingPages,
44
+ };
45
+ const analysis = options.mode === 'single-stage' ? '' : await options.llm.chat({
46
+ system: buildAnalysisSystemPrompt(template), prompt: buildAnalysisPrompt(context), label: 'wiki-analysis',
47
+ });
48
+ const raw = await options.llm.chat({
49
+ system: buildSystemPrompt(template),
50
+ prompt: analysis.trim() ? buildGenerateFromAnalysisPrompt({ ...context, analysis }) : buildGeneratePrompt(context),
51
+ label: 'wiki-generate',
52
+ });
53
+ const parsed = parseFileBlocks(raw);
54
+ warnings.push(...parsed.warnings);
55
+ if (!parsed.files.length)
56
+ throw new Error(`Wiki generation returned no complete pages for chunk ${index + 1}`);
57
+ for (const file of parsed.files) {
58
+ const page = parseFrontmatter(file.content);
59
+ if (!page.hasFrontmatter || !page.body.trim()) {
60
+ warnings.push(`Invalid frontmatter or empty body: ${file.path}`);
61
+ continue;
62
+ }
63
+ const title = page.frontmatter.title;
64
+ const path = typeof title === 'string' && slugify(title) ? pageRelPath(page.frontmatter.type, title) : file.path;
65
+ if (structuralPages.has(file.path.toLowerCase()) || structuralPages.has(path.toLowerCase()))
66
+ continue;
67
+ if (file.path.toLowerCase().startsWith('wiki/entries/') || path.toLowerCase().startsWith('wiki/entries/')) {
68
+ warnings.push(`Managed Wiki entries require the publishing workflow: ${file.path}`);
69
+ continue;
70
+ }
71
+ const full = checkedPath(root, path);
72
+ const candidate = buildPage({ ...page.frontmatter, sources: unionSources(readSources(file.content), [sourceName]) }, page.body);
73
+ if (!original.has(path))
74
+ original.set(path, readIfPresent(full));
75
+ const previous = staged.get(path) ?? original.get(path);
76
+ const decision = await mergePage(previous, candidate, options.llm);
77
+ generated++;
78
+ if (decision.action === 'write' && decision.content !== previous)
79
+ staged.set(path, decision.content);
80
+ }
81
+ }
82
+ if (!generated)
83
+ throw new Error('Wiki generation returned no usable content pages');
84
+ for (const path of staged.keys()) {
85
+ if (readIfPresent(checkedPath(root, path)) !== original.get(path)) {
86
+ throw new Error(`Wiki page changed during ingestion: ${path}`);
87
+ }
88
+ }
89
+ for (const [path, content] of staged) {
90
+ const full = checkedPath(root, path);
91
+ mkdirSync(dirname(full), { recursive: true });
92
+ const temp = join(dirname(full), `.${randomUUID()}.tmp`);
93
+ try {
94
+ writeFileSync(temp, content, { encoding: 'utf8', flag: 'wx' });
95
+ renameSync(temp, full);
96
+ }
97
+ finally {
98
+ rmSync(temp, { force: true });
99
+ }
100
+ }
101
+ return { written: [...staged.keys()], warnings, ...wiki.build() };
102
+ }
103
+ finally {
104
+ inProgress.delete(root);
105
+ }
106
+ }
107
+ function readIfPresent(path) {
108
+ return lstatSync(path, { throwIfNoEntry: false }) ? readFileSync(path, 'utf8') : null;
109
+ }
110
+ function checkedPath(root, path) {
111
+ if (path !== 'wiki' && (normalizeWikiPath(path) !== path || extname(path).toLowerCase() !== '.md')) {
112
+ throw new InputError(`Invalid wiki path: ${path}`);
113
+ }
114
+ let full = root;
115
+ for (const part of path.split('/')) {
116
+ if (/[<>:"|?*\u0000-\u001f]/.test(part) || /[. ]$/.test(part) ||
117
+ /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part)) {
118
+ throw new InputError(`Invalid wiki path component: ${part}`);
119
+ }
120
+ full = join(full, part);
121
+ if (lstatSync(full, { throwIfNoEntry: false })?.isSymbolicLink()) {
122
+ throw new InputError(`Wiki path contains a symbolic link: ${path}`);
123
+ }
124
+ }
125
+ return full;
126
+ }
@@ -0,0 +1,16 @@
1
+ import type { Wiki } from './wiki.js';
2
+ interface LegacyWikiLayer {
3
+ scope: 'project' | 'global' | 'team' | 'personal';
4
+ uid?: string;
5
+ knowhowOnly?: boolean;
6
+ }
7
+ export declare function validateWikiMemberUid(uid: string | undefined): string;
8
+ export declare function migrateLegacyWiki(wiki: Wiki, sourceRoot: string, project: string, apply?: boolean, layer?: LegacyWikiLayer): {
9
+ issues?: string[] | undefined;
10
+ id: string;
11
+ origin: string;
12
+ alias: string;
13
+ status: "active" | "deprecated" | "needs_review";
14
+ existing: boolean;
15
+ }[];
16
+ export {};