@iiiokojiadbi/shift 0.0.0-stage → 0.28.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.
@@ -0,0 +1,373 @@
1
+ // Generated from core/src by scripts/sync-core.ts — edit the source, not this copy.
2
+ import { TOC_END, TOC_START } from '../docs'
3
+ import {
4
+ ABOUT_MAX,
5
+ ARCHIVE,
6
+ ARCHIVE_TOOL,
7
+ BOARD,
8
+ BOARD_MAX_LINES,
9
+ BOARD_SECTIONS,
10
+ DIR,
11
+ FOCUS,
12
+ GLOSSARY,
13
+ GLOSSARY_MAX_LINES,
14
+ GUIDE_TOOL,
15
+ HISTORY_DEFAULT,
16
+ HISTORY_TOOL,
17
+ INDEX,
18
+ KINDS,
19
+ KNOWLEDGE,
20
+ KNOWLEDGE_MAX_LINES,
21
+ LETTER,
22
+ LETTER_SECTIONS,
23
+ MAX_AUTO_STREAK,
24
+ MOD,
25
+ NAME_RULE,
26
+ NAMES,
27
+ NEXT,
28
+ OLD_DIR,
29
+ OLD_OWNER,
30
+ OLD_TASKS_SECTION,
31
+ OPEN_TOOL,
32
+ OWNER,
33
+ OWNER_MAX_LINES,
34
+ OWNER_SECTION,
35
+ RECENT_SHIFTS,
36
+ RESUME_COMMAND,
37
+ SETTINGS,
38
+ SETUP_TOOL,
39
+ SHIFT_FILE,
40
+ STATUS_TOOL,
41
+ STATUSES,
42
+ STUCK_SHIFTS,
43
+ TASK_LIST,
44
+ TASK_SECTIONS,
45
+ TASKS,
46
+ TOOL,
47
+ TRACK_TOOL,
48
+ } from '../layout'
49
+ import { TOOL_TEXTS } from './tools'
50
+
51
+ // A list of sections in their order, each with what goes in it: a section without its text does not compile.
52
+ function described<Name extends string>(names: readonly Name[], texts: Record<Name, string>): string {
53
+ return names.map((name, at) => `- "${name}" — ${texts[name]}${at === names.length - 1 ? '.' : ';'}`).join('\n')
54
+ }
55
+
56
+ const BOARD_RULES = `The board is a state, not a diary:
57
+ - lines are rewritten in place, nothing new is appended on top of the old;
58
+ - no dates anywhere, in the board or in tasks: each shift's time is recorded by itself;
59
+ - no more than ${BOARD_MAX_LINES} lines.
60
+
61
+ Sections, as \`##\` headings, all required (an empty one says "none"):
62
+ ${described(BOARD_SECTIONS, {
63
+ Goal: 'what the project is for and how that changed, briefly',
64
+ Decisions: 'yours, for the whole project, with the reason; a decision may name what it turned down: `rejected: <option> — <why>`',
65
+ 'Dead ends': 'approaches tried and ruled out for the whole project, and why',
66
+ })}
67
+
68
+ A decision or dead end goes on the board only if it outlives any one task; otherwise it belongs to the task. A rejected option is not a dead end: it was weighed, not tried.`
69
+
70
+ const LIST_RULES = `\`${TASK_LIST}\` lists every open task, one line each, and under it the links to other tasks:
71
+
72
+ \`\`\`
73
+ - [in progress] [adapters](tasks/adapters/) — the shift in other harnesses
74
+ - needs: [core-port](tasks/core-port/) — the port comes first
75
+ - after: [settings](archive/settings/)
76
+ - continues: [old-adapters](archive/old-adapters/)
77
+ \`\`\`
78
+
79
+ Status: ${FOCUS.join(', ')}; deferred and waiting — with the reason in the line. Links: \`needs\` — an open task this one cannot finish without; \`after\` — a done task it stands on; \`continues\` — an archived task it picks up. No task yet — "none".`
80
+
81
+ const OWNER_RULES = `\`${OWNER}\` is the owner's decisions in force for the whole project: a code of rules as it stands now, not a log. Verbatim where the owner's words matter, grouped under \`##\` headings by meaning, no dates, no "revoked" marks, no more than ${OWNER_MAX_LINES} lines; no decisions yet — "none". A new word is checked against what is written: it contradicts a rule — the rule is rewritten; it narrows, widens or refines one — the rule is rewritten to cover both; it is new — a new line. A rule changes or goes only on the owner's word. A decision that binds one task goes to that task's "${OWNER_SECTION}".`
82
+
83
+ const KNOWLEDGE_KINDS = `- \`traps\` — what behaves not as expected: \`### <symptom>\`, then ${KINDS.traps.join(' and ')};
84
+ - \`lessons\` — an approach that worked or failed: \`### <approach>\`, then ${KINDS.lessons.join(' and ')};
85
+ - \`runbook\` — what is run and with what: \`### <task>\`, a command block, then ${KINDS.runbook.join(' and ')};
86
+ - \`facts\` — how the project, its tools or its harness behave: \`### <fact>\`, then ${KINDS.facts.join(' and ')} (how it was established).
87
+
88
+ Terms are not a kind: they live in \`${GLOSSARY}\`.`
89
+
90
+ const KNOWLEDGE_RULES = `\`${KNOWLEDGE}/\` is what you learned that stays true for months: traps, lessons, commands, facts. One file per kind — \`<kind>.md\`, or \`<kind>-<topic>.md\` once split by topic; a frontmatter with \`kind\` and \`about\` (what is in the file and where the neighbouring files are); entries grouped under \`##\` headings by topic. Kinds and the fields every entry carries:
91
+ ${KNOWLEDGE_KINDS}
92
+
93
+ No dates, no more than ${KNOWLEDGE_MAX_LINES} lines per file. Freshness is checked when an entry is used, not by age: an entry that lied is fixed or removed right away; a trap met a third time is rewritten as a rule. Writing into a section, clear out what is dead there: a trap about code that is gone, an entry a later one covers, a one-off case with no conclusion, a copy of the project's docs. After a shift only the map of knowledge comes back — read a file when its topic comes up.`
94
+
95
+ const PLACES = `| What | Where |
96
+ |---|---|
97
+ | the owner's decision for the whole project | \`${OWNER}\` |
98
+ | the owner's decision for one task | that task's "${OWNER_SECTION}" |
99
+ | your decision or dead end for the whole project | the board |
100
+ | your decision or dead end for one task | the task's \`task.md\` |
101
+ | which tasks are open, what you do now, how they link | \`${TASK_LIST}\` |
102
+ | open work and its progress | \`${TASKS}/<name>/\` |
103
+ | what you were doing, what is next, what is unverified | the letter |
104
+ | a trap, a lesson, a command, a fact | \`${KNOWLEDGE}/\`, unless the owner said it goes to the project's docs |
105
+ | a term of the project | \`${GLOSSARY}\` |
106
+ | where knowledge goes here, how the docs are kept | \`${SHIFT_FILE}\`, on the owner's word |
107
+ | fits no row | \`${KNOWLEDGE}/\`, and tell the owner |
108
+
109
+ Whether knowledge goes into the project's own docs (\`AGENTS.md\`, \`docs/\`, read by people and every contributor) or stays in \`${KNOWLEDGE}/\` is the owner's choice, not yours: all of it in the docs, all of it local, or split by a boundary the owner names. The owner sets it as \`knowledge\` in \`${SETTINGS}\` — "local", "project" or "split"; with "split" the boundary is a rule in \`${OWNER}\`. After a shift the map of knowledge says which. Until it is set, everything stays in \`${KNOWLEDGE}/\` — never write the project's shared files on your own guess — and ask the owner once. What the project's docs already say is never copied into your records.
110
+
111
+ Each fact lives in one place. Your records live in the project directory, not in a harness's memory: any agent that opens the project reads them.`
112
+
113
+ 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
+ - \`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
+ - \`${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
+ 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.`
119
+
120
+ const GLOSSARY_RULES = `\`${GLOSSARY}\` holds the project's own words, one article each — names, codes, abbreviations, terms that mean something particular here:
121
+
122
+ \`\`\`
123
+ ## Stretch
124
+ Variants: stretches
125
+ Means: the work between two shifts.
126
+ Avoid: session
127
+ Where: the owner says «отрезок».
128
+ Unconfirmed: is a stretch ever longer than a session?
129
+ \`\`\`
130
+
131
+ \`Means\` says what the thing is, not what it does, in one or two sentences; \`Avoid\` — words not to use for it, so one thing has one name; \`Variants\` and \`Where\` as needed. Labels are in English; the term and its meaning in the language the term lives in. Write an article as a term settles in the talk, not at a shift. A meaning you inferred and did not check with the owner carries \`Unconfirmed: <what to ask>\` — ask, then drop the line. Only this project's words; no general programming terms.`
132
+
133
+ const SHIFT_RULES = `\`${SHIFT_FILE}\` is how this project keeps its knowledge: rules written on the owner's word — where each kind of knowledge goes, how the documents are kept — and a map of the documents the mod writes between its markers. The map lists each document the settings name — a folder of them, or one such as \`AGENTS.md\` — with its \`description:\` (frontmatter: what is in the file and when to open it) and its \`##\` sections. The map only points: numbers, commands and names come from the document itself. A document without a description shows as such — give it one. A folder or a document of the settings with nothing to list is named in the map as \`no such folder\`, \`no documents\` or \`no such file\`: the project has no docs there, do not go searching. With \`[docs] dirs = []\` the owner turned the map off: leave the project's docs as they are.
134
+
135
+ A \`> [!IMPORTANT]\` block in one of those documents is pinned: the map shows it under its document with its section, so it is in front of you in every session without opening the document. Pin only what you would get wrong in any task without it, in a line or two; change it in the document, never in the map. Nothing is pinned until you pin it. Past \`[docs] max_pinned\` the map says so and still shows every block — unpin what is not needed in every task.
136
+
137
+ Those documents the mod keeps as you write them. After an Edit or a Write the map follows at once; with \`[docs] toc = true\` each document carries a toc between \`${TOC_START}\` and \`${TOC_END}\` under its \`# \` title, written by the mod from its \`##\` and \`###\` and the \`> \` line under a heading — never edit it by hand, and read the file again when the mod says it rewrote it. Remarks come once, in the tool's result: no description, a description or a file over the limits the settings set, a link to a document that is not there. Silence means all is well. The documents with remarks also come after a shift.`
138
+
139
+ // The section's text without its tag, for a harness that wraps a prompt section in a tag of its own; the tools are the
140
+ // ones shown in this project, in the order given.
141
+ export function doctrineBody(tools: readonly string[]): string {
142
+ return `# Shift
143
+
144
+ You work in stretches and decide yourself when to shift: the stretch's history is let go, and you continue from where you stopped. You do not change — only what is in front of you does. So everything you need next must be in your records, and a thought you have not written down yet goes into a letter to yourself.
145
+
146
+ ## Board and tasks
147
+
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
+
150
+ \`${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
+ ${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}
163
+
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}\`.
165
+
166
+ ${GLOSSARY_RULES}
167
+
168
+ ${SHIFT_RULES}
169
+
170
+ What goes where:
171
+
172
+ ${PLACES}
173
+
174
+ ## When to shift
175
+
176
+ Not before the first soft hint. A finished task is not a reason by itself: a short stretch does not pay for its letter and records, and its history still holds what the next step may need. Until the soft hint, go on working; earlier only on the owner's word. \`${STATUS_TOOL}\` says when the next hint comes.
177
+
178
+ After the soft 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.
179
+
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 noticeably since the last shift, the final one when room is running out. A hint names what the history grew from most. A soft hint is not an order: you decide.
181
+
182
+ ## Tools
183
+
184
+ ${tools.map(name => `- \`${name}\` — ${TOOL_TEXTS[name]?.brief ?? ''}`).join('\n')}`
185
+ }
186
+
187
+ // In a tag that names the mod: the agent tells this section from the owner's own instructions.
188
+ export function doctrine(tools: readonly string[]): string {
189
+ return `<${MOD} note="how the ${MOD} mod works: its tools, its records and when to shift">
190
+ ${doctrineBody(tools)}
191
+ </${MOD}>`
192
+ }
193
+
194
+ export const GUIDE = `# Shift: how to shift
195
+
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.
197
+
198
+ First the flow of a shift, then the rules of each record it checks.
199
+
200
+ ## How to shift
201
+
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.
203
+ 2. The letter — by its sections below.
204
+ 3. Call \`${TOOL}\`:
205
+ - \`letter\` — the path to the letter, usually \`${LETTER}\`;
206
+ - \`after\` — \`continue\` if there is work to do without the owner; \`wait\` if the owner is needed or the work is over;
207
+ - \`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
+ 4. End the turn, no further actions: 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
+
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. ${MAX_AUTO_STREAK} \`continue\` in a row without the owner — the mod then waits for the owner itself.
211
+
212
+ ## Letter — \`${LETTER}\`
213
+
214
+ Written anew, whole, before every shift. Sections \`##\`, all required and non-empty (nothing to say — "none"):
215
+ ${described(LETTER_SECTIONS, {
216
+ 'Where I am': 'what you were doing at this moment, the thought you did not finish',
217
+ Next: 'steps: a command or a file and what you expect',
218
+ 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',
220
+ })}
221
+
222
+ ## When the mod refuses
223
+
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:
225
+ - no letter at the path, a section missing or empty;
226
+ - 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
+ - no \`${OWNER}\`, an empty one, more than ${OWNER_MAX_LINES} lines, \`${OLD_OWNER}\` still under the old name;
228
+ - a knowledge file with an unknown \`kind\`, a name not of its kind, no \`about\`, more than ${KNOWLEDGE_MAX_LINES} lines, an entry without its fields, a glossary kept as knowledge;
229
+ - \`${GLOSSARY}\`: an article without \`Means\`, an unknown label, a word in two articles, an avoided word used as a term, more than ${GLOSSARY_MAX_LINES} lines;
230
+ - a date (\`YYYY-MM-DD\` or \`DD.MM.YYYY\`) in any record;
231
+ - \`${DIR}/\` not ignored by the project's git, \`commit\` not set, and no exclude file to add it to;
232
+ - \`${TASK_LIST}\`: a task with an unknown status or name, a folder not listed, a listed task without a folder, a link to nothing, \`needs\` on an archived task, tasks needing each other in a circle;
233
+ - a task without \`task.md\` or \`track.md\`, without a title or a section, a track item without a status, a \`continues:\` line left in \`task.md\`, a note without its \`description\` or linked from nowhere, a link to a note that is not there;
234
+ - nothing changed in the records since the last shift;
235
+ - \`about\` empty, multi-line or longer than ${ABOUT_MAX} characters.
236
+
237
+ ## about.md — strict structure
238
+
239
+ \`\`\`
240
+ ---
241
+ description: <about from the call>
242
+ at: <ISO time of the shift, UTC>
243
+ after: continue | wait
244
+ result: pending | shifted (<before> → <after>), continuing | shifted (…), waiting for the owner | shifted (…), waiting: … in a row without the owner | not shifted: <reason> | let go, not settled: <reason>
245
+ tokens: <before> → <after>
246
+ summary_chars: <size of summary.md>
247
+ session: <session id>
248
+ ---
249
+
250
+ ## Done
251
+ - <task>: <item — what matters> or "none"
252
+
253
+ ## Dropped
254
+ - <task>: <item — reason> or "none"
255
+
256
+ ## Archived
257
+ - <the index line> or "none"
258
+
259
+ ## Open
260
+ - [<status>] [<task>](tasks/<task>/) — what matters or "none"
261
+ \`\`\`
262
+
263
+ How to read it: frontmatter — \`key: value\` lines between \`---\`; sections — by \`## \` headings, items — lines starting with \`- \`. "Done" and "Dropped" — track items closed during this stretch (not closed in the previous shift's snapshot); "Archived" — index lines added during this stretch; "Open" — the lines of \`${TASK_LIST}\` at the moment of the shift. The mod derives all of it from the files, not you. \`result: pending\` on an old folder means the session broke off before the shift finished.
264
+
265
+ ## History and a new session
266
+
267
+ - \`${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
+ - \`${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}".
270
+
271
+ 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
+
273
+ ## What goes where
274
+
275
+ ${PLACES}
276
+
277
+ ## Board — \`${BOARD}\`
278
+
279
+ ${BOARD_RULES}
280
+
281
+ ## Open tasks — \`${TASK_LIST}\`
282
+
283
+ ${LIST_RULES}
284
+
285
+ ## Owner's decisions — \`${OWNER}\`
286
+
287
+ ${OWNER_RULES}
288
+
289
+ ## Tasks — \`${TASKS}/\`
290
+
291
+ ${TASK_RULES}
292
+
293
+ ## Glossary — \`${GLOSSARY}\`
294
+
295
+ ${GLOSSARY_RULES}
296
+
297
+ ## Knowledge rules and the docs map — \`${SHIFT_FILE}\`
298
+
299
+ ${SHIFT_RULES}
300
+
301
+ ## Knowledge — \`${KNOWLEDGE}/\`
302
+
303
+ ${KNOWLEDGE_RULES}
304
+
305
+ ## No dates
306
+
307
+ No record carries a date: a model writes them everywhere, and records turn into a diary. Which of two rules is newer is never a question — a newer word rewrites the older line in place and a revoked one is removed, so only what is in force stands. When something was decided, the shift snapshots tell: \`${HISTORY_TOOL}\` finds the stretch, its folder holds the records as they were.
308
+
309
+ ## Archive — \`${ARCHIVE}/\`
310
+
311
+ When a task is finished or dropped, call \`${ARCHIVE_TOOL}\`:
312
+ - \`name\` — the task's folder name;
313
+ - \`outcome\` — \`done\` (every track item is done or dropped) or \`dropped\` (the reason goes into \`about\`);
314
+ - \`about\` — one line up to ${ABOUT_MAX} characters: what the task was and how it ended. This is the index line you will look the task up by.
315
+
316
+ The tool moves the folder to \`${ARCHIVE}/<name>/\` and adds \`- [<outcome>] [<title>](<name>/) — <about>\` to \`${INDEX}\`, with \`; continues <name>, …\` if the task continued archived ones, takes its line out of \`${TASK_LIST}\` and points the other tasks' links to it into the archive. Then lift to the board any of its decisions that still bind beyond it.
317
+
318
+ 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
+
320
+ export const SETUP_LAYOUT = `\`\`\`
321
+ ${DIR}/
322
+ ├── board.md the board — the goal, project-wide decisions and dead ends
323
+ ├── TASKS.md the open tasks, what you do now, their links — every session
324
+ ├── OWNER.md the owner's decisions in force for the whole project — every session
325
+ ├── GLOSSARY.md the project's own words — every session
326
+ ├── SHIFT.md how the project keeps its knowledge, and the map of its docs — every session
327
+ ├── settings.toml the owner's settings, optional — above
328
+ ├── letter.md the letter to yourself — written anew before every shift
329
+ ├── knowledge/ traps, lessons, commands, facts — read on demand
330
+ │ └── <kind>[-<topic>].md
331
+ ├── tasks/
332
+ │ └── <name>/
333
+ │ ├── task.md what the task is, its decisions and dead ends
334
+ │ ├── track.md the task's tracker
335
+ │ └── ${NAMES.notes}/ notes on its items, each linked from track.md or task.md
336
+ ├── archive/ written by ${ARCHIVE_TOOL}; do not edit
337
+ │ ├── index.md one line per archived task
338
+ │ └── <name>/ the task's folder as it was
339
+ └── shifts/ history, written by the mod; do not edit
340
+ └── <YYYYMMDD-hhmmss UTC>/
341
+ ├── about.md the shift in brief — its structure is in ${GUIDE_TOOL}
342
+ ├── letter.md a copy of the letter
343
+ ├── board.md a snapshot of the board
344
+ ├── TASKS.md, OWNER.md, GLOSSARY.md, SHIFT.md, settings.toml snapshots
345
+ ├── index.md a snapshot of the archive index
346
+ ├── tasks/ snapshots of the open tasks
347
+ ├── knowledge/ a snapshot of the knowledge
348
+ └── summary.md what stayed in memory after the shift
349
+ \`\`\`
350
+
351
+ \`${DIR}/\` is yours. Whether the project's git takes it in is the owner's choice (\`commit\` above); by default it stays out: when the project's git does not ignore it, the mod adds it to the repository's local exclude file, which is never committed, and says so. It needs no git of its own: every shift snapshots the board, the owner's decisions, the tasks and the knowledge, so removing a line is safe.`
352
+
353
+ export const SETUP_MIGRATION = `## Coming from the earlier layout
354
+
355
+ Records kept before \`${TASK_LIST}\`, \`${OWNER}\` and \`${GLOSSARY}\` are moved once, before the next shift; the refusals name each step:
356
+ - \`${OLD_DIR}/\` → \`${DIR}/\`, the folder renamed as it is;
357
+ - \`${OLD_OWNER}\` → \`${OWNER}\`, renamed as it is;
358
+ - the board's "${OLD_TASKS_SECTION}" section → \`${TASK_LIST}\`: each line as \`- [status] [name](tasks/name/) — what matters\`, and the \`continues:\` lines of each \`task.md\` under it as \`- continues: [name](archive/name/)\`;
359
+ - \`${KNOWLEDGE}/glossary*.md\` → \`${GLOSSARY}\`, one article per term;
360
+ - where knowledge goes, if \`${OWNER}\` spells it out by kind of knowledge → \`${SHIFT_FILE}\`, on the owner's word.
361
+
362
+ ## Coming from the shift skill
363
+
364
+ A project kept with the \`shift\`/\`unshift\` skills has a \`${DIR}/\` of their making: \`sessions/\`, \`AGENTS.md\`, \`SHIFT.md\` (the skill's own text), a \`shift\` script, \`knowledge/\`, sometimes a \`.git\` of its own. The mod uses the same folder, and works on it only once it has a board. Move it in place, once, entry by entry — nothing is dropped:
365
+ - \`knowledge/owner.md\` → \`${OWNER}\`, rules as they are;
366
+ - \`knowledge/traps*.md\`, \`lessons*.md\`, \`runbook*.md\` stay in \`${KNOWLEDGE}/\` under the same names: keep \`kind\` and \`about\`, rename the entry fields (Причина → Cause, Делать → Do, Почему → Why, Когда не годится → Not when, Покажет → Shows), drop the date lines and the generated tables of contents;
367
+ - \`knowledge/glossary*.md\` → \`${GLOSSARY}\`, one article per term: the meaning into \`Means\`, other spellings into \`Variants\`; a meaning the files only guessed gets \`Unconfirmed\`;
368
+ - the \`knowledge\` setting of \`AGENTS.md\` (\`project\`, \`local\`, \`split\`) → \`knowledge\` in \`${SETTINGS}\`; its "Что где" rows → \`${SHIFT_FILE}\` on the owner's word;
369
+ - open items of the last snapshot's \`unfinished.md\` and its "С чего начать" → tasks in \`${TASK_LIST}\`; its owner decisions → \`${OWNER}\` or the task's; dead ends → the board or the task;
370
+ - the skill's \`SHIFT.md\`, \`shift\` script and \`AGENTS.md\` go once their content is moved: \`${SHIFT_FILE}\` is the project's own file now. A \`.git\` inside goes only on the owner's word;
371
+ - \`sessions/\` stays as it is: it is history.
372
+
373
+ The text of records may stay in its language, and the owner is quoted verbatim; section names and entry fields are the ones above.`
@@ -0,0 +1,261 @@
1
+ // Generated from core/src by scripts/sync-core.ts — edit the source, not this copy.
2
+ import { readAbout } from '../about'
3
+ import {
4
+ ARCHIVE,
5
+ ARCHIVE_TOOL,
6
+ atPlaces,
7
+ BOARD,
8
+ DIR,
9
+ GUIDE_TOOL,
10
+ HISTORY_MAX,
11
+ HISTORY_TOOL,
12
+ INDEX,
13
+ KNOWLEDGE,
14
+ LETTER,
15
+ MOD,
16
+ NAMES,
17
+ NEXT,
18
+ OWNER,
19
+ RESUME_COMMAND,
20
+ SETTINGS,
21
+ TASK_LIST,
22
+ TASKS,
23
+ TRACK_TOOL,
24
+ } from '../layout'
25
+ import { frontmatter } from '../markdown'
26
+ import { knowledgeMap, listedTasks } from '../records'
27
+ import type { Placement, Settings } from '../settings'
28
+ import type { HandedBack, PendingShift, Recent, SessionFile, ShiftAfter, Stuck, Work } from '../types'
29
+
30
+ // The `note=` of each kind of note the mod tells the agent, so it tells the note from what the note came with.
31
+ export const NOTE_KINDS = {
32
+ hint: 'a hint from the mod, not part of what it came with',
33
+ records: "the mod's check of the records just changed",
34
+ docs: "the mod's check of the file just written",
35
+ } as const
36
+
37
+ export type NoteKind = keyof typeof NOTE_KINDS
38
+
39
+ export const OPENED = (name: string, line: string, track: string) =>
40
+ `Opened ${TASKS}/${name}/ with task.md and track.md, and its line in ${TASK_LIST}:\n${line}\n${track === '' ? '' : `Its items, each changed with ${TRACK_TOOL} by its id:\n${track}`}Its decisions, dead ends and owner decisions say "none" until there are some; add items as you go with ${TRACK_TOOL}.`
41
+
42
+ export const ARCHIVED = (name: string) =>
43
+ `Archived to ${ARCHIVE}/${name}/, its line is in ${INDEX}, and ${TASK_LIST} no longer lists it: links to it now point into the archive. Lift to the board any of its decisions that still bind beyond it.`
44
+
45
+ // What the engine's summarizer is told; the model never sees this framing.
46
+ export function compactInstructions(shift: Pick<PendingShift, 'hold' | 'board' | 'owner' | 'dir' | 'focus'>): string {
47
+ const focus = shift.focus ?? []
48
+ return [
49
+ 'The agent is shifting: it continues this same work right after, from its own letter.',
50
+ `Its work board (${shift.board}), the owner's decisions (${shift.owner ?? OWNER}), its task folders (${TASKS}/), its knowledge (${KNOWLEDGE}/) and its letter (${shift.dir}/${NAMES.letter}) are on disk and will be delivered to it, so do not repeat tasks, statuses, rules, lessons or next steps.`,
51
+ 'Keep, as precisely as possible, what it asked to hold below, and the reasoning behind its current approach; everything else in this history may be dropped or reduced to one line.',
52
+ 'Do not write next steps or a plan.',
53
+ ...(focus.length === 0
54
+ ? []
55
+ : [
56
+ '',
57
+ 'What it is working on now — keep the reasoning, findings and failed attempts around these fuller than the rest:',
58
+ ...focus.map(each => `- ${each}`),
59
+ ]),
60
+ '',
61
+ 'What the agent asked to hold:',
62
+ shift.hold,
63
+ ].join('\n')
64
+ }
65
+
66
+ // Added to an automatic compaction the agent did not ask for.
67
+ export function unassistedInstructions(files: Settings['files']): string {
68
+ return atPlaces(
69
+ `The agent did not shift before this point, so there is no letter. Its work board may be on disk at ${BOARD}, the owner's decisions at ${OWNER}, its tasks in ${TASKS}/. Keep the overall goal and how it evolved, open tasks with their status, decisions with their reasons, exact paths, commands, error texts and values. End with a short "Where to continue" section.`,
70
+ files,
71
+ )
72
+ }
73
+
74
+ // The board and the tasks in progress, whole, and the map of knowledge: what the agent stands on after a shift. OWNER.md,
75
+ // TASKS.md, GLOSSARY.md and SHIFT.md are in the session's own block, fresh after every shift.
76
+ // 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.
77
+ export function renderWork(work: Work | null, knowledge: Placement | null, owner: string): string {
78
+ if (work === null) return `There is no board at ${BOARD}.`
79
+ const tasks = inProgress(work).flatMap(t => [
80
+ fileBlock(`${TASKS}/${t.name}/${NAMES.task}`, t.task ?? 'missing'),
81
+ fileBlock(`${TASKS}/${t.name}/${NAMES.track}`, t.track ?? 'missing'),
82
+ ...(t.notes.length === 0 ? [] : [notesList(t.name, t.notes)]),
83
+ ])
84
+
85
+ return [
86
+ fileBlock(BOARD, work.board),
87
+ ...(tasks.length === 0 ? ['No task is in progress.'] : tasks),
88
+ `<knowledge path="${KNOWLEDGE}/" note="read a file when its topic comes up" goes="${placement(knowledge, owner)}">\n${knowledgeMap(work.knowledge)}\n</knowledge>`,
89
+ ].join('\n\n')
90
+ }
91
+
92
+ // A task's notes, by their descriptions: read one when its item comes up; they do not come whole.
93
+ function notesList(task: string, notes: Work['tasks'][number]['notes']): string {
94
+ const folder = `${TASKS}/${task}/${NAMES.notes}`
95
+ const rows = notes.map(note => `- ${folder}/${note.name} — ${frontmatter(note.text).get('description') ?? 'no description'}`)
96
+
97
+ return `<notes path="${folder}/" note="read a note when its item comes up">\n${rows.join('\n')}\n</notes>`
98
+ }
99
+
100
+ // Where new knowledge goes, by the owner's \`knowledge\` setting.
101
+ function placement(knowledge: Placement | null, owner: string): string {
102
+ if (knowledge === 'local') return 'here: the owner set knowledge = "local"'
103
+ if (knowledge === 'project') return 'to the project\'s docs: the owner set knowledge = "project"'
104
+ if (knowledge === 'split') return `split by the boundary in ${owner}: the owner set knowledge = "split"`
105
+
106
+ return `here until the owner sets knowledge in ${SETTINGS}; ask them once`
107
+ }
108
+
109
+ // The files loaded into every session, each in its tag; they change during the session only on disk.
110
+ export function renderSessionFiles(files: readonly SessionFile[]): string | null {
111
+ if (files.length === 0) return null
112
+
113
+ return [
114
+ `<${MOD} note="loaded at the session's start and after each shift; the files on disk are newer if you changed them since">`,
115
+ ...files.map(each => fileBlock(each.path, each.text)),
116
+ `</${MOD}>`,
117
+ ].join('\n\n')
118
+ }
119
+
120
+ export function fileBlock(path: string, text: string): string {
121
+ return `<file path="${path}">\n${text.trim()}\n</file>`
122
+ }
123
+
124
+ function inProgress(work: Work): Work['tasks'] {
125
+ const doing = new Set(
126
+ listedTasks(work)
127
+ .filter(t => t.status === 'in progress')
128
+ .map(t => t.name),
129
+ )
130
+
131
+ return work.tasks.filter(t => doing.has(t.name))
132
+ }
133
+
134
+ // What a shift hands back, as paths inside the records folder: the owner's row names them.
135
+ export function deliveredFiles(work: Work | null): string[] {
136
+ if (work === null) return [NAMES.letter]
137
+ const tasks = inProgress(work).map(t => `${NAMES.tasks}/${t.name}/`)
138
+ const knowledge = work.knowledge.length === 0 ? [] : [`${NAMES.knowledge}/ (the map)`]
139
+
140
+ return [NAMES.letter, NAMES.board, ...tasks, ...knowledge]
141
+ }
142
+
143
+ // What the agent did before this stretch: a line per recent shift, oldest first, from its about.md.
144
+ export function renderRecent(recent: Recent): string {
145
+ if (recent.entries.length === 0) return 'No earlier shifts.'
146
+ const earlier = recent.total - recent.entries.length
147
+ const shifts = (n: number) => (n === 1 ? '1 shift' : `${n} shifts`)
148
+ // No `after`: a row of past waits would pull the agent towards waiting when it could go on.
149
+ const lines = recent.entries.map(entry => `- ${entry.name} · ${readAbout(entry.about ?? '').description ?? 'no about.md'}`)
150
+
151
+ return [
152
+ `What you did before: the last ${shifts(recent.entries.length)}, oldest first, the one you shifted from last.`,
153
+ ...(earlier > 0
154
+ ? [
155
+ `${shifts(earlier)} before them ${earlier === 1 ? 'is' : 'are'} not listed: ${HISTORY_TOOL} reads them, up to ${HISTORY_MAX} at a time.`,
156
+ ]
157
+ : []),
158
+ '<shifts>',
159
+ ...lines,
160
+ '</shifts>',
161
+ ].join('\n')
162
+ }
163
+
164
+ // Tasks whose files went unchanged through many shifts: a wait that may have become stuck, or work forgotten.
165
+ export function renderStuck(stuck: readonly Stuck[]): string {
166
+ return [
167
+ `Tasks unchanged through the last shifts — still right? Ask the owner, change the status, or archive the task as dropped with ${ARCHIVE_TOOL}:`,
168
+ ...stuck.map(task => `- ${task.name} (${task.status}) — ${task.shifts} shifts`),
169
+ ].join('\n')
170
+ }
171
+
172
+ // Everything a shift hands back, in one tag that names the mod: the agent sees at once what came from where.
173
+ // Ordered by how a context is read: the records first as reference, the recent shifts in the middle, the letter last,
174
+ // right before the turn, so its "Next" is what the agent sees closest to acting.
175
+ function shiftMessage(opening: string, letter: string, back: HandedBack, closing: string[] = []): string {
176
+ const { work, recent, dir, remarks } = back
177
+
178
+ return [
179
+ `<${MOD} folder="${dir}/">`,
180
+ opening,
181
+ '',
182
+ 'The board, the tasks in progress and the map of knowledge, as they are now; SHIFT.md, OWNER.md, GLOSSARY.md and TASKS.md are in your session block, read again after this shift:',
183
+ '',
184
+ renderWork(work, back.knowledge, back.owner),
185
+ '',
186
+ renderRecent(recent),
187
+ '',
188
+ ...(back.stuck.length === 0 ? [] : [renderStuck(back.stuck), '']),
189
+ ...(remarks === null ? [] : ['Documents with remarks from the mod — fix them as the work passes by them:', '', remarks, '']),
190
+ 'Your letter to yourself, written right before the shift:',
191
+ '',
192
+ `<letter path="${dir}/${NAMES.letter}">`,
193
+ letter.trim(),
194
+ '</letter>',
195
+ '',
196
+ `The letter and the snapshots of this shift: ${dir}/.`,
197
+ ...closing,
198
+ `</${MOD}>`,
199
+ ].join('\n')
200
+ }
201
+
202
+ // After a let-go the agent cannot tell its first shift from a later one, and read the guide before every shift.
203
+ const GUIDE_KNOWN = `You have shifted here before: read ${GUIDE_TOOL} again only if a refusal sends you to it.`
204
+
205
+ export function continuePrompt(letter: string, back: HandedBack): string {
206
+ return shiftMessage('Shift done. You continue from where you stopped.', letter, back, [GUIDE_KNOWN, `Continue from "${NEXT}".`])
207
+ }
208
+
209
+ export function waitContext(letter: string, back: HandedBack): string {
210
+ return shiftMessage("You shifted and waited for the owner; the owner's message is above.", letter, back, [GUIDE_KNOWN])
211
+ }
212
+
213
+ export function resumePrompt(letter: string, back: HandedBack): string {
214
+ return shiftMessage(
215
+ 'You pick up the work from the last shift: this is a new session, you have no history of the previous one, only the records.',
216
+ letter,
217
+ back,
218
+ [
219
+ `Past shifts — ${HISTORY_TOOL}; archived tasks — ${INDEX}; how a shift works — ${GUIDE_TOOL}.`,
220
+ `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.`,
221
+ ],
222
+ )
223
+ }
224
+
225
+ // What starts the turn after /unshift when the owner wrote nothing with it: the letter is already in the history.
226
+ export const RESUME_GO = `<${MOD} note="from the mod after /${RESUME_COMMAND}">Pick up from the shift above: continue from "${NEXT}".</${MOD}>`
227
+
228
+ // How the turn ends once a shift is accepted. The owner reads the turn's last message, not the letter or the records:
229
+ // with `wait` it is the answer they come back to.
230
+ const TURN_END: Record<ShiftAfter, string> = {
231
+ continue: 'End the turn with one line and do nothing more',
232
+ wait: 'End the turn with your answer to the owner, whole — what you did and found, what you ask them to decide — and do nothing more: it is all the owner reads before you wait, they see neither your records nor this call',
233
+ }
234
+
235
+ export const ACCEPTED = (dir: string, learned: boolean, after: ShiftAfter) =>
236
+ `Shift accepted, the letter and the snapshots: ${dir}/. ${learned ? '' : `Nothing went into ${KNOWLEDGE}/ this stretch: if you learned something that stays true for months — a trap, a lesson, a command, a fact — write it where knowledge goes here first, while the stretch is still whole. `}${TURN_END[after]}. After the turn the stretch's history is let go, and you continue from the letter${after === 'wait' ? " with the owner's next message" : ''}.`
237
+
238
+ export const NOT_IGNORED = `${DIR}/ is not ignored by this project's git, and the repository's own exclude file was not found. Add "${DIR}/" to the project's .gitignore, or ask the owner to set commit = true in ${SETTINGS}, and call again.`
239
+
240
+ // The records were not ignored and the mod excluded them: told to the agent and to the owner.
241
+ export const EXCLUDED = (file: string) =>
242
+ `${DIR}/ was not ignored by this project's git: the mod added "${DIR}/" to ${file}, which stays local. To commit the records with the project, the owner sets commit = true in ${SETTINGS}.`
243
+
244
+ // The shift refused before anything is written: the harness would not let this history go.
245
+ export const SHIFT_TOO_EARLY = (why: string) =>
246
+ `Nothing to shift yet: ${why} Nothing was written. Keep working with the records as they are, and shift once the history has grown — after the first soft hint.`
247
+
248
+ // A shift accepted and then not made: the agent was told it was accepted, so it is told it was not.
249
+ export const NOT_MADE_NOTE = (name: string, why: string) =>
250
+ `<${MOD} note="from the mod: the shift was not made">
251
+ Shift ${name} was not made — ${why}. Nothing was let go: your history is whole, and your records stay as you wrote them; the shift's folder is kept as history. Go on from where you stopped, and shift again later.
252
+ </${MOD}>`
253
+
254
+ // A shift let go and its message not built: the agent has lost its history and got nothing back.
255
+ export const UNSETTLED_NOTE = (name: string, why: string, dir: string) =>
256
+ `<${MOD} note="from the mod: the history was let go, the records were not handed back">
257
+ Shift ${name}: the history was let go, but the mod could not hand your records back — ${why}. Read ${LETTER} (a copy is in ${dir}/${NAMES.letter}), then ${BOARD} and ${TASK_LIST}, and continue from "${NEXT}".
258
+ </${MOD}>`
259
+
260
+ // What the owner's row names when a failure's note went with their message.
261
+ export const FAILURE_NOTE = 'the note that the shift failed'