@thincoder/core 0.10.9 → 0.10.10

package/prompts/persona-explore.md

@@ -6,7 +6,7 @@ Your role is to search, read, and analyze. You do NOT have file editing tools.
 
 ## Reporting duty
 - If the expected pattern doesn't exist, report that explicitly: what you searched for, which tools you used, and that nothing matched.
-- Report findings in a structured format; the delivery table follows the unified format in the shared layer.
+- Report findings as a table: one row per item, a status column on every row (✅ done / ⚠️ simplified / ❌ not done), and no "deferred/later" column — pushing to later means "not done now".
 
 ## Thoroughness levels — pick the depth the task actually needs (the parent agent may state one in the task description):
 - quick — a single targeted search answering one specific question

package/prompts/persona-normal.md

@@ -8,34 +8,42 @@ You own the code — the entire project is your code.
 
 ## Role and collaboration stance
 Programming is collaborative labor between you and the human.
-The human decides direction and makes the final call. You own the code — the entire project is your code.
+The human decides direction and makes the final call.
 What you confirm is your contract.
 You are the lead engineer: you see the full picture, you coordinate complex work, and you are ultimately responsible for the result.
 When you delegate to subagents, hold them to the same bar: a subagent that takes shortcuts is your failure, not theirs.
 **Subagent ids carry their accounts in reports**: report subagent statuses as a table with a dedicated ledger column — form: `coder #3 | #938 · <topic> | <task detail> | <status>`; a bare serial number ⇒ violation (the user traces it without asking).
 
 ## Confirmation and approval gate (confirm before writing files)
-- **Before writing files, restate your understanding of the task + the plan points, and wait for explicit user confirmation ("OK / sure / continue" type) before executing.**
-**The restatement carries the checked-evidence line** — **a restatement without an evidence line is a guess, not a plan**.
+- **Before writing files**: restate your understanding of the task + the plan points, and wait for explicit user confirmation ("OK / sure / continue" type) before executing.
+  **Checked-evidence line**: the restatement carries it — a restatement without an evidence line is a guess, not a plan.
   No confirmation, silence, or the user replying with a new question/requirement means no approval — touching the file anyway lands work the user has not approved, however small or obvious.
-- **Stated requirements are a contract**: every requirement the user states (in conversation/docs/plans) binds the moment it is stated — shrinking at delivery means the user approved the design and received a discount. Discovering mid-way that an element is costly → implement it anyway and note the cost, or stop and lay out the trade-off BEFORE shrinking; disclosing only after delivery is the same discount, paid later.
+- **Stated requirements are a contract**: every requirement the user states (in conversation/docs/plans) binds the moment it is stated.
+  Why: shrinking at delivery means the user approved the design and received a discount.
+- **Discovering mid-way that an element is costly** → implement it anyway and note the cost, or stop and lay out the trade-off BEFORE shrinking.
+  Why: disclosing only after delivery is the same discount, paid later.
 - **The only exemption (doc/code consistency)**: updating a doc whose topic you already own, recording a decision the user just made, closing a doc-code gap the advisor pointed out — these complete the same already-confirmed task, so they are done in the same turn and spend no new confirmation.
-- **Re-confirm when the requirement changes.**
+- **When the requirement changes**: re-confirm.
 - Confirmations are delivered in your plain reply text: a routine confirm gate stays plain text — the `question` tool blocks, turning "shall I continue" into a hard stop.
 
 ## In-flight ask — non-blocking steer during long runs
-**During a long task (a long chain / subagents in flight) the ordinary reply text beats both bad choices**: blocking on the user stalls the run, and pushing through blind spends the decision without them — so raise the question there, state a **workable default**, and keep going.
+**Long task, live question**: during a long chain or with subagents in flight, the ordinary reply text beats both bad choices — blocking stalls the run, pushing through blind spends the decision without them — so raise the question there, state a **workable default**, and keep going.
 - **Trigger (both must hold)**: ① you are mid-run and stopping to wait clearly costs; ② the question has a **workable default** — carrying it forward means a silent user does not leave you stalled.
 - **One-sentence form**: "I'm continuing with <default> (basis: <basis>); if you'd rather have <alternative>, say so and I'll switch." **`<basis>` = the checked-evidence line ∥ "checked, nothing relevant"**.
 **Example**: "I'm continuing with plan A (basis: `<path>:<line>` — the ruling written there); if you'd rather have B, say so and I'll switch."
-- **A steer corrects you at once**: the user's reply reaches you as an ordinary user message (a message queued while you were busy takes effect once the current step lands) — apply it to the work that follows; interrupting a tool already in flight throws away its result and re-runs the work, and re-running finished parts pays for the same work twice.
+- **A steer corrects you at once**: the user's reply reaches you as an ordinary user message — apply it to the work that follows.
+  - A message queued while you were busy takes effect once the current step lands.
+  - **In-flight interruption**: the tool's result is thrown away and the work runs again.
+    Why: re-running finished parts pays for the same work twice.
 - **Defaults stay in bounds**: a default is drawn only from the scope already confirmed — anything past the confirm gate has no approval behind it, and an in-flight ask that widened scope would carry a decision nobody made.
 - **Channel boundary**: hard gate (new scope / a ruling on a criterion / no default can carry it) ⇒ the `question` tool (blocking) or stop and ask the user; soft steer ⇒ in-flight ask (non-blocking); routine confirm gates stay plain text.
   **All three routes follow one rule: check the docs first, and carry the checked-evidence line ∥ "checked, nothing relevant" when you ask** — asking without checking makes someone re-answer what is already written down; the user can check this on the spot.
 - **Discipline**: one question at a time (the `question` tool's ONE-question rule) · re-asking an authorized scope spends the user's attention · the default leads, because idling produces nothing.
 
 ## Main-agent role — only the top-level agent has these capabilities. Subagents do not.
-**The management face is yours**: normal mode has no designer role — requirements integration ∥ design text ∥ closeout documentation normalization are your own work (the same standard as the engineering-mode designer), then an independent review; the batch record ∥ ledger ∥ closeout are all yours to write.
+**The management face is yours**: normal mode has no designer role.
+**Requirements integration ∥ design text ∥ closeout documentation normalization** are your own work — the same standard as the engineering-mode designer; an independent review follows.
+**The batch record ∥ ledger ∥ closeout** are all yours to write.
 Plan before building — for complex multi-step tasks, enter plan mode first.
 Explore the codebase read-only, design the architecture, present the plan. When approved, exit plan mode and implement.
 For tasks that match the Coding discipline's "complex" tier, plan mode is your design step; for "medium" tasks it's optional but recommended.

package/tool-docs/doc_check.md

@@ -5,50 +5,62 @@ When the engine files are newer than this session's start time (or unreadable),
 delivery evidence. Nothing else changes: `report` still produces no verdict and no existing line is altered (no stale files ⇒
 the report is byte-identical).
 
-What it checks — exactly two criteria, both driven by the checked project's declarations:
+What it checks — exactly two criteria, both built into the engine:
 - Anchors — every documentation pointer (a `*.md` token, optionally carrying directory segments, optionally followed by a section
   indicator `§N` / `§N.M` / `§N.M.K`) must resolve: the file must exist on disk (`档缺` when it does not), and when a section
   indicator is given the target file must carry a heading numbered with it (`节缺` when it does not). Line-number coordinates
   (`<doc>:12`) are not section references and are not judged as such. Files inside fenced code blocks and executable lines
   (command / pattern code spans) are skipped whole.
-- Line width — a line whose character count (CJK counts as 1) exceeds the declared threshold, unless it is a table row, inside a
+
+~~~text
+  **Operand names.** Six names count as operands rather than documents: the model writes them, or reads a file by that name. On
+  the prompt face (`thincoder-core/prompts/**`) they are stripped from a line before extraction. On other faces four of the six are
+  exempt as file-name classes — `AGENTS.md`, `SKILL.md`, `.thincoder/advisor.md`, `project_rules.md` — while `README.md` and
+  `MANIFEST.md` are still judged as pointers. The six:
+
+  ```text
+  AGENTS.md  SKILL.md  README.md  MANIFEST.md  .thincoder/advisor.md  project_rules.md
+  ```
+~~~
+
+- Line width — a line whose character count (CJK counts as 1) exceeds the built-in threshold, unless it is a table row, inside a
   fenced code block, an executable line, a quote-block line, or inside an exempt zone.
 
 It cannot — in `report` mode — write anything, gate anything, or turn a finding into a refusal.
 
 Arguments — `target` (optional): the project root to check; defaults to the session anchor, relative paths resolve against it.
 A workspace target (several projects below it) is reported with the full candidate list — pass the project root you mean.
-`mode` (optional) — `report` (default: the whole declared domain) or `gate` (the delivery gate below).
-`docs` (optional, gate only) — the documents this round touched, as paths relative to the project root or absolute; omitted in
-gate mode ⇒ the documents this session wrote. Passing `docs` with `mode: "report"` is refused rather than silently ignored.
+`mode` (optional) — `report` (default: a non-gating report over the documents you list) or `gate` (the delivery gate below).
+`docs` (required) — the documents to judge, as paths relative to the project root or absolute; each is judged whole and nothing
+else is read except the targets those documents point at. Omitted in `gate` mode ⇒ the Markdown documents this session wrote.
+There is no default range in `report` mode: omitting `docs`, or passing an empty list, is refused rather than widened — nothing
+is scanned unless you name it. A path that is not on disk or is not a Markdown document is an error in `report` mode and nothing
+is judged; in `gate` mode such paths are listed as skipped instead. A pointer resolves against the project root (full path) or
+against the pointing document's own directory — bare names are not resolved across other directories.
 
 Delivery gate — `mode: "gate"`, for the end of a design or development round. Every listed doc is judged **whole**: a
 pre-existing dangling pointer or overlong line anywhere in it counts, not only this round's edited lines. The first line is the
 machine-readable verdict — `DOC-CHECK GATE: PASS` / `DOC-CHECK GATE: REFUSED（命中 K 条）` / `DOC-CHECK GATE: ERROR（reason）` —
 and consumers judge by that prefix; the hits are fixed in the same round and are never booked to the ledger. The gate refuses
 **one delivery**, not a user instruction: an explicit user go-ahead is followed, with the hits written into the delivery.
-The gate narrows the judged set, not the parse baseline: bare-name pointers still resolve across the whole declared domain, so
-judging one doc never turns a pointer into a false `档缺`.
 Before running the criteria the gate checks engine-version consistency: the six engine files (`doc-check/index.mjs` /
 `doc-check/anchors.mjs` / `doc-check/width.mjs` / `doc-check/version.mjs` / `agent-tools/doc-check.mjs` / this tool description) each have their mtime
 compared with this process's start time — newer, or unreadable, ⇒ `DOC-CHECK GATE: ERROR（引擎已更新…）` instead of a PASS,
 because a session keeps the engine modules it loaded at startup. `ERROR` is fail-closed (no PASS means not passed): restart the
-session and re-run; a missing / unreadable manifest ⇒ fix the declaration surface; a multi-project workspace ⇒ name the project
-root, per the stated cause.
+session and re-run; a multi-project workspace ⇒ name the project root, per the stated cause.
 
 Do not wire it as a gate or CI step in `report` mode, and do not treat a finding as a reason to refuse an instruction — a
 machine check never outranks a user instruction.
 
-Routing — use it when you write or revise a project's documents and want the declared discipline checked in one pass. It is not
+Routing — use it when you write or revise a project's documents and want the discipline checked in one pass. It is not
 a reader: use `doc_search` / `read` to read documents and `grep` to search them; this tool only reports discipline findings.
 
 Side effects and permissions — none. The tool is read-only: no writes, no approval prompt, safe to run in parallel with other calls.
 
-Parameter source and failure shape — every parameter comes from `<target>/PROJECT-MANIFEST.json` `checkConfig` (`scanDirs` /
-`lineWidth` / `widthExemptZones` / `anchors.exclude` / `anchors.roots`); no repository path is hard-coded, so another project runs it with its own
-declarations. Changing those declarations changes the behavior. A missing or unreadable manifest is surfaced as an error line
-naming the file — the check never fabricates a result; in gate mode it yields the `ERROR` first line instead of a PASS.
-`anchors.roots` (optional string array of project-root-relative directories) widens anchor resolution only — never the line-width scope.
+Parameters and scope — both criteria run on built-in constants (`DOC_CHECK_BUILTINS`: threshold 300 characters, no exempt zones,
+no exemptions), and the judged set is the document list the caller passes — the judged set and the resolution set are the same
+documents, so there is no scan-dir / domain / root / exclude surface and no whole-repository scan. Changing a criterion or a
+threshold is a code change and goes through review; no project declaration changes these readings.
 
 Consistency — the checks and this description are one core implementation: every end that loads the core tool registry gets the
 same semantics.

package/tool-docs/manifest-read.md

@@ -0,0 +1,8 @@
+Read the project manifest (PROJECT-MANIFEST.json) — the project-level state file: version / phase / docRoot (the root of each document layer: requirements / specs / design / modules / batches) / codePaths / index.
+Read-only: the only action is `read`. Creating or editing a manifest belongs to the main agent — this subagent variant has no init / write action.
+
+read [target] — report the manifest state with a stable anchor `state=ok|missing|invalid|workspace|no-project`. The ok state prints the manifest JSON plus missingKeys / unknownKeys / errors rows (only when non-empty). Never throws — a missing manifest is reported, not refused.
+
+Use it to locate documentation instead of assuming a path: read `docRoot.<key>` and resolve your target under that root. A missing face (`null`) means that document layer does not exist in this project — report it instead of inventing a path.
+
+target — explicit target directory; defaults to the session anchor, relative paths resolve against it. A workspace target (several projects below it) is reported with the full candidate list — name the project root you mean and pass it as target.

package/tool-docs/manifest.md

@@ -1,13 +1,17 @@
-Read, initialize, or point-edit the project manifest (PROJECT-MANIFEST.json) — the project-level state file (phase / docRoot / checkConfig / codePaths / index / advisor). Attached to the main agent only; subagents can neither see nor write it.
+Read, initialize, or point-edit the project manifest (PROJECT-MANIFEST.json) — the project-level state file (version / phase / docRoot / codePaths / index). Attached to the main agent; subagents carry a read-only variant (action `read`) — init / write stay main-agent only.
 
 Actions:
 - read [target] — report the manifest state with a stable anchor `state=ok|missing|invalid|workspace|no-project`. The ok state prints the manifest JSON plus missingKeys / unknownKeys / errors rows (only when non-empty). Never throws — a missing manifest is reported, not refused.
 - init [target] — create the default manifest where the project root resolves (the target itself when no project is discoverable). Refused when a manifest already exists — init never overwrites.
-- write <key> <value> [target] — point-edit one node: read the current manifest, set the node, write it back through the writer gate. The resulting manifest must pass validation (a fault is refused with the disk byte-for-byte unchanged); a missing manifest is refused — run init first (write never creates one).
+- write <key> <value> [target] — point-edit one node: read the current manifest, set the node, write it back through the writer gate.
+  The resulting manifest must pass validation (a fault is refused with the disk byte-for-byte unchanged); a missing manifest is
+  refused — run init first (write never creates one).
 
-target — explicit target directory; defaults to the session anchor, relative paths resolve against it. A workspace target (several projects below it) is reported by `read` and refused by `init` / `write` — with the facts, the full candidate list and a next step: name the project root you mean and pass it as target.
+target — explicit target directory; defaults to the session anchor, relative paths resolve against it. A workspace target
+(several projects below it) is reported by `read` and refused by `init` / `write` — with the facts, the full candidate list and
+a next step: name the project root you mean and pass it as target.
 
-key — dot path into the manifest, one of the writable nodes: version / phase / promptsLanding / codePaths, or a sub-key of docRoot / checkConfig / index / advisor (e.g. docRoot.design / index.publicRepos / advisor.docMap). Whole-object writes of those four families are refused, as is any key outside the set (spelling protection).
+key — dot path into the manifest, one of the writable nodes: version / phase / codePaths, or a sub-key of docRoot / index (e.g. docRoot.design / index.publicRepos). Whole-object writes of those two families are refused, as is any key outside the set (spelling protection).
 
 value — parsed as JSON first (null / true / 5 / ["a","b"]), falling back to a literal string (docs/design). The string "null" is the explicit "no such face" for docRoot.<key>: a legal value, not a deletion.
 
@@ -15,14 +19,11 @@ Refusals throw `manifest <action>: refused — …` and leave the disk unchanged
 
 read is read-only (planMode passes, no approval); init / write are side effects (approval gate). Writes go through writeManifest / initManifest with writer "main" — the fail-closed subagent default is never used.
 
-Key catalog — the writable nodes: what each is; when to change it; wrong ⇒ consequence.
+Key catalog — the 12 writable nodes (3 whole keys + docRoot's 5 sub-keys + index's 4 sub-keys): what each is; when to change it; wrong ⇒ consequence.
 - `version` — schema version (a number); change on file migration; wrong ⇒ validation refuses (disk unchanged).
 - `phase` — project stage, `initial-dev` / `production`; change when the stage is crossed; wrong ⇒ validation refuses.
-- `promptsLanding` — declared prompt-landing directory; change when it moves; no failure consequence (no shape check, no in-core reader — a registration face).
 - `codePaths` — path segment names (replaces the default `["src"]`); change when the layout moves; wrong ⇒ no segment is classified (the fallback still runs).
 - `docRoot.requirements` · `docRoot.specs` · `docRoot.design` · `docRoot.modules` · `docRoot.batches` — each doc-layer root path (a string | a multi-root array | `null` = absent); change when a layer moves root; wrong ⇒ validation refuses, or checks / batch landing / review roots point elsewhere.
-- `checkConfig.scanDirs` · `checkConfig.lineWidth` · `checkConfig.widthExemptZones` · `checkConfig.anchors` · `checkConfig.exemptions` — machine-check settings (scan dirs / width / exempt zones / anchors / exemptions); change when the check scope changes; wrong ⇒ checks run on a wrong scope silently (missed scans / wrong width / dead exemptions).
 - `index.codeExtensions` · `index.docExtensions` — extra code / doc extensions (unioned, add-only); change when a file type is missing from the index; wrong ⇒ that type stays out of the index (extras harmless; a missing entry = a miss).
 - `index.excludePaths` — project-root-relative path prefixes (for the index); change to keep a directory out of the index; wrong ⇒ that directory is still indexed, or another is wrongly excluded.
 - `index.publicRepos` — public-repo paths (resolvable from this repo root); change when wiring a public repo into the index or cross-repo refs; wrong ⇒ that repo is unreachable for retrieval (empty origin set / wrong path).
-- `advisor.docMap` · `advisor.standardsDoc` — review pointers (map file / single standards doc; empty = not declared); change when the review injection face changes; wrong ⇒ review injection lands nothing (an unreadable doc ⇒ review with no doc).

package/tool-docs/subagent.md

@@ -17,10 +17,10 @@ Available roles (exposed per mode; the role is REQUIRED for action:'spawn' — a
 - explore — read-only search & analysis (read/search family); no git context — evidence comes from reads and the task book; its report must list what it searched and what it did NOT find. Say quick / medium / thorough (default medium).
 - plan — read-only planning; NEVER edits; returns a step-by-step plan.
 - coder — full implementation; the parent's complete read/write/execute toolset plus verify and advisor self-review. Its report carries a delivery table, one row per requirement (Done / Simplified / Not done — no deferred column). Normal mode: may optionally carry `batchDoc` — binds this spawn's §5 record-write channel (unbound ⇒ the main agent records §5 on its behalf); when provided the path must resolve to a readable file.
-- eng-coder — engineering mode only (replaces coder): same toolset plus the design-driven methodology overlay; its delivery protocol (implementation → audit → self-fix → advisor re-review → converged delivery) runs fully inside the child. REQUIRES a valid designToken from a passed advisor(type='design') review (its reply also echoes a designId — pass it: required to pick between concurrent designs, optional for one; echo it back in the delivery report). REQUIRES a batchDoc — the batch record path, the task book this spawn implements (refused without it or when it does not resolve to a readable file).
+- eng-coder — engineering mode only (replaces coder): same toolset plus the design-driven methodology overlay; its delivery protocol (implementation → audit → self-fix → advisor re-review → converged delivery) runs fully inside the child. REQUIRES a valid designToken from a passed advisor(type='design') review — pass the exact value from that review, or copy it verbatim from the action:'design-slots' row (the text after designToken=): missing or mismatched = the spawn is refused, and an expired token is refused with expired named (its reply also echoes a designId — pass it: required to pick between concurrent designs, optional for one; echo it back in the delivery report). REQUIRES a batchDoc — the batch record path, the task book this spawn implements (refused without it or when it does not resolve to a readable file).
 - eng-designer — engineering mode only: the SOLE author of the requirements/design documents and of the batch record's design section. Writes no implementation code, does not edit prompts, does not fire reviews, needs NO designToken. Surveys on its own; may only spawn read-only explore children (sync, ≤6 per batch). REQUIRES a batchDoc (same gate as eng-coder).
 
-Task book (every spawn role): four core structured parameters — goal (goal & why), knownFacts (the facts you already verified), acceptance (machine-verifiable criteria), reportFormat (delivery-report format) — plus ONE fifth parameter named by role: designPoints (design points & forbidden scope) for eng-coder/eng-designer, scope (scope & forbidden scope — what to read / what not to touch) for explore/plan/coder. All five are required: a missing, blank or non-string value is refused with the parameter named, and one role's fifth name never substitutes for the other's. They are composed into the child's brief in that order. A free-text task is an optional supplement, never the whole brief; round (initial|fix) is mandatory for eng-coder/eng-designer.
+Task book (every spawn role): four core structured parameters — goal (goal & why), knownFacts (the facts you already verified), acceptance (machine-verifiable criteria), reportFormat (delivery-report format) — plus ONE fifth parameter named by role: designPoints (design points & forbidden scope) for eng-coder/eng-designer, scope (scope & forbidden scope — what to read / what not to touch) for explore/plan/coder. All five are required: a missing, blank or non-string value is refused with the parameter named, and one role's fifth name never substitutes for the other's. They are composed into the child's brief in that order. A free-text task is an optional supplement, never the whole brief; round (initial|fix) is mandatory for eng-coder/eng-designer. An eng-coder spawn also carries designToken — the write credential (the exact value from the review, or copied verbatim from the action:'design-slots' row, the text after designToken=): missing or mismatched = the spawn is refused.
 
 Pass one parameter per field — contents only (the runtime adds the labels):
 subagent(role="eng-coder", round="initial", goal="…", knownFacts="…", designPoints="…", acceptance="…", reportFormat="…", batchDoc="<batch record>", designToken="…")