@iiiokojiadbi/shift 0.36.1 → 0.38.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/core/index.ts CHANGED
@@ -15,6 +15,7 @@ export * from './project'
15
15
  export * from './records'
16
16
  export * from './settings'
17
17
  export * from './setup'
18
+ export * from './sizes'
18
19
  export * from './store'
19
20
  export * from './texts/doctrine'
20
21
  export * from './texts/prompts'
package/core/layout.ts CHANGED
@@ -16,6 +16,8 @@ export const TRACK_TOOL = 'task_track'
16
16
 
17
17
  export const STATUS_TOOL = 'shift_status'
18
18
 
19
+ export const SIZES_TOOL = 'shift_sizes'
20
+
19
21
  export const SETUP_TOOL = 'shift_setup'
20
22
 
21
23
  export const OUTLINE_TOOL = 'doc_outline'
@@ -166,6 +168,8 @@ export const HISTORY_MAX = 50
166
168
  // How many shifts' descriptions go back with the message after a shift.
167
169
  export const RECENT_SHIFTS = 10
168
170
 
171
+ export const RECENT_CLOSED_ITEMS = 10
172
+
169
173
  // A task whose files went unchanged through this many shifts is named after a shift: waiting may have become stuck.
170
174
  export const STUCK_SHIFTS = 5
171
175
 
package/core/loop.ts CHANGED
@@ -63,6 +63,8 @@ export type LetGoHarness = {
63
63
  continueWith(prompt: string, attachments?: readonly unknown[]): Promise<void>
64
64
  // What the harness refreshes once the history is let go, before the message after it.
65
65
  afterLetGo?(): Promise<void>
66
+ // Parks a wait letter in durable history before the waiting outcome is observable.
67
+ parkWait?(note: WaitNote): Promise<void>
66
68
  }
67
69
 
68
70
  export const FRESH_LOOP: LoopState = { pending: null, note: null }
@@ -142,8 +144,9 @@ async function letGoShift(project: Project, loop: Loop, harness: LetGoHarness, s
142
144
  {
143
145
  shift,
144
146
  messages: done.messages,
147
+ parkWait: harness.parkWait,
145
148
  before: done.before ?? before,
146
- after: done.after ?? (await harness.fill()) ?? 0,
149
+ after: done.after ?? (await harness.fill()),
147
150
  },
148
151
  back ?? undefined,
149
152
  )
@@ -155,7 +158,8 @@ async function letGoShift(project: Project, loop: Loop, harness: LetGoHarness, s
155
158
  }
156
159
  if (settled.after === 'wait') {
157
160
  loop.tell(settled.row, 'info')
158
- await leave(loop, harness, settled.note)
161
+ if (harness.parkWait) await dropWaiting(loop)
162
+ else await leave(loop, harness, settled.note)
159
163
  return
160
164
  }
161
165
  loop.tell(settled.row, 'info')
package/core/markdown.ts CHANGED
@@ -197,7 +197,8 @@ function isDay(found: RegExpMatchArray, at: { year: number; month: number; day:
197
197
  export function itemsOf(text: string): Item[] {
198
198
  return text.split('\n').flatMap((raw, index) => {
199
199
  if (!raw.startsWith('- ')) return []
200
- const line = raw.trim()
200
+ const stamp = / <!-- shift-times (\d+|-) (\d+|-) -->$/.exec(raw.trim())
201
+ const line = stamp ? raw.trim().slice(0, stamp.index) : raw.trim()
201
202
  const match = /^- \[([^\]]+)\] *(.*)$/.exec(line)
202
203
  const rest = match?.[2] ?? line.slice(2).trim()
203
204
  const id = /^#(\d+) +/.exec(rest)
@@ -206,6 +207,8 @@ export function itemsOf(text: string): Item[] {
206
207
 
207
208
  return [
208
209
  {
210
+ created: stamp && stamp[1] !== '-' ? Number(stamp[1]) : null,
211
+ closed: stamp && stamp[2] !== '-' ? Number(stamp[2]) : null,
209
212
  status: match?.[1] ?? '',
210
213
  // An id past the safe integers cannot be counted on: the item is numbered anew.
211
214
  id: id === null || !Number.isSafeInteger(Number(id[1])) ? null : Number(id[1]),
@@ -219,6 +222,10 @@ export function itemsOf(text: string): Item[] {
219
222
  })
220
223
  }
221
224
 
225
+ export function trackTimes(created: number | null, closed: number | null): string {
226
+ return created === null && closed === null ? '' : ` <!-- shift-times ${created ?? '-'} ${closed ?? '-'} -->`
227
+ }
228
+
222
229
  export function formatItem(status: string, id: number, name: string, note: string | null): string {
223
230
  return `- [${status}] #${id} ${name}${note === null ? '' : ` — ${note}`}`
224
231
  }
package/core/records.ts CHANGED
@@ -109,7 +109,12 @@ function checkRecords(work: Work, previous: Work | null, project: Pick<Project,
109
109
 
110
110
  // After the agent wrote one record: only the checks of that file, so a broken record is seen as it is written, not
111
111
  // hundreds of K later at the shift. `path` is from the project's root; null for a file that is not a record.
112
- export function checkWritten(path: string, work: Work, project: Pick<Project, 'settings' | 'problem'>): string | null {
112
+ export function checkWritten(
113
+ path: string,
114
+ work: Work,
115
+ project: Pick<Project, 'settings' | 'problem'>,
116
+ deferLinks?: (name: string) => void,
117
+ ): string | null {
113
118
  const { files } = project.settings
114
119
  const [dir, name = '', rest] = path.split('/').slice(1)
115
120
  const inShift = path.startsWith(`${DIR}/`)
@@ -126,7 +131,7 @@ export function checkWritten(path: string, work: Work, project: Pick<Project, 's
126
131
  else if (path === files.glossary) problem = checkGlossary(work.glossary, GLOSSARY)
127
132
  else if (inShift && dir === NAMES.tasks && rest !== undefined) {
128
133
  const task = work.tasks.find(each => each.name === name)
129
- problem = task === undefined ? null : checkTask(task)
134
+ problem = task === undefined ? null : checkTask(task, deferLinks)
130
135
  } else if (inShift && dir === NAMES.knowledge && rest === undefined && name.endsWith('.md')) {
131
136
  const file = work.knowledge.find(each => each.name === name)
132
137
  problem = file === undefined ? null : checkKnowledge(file)
@@ -161,7 +166,7 @@ function checkBoard(board: string): string | null {
161
166
  )
162
167
  }
163
168
 
164
- export function checkTask({ name, task, track, notes: notes_ }: TaskFiles): string | null {
169
+ export function checkTask({ name, task, track, notes: notes_ }: TaskFiles, deferLinks?: (name: string) => void): string | null {
165
170
  const where = `${TASKS}/${name}/`
166
171
  if (task === null) return `${where} has no task.md.`
167
172
  if (track === null) return `${where} has no track.md.`
@@ -174,8 +179,15 @@ export function checkTask({ name, task, track, notes: notes_ }: TaskFiles): stri
174
179
  return `${where}task.md has a "continues:" line: links live in ${TASK_LIST} now. Remove it, and under the task's line there write it as " - continues: [<name>](archive/<name>/)".`
175
180
  const rejected = badRejected(task, `${where}task.md`)
176
181
  if (rejected !== null) return rejected
177
- const notes = checkNotes(where, task, track, notes_)
178
- if (notes !== null) return notes
182
+ for (const note of notes_)
183
+ if ((frontmatter(note.text).get('description') ?? '') === '') {
184
+ return `${where}${NAMES.notes}/${note.name} needs a frontmatter "description": what is in it, as the list after a shift shows it.`
185
+ }
186
+ const notes = noteLinks({ name, task, track, notes: notes_ })
187
+ if (notes !== null) {
188
+ if (!deferLinks) return notes
189
+ deferLinks(name)
190
+ }
179
191
  const bad = itemsOf(track).filter(item => !(STATUSES as readonly string[]).includes(item.status))
180
192
  if (bad.length > 0)
181
193
  return `Track items without a status (${STATUSES.join(', ')}) in ${where}track.md: ${quote(
@@ -208,7 +220,8 @@ function checkOwner(owner: string | null): string | null {
208
220
 
209
221
  // A task's notes: each with its description, each linked from track.md or task.md, every link reaching a note. Beside
210
222
  // the description a note is free: research, a decision worked out, evidence.
211
- function checkNotes(where: string, task: string, track: string, notes: TaskFiles['notes']): string | null {
223
+ export function noteLinks({ name, task, track, notes }: TaskFiles): string | null {
224
+ const where = `${TASKS}/${name}/`
212
225
  // The notes the links reach, as Markdown reads a link outside code fences: its `#fragment` and `?query` are not the
213
226
  // file's, and `%23` is a `#` in its name.
214
227
  const linked = linkTargets(`${task}\n${track}`).flatMap(({ file }) => {
@@ -216,9 +229,6 @@ function checkNotes(where: string, task: string, track: string, notes: TaskFiles
216
229
  return path.startsWith(`${NAMES.notes}/`) ? [path.slice(NAMES.notes.length + 1)] : []
217
230
  })
218
231
  for (const note of notes) {
219
- if ((frontmatter(note.text).get('description') ?? '') === '') {
220
- return `${where}${NAMES.notes}/${note.name} needs a frontmatter "description": what is in it, as the list after a shift shows it.`
221
- }
222
232
  if (!linked.includes(note.name)) {
223
233
  return `${where}${NAMES.notes}/${note.name} is linked from nowhere: link it from its item in ${NAMES.track}, or from ${NAMES.task}, as [what it holds](${NAMES.notes}/${encodeURIComponent(note.name)}).`
224
234
  }
package/core/sizes.ts ADDED
@@ -0,0 +1,77 @@
1
+ // Generated from core/src by scripts/sync-core.ts — edit the source, not this copy.
2
+ import { mapBounds } from './docs'
3
+ import { handBack, sessionFiles } from './flows'
4
+ import { BOARD, LETTER, NAMES, SHIFTS, TASKS } from './layout'
5
+ import type { Project } from './project'
6
+ import { knowledgeMap } from './records'
7
+ import { shiftNames } from './store'
8
+ import {
9
+ continuePrompt,
10
+ fileBlock,
11
+ inProgress,
12
+ notesList,
13
+ renderRecent,
14
+ renderSessionFiles,
15
+ renderStuck,
16
+ trackPreview,
17
+ } from './texts/prompts'
18
+ import { sessionDoctrine } from './tools'
19
+
20
+ // Count complete rendered messages for totals: token boundaries need not align at row edges.
21
+ export async function sizeReport(project: Project, counter?: (text: string) => number): Promise<string> {
22
+ if (!project.settings.enabled) return 'Shift is disabled in this project.'
23
+ const count = counter ?? ((text: string) => Math.ceil(text.length / 4))
24
+ const lines = [
25
+ counter ? 'Text tokens (o200k_base).' : 'Estimated text tokens (4 characters per token).',
26
+ 'Totals include message framing written by Shift. Detail and saved-letter rows are not additive.',
27
+ '',
28
+ '| Delivery | Entity | Tokens |',
29
+ '|---|---|---:|',
30
+ ]
31
+ const row = (group: string, label: string, tokens: number) =>
32
+ lines.push(`| ${group} | ${label.replaceAll('|', '\\|').replace(/[\r\n]/g, ' ')} | ${tokens} |`)
33
+ const files = await sessionFiles(project, { refresh: false })
34
+ const doctrine = sessionDoctrine(project.settings).doctrine
35
+ row('Session', 'Doctrine', count(doctrine))
36
+ for (const file of files) {
37
+ row('Session', file.path, count(fileBlock(file.path, file.text)))
38
+ if (file.path === project.settings.files.shift) {
39
+ const parts = file.text.split('\n')
40
+ const { start, end } = mapBounds(parts)
41
+ if (end >= 0) row('Included above', 'Documentation map', count(parts.slice(start, end + 1).join('\n')))
42
+ }
43
+ }
44
+ const session = count([doctrine, renderSessionFiles(files)].filter(Boolean).join('\n\n'))
45
+ row('Total', 'Session', session)
46
+ const folders = (await shiftNames(project)).reverse()
47
+ const saved: { name: string; letter: string }[] = []
48
+ for (const name of folders) {
49
+ const letter = await project.store.read(`${project.root}/${SHIFTS}/${name}/${NAMES.letter}`)
50
+ if (letter !== null) saved.push({ name, letter })
51
+ if (saved.length === 3) break
52
+ }
53
+ const dir = `${project.root}/${SHIFTS}/${saved[0]?.name ?? '<next-shift>'}`
54
+ const back = await handBack(project, dir)
55
+ if (back.work) {
56
+ row('Continue', BOARD, count(back.work.board))
57
+ for (const task of inProgress(back.work)) {
58
+ const folder = `${TASKS}/${task.name}`
59
+ row('Continue', `${folder}/${NAMES.task}`, count(task.task ?? 'missing'))
60
+ row('Continue', `${folder}/${NAMES.track}`, count(trackPreview(task.track ?? 'missing')))
61
+ if (task.notes.length) row('Continue', `${folder}/notes (descriptions)`, count(notesList(task.name, task.notes)))
62
+ }
63
+ row('Continue', 'Knowledge index', count(knowledgeMap(back.work.knowledge)))
64
+ }
65
+ row('Continue', 'Recent shifts', count(renderRecent(back.recent)))
66
+ if (back.stuck.length) row('Continue', 'Unchanged tasks', count(renderStuck(back.stuck)))
67
+ if (back.remarks) row('Continue', 'Document remarks', count(back.remarks))
68
+ const draft = await project.store.read(`${project.root}/${LETTER}`)
69
+ const letter = draft ?? saved[0]?.letter ?? ''
70
+ row('Continue', draft !== null ? 'Working letter' : saved.length ? 'Latest saved letter' : 'Letter (missing)', count(letter))
71
+ const continuation = count(continuePrompt(letter, back))
72
+ row('Total', 'Continue message', continuation)
73
+ row('Total', 'Session + continue', session + continuation)
74
+ for (const entry of saved) row('Saved letter', `${SHIFTS}/${entry.name}/${NAMES.letter}`, count(entry.letter))
75
+ if (!saved.length) lines.push('', 'No saved letters.')
76
+ return lines.join('\n')
77
+ }
@@ -31,6 +31,7 @@ import {
31
31
  OWNER,
32
32
  OWNER_MAX_LINES,
33
33
  OWNER_SECTION,
34
+ RECENT_CLOSED_ITEMS,
34
35
  RECENT_SHIFTS,
35
36
  RESUME_COMMAND,
36
37
  SETTINGS,
@@ -112,7 +113,7 @@ Each fact lives in one place. Your records live in the project directory, not in
112
113
 
113
114
  const TASK_RULES = `A task is one line of work, split by meaning: a feature, an adapter, a migration. Each lives in \`${TASKS}/<name>/\`, \`<name>\` in ${NAME_RULE}:
114
115
  - \`task.md\` — what the task is: a \`# <title>\` line, then sections ${TASK_SECTIONS.map(s => `"${s}"`).join(', ')}, all required ("none" if empty). Update it as the task changes. Decisions and dead ends that matter only inside this task go here;
115
- - \`track.md\` — the task's tracker: one line per item, \`- [status] #<id> item — what matters\`, status: ${STATUSES.join(', ')}. Add items as you go and set their status with \`${TRACK_TOOL}\`, not by hand: it gives a new item its id and finds an item by it; closed items stay until the task is archived — the track is the task's history;
116
+ - \`track.md\` — the task's tracker: one line per item, \`- [status] #<id> item — what matters\`, status: ${STATUSES.join(', ')}. Add items as you go and set their status with \`${TRACK_TOOL}\`, not by hand: it gives a new item its id and finds an item by it; closed items stay until the task is archived — the track is the task's history. The tools store creation and closure times in a trailing HTML comment. Reopening clears the closure time. After a shift, older closed items remain accessible by reading the track file;
116
117
  - \`${NAMES.notes}/\` — notes, when a line is not enough: research, a decision worked out, evidence. A markdown file with a frontmatter \`description\` and nothing else required, linked from its item in \`track.md\` — \`- [open] #3 item — see [what it holds](${NAMES.notes}/<file>.md)\` — or from \`task.md\` when it is about the whole task. After a shift a task in progress shows its notes as a list with their descriptions; open one when its item comes up. Most items need none.
117
118
 
118
119
  Open a task with \`${OPEN_TOOL}\`, which writes its folder, its files and its line valid at once. Every folder in \`${TASKS}/\` is in \`${TASK_LIST}\`, and every listed task has its folder. What is "in progress" there is what you are doing now — one task, several, or none.`
@@ -145,39 +146,21 @@ You work in stretches and decide yourself when to shift: the stretch's history i
145
146
 
146
147
  ## Board and tasks
147
148
 
148
- \`${BOARD}\` is the state of the work: the goal, the decisions and the dead ends. \`${TASK_LIST}\` says which tasks are open and which you are doing now; each task has its own folder with a description and a tracker. Keep them as you go, not before a shift: took a task, finished an item, dropped one, made a decision, heard the owner's decision, hit a dead end, a term settled — fix the board, \`${TASK_LIST}\`, \`${OWNER}\`, \`${GLOSSARY}\` or the task right away. No board — create it.
149
+ \`${BOARD}\` is the state of the work: the goal, the decisions and the dead ends. \`${TASK_LIST}\` says which tasks are open and which you are doing now; each task has its own folder with a description and a tracker. Keep them as you go, not before a shift: took a task, finished an item, dropped one, made a decision, heard the owner's decision, hit a dead end, a term settled — fix the board, \`${TASK_LIST}\`, \`${OWNER}\`, \`${GLOSSARY}\` or the task right away. No board — create it. Before starting the next item, record the outcome of this one. When a change affects a documented interface, workflow or design decision, update its document alongside the change, following the project's knowledge rules in \`${SHIFT_FILE}\`. At shift time, check the records and write the letter.
149
150
 
150
151
  \`${SHIFT_FILE}\`, \`${OWNER}\`, \`${GLOSSARY}\` and \`${TASK_LIST}\` come into every session whole; the board, the letter and the tasks in progress come after a shift. The settings may move the first three elsewhere in the project.
151
152
 
152
- ${BOARD_RULES}
153
-
154
- ${LIST_RULES}
155
-
156
- ${TASK_RULES}
157
-
158
- A finished or dropped task goes to the archive through \`${ARCHIVE_TOOL}\`, which also takes it out of \`${TASK_LIST}\`; \`${INDEX}\` lists every archived task. A new task may continue an archived one. The project may also have a tracker of its own; it is a different thing — do not link tasks to it.
159
-
160
- ## Owner's decisions and knowledge
161
-
162
- ${OWNER_RULES}
153
+ Open each task with \`${OPEN_TOOL}\`, change its items by ID with \`${TRACK_TOOL}\`, and archive it with \`${ARCHIVE_TOOL}\` when finished. Keep the board current, with Goal, Decisions and Dead ends. Keep a task's decisions in its folder. Write a short linked note when an item needs evidence. Dates belong to the mod's snapshots.
163
154
 
164
- \`${KNOWLEDGE}/\` holds traps, lessons, commands and facts, one file per kind (${Object.keys(KINDS).join(', ')}); write an entry when you learn it, read a file when its topic comes up. The layout and entry fields are in \`${GUIDE_TOOL}\`.
155
+ \`${OWNER}\` is the owner's standing decisions. Update a rule on the owner's word and quote wording that matters. Record decisions for one task in that task. Keep project terms in \`${GLOSSARY}\`. Read \`${SHIFT_FILE}\` for the project's knowledge rules, documentation map and pinned advice. Open the mapped document for details. Keep knowledge local in \`${KNOWLEDGE}/\` until the owner chooses its placement.
165
156
 
166
- ${GLOSSARY_RULES}
167
-
168
- ${SHIFT_RULES}
169
-
170
- What goes where:
171
-
172
- ${PLACES}
157
+ Read \`${GUIDE_TOOL}\` before your first shift in this project. For a record format, ask for section "records"; for the letter, a refusal or how to continue, use "flow".
173
158
 
174
159
  ## When to shift
175
160
 
176
- Never before the first hint, never on a small history. A shift costs the owner's limits: the harness builds its cache of the history anew, and the files of the work are read again. A short stretch does not pay for that, nor for its letter and records, and its history still holds what the next step may need. A finished task is not a reason by itself. Until the first hint, go on working; earlier only on the owner's word. \`${STATUS_TOOL}\` says when the next hint comes.
177
-
178
- After a hint — at a stage boundary: an item or a task is done, a commit is made, the plan moved to its next step — and the stretch's history is not needed whole any more. Not in the middle of a thought that is easier to finish than to write down.
161
+ Keep working until the first hint unless the owner asks for an earlier shift. Each shift rebuilds the history cache and rereads the records. A finished task alone is too early. \`${STATUS_TOOL}\` shows when the next hint comes.
179
162
 
180
- The mod hints with a "Shift hint" line at the end of a tool result or next to a message: the soft hint when the history has grown by a large share of the room since the last shift, the final one when room is running out. On a small window the final hint is the only one. A hint names what the history grew from most. A soft hint is not an order: you decide.
163
+ A soft hint is optional. Shift at a stage boundary when you can continue from your records. At the final hint, shift now. Check the records, write the letter and call \`${TOOL}\` before starting more work. Use \`continue\` when work remains and you can proceed on your own.
181
164
 
182
165
  ## Tools
183
166
 
@@ -191,15 +174,15 @@ ${doctrineBody(tools)}
191
174
  </${MOD}>`
192
175
  }
193
176
 
194
- export const GUIDE = `# Shift: how to shift
177
+ export const GUIDE_FLOW = `# Shift: how to shift
195
178
 
196
- A shift is the boundary between stretches of work. You prepare your records, call \`${TOOL}\`, the stretch's history is let go, and you continue from your letter. You do not change: you write the letter to yourself, not to a successor.
179
+ A shift is the boundary between stretches of work. You check the records kept during the stretch, write your letter and call \`${TOOL}\`, the stretch's history is let go, and you continue from your letter. You do not change: you write the letter to yourself, not to a successor.
197
180
 
198
- First the flow of a shift, then the rules of each record it checks.
181
+ A soft hint leaves the timing to you. At the final hint, start the steps below immediately.
199
182
 
200
183
  ## How to shift
201
184
 
202
- 1. Board and tasks: every open task in \`${TASK_LIST}\` with its status, each touched task's track up to date, decisions recorded where they belong, finished tasks archived.
185
+ 1. Check the board and tasks: every open task in \`${TASK_LIST}\` with its status, each touched task's track up to date, decisions recorded where they belong, finished tasks archived.
203
186
  2. The letter — by its sections below.
204
187
  3. Call \`${TOOL}\`:
205
188
  - \`letter\` — the path to the letter, usually \`${LETTER}\`;
@@ -207,7 +190,7 @@ First the flow of a shift, then the rules of each record it checks.
207
190
  - \`about\` — one line up to ${ABOUT_MAX} characters: what the stretch did and where you stand. This is the history line you will look the stretch up by, and it comes back after the next shifts: write the work, not whether you continue or wait.
208
191
  4. End the turn, nothing more but what the call's result asks: with \`continue\` — one line; with \`wait\` — your answer to the owner, whole: what you did and found, what you ask them to decide. The owner reads that message, not your letter or records.
209
192
 
210
- After the shift, the first message is "Shift done": the board and the tasks in progress, whole, with their notes listed, and the map of knowledge — \`${SHIFT_FILE}\`, \`${OWNER}\`, \`${GLOSSARY}\` and \`${TASK_LIST}\` are read again into the session's own block; then the descriptions of the last ${RECENT_SHIFTS} shifts, an open task unchanged through ${STUCK_SHIFTS} shifts and the documents with remarks, if any; your letter last. Continue from "${NEXT}". With \`wait\` they come together with the owner's next message.
193
+ After the shift you receive the board, active task descriptions, all open items, a count and the latest ${RECENT_CLOSED_ITEMS} closed items per track, with notes listed, and the map of knowledge — \`${SHIFT_FILE}\`, \`${OWNER}\`, \`${GLOSSARY}\` and \`${TASK_LIST}\` are read again into the session's own block; then the descriptions of the last ${RECENT_SHIFTS} shifts, an open task unchanged through ${STUCK_SHIFTS} shifts and the documents with remarks, if any; your letter last. Continue from "${NEXT}". With \`wait\` they come together with the owner's next message.
211
194
 
212
195
  ## Letter — \`${LETTER}\`
213
196
 
@@ -216,12 +199,12 @@ ${described(LETTER_SECTIONS, {
216
199
  'Where I am': 'what you were doing at this moment, the thought you did not finish',
217
200
  Next: 'steps: a command or a file and what you expect',
218
201
  Unverified: 'and what not to trust',
219
- Hold: 'what from this stretch must stay in memory exactly: paths, commands, error texts, values, the line of reasoning. This section and the items in progress of the tasks in progress steer what stays in memory; do not repeat the board, the tasks or the letter — they come back to you whole. A value found in the work and needed later goes into its track item too: memory fades over shifts, the records do not',
202
+ Hold: 'what from this stretch must stay in memory exactly: paths, commands, error texts, values, the line of reasoning. This section and the items in progress of the tasks in progress steer what stays in memory; do not repeat the board, the tasks or the letter — the current records and letter come back to you. A value found in the work and needed later goes into its track item too: memory fades over shifts, the records do not',
220
203
  })}
221
204
 
222
205
  ## When the mod refuses
223
206
 
224
- The mod looks at the records around every tool you run. A record you changed — by Edit, a shell command or a script — is checked by the checks of its file, and what is wrong comes once in that tool's result; silence means it is whole. A record changed between your tools — by the owner or another session — is named in the next result: read it before you write it. The shift checks them all; a refusal names the reason — fix it and call again:
207
+ The mod looks at the records around every tool you run. A record you changed — by Edit, a shell command or a script — is checked by the checks of its file, and problems are reported. Note links settle with the next prompt so the note and its link can be written in either order. A record changed between your tools — by the owner or another session — is named in the next result: read it before you write it. The shift checks them all; a refusal names the reason — fix it and call again:
225
208
  - no letter at the path, a section missing or empty;
226
209
  - no board, a section missing, more than ${BOARD_MAX_LINES} lines, an "${OWNER_SECTION}" or a "${OLD_TASKS_SECTION}" section left on it, a \`rejected:\` without its reason;
227
210
  - no \`${OWNER}\`, an empty one, more than ${OWNER_MAX_LINES} lines, \`${OLD_OWNER}\` still under the old name;
@@ -266,11 +249,13 @@ How to read it: frontmatter — \`key: value\` lines between \`---\`; sections
266
249
 
267
250
  - \`${HISTORY_TOOL}\` with \`count\` (default ${HISTORY_DEFAULT}) — the last shifts in brief: time, outcome, description, what was done, dropped and archived, and for the last one what is open. The stretch in detail — \`letter.md\`, \`board.md\` and \`tasks/\` of its folder.
268
251
  - \`${INDEX}\` — every archived task, one line each.
269
- - In a new session the owner calls \`/${RESUME_COMMAND}\`: the last shift's letter, the board, the owner's decisions, the tasks in progress and the map of knowledge come to you; continue from "${NEXT}".
252
+ - In a new session use \`/${RESUME_COMMAND}\` or the harness's \`${RESUME_COMMAND}\` tool: the last shift's letter, the board, the owner's decisions, the tasks in progress and the map of knowledge come to you; continue from "${NEXT}".
270
253
 
271
254
  How the mod is set up in this project — the settings, the files of the session's block, the layout of \`${DIR}/\`, moving from earlier layouts — is \`${SETUP_TOOL}\`.
272
255
 
273
- ## What goes where
256
+ `
257
+
258
+ export const GUIDE_RECORDS = `## What goes where
274
259
 
275
260
  ${PLACES}
276
261
 
@@ -317,6 +302,8 @@ The tool moves the folder to \`${ARCHIVE}/<name>/\` and adds \`- [<outcome>] [<t
317
302
 
318
303
  To come back to an archived topic, open a new task with \`${OPEN_TOOL}\` and \`continues: ["<name>"]\`, which puts \`- continues: [<name>](archive/<name>/)\` under its line in \`${TASK_LIST}\`; read the archived folder first.`
319
304
 
305
+ export const GUIDE = `${GUIDE_FLOW.trimEnd()}\n\n${GUIDE_RECORDS}`
306
+
320
307
  // The tree's rows: the prefix, the name, padded to its level's column, and what it is.
321
308
  const row = (prefix: string, name: string, width: number, what: string) => `${prefix}${name.padEnd(width)}${what}`
322
309
 
@@ -5,6 +5,7 @@ import {
5
5
  ARCHIVE_TOOL,
6
6
  atPlaces,
7
7
  BOARD,
8
+ CLOSED,
8
9
  DIR,
9
10
  GUIDE_TOOL,
10
11
  HISTORY_MAX,
@@ -16,6 +17,7 @@ import {
16
17
  NAMES,
17
18
  NEXT,
18
19
  OWNER,
20
+ RECENT_CLOSED_ITEMS,
19
21
  RESUME_COMMAND,
20
22
  SETTINGS,
21
23
  SHIFT_COMMAND,
@@ -24,7 +26,7 @@ import {
24
26
  TOOL,
25
27
  TRACK_TOOL,
26
28
  } from '../layout'
27
- import { frontmatter } from '../markdown'
29
+ import { frontmatter, itemsOf } from '../markdown'
28
30
  import { knowledgeMap, listedTasks } from '../records'
29
31
  import type { Placement, Settings } from '../settings'
30
32
  import type { HandedBack, PendingShift, Recent, SessionFile, ShiftAfter, Stuck, Work } from '../types'
@@ -73,14 +75,14 @@ export function unassistedInstructions(files: Settings['files']): string {
73
75
  )
74
76
  }
75
77
 
76
- // The board and the tasks in progress, whole, and the map of knowledge: what the agent stands on after a shift. OWNER.md,
78
+ // The board, active tasks with their track previews, and the map of knowledge: what the agent stands on after a shift. OWNER.md,
77
79
  // TASKS.md, GLOSSARY.md and SHIFT.md are in the session's own block, fresh after every shift.
78
80
  // Each file goes in a tag with its path: the records carry headings and code blocks of their own, so neither can mark where a file ends.
79
81
  export function renderWork(work: Work | null, knowledge: Placement | null, owner: string): string {
80
82
  if (work === null) return `There is no board at ${BOARD}.`
81
83
  const tasks = inProgress(work).flatMap(t => [
82
84
  fileBlock(`${TASKS}/${t.name}/${NAMES.task}`, t.task ?? 'missing'),
83
- fileBlock(`${TASKS}/${t.name}/${NAMES.track}`, t.track ?? 'missing'),
85
+ fileBlock(`${TASKS}/${t.name}/${NAMES.track}`, trackPreview(t.track ?? 'missing')),
84
86
  ...(t.notes.length === 0 ? [] : [notesList(t.name, t.notes)]),
85
87
  ])
86
88
 
@@ -91,8 +93,20 @@ export function renderWork(work: Work | null, knowledge: Placement | null, owner
91
93
  ].join('\n\n')
92
94
  }
93
95
 
96
+ export function trackPreview(text: string): string {
97
+ const items = itemsOf(text)
98
+ const closed = items.filter(item => CLOSED.has(item.status)).sort((a, b) => (b.closed ?? -1) - (a.closed ?? -1) || b.index - a.index)
99
+ const omitted = new Set(closed.slice(RECENT_CLOSED_ITEMS).map(item => item.index))
100
+ const lines = text.split('\n')
101
+ for (const item of items) lines[item.index] = item.line
102
+ const preview = lines.filter((_, i) => !omitted.has(i)).join('\n')
103
+ if (!closed.length) return preview
104
+ const detail = omitted.size ? `; latest ${RECENT_CLOSED_ITEMS} shown. Read the track file for all items.` : '.'
105
+ return `${preview.trimEnd()}\n\n${closed.length} closed${detail}`
106
+ }
107
+
94
108
  // A task's notes, by their descriptions: read one when its item comes up; they do not come whole.
95
- function notesList(task: string, notes: Work['tasks'][number]['notes']): string {
109
+ export function notesList(task: string, notes: Work['tasks'][number]['notes']): string {
96
110
  const folder = `${TASKS}/${task}/${NAMES.notes}`
97
111
  const rows = notes.map(note => `- ${folder}/${note.name} — ${frontmatter(note.text).get('description') ?? 'no description'}`)
98
112
 
@@ -123,7 +137,7 @@ export function fileBlock(path: string, text: string): string {
123
137
  return `<file path="${path}">\n${text.trim()}\n</file>`
124
138
  }
125
139
 
126
- function inProgress(work: Work): Work['tasks'] {
140
+ export function inProgress(work: Work): Work['tasks'] {
127
141
  const doing = new Set(
128
142
  listedTasks(work)
129
143
  .filter(t => t.status === 'in progress')
@@ -202,7 +216,7 @@ function shiftMessage(opening: string, letter: string, back: HandedBack, closing
202
216
  }
203
217
 
204
218
  // After a let-go the agent cannot tell its first shift from a later one, and read the guide before every shift.
205
- const GUIDE_KNOWN = `You have shifted here before: read ${GUIDE_TOOL} again only if a refusal sends you to it.`
219
+ const GUIDE_KNOWN = `You have shifted here before: use ${GUIDE_TOOL} for a specific record format or refusal.`
206
220
 
207
221
  export function continuePrompt(letter: string, back: HandedBack): string {
208
222
  return shiftMessage('Shift done. You continue from where you stopped.', letter, back, [GUIDE_KNOWN, `Continue from "${NEXT}".`])
@@ -227,7 +241,7 @@ export function resumePrompt(letter: string, back: HandedBack, outcome: string |
227
241
  back,
228
242
  [
229
243
  `Past shifts — ${HISTORY_TOOL}; archived tasks — ${INDEX}; how a shift works — ${GUIDE_TOOL}.`,
230
- `Check "${NEXT}" against what is on disk now and continue from the first step not done; a message from the owner after this one goes first.`,
244
+ `Check "${NEXT}" against what is on disk now and continue from the first step not done; the owner's accompanying request takes priority.`,
231
245
  ],
232
246
  )
233
247
  }
@@ -18,6 +18,7 @@ import {
18
18
  OUTCOMES,
19
19
  OUTLINE_TOOL,
20
20
  SETUP_TOOL,
21
+ SIZES_TOOL,
21
22
  STATUS_TOOL,
22
23
  STATUSES,
23
24
  TASK_LIST,
@@ -29,8 +30,7 @@ import { quote } from '../markdown'
29
30
 
30
31
  export const TOOL_DESCRIPTION = `Make a shift: the stretch's history is let go, and you continue from your letter to yourself (after: continue) or wait for the owner (after: wait). Before the call the board, the tasks and the letter must be ready — how is in ${GUIDE_TOOL}, read once per project. After the call, end the turn: one line with continue; with wait, your whole answer to the owner — it is all they read. Only the main agent shifts: a subagent's call is refused.`
31
32
 
32
- export const GUIDE_DESCRIPTION =
33
- 'How to shift: the steps, the letter, when the mod refuses, the strict structure of about.md, then the rules of the board, the tasks, the archive and the other records a shift checks. Read it once, before your first shift in a project; after that only when a refusal sends you to it — the steps do not change between shifts.'
33
+ export const GUIDE_DESCRIPTION = `How to shift: the steps, the letter, when the mod refuses, the strict structure of about.md, then the rules of the board, the tasks, the archive and the other records a shift checks. Read it once, before your first shift in a project; use section "flow" or "records" to look up one part later.`
34
34
 
35
35
  export const SETUP_DESCRIPTION =
36
36
  "How the mod is set up in this project: every key of settings.toml with its value here, its default and the mod's version it came in; the records by every check a shift makes; the files loaded into every session and whether this session's copy is older than them; the documents with remarks; the layout of .shift/ and moving from earlier layouts. Call it when setting a project up, after the mod or the settings changed, or when the session's files look stale."
@@ -130,7 +130,12 @@ export const MENTIONS_SCHEMA = {
130
130
  required: ['file'],
131
131
  }
132
132
 
133
- export const GUIDE_SCHEMA = { type: 'object', properties: {} }
133
+ export const GUIDE_SCHEMA = {
134
+ type: 'object',
135
+ properties: {
136
+ section: { type: 'string', enum: ['flow', 'records'], description: 'Optional part to read. Omit for the complete guide.' },
137
+ },
138
+ }
134
139
 
135
140
  export const HISTORY_SCHEMA = {
136
141
  type: 'object',
@@ -189,8 +194,7 @@ export const TOOL_TEXTS: Record<string, ToolText> = {
189
194
  [GUIDE_TOOL]: {
190
195
  label: 'Shift guide',
191
196
  description: GUIDE_DESCRIPTION,
192
- brief:
193
- 'how to shift properly and how the files are laid out. Read it once, before your first shift in a project; after that only when a refusal sends you to it — the steps do not change between shifts.',
197
+ brief: 'the shift procedure and record formats, optionally by section.',
194
198
  schema: GUIDE_SCHEMA,
195
199
  },
196
200
  [TOOL]: { label: 'Shift', description: TOOL_DESCRIPTION, brief: 'make a shift.', schema: TOOL_SCHEMA },
@@ -224,6 +228,13 @@ export const TOOL_TEXTS: Record<string, ToolText> = {
224
228
  brief: 'how full the history is, when the next hints come, and what it grew from.',
225
229
  schema: STATUS_SCHEMA,
226
230
  },
231
+ [SIZES_TOOL]: {
232
+ label: 'Shift sizes',
233
+ description:
234
+ 'Report estimated token counts by entity for the session and continuation, and for the last three saved letters. Returns sizes and paths only.',
235
+ brief: 'sizes of delivered records and saved letters.',
236
+ schema: SETUP_SCHEMA,
237
+ },
227
238
  [SETUP_TOOL]: {
228
239
  label: 'Shift setup',
229
240
  description: SETUP_DESCRIPTION,
package/core/tools.ts CHANGED
@@ -13,6 +13,7 @@ import {
13
13
  OPEN_TOOL,
14
14
  OUTLINE_TOOL,
15
15
  SETUP_TOOL,
16
+ SIZES_TOOL,
16
17
  STATUS_TOOL,
17
18
  TOOL,
18
19
  TRACK_TOOL,
@@ -21,7 +22,8 @@ import { holdShift, type Loop } from './loop'
21
22
  import type { Project } from './project'
22
23
  import type { Settings } from './settings'
23
24
  import { setupReport } from './setup'
24
- import { doctrine, doctrineBody, GUIDE } from './texts/doctrine'
25
+ import { sizeReport } from './sizes'
26
+ import { doctrine, doctrineBody, GUIDE, GUIDE_FLOW, GUIDE_RECORDS } from './texts/doctrine'
25
27
  import { EXCLUDED, SHIFT_TOO_EARLY } from './texts/prompts'
26
28
  import { TOOL_TEXTS, type ToolText } from './texts/tools'
27
29
  import { updateTrack } from './track'
@@ -62,7 +64,15 @@ export type Tool = ToolText & {
62
64
  type Row = Omit<Tool, keyof ToolText | 'writes' | 'docs'> & { writes?: boolean; docs?: boolean }
63
65
 
64
66
  const ROWS: readonly Row[] = [
65
- { name: GUIDE_TOOL, run: async (_raw, call) => ({ result: atPlaces(GUIDE, (await call.project()).settings.files) }) },
67
+ {
68
+ name: GUIDE_TOOL,
69
+ run: async (raw, call) => {
70
+ if (raw.section !== undefined && raw.section !== 'flow' && raw.section !== 'records')
71
+ return { deny: 'section must be flow or records.' }
72
+ const guide = raw.section === 'flow' ? GUIDE_FLOW : raw.section === 'records' ? GUIDE_RECORDS : GUIDE
73
+ return { result: atPlaces(guide.trimEnd(), (await call.project()).settings.files) }
74
+ },
75
+ },
66
76
  {
67
77
  name: TOOL,
68
78
  writes: true,
@@ -86,7 +96,7 @@ const ROWS: readonly Row[] = [
86
96
  run: async (raw, call) => {
87
97
  const input = parseOpenInput(raw)
88
98
 
89
- return typeof input === 'string' ? { deny: input } : openTask(await call.project(), input)
99
+ return typeof input === 'string' ? { deny: input } : openTask(await call.project(), input, await call.now())
90
100
  },
91
101
  },
92
102
  {
@@ -104,7 +114,7 @@ const ROWS: readonly Row[] = [
104
114
  run: async (raw, call) => {
105
115
  const input = parseTrackInput(raw)
106
116
 
107
- return typeof input === 'string' ? { deny: input } : updateTrack(await call.project(), input)
117
+ return typeof input === 'string' ? { deny: input } : updateTrack(await call.project(), input, await call.now())
108
118
  },
109
119
  },
110
120
  {
@@ -116,6 +126,7 @@ const ROWS: readonly Row[] = [
116
126
  },
117
127
  },
118
128
  { name: STATUS_TOOL, run: async (_raw, call) => ({ result: await call.status() }) },
129
+ { name: SIZES_TOOL, run: async (_raw, call) => ({ result: await sizeReport(await call.project()) }) },
119
130
  { name: SETUP_TOOL, run: async (_raw, call) => ({ result: await setupReport(await call.project(), await call.loaded()) }) },
120
131
  {
121
132
  name: OUTLINE_TOOL,