@iiiokojiadbi/shift 0.32.0 → 0.34.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/README.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # shift for pi and opencode
2
2
 
3
+ [![npm](https://img.shields.io/npm/v/@iiiokojiadbi/shift)](https://www.npmjs.com/package/@iiiokojiadbi/shift)
4
+ [![downloads](https://img.shields.io/npm/dm/@iiiokojiadbi/shift)](https://www.npmjs.com/package/@iiiokojiadbi/shift)
5
+ [![license](https://img.shields.io/npm/l/@iiiokojiadbi/shift)](https://github.com/iiiokojiadbi/shift/blob/main/LICENSE)
6
+
3
7
  The agent decides by itself when to **shift**. At a stage boundary it updates its work board and task folders, writes a letter to itself, and has the harness let the stretch's history go, with a direction of what to hold. Right after the shift it gets its letter, board and tasks in progress back whole and continues from where it stopped.
4
8
 
5
9
  One package for both harnesses: pi loads `index.ts`, opencode loads `server.ts`.
package/core/about.ts CHANGED
@@ -33,17 +33,17 @@ export type About = {
33
33
 
34
34
  export function renderAbout(meta: AboutMeta): string {
35
35
  const list = (items: string[]) => (items.length === 0 ? ['none'] : items.map(item => `- ${item}`))
36
+ const fill = (tokens: number | undefined) => (tokens === undefined ? '?' : formatK(tokens))
36
37
  const tokens =
37
- meta.tokensBefore === undefined
38
- ? 'unknown'
39
- : `${formatK(meta.tokensBefore)} → ${meta.tokensAfter === undefined ? '?' : formatK(meta.tokensAfter)}`
38
+ meta.tokensBefore === undefined && meta.tokensAfter === undefined ? 'unknown' : `${fill(meta.tokensBefore)} → ${fill(meta.tokensAfter)}`
40
39
 
41
40
  return [
42
41
  '---',
43
42
  `description: ${meta.about}`,
44
43
  `at: ${new Date(meta.at).toISOString()}`,
45
44
  `after: ${meta.after}`,
46
- `result: ${meta.result}`,
45
+ // A harness's reason may run over lines; the line keeps all of it.
46
+ `result: ${meta.result.replace(/\s*\r?\n\s*/g, ' ')}`,
47
47
  `tokens: ${tokens}`,
48
48
  `summary_chars: ${meta.summaryChars ?? 'unknown'}`,
49
49
  `session: ${meta.sessionId}`,
package/core/delivery.ts CHANGED
@@ -1,9 +1,9 @@
1
1
  // Generated from core/src by scripts/sync-core.ts — edit the source, not this copy.
2
- import { followWrite, settleDocs } from './docs'
2
+ import { docStamps, followWrite, refreshDocs, settleDocs } from './docs'
3
3
  import { type ChangedBy, changedRecords, type Seen } from './flows'
4
4
  import type { GaugeKeeper } from './hint'
5
5
  import { MOD } from './layout'
6
- import { type Loop, loopHint, waitingNote } from './loop'
6
+ import { type Loop, loopHint, loopOffer, waitingNote } from './loop'
7
7
  import type { Project } from './project'
8
8
  import { NOTE_KINDS, type NoteKind } from './texts/prompts'
9
9
  import { TOLD } from './texts/rows'
@@ -15,7 +15,8 @@ import { TOLD } from './texts/rows'
15
15
 
16
16
  // What the mod last saw of the records and how many of the main agent's tools run now: a change seen while one runs
17
17
  // may be that tool's own. `written`: the files written since the docs were last settled, from the project's root.
18
- export type Looks = { seen: Seen | null; running: number; written?: readonly string[] }
18
+ // `docs`: the documents' stamps as the last prompt saw them, so one a script changed is settled like one written.
19
+ export type Looks = { seen: Seen | null; running: number; written?: readonly string[]; docs?: Record<string, string> }
19
20
 
20
21
  export const FRESH_LOOKS: Looks = { seen: null, running: 0 }
21
22
 
@@ -43,12 +44,21 @@ export type ToolEnd = {
43
44
 
44
45
  // Before a tool of the main agent: what changed since the last look is someone else's — the owner's hand, another
45
46
  // session — unless another tool runs now, whose own change it may be. The notes go with this tool's result.
47
+ // Of tools started together only the first looks: the count is claimed in one change, so two never tell the same change.
48
+ // What it saw is kept at once: a tool that throws loses its note, which only a failing harness does, while a look kept
49
+ // open would let a sibling tool take the change as its own or put back what it saw.
46
50
  export async function beforeTool(courier: Courier): Promise<Note[]> {
47
- const { running } = await courier.looks()
48
- const outside = running === 0 ? await look(courier, 'other') : null
49
- await courier.updateLooks(current => ({ ...current, running: current.running + 1 }))
50
-
51
- return outside === null ? [] : [{ kind: 'records', body: outside }]
51
+ const claim: { first?: boolean } = {}
52
+ await courier.updateLooks(current => {
53
+ claim.first = current.running === 0
54
+ return { ...current, running: current.running + 1 }
55
+ })
56
+ if (claim.first !== true) return []
57
+ const outside = await look(courier, 'other')
58
+ if (outside === null) return []
59
+ await remember(courier, outside.seen)
60
+
61
+ return outside.body === null ? [] : [{ kind: 'records', body: outside.body }]
52
62
  }
53
63
 
54
64
  // After a tool of the main agent: the notes from before it, what it changed in the records, and a hint if the fill
@@ -58,7 +68,8 @@ export async function afterTool(courier: Courier, before: readonly Note[], done:
58
68
  if (done === null) return []
59
69
  const notes = [...before]
60
70
  const own = done.readOnly ? null : await look(courier, 'agent')
61
- if (own !== null && !done.own) notes.push({ kind: 'records', body: own })
71
+ if (own !== null) await remember(courier, own.seen)
72
+ if (own?.body != null && !done.own) notes.push({ kind: 'records', body: own.body })
62
73
  if (done.written !== undefined) await follow(courier, done.written)
63
74
  const hint = await loopHint(courier.loop, courier.gauge).catch(() => null)
64
75
  if (hint !== null) notes.push({ kind: 'hint', body: hint })
@@ -73,7 +84,8 @@ export async function afterWrite(courier: Courier, file: string): Promise<void>
73
84
 
74
85
  // With the next prompt: what changed between turns, the docs written in the run settled, a hint, and after a wait the
75
86
  // letter, last, when the owner speaks. With a tool running — a message queued mid-run — the docs wait: it may be an edit.
76
- // The notes are told to the owner and the letter cleared only once `delivered` says the prompt went with them.
87
+ // Nothing is marked told — the records seen, the docs settled, the hint, the letter — until `delivered` says the prompt
88
+ // went with them: a prompt that failed or was dropped leaves every note for the next one.
77
89
  export async function atPrompt(
78
90
  courier: Courier,
79
91
  { runStarts, owner }: { runStarts: boolean; owner: boolean },
@@ -81,17 +93,30 @@ export async function atPrompt(
81
93
  if (runStarts) await courier.updateLooks(current => ({ ...current, running: 0 }))
82
94
  const notes: Note[] = []
83
95
  const { running } = await courier.looks()
96
+ const { seen } = await courier.looks()
84
97
  const outside = running === 0 ? await look(courier, 'other') : null
85
- if (outside !== null) notes.push({ kind: 'records', body: outside })
98
+ if (outside?.body === null) await remember(courier, outside.seen)
99
+ if (outside?.body != null) notes.push({ kind: 'records', body: outside.body })
100
+ if (running === 0) await scripted(courier)
86
101
  const docs = running === 0 ? await settle(courier) : null
87
- if (docs !== null) notes.push({ kind: 'docs', body: docs })
88
- const hint = await loopHint(courier.loop, courier.gauge).catch(() => null)
89
- if (hint !== null) notes.push({ kind: 'hint', body: hint })
102
+ if (docs !== null) notes.push({ kind: 'docs', body: docs.body })
103
+ const hint = await loopOffer(courier.loop, courier.gauge).catch(() => null)
104
+ if (hint !== null) notes.push({ kind: 'hint', body: hint.text })
90
105
  const letter = owner ? await waitingNote(courier.loop) : null
91
106
 
92
107
  return {
93
108
  notes: [...notes.map(wrap), ...(letter === null ? [] : [letter.context])],
94
109
  delivered: async () => {
110
+ // Kept unless a look since has kept newer records: putting back the older ones would tell their change again.
111
+ if (outside?.body != null)
112
+ await courier.updateLooks(current => (same(current.seen, seen) ? { ...current, seen: outside.seen } : current))
113
+ if (docs !== null) {
114
+ const skipped = await docs.write().catch(() => docs.paths)
115
+ const settled = docs.paths.filter(path => !skipped.includes(path))
116
+ await forget(courier, settled)
117
+ await restamp(courier, settled)
118
+ }
119
+ await hint?.take()
95
120
  for (const note of notes) courier.loop.tell(TOLD(note.body), 'info')
96
121
  await letter?.delivered()
97
122
  },
@@ -103,19 +128,20 @@ export async function runEnded(courier: Courier): Promise<void> {
103
128
  await courier.updateLooks(current => (current.running === 0 ? current : { ...current, running: 0 }))
104
129
  }
105
130
 
106
- // The records changed since the last look; the first look only remembers them. A look that fails says nothing: it
107
- // must never stand between the agent and its tool.
108
- async function look(courier: Courier, by: ChangedBy): Promise<string | null> {
131
+ // The records changed since the last look and what they are now, kept by `remember`; the first look finds nothing to
132
+ // tell. A look that fails says nothing: it must never stand between the agent and its tool.
133
+ async function look(courier: Courier, by: ChangedBy): Promise<{ body: string | null; seen: Seen } | null> {
109
134
  try {
110
- const changed = await changedRecords(await courier.project(), (await courier.looks()).seen, by)
111
- await courier.updateLooks(current => ({ ...current, seen: changed.seen }))
112
-
113
- return changed.body
135
+ return await changedRecords(await courier.project(), (await courier.looks()).seen, by)
114
136
  } catch {
115
137
  return null
116
138
  }
117
139
  }
118
140
 
141
+ async function remember(courier: Courier, seen: Seen): Promise<void> {
142
+ await courier.updateLooks(current => ({ ...current, seen }))
143
+ }
144
+
119
145
  // A written file the docs follow is remembered for the next prompt; the map follows a document at once.
120
146
  async function follow(courier: Courier, file: string): Promise<void> {
121
147
  const path = await followWrite(await courier.project(), file).catch(() => null)
@@ -125,14 +151,67 @@ async function follow(courier: Courier, file: string): Promise<void> {
125
151
  )
126
152
  }
127
153
 
128
- // The files written since the last settling, settled now and forgotten; a settling that fails says nothing.
129
- async function settle(courier: Courier): Promise<string | null> {
154
+ // The files written since the last settling, settled now and forgotten once told; a settling that fails says nothing.
155
+ // Nothing to tell is settled and forgotten at once: an adapter calls `delivered` only when a note goes.
156
+ async function settle(courier: Courier): Promise<{ body: string; paths: readonly string[]; write(): Promise<readonly string[]> } | null> {
130
157
  const written = (await courier.looks()).written ?? []
131
158
  if (written.length === 0) return null
132
- await courier.updateLooks(current => ({ ...current, written: (current.written ?? []).filter(path => !written.includes(path)) }))
133
- const lines = await settleDocs(await courier.project(), written).catch(() => [])
159
+ const settled = await settleDocs(await courier.project(), written).catch(() => null)
160
+ if (settled !== null && settled.lines.length > 0) return { body: settled.lines.join('\n'), paths: written, write: settled.write }
161
+ const skipped = (await settled?.write().catch(() => written)) ?? []
162
+ const done = written.filter(path => !skipped.includes(path))
163
+ await forget(courier, done)
164
+ await restamp(courier, done)
165
+
166
+ return null
167
+ }
168
+
169
+ // The documents changed since the last prompt that no write of the agent's tools named — a script, a command — are
170
+ // taken as written, and the map follows them. The first look only remembers: there is nothing to compare with yet.
171
+ async function scripted(courier: Courier): Promise<void> {
172
+ try {
173
+ const project = await courier.project()
174
+ const now = await docStamps(project)
175
+ const before = (await courier.looks()).docs
176
+ const changed = Object.keys(now).filter(path => before?.[path] !== now[path])
177
+ const removed = Object.keys(before ?? {}).some(path => now[path] === undefined)
178
+ if (before !== undefined && (changed.length > 0 || removed)) {
179
+ await courier.updateLooks(current => ({
180
+ ...current,
181
+ written: [...(current.written ?? []), ...changed.filter(path => !(current.written ?? []).includes(path))],
182
+ }))
183
+ await refreshDocs(project, { tocs: false })
184
+ }
185
+ // Remembered once the map follows: a refresh that failed finds the same change at the next look.
186
+ await courier.updateLooks(current => ({ ...current, docs: now }))
187
+ } catch {
188
+ // A look that fails says nothing: the documents are settled at the next one, or at a shift.
189
+ }
190
+ }
191
+
192
+ // A document settled is remembered as it is now, the toc the mod wrote included, so it is not taken for a script's change.
193
+ async function restamp(courier: Courier, paths: readonly string[]): Promise<void> {
194
+ if (paths.length === 0) return
195
+ const now = await docStamps(await courier.project()).catch(() => null)
196
+ if (now === null) return
197
+ await courier.updateLooks(current => {
198
+ if (current.docs === undefined) return current
199
+ const docs = { ...current.docs }
200
+ for (const path of paths) {
201
+ if (now[path] === undefined) delete docs[path]
202
+ else docs[path] = now[path]
203
+ }
204
+ return { ...current, docs }
205
+ })
206
+ }
207
+
208
+ // Seen records compared by value: a harness may keep them serialized.
209
+ function same(a: Seen | null, b: Seen | null): boolean {
210
+ return JSON.stringify(a) === JSON.stringify(b)
211
+ }
134
212
 
135
- return lines.length === 0 ? null : lines.join('\n')
213
+ async function forget(courier: Courier, paths: readonly string[]): Promise<void> {
214
+ await courier.updateLooks(current => ({ ...current, written: (current.written ?? []).filter(path => !paths.includes(path)) }))
136
215
  }
137
216
 
138
217
  function deliver(loop: Loop, notes: readonly Note[]): string[] {
package/core/docs.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  // Generated from core/src by scripts/sync-core.ts — edit the source, not this copy.
2
- import { DIR, MOD } from './layout'
3
- import { frontmatter, type Heading, headings, lineCount, type Pin, pinned } from './markdown'
4
- import { basename, dirname, fromRoot, normalize } from './paths'
2
+ import { DIR, DOCS_MAX_DEPTH, MOD } from './layout'
3
+ import { frontmatter, type Heading, headings, lineCount, lineOutside, linkTargets, type Pin, pinned, unfenced } from './markdown'
4
+ import { basename, dirname, fromRoot, normalize, resolvePath } from './paths'
5
5
  import type { Project } from './project'
6
6
  import type { DocsSettings } from './settings'
7
7
  import type { Store } from './store'
@@ -19,21 +19,22 @@ export function outline(text: string): Heading[] {
19
19
  return headings(text).filter(heading => heading.level === 2 || heading.level === 3)
20
20
  }
21
21
 
22
- // The text with its toc block written from its headings: in place of the old block, else right under the `# ` title;
23
- // null when there is neither.
22
+ // The text with its toc block written from its headings: in place of the old block — its markers on lines of their own,
23
+ // outside code fences — else right under the `# ` title; null when there is neither.
24
24
  export function withToc(text: string): string | null {
25
25
  const rows = outline(text).map(
26
26
  heading => `${' '.repeat(heading.level - 2)}- ${heading.title}${heading.note === '' ? '' : ` - ${heading.note}`}`,
27
27
  )
28
- const block = [TOC_START, ...rows, TOC_END].join('\n')
29
- const start = text.indexOf(TOC_START)
30
- const end = start === -1 ? -1 : text.indexOf(TOC_END, start)
31
- if (end !== -1) return `${text.slice(0, start)}${block}${text.slice(end + TOC_END.length)}`
28
+ const lines = text.split('\n')
29
+ const start = lineOutside(lines, line => line.trim() === TOC_START)
30
+ const end = start === -1 ? -1 : lineOutside(lines, line => line.trim() === TOC_END, start + 1)
31
+ const eol = lines[0]?.endsWith('\r') ? '\r' : ''
32
+ const block = [TOC_START, ...rows, TOC_END].map(line => `${line}${eol}`)
33
+ if (end !== -1) return [...lines.slice(0, start), ...block, ...lines.slice(end + 1)].join('\n')
32
34
  const title = headings(text).find(heading => heading.level === 1)
33
35
  if (title === undefined) return null
34
- const lines = text.split('\n')
35
36
 
36
- return [...lines.slice(0, title.line), '', block, ...lines.slice(title.line)].join('\n')
37
+ return [...lines.slice(0, title.line), eol, ...block, ...lines.slice(title.line)].join('\n')
37
38
  }
38
39
 
39
40
  export function isDoc(path: string, dirs: readonly string[]): boolean {
@@ -63,20 +64,24 @@ export function docRemarks(text: string, docs: DocsSettings): string[] {
63
64
  return remarks
64
65
  }
65
66
 
66
- // Links to documents that are not there: a `<folder>/….md` path anywhere in the text, from the project's root, and in
67
- // a Markdown file a `[text](file.md)` from the file's own folder. A path with `<` or `*` is a pattern, not a link.
67
+ // Links to documents that are not there: in a Markdown file, outside code fences, a link — `[text](file.md)` or a
68
+ // reference's `[ref]: file.md` — from the file's own folder (from the root with a leading `/`); then a bare
69
+ // `<folder>/….md` path anywhere else in the text, from the project's root. A path with `<` or `*` is a pattern, a URL
70
+ // is not the project's, and a link's `?query` and `#fragment` are not part of its file.
68
71
  export async function brokenLinks(store: Store, root: string, path: string, text: string, dirs: readonly string[]): Promise<string[]> {
69
72
  const targets = new Map<string, string | null>()
70
- for (const dir of dirs.map(trimDir).filter(entry => !isFile(entry))) {
71
- const pattern = new RegExp(`(?<![\\w./-])${escapeRegExp(dir)}/[^\\s\`'"()\\[\\],:;»<>*]+?\\.md(?![\\w-])`, 'g')
72
- for (const found of text.matchAll(pattern)) targets.set(found[0], found[0])
73
- }
73
+ let bare = text
74
74
  if (path.endsWith('.md')) {
75
- for (const found of text.matchAll(/\]\(([^)#\s]+\.md)(?:#[^)]*)?\)/g)) {
76
- const link = found[1] ?? ''
77
- if (/^[a-z]+:/i.test(link) || link.includes('*') || targets.has(link)) continue
78
- targets.set(link, normalize(`${dirname(path)}/${link}`))
75
+ bare = unfenced(text)
76
+ for (const { link, file } of linkTargets(text)) {
77
+ if (!link.endsWith('.md') || /^[a-z][\w+.-]*:|^\/\//i.test(link) || link.includes('*')) continue
78
+ targets.set(link, file === null ? null : normalize(file.startsWith('/') ? file.slice(1) : `${dirname(path)}/${file}`))
79
79
  }
80
+ bare = bare.replace(/\]\([^)]*\)/g, ']()').replace(/^ {0,3}\[[^\]]+\]:.*$/gm, '')
81
+ }
82
+ for (const dir of dirs.map(trimDir).filter(entry => !isFile(entry))) {
83
+ const pattern = new RegExp(`(?<![\\w./-])${escapeRegExp(dir)}/[^\\s\`'"()\\[\\],:;»<>*]+?\\.md(?![\\w-])`, 'g')
84
+ for (const found of bare.matchAll(pattern)) if (!targets.has(found[0])) targets.set(found[0], found[0])
80
85
  }
81
86
  const missing: string[] = []
82
87
  for (const [link, target] of targets) {
@@ -98,27 +103,41 @@ export async function followWrite(project: Project, file: string): Promise<strin
98
103
  return path
99
104
  }
100
105
 
101
- // The files written in a run, once it is over: each document gets its toc written, and the remarks — a document's own,
102
- // any file's links still not there — come back as lines of one note. Not after each write: a document written before
103
- // the one it links to has no remark to make, and a toc written mid-run would make the agent read the file again before
104
- // each next edit. None when all is well: a check that speaks on every run is noise.
105
- export async function settleDocs(project: Project, paths: readonly string[]): Promise<string[]> {
106
+ // The files written in a run, once it is over: each document's toc, and the remarks — a document's own, any file's
107
+ // links still not there — as lines of one note. Not after each write: a document written before the one it links to
108
+ // has no remark to make, and a toc written mid-run would make the agent read the file again before each next edit.
109
+ // The tocs are written by `write`, once the note went: a note that did not go finds them still to write. None when all
110
+ // is well: a check that speaks on every run is noise.
111
+ export async function settleDocs(project: Project, paths: readonly string[]): Promise<{ lines: string[]; write(): Promise<string[]> }> {
106
112
  const { store, root, settings } = project
107
113
  const docs = settings.docs
108
- if (!settings.enabled || docs.dirs.length === 0) return []
109
- const rewritten: string[] = []
114
+ const read = new Map<string, string>()
115
+ const tocs = new Map<string, string>()
116
+ // A file changed since it was read keeps its change and is settled again with the next prompt: its toc is not written
117
+ // over it, and its remarks are of the text before. The files skipped come back.
118
+ const write = async () => {
119
+ const skipped: string[] = []
120
+ for (const [path, was] of read) {
121
+ const next = tocs.get(path)
122
+ if ((await store.read(`${root}/${path}`)) !== was) skipped.push(path)
123
+ else if (next !== undefined) await store.write(`${root}/${path}`, next)
124
+ }
125
+
126
+ return skipped
127
+ }
128
+ if (!settings.enabled || docs.dirs.length === 0) return { lines: [], write }
110
129
  const remarked: string[] = []
111
130
  let pins = false
112
131
  for (const path of paths) {
113
132
  let text = await store.read(`${root}/${path}`)
114
133
  if (text === null) continue
134
+ read.set(path, text)
115
135
  const doc = isDoc(path, docs.dirs)
116
136
  if (doc && docs.toc) {
117
137
  const next = withToc(text)
118
138
  if (next !== null && next !== text) {
119
- await store.write(`${root}/${path}`, next)
139
+ tocs.set(path, next)
120
140
  text = next
121
- rewritten.push(path)
122
141
  }
123
142
  }
124
143
  if (doc && pinned(text).length > 0) pins = true
@@ -128,11 +147,11 @@ export async function settleDocs(project: Project, paths: readonly string[]): Pr
128
147
  ]
129
148
  if (remarks.length > 0) remarked.push(`\`${path}\`: ${remarks.join('; ')}.`)
130
149
  }
150
+ const rewritten = [...tocs.keys()]
131
151
  const named = rewritten.map(path => `\`${path}\``).join(', ')
132
152
  // Pinned blocks past the limit are told when a document written has some: the write may be what passed it.
133
153
  const over = pins ? pinnedOver(await refreshDocs(project, { tocs: false }), docs) : null
134
-
135
- return [
154
+ const lines = [
136
155
  ...(rewritten.length === 0
137
156
  ? []
138
157
  : [
@@ -143,6 +162,8 @@ export async function settleDocs(project: Project, paths: readonly string[]): Pr
143
162
  ...(over === null ? [] : [over]),
144
163
  ...remarked,
145
164
  ]
165
+
166
+ return { lines, write }
146
167
  }
147
168
 
148
169
  // The documents with remarks and the root's Markdown files with a broken link, short enough to read after a shift:
@@ -153,10 +174,11 @@ export async function docsReport(project: Project): Promise<string | null> {
153
174
  const docs = settings.docs
154
175
  if (!settings.enabled || docs.dirs.length === 0) return null
155
176
  const rootFiles = (await store.list(root, 'file')).filter(name => name.endsWith('.md'))
177
+ const paths = new Set([...(await docPaths(store, root, docs.dirs)), ...rootFiles])
156
178
  const undescribed: string[] = []
157
179
  const lines: string[] = []
158
180
  const kept: Doc[] = []
159
- for (const path of [...(await docPaths(store, root, docs.dirs)), ...rootFiles]) {
181
+ for (const path of paths) {
160
182
  const text = (await store.read(`${root}/${path}`)) ?? ''
161
183
  if (isDoc(path, docs.dirs)) kept.push(readDoc(path, text))
162
184
  const own = isDoc(path, docs.dirs) ? docRemarks(text, docs) : []
@@ -196,7 +218,7 @@ const REPORT_DOCS = 10
196
218
  // A document's description and its `##` and `###` with line numbers, so the agent reads only the section it needs.
197
219
  export async function docOutline({ store, root }: Project, file: string): Promise<string> {
198
220
  const path = fromRoot(root, file)
199
- const text = await store.read(`${root}/${path}`)
221
+ const text = await store.read(resolvePath(root, path))
200
222
  if (text === null) return `No file at ${path}.`
201
223
  const rows = outline(text).map(
202
224
  heading =>
@@ -242,9 +264,10 @@ export type Doc = { path: string; description: string | null; sections: string[]
242
264
  // has none, a hidden one is skipped — and a named document that is there.
243
265
  export async function docPaths(store: Store, root: string, dirs: readonly string[]): Promise<string[]> {
244
266
  const paths = new Set<string>()
245
- const walk = async (dir: string): Promise<void> => {
267
+ const walk = async (dir: string, depth = 0): Promise<void> => {
246
268
  for (const name of await store.list(`${root}/${dir}`, 'file')) if (name.endsWith('.md')) paths.add(`${dir}/${name}`)
247
- for (const name of await store.list(`${root}/${dir}`, 'dir')) if (!name.startsWith('.')) await walk(`${dir}/${name}`)
269
+ if (depth >= DOCS_MAX_DEPTH) return
270
+ for (const name of await store.list(`${root}/${dir}`, 'dir')) if (!name.startsWith('.')) await walk(`${dir}/${name}`, depth + 1)
248
271
  }
249
272
  for (const entry of dirs.map(trimDir)) {
250
273
  if (!isFile(entry)) await walk(entry)
@@ -254,8 +277,33 @@ export async function docPaths(store: Store, root: string, dirs: readonly string
254
277
  return [...paths].sort((a, b) => a.localeCompare(b))
255
278
  }
256
279
 
280
+ // Every document the settings name with its stamp, from one listing per folder and no reads: what the next prompt
281
+ // compares to find the documents a script changed, which no Edit or Write told the mod of. The map is the mod's own.
282
+ export async function docStamps(project: Project): Promise<Record<string, string>> {
283
+ const { store, root, settings } = project
284
+ const found: Record<string, string> = {}
285
+ if (!settings.enabled) return found
286
+ const walk = async (dir: string, depth = 0): Promise<void> => {
287
+ for (const [name, stamp] of Object.entries(await store.stamps(`${root}/${dir}`)))
288
+ if (name.endsWith('.md') && `${dir}/${name}` !== settings.files.shift) found[`${dir}/${name}`] = stamp
289
+ if (depth >= DOCS_MAX_DEPTH) return
290
+ for (const name of await store.list(`${root}/${dir}`, 'dir')) if (!name.startsWith('.')) await walk(`${dir}/${name}`, depth + 1)
291
+ }
292
+ for (const entry of settings.docs.dirs.map(trimDir)) {
293
+ if (!isFile(entry)) await walk(entry)
294
+ else {
295
+ const folder = dirname(entry)
296
+ const stamp = (await store.stamps(folder === '.' ? root : `${root}/${folder}`))[basename(entry)]
297
+ if (stamp !== undefined && entry !== settings.files.shift) found[entry] = stamp
298
+ }
299
+ }
300
+
301
+ return found
302
+ }
303
+
304
+ // An entry of `[docs] dirs` as paths from the root are written: `./docs/` is `docs`.
257
305
  export function trimDir(dir: string): string {
258
- return dir.replace(/\/+$/, '')
306
+ return dir.replace(/^(\.\/)+/, '').replace(/\/+$/, '')
259
307
  }
260
308
 
261
309
  // An entry of `[docs] dirs` that names one document rather than a folder.
@@ -352,11 +400,18 @@ export function withMap(shift: string | null, map: string): string {
352
400
  if (shift === null) {
353
401
  return `# Shift\n\nHow this project keeps its knowledge. The rules are written on the owner's word; the map below is the mod's.\n\n${map}\n`
354
402
  }
355
- const start = shift.indexOf(MAP_START.slice(0, MAP_START.indexOf(' — ')))
356
- const end = shift.indexOf(MAP_END)
357
- if (start === -1 || end === -1) return `${shift.trimEnd()}\n\n${map}\n`
358
-
359
- return `${shift.slice(0, start)}${map}${shift.slice(end + MAP_END.length)}`
403
+ // The markers on lines of their own, outside code fences: a sentence or an example that names them is the owner's.
404
+ const lines = shift.split('\n')
405
+ // The opener as any version of the mod wrote it: one comment, the whole line, that starts as the mod's does.
406
+ const opener = `${MAP_START.slice(0, MAP_START.indexOf(' — '))} — `
407
+ const start = lineOutside(lines, line => {
408
+ const trimmed = line.trim()
409
+ return trimmed.startsWith(opener) && trimmed.indexOf('-->') === trimmed.length - 3
410
+ })
411
+ const end = start === -1 ? -1 : lineOutside(lines, line => line.trim() === MAP_END, start + 1)
412
+ if (end === -1) return `${shift.trimEnd()}\n\n${map}\n`
413
+
414
+ return [...lines.slice(0, start), map, ...lines.slice(end + 1)].join('\n')
360
415
  }
361
416
 
362
417
  // Every document read once: its toc rewritten when the settings ask for one, then the map in SHIFT.md written when it
@@ -381,7 +436,8 @@ export async function refreshDocs(project: Project, { tocs = true }: { tocs?: bo
381
436
  }
382
437
  const shift = `${root}/${project.settings.files.shift}`
383
438
  const current = await store.read(shift)
384
- if (docs.length === 0 && current === null) return docs
439
+ // A file there that cannot be read is not written over: the owner's text in it would be lost.
440
+ if ((docs.length === 0 || (await store.exists(shift))) && current === null) return docs
385
441
  const map = withMap(current, renderMap(docs, settings, missing))
386
442
  if (map !== current) await store.write(shift, map)
387
443