@iiiokojiadbi/shift 0.38.2 → 0.39.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/docs.ts +22 -49
- package/core/layout.ts +1 -1
- package/core/settings.ts +2 -2
- package/core/texts/doctrine.ts +16 -4
- package/core/texts/tools.ts +1 -1
- package/package.json +1 -1
package/core/docs.ts
CHANGED
|
@@ -258,7 +258,7 @@ function escapeRegExp(text: string): string {
|
|
|
258
258
|
export const MAP_START = `<!-- ${MOD}:docs — written by the mod from each document's description and ## headings; edit those, not this -->`
|
|
259
259
|
export const MAP_END = `<!-- /${MOD}:docs -->`
|
|
260
260
|
|
|
261
|
-
export type Doc = { path: string; description: string | null; sections: string[]; pins: Pin[] }
|
|
261
|
+
export type Doc = { path: string; description: string | null; archived?: boolean; sections: string[]; pins: Pin[] }
|
|
262
262
|
|
|
263
263
|
// Every document the settings name, from the project's root, sorted: each .md file under a folder — a missing folder
|
|
264
264
|
// has none, a hidden one is skipped — and a named document that is there.
|
|
@@ -316,14 +316,9 @@ function entryName(entry: string): string {
|
|
|
316
316
|
return isFile(entry) ? `\`${entry}\`` : `\`${entry}/\``
|
|
317
317
|
}
|
|
318
318
|
|
|
319
|
-
//
|
|
320
|
-
// crowds the session and loses the descriptions last. A map cut down says so, and what this level dropped, so the
|
|
321
|
-
// agent knows what it does not see. A folder of the
|
|
322
|
-
// settings with nothing to list is named with why — no such folder, or no documents in it — so the agent knows the
|
|
323
|
-
// project has no docs there and does not go searching. `[docs] dirs = []` is the owner turning the map off — the
|
|
324
|
-
// project's docs may be shared with people and not the agent's to describe — and the block says just that.
|
|
319
|
+
// Each active entry keeps its sections regardless of the size of its siblings.
|
|
325
320
|
export function renderMap(docs: readonly Doc[], settings: DocsSettings, missing: readonly string[]): string {
|
|
326
|
-
const { dirs
|
|
321
|
+
const { dirs } = settings
|
|
327
322
|
if (dirs.length === 0) {
|
|
328
323
|
const off =
|
|
329
324
|
"off: the owner set `[docs] dirs = []` in the settings. No map of the documents; do not add descriptions, headings or anything else to the project's docs for it."
|
|
@@ -342,41 +337,17 @@ export function renderMap(docs: readonly Doc[], settings: DocsSettings, missing:
|
|
|
342
337
|
}
|
|
343
338
|
// A folder before the folders inside it.
|
|
344
339
|
const sorted = [...folders].sort(([a], [b]) => a.localeCompare(b))
|
|
345
|
-
const
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
)
|
|
357
|
-
const size = (body: string[]): number => body.join('\n\n').length
|
|
358
|
-
const full = listed(true)
|
|
359
|
-
const described = listed(false)
|
|
360
|
-
const over = `the full map is ${size(full)} characters, over \`[docs] max_chars = ${maxChars}\` in the settings`
|
|
361
|
-
const back =
|
|
362
|
-
'Tell the owner: they may raise `[docs] max_chars`; shorter descriptions and fewer `##` sections also bring the map back whole.'
|
|
363
|
-
const [body, note] =
|
|
364
|
-
size(full) <= maxChars
|
|
365
|
-
? [full, 'Open a document for numbers, commands and names: the map only points.']
|
|
366
|
-
: size(described) <= maxChars
|
|
367
|
-
? [
|
|
368
|
-
described,
|
|
369
|
-
`Cut down: ${over}. Dropped at this level: the \`sections:\` line of every document — open a document for its \`##\` sections. Whole: every document with its description. ${back}`,
|
|
370
|
-
]
|
|
371
|
-
: [
|
|
372
|
-
sorted.map(([folder, inside]) =>
|
|
373
|
-
[
|
|
374
|
-
`- \`${folder}/\` — ${inside.length} docs: ${inside.map(doc => basename(doc.path)).join(', ')}`,
|
|
375
|
-
...inside.flatMap(doc => (doc.pins.length === 0 ? [] : [` \`${doc.path}\`:`, ...pinRows(doc.pins, ' ')])),
|
|
376
|
-
].join('\n'),
|
|
377
|
-
),
|
|
378
|
-
`Cut down: ${over}, and ${size(described)} without the sections. Dropped at this level: the description and the sections of every document — read a document's frontmatter \`description:\` for what it holds. Whole: every folder with its file names. ${back}`,
|
|
379
|
-
]
|
|
340
|
+
const body = sorted.map(([folder, inside]) =>
|
|
341
|
+
[
|
|
342
|
+
`### ${folder}/`,
|
|
343
|
+
'',
|
|
344
|
+
...inside.flatMap(doc => [
|
|
345
|
+
`- \`${doc.path}\` — ${doc.archived ? '[archived] ' : ''}${doc.description ?? 'no description: add `description:` to its frontmatter'}`,
|
|
346
|
+
...(doc.archived || doc.sections.length === 0 ? [] : [` sections: ${doc.sections.join(' · ')}`]),
|
|
347
|
+
...pinRows(doc.pins),
|
|
348
|
+
]),
|
|
349
|
+
].join('\n'),
|
|
350
|
+
)
|
|
380
351
|
const nothing = empty.length === 0 ? [] : ['', 'Nothing to list:', ...empty]
|
|
381
352
|
const pins = pinnedOver(docs, settings)
|
|
382
353
|
|
|
@@ -385,7 +356,7 @@ export function renderMap(docs: readonly Doc[], settings: DocsSettings, missing:
|
|
|
385
356
|
'',
|
|
386
357
|
`## Documents`,
|
|
387
358
|
'',
|
|
388
|
-
|
|
359
|
+
'Open a document for numbers, commands and names: the map only points.',
|
|
389
360
|
...(pins === null ? [] : ['', pins]),
|
|
390
361
|
'',
|
|
391
362
|
body.join('\n\n'),
|
|
@@ -420,7 +391,7 @@ export function mapBounds(lines: readonly string[]) {
|
|
|
420
391
|
}
|
|
421
392
|
|
|
422
393
|
// Group the rendered map by its actual entries, including the sections and pins under each.
|
|
423
|
-
//
|
|
394
|
+
// Older maps can contain folder entries. Rules and map-level notices can be refreshed by path.
|
|
424
395
|
export function mapParts(text: string) {
|
|
425
396
|
const lines = text.split('\n')
|
|
426
397
|
const { start, end } = mapBounds(lines)
|
|
@@ -469,14 +440,14 @@ export async function refreshDocs(project: Project, { tocs = true }: { tocs?: bo
|
|
|
469
440
|
|
|
470
441
|
// A document's pinned blocks under its entry, each with the section it is in: the label on a line of its own, then
|
|
471
442
|
// every line of the block under it starting with " · ", a list item's own marker replaced.
|
|
472
|
-
function pinRows(pins: readonly Pin[]
|
|
443
|
+
function pinRows(pins: readonly Pin[]): string[] {
|
|
473
444
|
return pins.flatMap(pin => [
|
|
474
|
-
|
|
445
|
+
` pinned${pin.section === null ? '' : ` (${pin.section})`}:`,
|
|
475
446
|
...pin.text
|
|
476
447
|
.split('\n')
|
|
477
448
|
.map(line => line.trim().replace(/^[-*+] +/, ''))
|
|
478
449
|
.filter(line => line !== '')
|
|
479
|
-
.map(line =>
|
|
450
|
+
.map(line => ` · ${line}`),
|
|
480
451
|
])
|
|
481
452
|
}
|
|
482
453
|
|
|
@@ -491,9 +462,11 @@ export function pinnedOver(docs: readonly Doc[], settings: DocsSettings): string
|
|
|
491
462
|
|
|
492
463
|
// What the map shows of a document.
|
|
493
464
|
function readDoc(path: string, text: string): Doc {
|
|
465
|
+
const meta = frontmatter(text)
|
|
494
466
|
return {
|
|
495
467
|
path,
|
|
496
|
-
description: description
|
|
468
|
+
description: meta.get('description') || null,
|
|
469
|
+
archived: meta.get('archived') === 'true',
|
|
497
470
|
sections: outline(text)
|
|
498
471
|
.filter(h => h.level === 2)
|
|
499
472
|
.map(h => h.title),
|
package/core/layout.ts
CHANGED
|
@@ -42,7 +42,7 @@ export const TASKS_MAX_LINES = 150
|
|
|
42
42
|
// GLOSSARY.md comes into every session whole.
|
|
43
43
|
export const GLOSSARY_MAX_LINES = 400
|
|
44
44
|
|
|
45
|
-
//
|
|
45
|
+
// Historical default for the accepted docs.max_chars setting.
|
|
46
46
|
export const DOCS_MAP_MAX_CHARS = 100000
|
|
47
47
|
|
|
48
48
|
// The pinned blocks of the docs, in characters; past it the map says so, and shows them all still.
|
package/core/settings.ts
CHANGED
|
@@ -18,7 +18,7 @@ export type Settings = {
|
|
|
18
18
|
}
|
|
19
19
|
|
|
20
20
|
// The project's documents the mod keeps: the folders, relative to the project's root (none — the mod touches no
|
|
21
|
-
// document),
|
|
21
|
+
// document), whether each document carries a toc, and the limits a document is
|
|
22
22
|
// checked against after an edit (null — no such check).
|
|
23
23
|
export type DocsSettings = {
|
|
24
24
|
dirs: string[]
|
|
@@ -114,7 +114,7 @@ export const SETTING_KEYS: readonly Key[] = [
|
|
|
114
114
|
since: '0.4.3',
|
|
115
115
|
kind: 'limit',
|
|
116
116
|
at: ['docs', 'maxChars'],
|
|
117
|
-
about: '
|
|
117
|
+
about: 'legacy setting accepted for compatibility; the map shows every active document with its sections at any size',
|
|
118
118
|
},
|
|
119
119
|
{
|
|
120
120
|
key: 'docs.max_pinned',
|
package/core/texts/doctrine.ts
CHANGED
|
@@ -20,6 +20,7 @@ import {
|
|
|
20
20
|
KNOWLEDGE_MAX_LINES,
|
|
21
21
|
LETTER,
|
|
22
22
|
LETTER_SECTIONS,
|
|
23
|
+
MENTIONS_TOOL,
|
|
23
24
|
MOD,
|
|
24
25
|
NAME_RULE,
|
|
25
26
|
NAMES,
|
|
@@ -28,6 +29,7 @@ import {
|
|
|
28
29
|
OLD_OWNER,
|
|
29
30
|
OLD_TASKS_SECTION,
|
|
30
31
|
OPEN_TOOL,
|
|
32
|
+
OUTLINE_TOOL,
|
|
31
33
|
OWNER,
|
|
32
34
|
OWNER_MAX_LINES,
|
|
33
35
|
OWNER_SECTION,
|
|
@@ -131,7 +133,7 @@ Unconfirmed: is a stretch ever longer than a session?
|
|
|
131
133
|
|
|
132
134
|
Each field is one line. \`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.`
|
|
133
135
|
|
|
134
|
-
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.
|
|
136
|
+
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. With \`archived: true\` in its frontmatter, the entry shows its path, archive status, description and pins. Use \`${OUTLINE_TOOL}\` for 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.
|
|
135
137
|
|
|
136
138
|
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.
|
|
137
139
|
|
|
@@ -146,15 +148,15 @@ You work in stretches and decide yourself when to shift: the stretch's history i
|
|
|
146
148
|
|
|
147
149
|
## Board and tasks
|
|
148
150
|
|
|
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,
|
|
151
|
+
\`${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, choose its document by the behavior that changed and update it alongside the change. ${tools.includes(MENTIONS_TOOL) ? `Use \`${MENTIONS_TOOL}\` to find additional filename references. ` : ''}Follow the project's knowledge rules in \`${SHIFT_FILE}\`. At shift time, check the records and write the letter.
|
|
150
152
|
|
|
151
153
|
\`${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.
|
|
152
154
|
|
|
153
155
|
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.
|
|
154
156
|
|
|
155
|
-
\`${OWNER}\` is the owner's standing decisions.
|
|
157
|
+
\`${OWNER}\` is the owner's standing decisions. On the owner's word, find the rule on that subject, check its scope and revise it in place. Add a line for a distinct decision. Quote wording that determines its meaning. 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.
|
|
156
158
|
|
|
157
|
-
Read \`${GUIDE_TOOL}\` before your first shift in this project. For
|
|
159
|
+
Read \`${GUIDE_TOOL}\` before your first shift in this project. For writing project documentation or keeping records, ask for section "records"; for the letter, a refusal or how to continue, use "flow".
|
|
158
160
|
|
|
159
161
|
## When to shift
|
|
160
162
|
|
|
@@ -259,6 +261,16 @@ export const GUIDE_RECORDS = `## What goes where
|
|
|
259
261
|
|
|
260
262
|
${PLACES}
|
|
261
263
|
|
|
264
|
+
## Writing project documentation during work
|
|
265
|
+
|
|
266
|
+
When you change what someone using or maintaining the project needs to know, update the relevant document in the same change, before taking the next item. Do this on your own initiative within the knowledge rules in \`${SHIFT_FILE}\`. A refactor that leaves the documented behavior accurate needs no new entry.
|
|
267
|
+
|
|
268
|
+
1. Name the reader's question. If a message can arrive during a shift, for example, the reader needs to know whether the agent receives its letter before answering. Use the map to find the document that explains that behavior. Where enabled, use \`${MENTIONS_TOOL}\` to catch other documents naming a changed file. A document can explain the behavior without naming the file.
|
|
269
|
+
2. Rewrite the affected passage in place. Say what happens, under which conditions, and why the distinction matters. Put exact commands and limits with the interface they belong to. For example, attach a character limit to the specific field and file. Link other mentions to that passage. Create a document when a distinct topic has no home. Give it a short \`description:\` saying what question it answers and when to open it. For example: "Which message reaches the agent first. Read before changing delivery during a shift." Use \`##\` headings a reader can choose from the map, such as "Messages received during a shift". Verify any command, field name or limit you publish against its source.
|
|
270
|
+
3. Keep the board useful at the next shift. A project-wide decision needs the action to preserve and the reason a future agent could get it wrong. For the message example, record the letter-first guarantee and why the answer depends on it. Link to the adapter document for event order and exceptions. Before shortening a long board entry, check that the linked section preserves the reasons worth keeping.
|
|
271
|
+
4. When the owner gives a decision, find earlier wording on the same subject. Name the scope (project, harness, task or field), fold refinements into the existing rule, and keep a quote where its wording matters. Recover an ambiguous reference from its source when possible. Ask if the evidence leaves two meanings that would lead to different actions.
|
|
272
|
+
5. When a design is superseded and its rationale is still useful, mark the reference \`archived: true\` and describe when to consult it. Keep current instructions in the active document. Read the resulting map entry as a new agent would: can you find the right document and tell when its instructions apply? Edit its frontmatter or headings to improve the entry.
|
|
273
|
+
|
|
262
274
|
## Board — \`${BOARD}\`
|
|
263
275
|
|
|
264
276
|
${BOARD_RULES}
|
package/core/texts/tools.ts
CHANGED
|
@@ -30,7 +30,7 @@ import { quote } from '../markdown'
|
|
|
30
30
|
|
|
31
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.`
|
|
32
32
|
|
|
33
|
-
export const GUIDE_DESCRIPTION = `
|
|
33
|
+
export const GUIDE_DESCRIPTION = `Read once before your first shift in a project. Use section "flow" for the shift, letter, refusals and about.md. Use "records" for writing project documentation during work and maintaining the board, owner decisions, tasks and archive.`
|
|
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."
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@iiiokojiadbi/shift",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.39.0",
|
|
4
4
|
"description": "The agent decides by itself when to shift: it keeps a work board and task folders, writes a letter to itself, and continues from where it stopped.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|