ptbk 0.119.0-13 → 0.119.0-15

package/README.md

@@ -1,40 +1,68 @@
 # Promptbook (`ptbk`)
 
-Promptbook operates readable agent and task Books over a Git project. This repository publishes one npm package, `ptbk`, which installs the `ptbk` command. Runtime state, requests, traces and the shared browser profile live in ignored `.ptbk/` files.
+Promptbook operates readable **agents** and **tasks** over a Git project. Agents are Books with lasting roles, goals and rules; tasks are bounded work. Once started, the agenda runs unattended: it executes one task at a time, routes unassigned tasks through Manager, verifies every result with your project check and commits it together with its completion record (`PTBK: <task title>` plus a `Task-ID` trailer). When the backlog is empty, agents with goals are asked whether new work is useful. You are asked only when something genuinely needs a person.
 
-Requires Node.js 22.13+ in the Node 22 line, or Node 24+, and npm 10+.
+This repository publishes exactly one npm package, `ptbk`, which installs the `ptbk` command. It requires Node.js 22.13+ (Node 22 line) or 24+, npm 10+ and Git.
+
+## Install
 
 ```bash
-# Global installation
+# Global
 npm install --global ptbk
-ptbk init --path ./project
 
-# Project-local installation
+# Or project-local (no PATH entry; use npx or npm scripts)
 npm install --save-dev ptbk
-npx ptbk init
+npx ptbk --version
+```
+
+Global and local installations are independent; every project keeps using the installation that started it, including after restarts.
+
+## Use
+
+```bash
+ptbk init                 # describe your project, answer a few setup questions; the agenda then starts in the background
+ptbk dashboard            # live terminal view and controls (Q leaves, the service keeps running)
+ptbk status               # one snapshot: requests, current work, queue, connection
+ptbk add "Improve CSV export"   # creates and commits a task (with its Task-ID); Manager assigns it
+ptbk list "#<task-id>"    # one task: its trace, browser video and commits
+ptbk answer               # answer questions agents asked you
+ptbk stop                 # stop (stays stopped after reboot until the next start or init)
+ptbk start                # start an initialized, cloned or stopped project
+ptbk run --limit 1        # finite run with one agent/harness configuration
 ```
 
-Initialization creates missing core agents, task templates, `ptbk.json` and project conventions, preserving customized files. Its wizard offers destination-local installation of the exact running version and selected global harness setup, reusing native login. Unattended setup requires `--installation local|global` or `--no-install`; `--non-interactive` disables prompts. Setup commits only safe generated artifacts; `--no-commit` defers persistence, and edits overlapping user work remain pending review. Configure meaningful project checks before starting work.
+`ptbk init` first asks what you are working on — free text, long pasted material, images or other files (Ctrl+O attaches a file, Ctrl+V pastes a clipboard image, long pastes become compact `[Pasted text #1, 120 lines]` tokens). Your input is saved verbatim in `specs/_initial.md` (attachments in `specs/_initial/`), and one ordinary task assigned to the engine-supplied Expert transforms the project according to it. Init shows `Step X of Y`, never runs that task itself, starts the background agenda and returns; a blank intent gives a small skeleton whose first task is a readiness review.
+
+Run `ptbk help` for all commands and `ptbk help <command>` for one command's options, defaults and examples.
+
+-   **Unattended setup:** `ptbk init --non-interactive --installation local --harness openai-codex --check "npm test" --intent-file brief.md --attach mockup.png` (`--no-start` only prepares the project).
+-   **Harnesses:** OpenAI Codex and Claude Code are featured; GitHub Copilot, Cline, OpenCode, Gemini CLI and Qwen Code are also supported. They are installed globally and use their own login.
+-   **Files:** agents in `agents/` (core Adam, Manager and Teacher in `agents/.core/`), tasks in `tasks/` (Books or Markdown), specifications in `specs/`, per-task audit evidence in `traces/<task-id>/`, configuration in `ptbk.json`, runtime state in the Git-ignored `.ptbk/`.
+-   **Task IDs and traces:** every task has a stable ID (`TASK ID` in Books, `<!-- ptbk-task-id: … -->` in Markdown sections) that also appears in its commits' `Task-ID` trailer and names `traces/<task-id>/`: the consolidated harness output (`harness.log`), events (`events.jsonl`) and, when the task used the project browser, its video (`video/`, sign-in steps excluded). `ptbk.json` `traces.commit` (default off: `traces/` is ignored), `traces.ignoreVideos` (default on) and `traces.recordVideo` (default on) are chosen on init's Traces screen. With `ffmpeg` on PATH videos are H.264 MP4, otherwise Motion-JPEG MOV.
+-   **Remote access:** `ptbk start` serves a dashboard on `127.0.0.1` and publishes it through a Cloudflare quick tunnel; devices must pair with a single-use link shown in the local terminal (`ptbk access pair`). Use `--no-tunnel` for local-only access or `--no-server` for neither.
+-   **Presentation:** pretty terminal UI by default; `--raw` (or redirected output) gives plain text without prompts. `--non-interactive` never asks questions.
+-   **Commits:** every mutating workflow commits its own changes with a `PTBK: ` subject; `--no-commit` is the explicit exception.
+
+The behavior is defined by [the specification](specs/_main.md).
+
+## Develop
 
 ```bash
-ptbk add "Implement the new behavior and its acceptance checks"
-ptbk list
-ptbk run --dry-run
-ptbk start                     # background agenda, protected remote dashboard, reboot persistence
-ptbk dashboard                 # attach terminal controls to the existing service
-ptbk show                      # inspect the same process and pending requests
-ptbk answer REQUEST_ID "Reply"
-ptbk stop                      # intentional stop also disables automatic restart
+npm ci
+npm run check        # typecheck, tests with a fake harness, packed local/global installation checks
+npm run ptbk -- --help
 ```
 
-`start` discovers available authenticated harnesses, uses Manager for missing assignments, and executes one task at a time. It requires reported outcome evidence and passing project checks before committing implementation, dated task completion and learning follow-ups together. It watches future work and materializes goal enquiries when no unfinished backlog remains. Failures retain work and expose recovery diagnostics.
+## Release
 
-Lifecycle commands report once and return; `start --raw` still launches a daemon. Use `dashboard` to attach terminal controls, or `start --foreground` to own execution in the current terminal (`--raw` gives plain foreground events). Q/Ctrl+C leaves an attached dashboard while its service continues. `--no-persist`, `--no-server`, `--no-qr` and `--port` customize startup. `run` executes a finite queue with one configuration; for example `ptbk run --harness openai-codex --check "npm run check" --limit 1`. Harness availability, account policy and capability checks happen before inference; unsupported installed provider features produce an actionable diagnostic.
+From a clean, committed, named branch:
 
-Suitable terminals default to rich presentation; `--raw` or redirected output gives plain results without prompts or QR codes. `ptbk add` guides and confirms task creation. Use `ptbk init --help`, `ptbk init help` or `ptbk help init` for the same command-specific offline reference.
+```bash
+npm version prerelease    # or patch / minor / major
+```
 
-Global installation, local `npx ptbk`, or a project script such as `"ptbk": "ptbk"` work outside this repository. Each process loads its own installed runtime/version and pins that installation for restart. See [runtime usage](docs/runtime.md), [compatibility and verification](docs/compatibility.md), and [the specification](https://github.com/webgptorg/promptbook/blob/main/specs/_main.md).
+`preversion` verifies the clean branch, typechecks, runs the tests and validates the manifest/lockfile. `postversion` atomically pushes the version commit and its `vX.Y.Z` tag. GitHub Actions then runs **Check ptbk** on Node 22/24 × Linux/macOS/Windows for the tag and, only if it passes, **Publish ptbk** publishes the single `ptbk` package with npm provenance and verifies the public registry and default local/global installations. Publishing needs the `NPM_TOKEN` secret or npm trusted publishing configured for this repository.
 
-For development, use `npm ci` and `npm run check`. Checks validate types, deterministic integration fixtures and real tarball installations in disposable external projects. CI runs on Linux, macOS and Windows with Node 22 and 24.
+## License
 
-For releases, run `npm version patch`, `npm version minor`, or `npm version prerelease` on a clean named branch after committing your work. Basic `preversion` checks run locally; `postversion` atomically pushes the version commit and exact `vVERSION` tag. GitHub Actions checks and publishes only `ptbk` with npm provenance, then verifies the public registry and installed CLI. Configure npm trusted publishing once as described in [releasing](docs/releasing.md).
+See [LICENSE.md](LICENSE.md).

package/dist/book/commitments.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Which document kinds a commitment belongs to.
+ *
+ * @private Book language
+ */
+export type CommitmentScope = 'agent' | 'task' | 'both';
+/**
+ * How a commitment's content is interpreted.
+ *
+ * - `instruction`: repeatable multi-line natural-language content
+ * - `control`: single-value control field (its value is the first line)
+ * - `repeatable-control`: control field that may appear several times (e.g. `TASK DONE`, `TASK DEPENDS ON`)
+ * - `flag`: marker without required content (e.g. `CLOSED`)
+ *
+ * @private Book language
+ */
+export type CommitmentKind = 'instruction' | 'control' | 'repeatable-control' | 'flag';
+/**
+ * Definition of one canonical commitment with its aliases.
+ *
+ * @private Book language
+ */
+export type CommitmentDefinition = {
+    /** Canonical uppercase keyword (may contain spaces). */
+    readonly keyword: string;
+    /** Alias keywords sharing the semantics. */
+    readonly aliases: readonly string[];
+    /** Document kinds accepting the commitment. */
+    readonly scope: CommitmentScope;
+    /** Content interpretation. */
+    readonly kind: CommitmentKind;
+    /** Short description used by help, Expert and diagnostics. */
+    readonly description: string;
+};
+/**
+ * Every recognized commitment.
+ *
+ * @private Book language
+ */
+export declare const COMMITMENTS: readonly CommitmentDefinition[];
+/**
+ * Recognizes a commitment at the beginning of a line.
+ *
+ * The keyword must be uppercase and complete: it is followed by whitespace or the end of the line.
+ *
+ * @private Book language
+ */
+export declare function matchCommitmentKeyword(line: string): {
+    definition: CommitmentDefinition;
+    written: string;
+    content: string;
+} | undefined;

package/dist/book/commitments.js

@@ -0,0 +1,72 @@
+/**
+ * Every recognized commitment.
+ *
+ * @private Book language
+ */
+export const COMMITMENTS = [
+    { keyword: 'PERSONA', aliases: ['PERSONAE'], scope: 'agent', kind: 'instruction', description: 'Role and identity of the agent.' },
+    { keyword: 'GOAL', aliases: ['GOALS'], scope: 'agent', kind: 'instruction', description: 'Lasting objective, also used for goal discovery.' },
+    { keyword: 'RULE', aliases: ['RULES'], scope: 'both', kind: 'instruction', description: 'Behavioral constraint (task rules apply only to that task).' },
+    { keyword: 'KNOWLEDGE', aliases: [], scope: 'agent', kind: 'instruction', description: 'Inline knowledge or a reference to relevant material.' },
+    { keyword: 'STYLE', aliases: ['STYLES'], scope: 'agent', kind: 'instruction', description: 'Style of communication or output.' },
+    { keyword: 'LANGUAGE', aliases: ['LANGUAGES'], scope: 'agent', kind: 'instruction', description: 'Language(s) of responses.' },
+    { keyword: 'WRITING SAMPLE', aliases: [], scope: 'agent', kind: 'instruction', description: 'Example of the desired writing style.' },
+    { keyword: 'WRITING RULES', aliases: ['WRITING RULE'], scope: 'agent', kind: 'instruction', description: 'Specific writing conventions.' },
+    { keyword: 'SAMPLE', aliases: ['EXAMPLE'], scope: 'agent', kind: 'instruction', description: 'Representative interaction or output.' },
+    { keyword: 'FORMAT', aliases: ['FORMATS'], scope: 'agent', kind: 'instruction', description: 'Requested output format.' },
+    { keyword: 'TEMPLATE', aliases: ['TEMPLATES'], scope: 'agent', kind: 'instruction', description: 'Reusable response/output pattern.' },
+    { keyword: 'FROM', aliases: [], scope: 'agent', kind: 'control', description: 'Single inheritance parent (default Adam).' },
+    { keyword: 'IMPORT', aliases: ['IMPORTS'], scope: 'agent', kind: 'repeatable-control', description: 'In-place inclusion of another agent\'s instructions.' },
+    { keyword: 'MODEL', aliases: ['MODELS'], scope: 'agent', kind: 'instruction', description: 'Model preference or requirement of the agent.' },
+    { keyword: 'ACTION', aliases: ['ACTIONS'], scope: 'agent', kind: 'instruction', description: 'Actions/tools the role intends to use.' },
+    { keyword: 'TEAM', aliases: [], scope: 'agent', kind: 'instruction', description: 'Whom the agent may consult and when.' },
+    { keyword: 'OPEN', aliases: [], scope: 'agent', kind: 'instruction', description: 'Permits learning, optionally with natural-language limits.' },
+    { keyword: 'CLOSED', aliases: [], scope: 'agent', kind: 'flag', description: 'Prohibits automatic learning changes.' },
+    { keyword: 'NOTE', aliases: ['NOTES', 'COMMENT', 'NONCE', 'TODO'], scope: 'both', kind: 'instruction', description: 'Non-executable commentary.' },
+    { keyword: 'DELETE', aliases: ['CANCEL', 'DISCARD', 'REMOVE'], scope: 'agent', kind: 'instruction', description: 'Withdraws an identified earlier commitment.' },
+    { keyword: 'DICTIONARY', aliases: [], scope: 'agent', kind: 'instruction', description: 'Terminology for the role\'s work.' },
+    { keyword: 'TASK', aliases: [], scope: 'task', kind: 'control', description: 'Declares a task: `TASK <title>` on the first nonempty line.' },
+    { keyword: 'TASK ID', aliases: [], scope: 'task', kind: 'control', description: 'Stable reference key, distinct from the title.' },
+    { keyword: 'TASK AGENT', aliases: [], scope: 'task', kind: 'control', description: 'Responsible agent.' },
+    { keyword: 'TASK HARNESS', aliases: [], scope: 'task', kind: 'control', description: 'Required execution harness.' },
+    { keyword: 'TASK MODEL', aliases: [], scope: 'task', kind: 'control', description: 'Required model.' },
+    { keyword: 'TASK THINKING LEVEL', aliases: [], scope: 'task', kind: 'control', description: 'Required reasoning/effort setting.' },
+    { keyword: 'TASK PRIORITY', aliases: [], scope: 'task', kind: 'control', description: 'Nonnegative number or textual importance; higher first.' },
+    { keyword: 'TASK AFTER', aliases: [], scope: 'task', kind: 'control', description: 'Inclusive earliest permitted start.' },
+    { keyword: 'TASK DUE DATE', aliases: [], scope: 'task', kind: 'control', description: 'Desired completion deadline (not a start condition).' },
+    { keyword: 'TASK DONE', aliases: [], scope: 'task', kind: 'repeatable-control', description: 'Completion stamp with explicit timezone.' },
+    { keyword: 'TASK STATUS', aliases: [], scope: 'task', kind: 'control', description: '`todo`, `not-ready`, `failed` or `retired`.' },
+    { keyword: 'TASK REPEAT', aliases: [], scope: 'task', kind: 'control', description: 'Positive fixed recurrence interval.' },
+    { keyword: 'TASK DEPENDS ON', aliases: [], scope: 'task', kind: 'repeatable-control', description: 'Prerequisite task references.' },
+    { keyword: 'TASK PARENT', aliases: [], scope: 'task', kind: 'control', description: 'Parent task reference (no implied ordering).' },
+    { keyword: 'TASK RUNNER', aliases: [], scope: 'task', kind: 'repeatable-control', description: 'Opaque any-of routing selectors from Markdown.' },
+    { keyword: 'TASK NOTE', aliases: [], scope: 'task', kind: 'instruction', description: 'Explanatory task metadata.' },
+    { keyword: 'TASK ORIGIN', aliases: [], scope: 'task', kind: 'control', description: 'Provenance of the task.' },
+];
+/**
+ * Lookup from every accepted keyword spelling to its definition.
+ */
+const KEYWORD_LOOKUP = new Map(COMMITMENTS.flatMap((definition) => [definition.keyword, ...definition.aliases].map((keyword) => [keyword, definition])));
+/**
+ * All keyword spellings, longest first (so `TASK AGENT` wins over `TASK`).
+ */
+const KEYWORDS_LONGEST_FIRST = [...KEYWORD_LOOKUP.keys()].sort((a, b) => b.length - a.length);
+/**
+ * Recognizes a commitment at the beginning of a line.
+ *
+ * The keyword must be uppercase and complete: it is followed by whitespace or the end of the line.
+ *
+ * @private Book language
+ */
+export function matchCommitmentKeyword(line) {
+    for (const keyword of KEYWORDS_LONGEST_FIRST) {
+        if (!line.startsWith(keyword))
+            continue;
+        const rest = line.slice(keyword.length);
+        if (rest !== '' && !/^\s/.test(rest))
+            continue;
+        return { definition: KEYWORD_LOOKUP.get(keyword), written: keyword, content: rest.trim() };
+    }
+    return undefined;
+}
+//# sourceMappingURL=commitments.js.map

package/dist/book/commitments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commitments.js","sourceRoot":"","sources":["../../src/book/commitments.ts"],"names":[],"mappings":"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"}

package/dist/book/edit.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Appends a commitment line at the end of a Book, preserving everything else.
+ *
+ * @private Book language
+ */
+export declare function appendCommitment(source: string, keyword: string, value: string): string;
+/**
+ * Sets a single-value control commitment: replaces the keyword line of its first occurrence (keeping continuation
+ * text) or appends it when absent.
+ *
+ * @private Book language
+ */
+export declare function setControlCommitment(source: string, keyword: string, value: string): string;

package/dist/book/edit.js

@@ -0,0 +1,49 @@
+import { parseBook } from './parse.js';
+/**
+ * Joins lines with the source's newline style and guarantees exactly one trailing newline.
+ */
+function joinLines(lines, newline) {
+    const result = [...lines];
+    while (result.length && result[result.length - 1].trim() === '')
+        result.pop();
+    return result.join(newline) + newline;
+}
+/**
+ * Formats one commitment line.
+ */
+function commitmentLine(keyword, value) {
+    return value ? `${keyword} ${value}` : keyword;
+}
+/**
+ * Appends a commitment line at the end of a Book, preserving everything else.
+ *
+ * @private Book language
+ */
+export function appendCommitment(source, keyword, value) {
+    const document = parseBook(source);
+    const lines = [...document.lines];
+    while (lines.length && lines[lines.length - 1].trim() === '')
+        lines.pop();
+    const last = lines[lines.length - 1] ?? '';
+    const lastIsCommitment = document.commitments.some((commitment) => commitment.startLine === lines.length - 1);
+    if (lines.length && !lastIsCommitment && last.trim() !== '')
+        lines.push('');
+    lines.push(commitmentLine(keyword, value));
+    return joinLines(lines, document.newline);
+}
+/**
+ * Sets a single-value control commitment: replaces the keyword line of its first occurrence (keeping continuation
+ * text) or appends it when absent.
+ *
+ * @private Book language
+ */
+export function setControlCommitment(source, keyword, value) {
+    const document = parseBook(source);
+    const existing = document.commitments.find((commitment) => commitment.keyword === keyword);
+    if (!existing)
+        return appendCommitment(source, keyword, value);
+    const lines = [...document.lines];
+    lines[existing.startLine] = commitmentLine(existing.written === keyword ? keyword : existing.written, value);
+    return joinLines(lines, document.newline);
+}
+//# sourceMappingURL=edit.js.map

package/dist/book/edit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit.js","sourceRoot":"","sources":["../../src/book/edit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC;;GAEG;AACH,SAAS,SAAS,CAAC,KAAwB,EAAE,OAAe;IACxD,MAAM,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IAC1B,OAAO,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,MAAM,CAAC,GAAG,EAAE,CAAC;IAC/E,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,OAAe,EAAE,KAAa;IAClD,OAAO,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,OAAe,EAAE,KAAa;IAC3E,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClC,OAAO,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,KAAK,CAAC,GAAG,EAAE,CAAC;IAC3E,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3C,MAAM,gBAAgB,GAAG,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC9G,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,gBAAgB,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5E,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;IAC3C,OAAO,SAAS,CAAC,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc,EAAE,OAAe,EAAE,KAAa;IAC/E,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;IAC3F,IAAI,CAAC,QAAQ;QAAE,OAAO,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IAC/D,MAAM,KAAK,GAAG,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,cAAc,CAAC,QAAQ,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC7G,OAAO,SAAS,CAAC,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;AAC9C,CAAC"}

package/dist/book/parse.d.ts

@@ -0,0 +1,84 @@
+import { type CommitmentDefinition } from './commitments.js';
+/**
+ * A problem found while reading a Book, with its 1-based line.
+ *
+ * @private Book language
+ */
+export type BookDiagnostic = {
+    /** 1-based line number (0 when not line-specific). */
+    readonly line: number;
+    /** Human-readable explanation. */
+    readonly message: string;
+    /** Errors block use of the document; warnings are informational. */
+    readonly severity: 'error' | 'warning';
+};
+/**
+ * One commitment occurrence in a Book.
+ *
+ * @private Book language
+ */
+export type BookCommitment = {
+    /** Canonical keyword of the commitment (alias resolved). */
+    readonly keyword: string;
+    /** Keyword spelling written in the source. */
+    readonly written: string;
+    /** Definition of the commitment. */
+    readonly definition: CommitmentDefinition;
+    /** Content on the keyword's own line. */
+    readonly value: string;
+    /** Full content including continuation lines (trimmed). */
+    readonly body: string;
+    /** Continuation lines only (trimmed). */
+    readonly continuation: string;
+    /** 0-based index of the keyword line. */
+    readonly startLine: number;
+    /** 0-based index after the last continuation line. */
+    readonly endLine: number;
+};
+/**
+ * A parsed Book document.
+ *
+ * @private Book language
+ */
+export type BookDocument = {
+    /** Agent (name on first line), task (`TASK <title>`), empty or invalid document. */
+    readonly kind: 'agent' | 'task' | 'empty' | 'invalid';
+    /** Agent name or task title. */
+    readonly name: string;
+    /** 0-based index of the identifying first nonempty line. */
+    readonly headerLine: number;
+    /** Natural text between the header and the first commitment (trimmed). */
+    readonly intro: string;
+    /** Commitments in source order. */
+    readonly commitments: readonly BookCommitment[];
+    /** Problems found while reading. */
+    readonly diagnostics: readonly BookDiagnostic[];
+    /** Source lines (without line terminators). */
+    readonly lines: readonly string[];
+    /** Line terminator used by the source. */
+    readonly newline: '\n' | '\r\n';
+};
+/**
+ * Reads a Book source: identifies the document kind and its commitments.
+ *
+ * Fenced literal content is preserved as text and never interpreted as commitments.
+ *
+ * @private Book language
+ */
+export declare function parseBook(source: string): BookDocument;
+/**
+ * Returns all commitments of a canonical keyword.
+ *
+ * @private Book language
+ */
+export declare function commitmentsOf(document: BookDocument, keyword: string): BookCommitment[];
+/**
+ * Returns the single effective value of a control commitment, reporting conflicting duplicates.
+ *
+ * @private Book language
+ */
+export declare function singleValue(document: BookDocument, keyword: string): {
+    value?: string;
+    commitment?: BookCommitment;
+    conflict?: BookDiagnostic;
+};

package/dist/book/parse.js

@@ -0,0 +1,142 @@
+import { matchCommitmentKeyword } from './commitments.js';
+/**
+ * Detects a fence opener/closer (``` or ~~~).
+ */
+function fenceMarker(line) {
+    const match = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+    return match?.[1];
+}
+/**
+ * Reads a Book source: identifies the document kind and its commitments.
+ *
+ * Fenced literal content is preserved as text and never interpreted as commitments.
+ *
+ * @private Book language
+ */
+export function parseBook(source) {
+    const newline = source.includes('\r\n') ? '\r\n' : '\n';
+    const text = source.startsWith('') ? source.slice(1) : source;
+    const lines = text.split(/\r?\n/);
+    const diagnostics = [];
+    const headerLine = lines.findIndex((line) => line.trim() !== '');
+    if (headerLine < 0) {
+        return { kind: 'empty', name: '', headerLine: -1, intro: '', commitments: [], diagnostics, lines, newline };
+    }
+    const header = lines[headerLine].trim();
+    let kind;
+    let name;
+    const headerMatch = matchCommitmentKeyword(header);
+    if (headerMatch && headerMatch.definition.keyword === 'TASK') {
+        kind = 'task';
+        name = headerMatch.content;
+        if (!name) {
+            kind = 'invalid';
+            diagnostics.push({ line: headerLine + 1, message: 'A task needs a nonempty title after `TASK`.', severity: 'error' });
+        }
+    }
+    else if (headerMatch && headerMatch.definition.scope !== 'agent' && headerMatch.definition.keyword.startsWith('TASK')) {
+        kind = 'invalid';
+        name = '';
+        diagnostics.push({ line: headerLine + 1, message: `\`${headerMatch.written}\` cannot start a Book; a task starts with \`TASK <title>\`.`, severity: 'error' });
+    }
+    else {
+        kind = 'agent';
+        name = header;
+    }
+    const commitments = [];
+    const introLines = [];
+    let current;
+    let fence;
+    const close = (end) => {
+        if (!current)
+            return;
+        const continuation = current.continuation.join('\n').trim();
+        const body = [current.match.content, ...current.continuation].join('\n').trim();
+        commitments.push({
+            keyword: current.match.definition.keyword,
+            written: current.match.written,
+            definition: current.match.definition,
+            value: current.match.content,
+            body,
+            continuation,
+            startLine: current.start,
+            endLine: end,
+        });
+        current = undefined;
+    };
+    for (let index = headerLine + 1; index < lines.length; index++) {
+        const line = lines[index];
+        const marker = fenceMarker(line);
+        if (fence) {
+            if (marker && marker[0] === fence[0] && marker.length >= fence.length && line.trim() === marker)
+                fence = undefined;
+        }
+        else if (marker) {
+            fence = marker;
+        }
+        else {
+            const match = matchCommitmentKeyword(line);
+            if (match) {
+                close(index);
+                current = { match, start: index, continuation: [] };
+                if (match.definition.keyword === 'TASK') {
+                    diagnostics.push({
+                        line: index + 1,
+                        message: 'A later `TASK` line does not declare another task; only the first nonempty line identifies the document.',
+                        severity: 'warning',
+                    });
+                }
+                continue;
+            }
+        }
+        if (current)
+            current.continuation.push(line);
+        else
+            introLines.push(line);
+    }
+    close(lines.length);
+    if (fence)
+        diagnostics.push({ line: lines.length, message: 'An unterminated fenced block runs to the end of the document.', severity: 'warning' });
+    for (const commitment of commitments) {
+        const scope = commitment.definition.scope;
+        if (kind === 'task' && scope === 'agent') {
+            diagnostics.push({ line: commitment.startLine + 1, message: `\`${commitment.written}\` is an agent commitment and has no meaning in a task.`, severity: 'warning' });
+        }
+        if (kind === 'agent' && scope === 'task') {
+            diagnostics.push({ line: commitment.startLine + 1, message: `\`${commitment.written}\` is a task commitment and has no meaning in an agent.`, severity: 'warning' });
+        }
+    }
+    return { kind, name, headerLine, intro: introLines.join('\n').trim(), commitments, diagnostics, lines, newline };
+}
+/**
+ * Returns all commitments of a canonical keyword.
+ *
+ * @private Book language
+ */
+export function commitmentsOf(document, keyword) {
+    return document.commitments.filter((commitment) => commitment.keyword === keyword);
+}
+/**
+ * Returns the single effective value of a control commitment, reporting conflicting duplicates.
+ *
+ * @private Book language
+ */
+export function singleValue(document, keyword) {
+    const found = commitmentsOf(document, keyword);
+    if (found.length === 0)
+        return {};
+    const distinct = new Set(found.map((commitment) => commitment.value));
+    if (distinct.size > 1) {
+        return {
+            value: found[0].value,
+            commitment: found[0],
+            conflict: {
+                line: found[1].startLine + 1,
+                message: `\`${keyword}\` has conflicting values (${[...distinct].map((value) => `"${value}"`).join(', ')}).`,
+                severity: 'error',
+            },
+        };
+    }
+    return { value: found[0].value, commitment: found[0] };
+}
+//# sourceMappingURL=parse.js.map

package/dist/book/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/book/parse.ts"],"names":[],"mappings":"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"}

package/dist/book/references.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Engine-supplied non-agents.
+ *
+ * @private Book language
+ */
+export type NonAgentName = 'Void' | 'User' | 'Expert';
+/**
+ * Normalizes an agent name or reference for comparison.
+ *
+ * Case, diacritics and word separators (whitespace, underscores, hyphens) are ignored; the original spelling is
+ * preserved elsewhere for display.
+ *
+ * @private Book language
+ */
+export declare function normalizeAgentName(name: string): string;
+/**
+ * Resolves a normalized name to a non-agent, if reserved.
+ *
+ * @private Book language
+ */
+export declare function nonAgentOf(normalized: string): NonAgentName | undefined;
+/**
+ * A parsed agent reference.
+ *
+ * @private Book language
+ */
+export type AgentReference = {
+    /** Exact source text, e.g. `@Developer` or `{Frontend Developer}`. */
+    readonly raw: string;
+    /** Name without reference syntax, e.g. `Frontend Developer`. */
+    readonly name: string;
+    /** Normalized comparison key. */
+    readonly normalized: string;
+    /** Offset in the scanned text. */
+    readonly index: number;
+};
+/**
+ * Parses a single dedicated reference field value (`@Name`, `{Name}` or a bare name, as in `FROM Adam`).
+ *
+ * Returns `undefined` for an empty or malformed value.
+ *
+ * @private Book language
+ */
+export declare function parseReferenceValue(value: string): AgentReference | undefined;
+/**
+ * Finds agent references (`@Token` and `{Name}`) in natural text, skipping fenced/inline code and email addresses.
+ *
+ * @private Book language
+ */
+export declare function findAgentReferences(text: string): AgentReference[];
+/**
+ * Replaces fenced blocks and inline code spans with spaces so their content is never interpreted.
+ *
+ * @private Book language
+ */
+export declare function maskCode(text: string): string;
+/**
+ * Formats an agent name as a reference (`@Name` for single tokens, `{Name}` otherwise).
+ *
+ * @private Book language
+ */
+export declare function formatAgentReference(name: string): string;