@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 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
- // The block itself; past `[docs] max_chars` first without the sections, then only folders and file names, so it never
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, maxChars } = settings
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 listed = (sections: boolean): string[] =>
346
- sorted.map(([folder, inside]) =>
347
- [
348
- `### ${folder}/`,
349
- '',
350
- ...inside.flatMap(doc => [
351
- `- \`${doc.path}\` — ${doc.description ?? 'no description: add `description:` to its frontmatter'}`,
352
- ...(!sections || doc.sections.length === 0 ? [] : [` sections: ${doc.sections.join(' · ')}`]),
353
- ...pinRows(doc.pins),
354
- ]),
355
- ].join('\n'),
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
- note,
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
- // A reduced map uses folder entries. Rules and map-level notices can be refreshed by path.
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[], indent = ''): string[] {
443
+ function pinRows(pins: readonly Pin[]): string[] {
473
444
  return pins.flatMap(pin => [
474
- `${indent} pinned${pin.section === null ? '' : ` (${pin.section})`}:`,
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 => `${indent} · ${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(text),
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
- // The docs map in SHIFT.md, in characters; past it only folders and file names are listed.
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), how long the map in SHIFT.md may be, whether each document carries a toc, and the limits a document is
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: 'how long the map may be: past it the sections go, then the descriptions, and the map says so',
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',
@@ -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, 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.
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. 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.
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 a record format, ask for section "records"; for the letter, a refusal or how to continue, use "flow".
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}
@@ -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 = `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.`
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.38.2",
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",