@erclx/aitk 0.87.0 → 0.89.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.87.0",
+  "version": "0.89.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/decision-escalate/REQUIREMENT.md

@@ -0,0 +1,45 @@
+---
+name: decision-escalate
+description: Scope boundary for handing a decision back to the operator, and the batching contract that keeps the handoff to one turn
+---
+
+# Decision escalate requirement
+
+## Gap
+
+Without this skill, a session facing a decision that belongs to the operator asks about it one question at a time across several turns, so the operator answers each without knowing how many are open and cannot trade one against another. It asks in prose with no options attached, so the operator has to invent the alternatives before picking one. It names an option and omits what the other one buys, so the pick is made blind. It escalates a call it could have settled from the repository or from its own judgment, which spends the operator's attention on work the session owed.
+
+It also empties a long backlog into one turn, so the questions past the first few arrive in no order and the operator cannot tell which ones the work is actually stalled on. It carries on with work the unanswered questions govern, so an answer arrives against output already built the other way. It takes the answer, acts, and leaves the plan, task, or record that posed the question reading as open, so the next session re-asks a decision the operator already made.
+
+A body written around a named tool fails a third way. A session on a surface carrying no structured question tool reads an instruction it cannot execute and falls back to whatever it would have done unaided, which is the per-decision ask this file exists against.
+
+The opposite failure is the one that ships silently. A session that takes a preference decision itself produces work the operator did not ask for and never learns a choice was made, because nothing in the output says a fork was passed.
+
+`CLAUDE.md` states both branches of the rule, sending an ordinary judgment call to a pick with the tradeoff in one sentence and a preference-deciding call to the operator. The first branch has `snippets/decision-help.md` behind it and the second had no surface at all.
+
+## Must
+
+- Collect every open decision before asking any of them, so the operator sees the set rather than the first one
+- Put the whole batch in one turn, since a batch split across turns is the per-decision ask this skill exists to replace
+- Give each question two to four options, each carrying what it means and what it costs, with the recommendation ranked first and named as such
+- State the behavior first and the tool second, so the body runs on a chat surface carrying no structured question tool
+- Cap a batch at four questions and say how many are held, since a structured question tool takes four and an uncapped batch hides the overflow
+- Hold every escalated decision until it is answered, and continue only the work depending on none of them
+- Route a pick that changes a written artifact into that artifact under the standard owning it, rather than leaving it in the session
+
+## Must not
+
+- Answer on the operator's behalf, or treat the recommendation as the answer because no reply arrived
+- Escalate a decision the session can settle from its own judgment or from reading the repository, which is the first branch of the rule and belongs to the session
+- Escalate a decision already taken, which goes to the record that holds it rather than back to the operator
+
+## Guards
+
+- Nothing open, stop rather than manufacturing a question to justify the invocation
+
+## Out of scope
+
+- Making the ordinary judgment call, which is a pick plus a one-sentence tradeoff and needs no surface
+- The chat-side pick with no repository behind it, which `snippets/decision-help.md` covers and reaches a different reader
+- Writing the decision into a plan, task, or architecture record, which each owning standard governs and this skill only routes to
+- Deciding when to fire. The skill is user-invoked through `disable-model-invocation`, so escalating is the operator's call rather than a description match.

package/claude/skills/decision-escalate/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: decision-escalate
+description: Collects every open decision whose answer turns on the operator's preference, puts them as one batch of questions each carrying options and a recommended default, then waits. Use when asked to "escalate this", "ask me the open questions", "batch the open decisions", "what do you need from me", or "stop and ask before you pick". Do NOT use for a judgment call the session can settle, which is a pick with the tradeoff stated in one sentence.
+disable-model-invocation: true
+---
+
+# Decision escalate
+
+Put every open decision that belongs to the operator as one batch, each carrying its options and a recommended default, then stop until the batch is answered.
+
+One batch is the whole point. A session that asks one question, acts, then asks the next spends the operator's attention once per decision and hides how many are open.
+
+## Guards
+
+- If nothing is open, stop: `❌ Nothing to escalate. Every open call is one this session can make.`
+- Escalate only a decision whose answer turns on the operator's preference. A judgment call with two or three reasonable options the session can weigh is a pick with the tradeoff stated in one sentence, taken without asking.
+- Escalate only what is open now. A decision already taken this session goes to the artifact that records it rather than back to the operator.
+- Do not act on any decision in the batch before it is answered. Continue the work that depends on none of them.
+- Do not escalate a question the session can answer by reading the repository. Read first, and escalate what the tree does not settle.
+
+## Step 1: collect what is open
+
+Sweep the session for every decision still unmade. The usual sources:
+
+- A plan question whose answer turns on preference rather than measurement
+- A fork the session parked to keep moving, where both branches still ship
+- A default the session took silently that changes what the operator receives
+- A scope boundary the request left ambiguous, where the two readings produce different work
+
+Drop anything the session can settle. What survives is the batch.
+
+## Step 2: shape each question
+
+Each entry carries a short header naming the axis, the question itself, and two to four options. Give every option what it means and what it costs. Rank the recommendation first and say it is the recommendation.
+
+An option with no stated cost is not an option, since the operator picks it without knowing what the other one buys.
+
+Cap the batch at four. A structured question tool takes four, and a batch past that is a session asking to be redesigned rather than answered. When more than four are open, send the four blocking the most work and say in one line how many are held.
+
+## Step 3: put the batch
+
+Put every question in one turn. Never split the batch across turns and never ask the first while the rest stay unstated.
+
+When the session runs on a surface carrying a structured question tool, such as `AskUserQuestion` in Claude Code, send the whole batch through one call with one entry per decision. The tool renders the options and collects the picks together.
+
+Otherwise write the batch as a numbered list in one message, each question followed by its lettered options with the recommendation marked. The behavior is the same on either surface, and only the rendering changes.
+
+Batch shape:
+
+```plaintext
+<N> open decisions. <M> held.
+
+1. <axis>: <question>
+   a. <option> (recommended): <what it means>, <what it costs>
+   b. <option>: <what it means>, <what it costs>
+
+2. <axis>: <question>
+   a. <option> (recommended): <what it means>, <what it costs>
+   b. <option>: <what it means>, <what it costs>
+```
+
+## Step 4: wait
+
+Stop after the batch. Do not answer on the operator's behalf, do not act on the recommendation because it is the recommendation, and do not fill the wait with work the batch would invalidate.
+
+An operator who answers some and not others has answered those. Continue on the answered ones and hold the rest.
+
+## Step 5: record and continue
+
+Restate each pick in one line, then continue the work.
+
+A pick that changes a written artifact goes into that artifact under the rule its own standard sets. An answer to an open plan question rewrites that question's `- Suggested:` line to the pick and names the operator as its source, leaving the `- Answer:` slot blank, per `.claude/standards/plan.md`, or `${CLAUDE_SKILL_DIR}/../../standards/plan.md` when the project does not have it. The standard bars a session from filling that slot even when the operator supplied the pick, and the blank slot resolves to the rewritten suggestion, so the record carries the operator's decision either way. A pick that settles nothing written stays in the session.
+
+Output after the answers land:
+
+```plaintext
+✅ <N> decisions answered
+<axis>: <pick>
+<axis>: <pick>
+<M held, restated in one line each>
+```

package/docs/agents/markdown-audit.md

@@ -51,7 +51,7 @@ A banned word is bounded on a word character or a hyphen either side. A plain wo
 
 A banned spelling keeps the plain word boundary, hyphens included. The two bans target different things: a word ban targets the word, so reading a compound as one word is correct, while a spelling ban targets the orthography inside it, which sits in `behaviour-driven` as plainly as it sits alone.
 
-Two ban shapes stay unmeasured and the report says so on every run. A phrase ban carries a placeholder standing in for the rest of the sentence, so no literal match reaches it, and every rule under `## Voice` is a judgment. A report listing hits without naming those would read as a verdict on the whole standard.
+Two ban shapes stay unmeasured and the report says so on every run. A multi-word ban escapes the harvest by width, whether it carries a placeholder standing in for the rest of the sentence or spells the phrase out in full, and every rule under `## Voice` is a judgment. The bans `## Language` states over what a sentence may claim sit in the first group by construction, since a literal match over a pattern reports the compliant text and reaches none of the violations. A report listing hits without naming those would read as a verdict on the whole standard.
 
 ### Bullets, paragraphs, and depth
 

package/docs/ai-workflow.md

@@ -169,6 +169,7 @@ Before the first feature session on a UI-heavy project, pick a design tier. The
 | `aitk:claude-intake`         | File a brain dump into an inventory under `.claude/intake/`, one item per finding with a verdict                     |
 | `aitk:claude-groundwork`     | Before a plan is warranted, measure an unknown in a track folder under `.claude/groundwork/`                         |
 | `aitk:claude-feature`        | Before implementation, scan for conflicts and ambiguities                                                            |
+| `aitk:decision-escalate`     | Batch every open decision that turns on your preference into one set of questions, each with a recommended default   |
 | `aitk:claude-roadmap`        | Sequence MVP scope into ordered versions in `.claude/ROADMAP.md`                                                     |
 | `aitk:claude-orchestrate`    | Assert the orchestrator role, refill the ready queue, and dispatch the feature, review, and worktree skills          |
 | `aitk:claude-diagram`        | Draft per-kind mermaid entries under `.claude/diagrams/` from architecture and code, then verify each rendered image |

package/docs/target-projects.md

@@ -72,6 +72,8 @@ The default path is `base`. `aitk init` on `base` installs base tooling configs,
 
 Escalate only for real web apps. The `setup-init` skill reads `package.json` and root configs, then picks the matching tooling stack (`vite-react` today) and the matching governance stack (`react`, `astro`, `node`).
 
+`node-server` is named rather than detected. It carries the server-side security and persistence rules for a project writing request handlers or a persistence layer in TypeScript, and the detect step matches a runtime or a framework against stack names, so nothing there marks a project as a backend. Pass it deliberately with `aitk init --stack node-server` or `aitk gov install node-server <target>`.
+
 Markdown-heavy projects, CLI tools, docs sites, research notebooks, and scripting repos stay on `base`. Escalation is a ceiling move, not a default.
 
 Run `aitk tooling list --json` and `aitk gov list --json` to see the current catalogs. Never hardcode stack names.

package/governance/stacks/node-server.toml

@@ -0,0 +1,2 @@
+extends = "node"
+rules = ["360-security-server", "370-database"]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.87.0",
+  "version": "0.89.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/standards/index.md

@@ -13,10 +13,10 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Diagram reference](diagrams.md): Shape and content rules for .claude/diagrams/<kind>.md files
 - [Groundwork reference](groundwork.md): Folder layout, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
 - [Intake reference](intake.md): Folder layout, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
-- [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, punctuation, emphasis, and file references
+- [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, and file references
 - [Memory reference](memory.md): Filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire
 - [Plan reference](plan.md): Filename and slug, required sections, the suggested-and-answer contract, and the lifecycle from the live folder to the archive
-- [Prose reference](prose.md): Voice, language, and frontmatter wording for reference markdown
+- [Prose reference](prose.md): Voice, language, what prose may claim, and frontmatter wording for reference markdown
 - [Publish reference](publish.md): Scan an author runs against finished text, the cross-reference form each destination takes, and the response to an unreadable source
 - [Readme reference](readme.md): Readme voice, structure, and content conventions
 - [Requirements reference](requirements.md): Shape and content rules for .claude/REQUIREMENTS.md

package/standards/markdown.md

@@ -1,6 +1,6 @@
 ---
 title: Markdown reference
-description: Headings, paragraph and list structure, code spans, punctuation, emphasis, and file references
+description: Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, and file references
 ---
 
 # Markdown reference
@@ -9,11 +9,11 @@ Applies to markdown reference docs, READMEs, and inline documentation in repos.
 
 ## Scope
 
-Governs the markdown mechanics of every markdown file: headings, paragraph and list structure, code spans and fences, punctuation, emphasis, and file references. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, and it carries no template because mechanics are written across every document and have no shape of their own.
+Governs the markdown mechanics of every markdown file: headings, paragraph and list structure, code spans and fences, the form a date takes, punctuation, emphasis, and file references. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, and it carries no template because mechanics are written across every document and have no shape of their own.
 
 Does not govern:
 
-- Voice, word choice, and the wording of a `title` or `description`: `prose.md`
+- Voice, word choice, what prose may claim, and the wording of a `title` or `description`: `prose.md`
 - What sections a document has, or what belongs in each: the standard for that document type
 - The text inside a fenced block, which follows the conventions of its own language rather than these
 - The scan that applies the punctuation bans to finished text on its way out: `publish.md`
@@ -49,6 +49,10 @@ Does not govern:
 - Use a language identifier on all fenced code blocks (`markdown`, `typescript`, `plaintext`). Never use a bare ` ``` `
 - In ASCII tree diagrams, use `←` for inline annotations. Never use `#`.
 
+## Dates
+
+- Write a date as `YYYY-MM-DD` wherever one appears, in frontmatter, in prose, and in a filename. Never a month name, a slash-separated form, or a two-digit year.
+
 ## Punctuation
 
 - Do not use em dashes (`—`) or semicolons (`;`). Rewrite or restructure the sentence to avoid them.

package/standards/prose.md

@@ -1,6 +1,6 @@
 ---
 title: Prose reference
-description: Voice, language, and frontmatter wording for reference markdown
+description: Voice, language, what prose may claim, and frontmatter wording for reference markdown
 ---
 
 # Prose reference
@@ -11,11 +11,11 @@ The yield covers voice alone. The language rules below stay in force on every su
 
 ## Scope
 
-Governs voice, word choice, and frontmatter wording wherever prose is written. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, yields on voice alone where that standard states one, and carries no template because voice is written across every document and has none of its own to shape.
+Governs voice, word choice, what prose may claim about its subject and its sources, and frontmatter wording wherever prose is written. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, yields on voice alone where that standard states one, and carries no template because voice is written across every document and has none of its own to shape.
 
 Does not govern:
 
-- Headings, list and paragraph structure, code spans, punctuation, emphasis, and file references: `markdown.md`
+- Headings, list and paragraph structure, code spans, the form a date takes, punctuation, emphasis, and file references: `markdown.md`
 - What sections a document has, or what belongs in each: the standard for that document type
 - Which frontmatter fields a document carries, which is that standard's own subject. This file governs the wording of a `title` and a `description` and nothing else about them.
 - Phase-label and semver discipline: `versioning.md`
@@ -44,8 +44,14 @@ Does not govern:
 - Do not pad verb phrases or delay the action. Write the shortest form (`in order to` → `to`, `ensure that X is set` → `set X`, `By doing X, you can Y` → state Y directly).
 - Do not address the reader as a participant (`Let's`, `Here's`, `Here are`). State the content directly.
 - Commit to a position. Do not hedge in clusters (`It might be worth considering`) or use false balance (`While X is true, Y is also important`). Recommend, or state the tradeoff.
+- Do not inflate significance. State what a thing does rather than calling it `a major milestone` or `a turning point for the field`.
+- Do not name a person, company, or product to borrow its authority. Name a source only where the claim turns on who made it.
+- Do not attribute a claim to an unnamed authority (`experts say`, `studies show`, `it is widely believed`). Name the source or cut the claim.
+- Do not introduce a fact, name, date, or citation the source does not carry when rewriting existing text. A rewrite changes wording and never claims.
 
-The character bans sit in `markdown.md` under `## Punctuation` rather than here, because an em dash and a semicolon are typography and these are word choice. A surface applying both reads both files.
+The character bans sit in `markdown.md` under `## Punctuation` rather than here, because an em dash and a semicolon are typography and the bans here reach the words a sentence chooses and the claims it makes. A surface applying both reads both files.
+
+Illustrate a pattern ban with a multi-word phrase. An audit reading this section harvests the single lowercase backticked words out of every `- Do not use ` bullet into a literal ban set, so a one-word example bans that word everywhere it appears rather than banning the pattern it stands for. Both the toolkit command and the audit hook a project installs parse that shape, so the constraint holds wherever this file lands.
 
 ## Frontmatter descriptions
 

package/tooling/claude/seeds/CLAUDE.md

@@ -36,11 +36,15 @@
 
 ## Output
 
-- After creating or modifying a file, include its path on its own line so terminal emulators can make it clickable. Do not paraphrase paths into prose ("the seeds folder", "your CLAUDE.md").
+- After creating or modifying a file, include its path on its own line so the reader can open it. Do not paraphrase paths into prose ("the seeds folder", "your CLAUDE.md").
+- Read `CLAUDE_CODE_ENTRYPOINT` once, at the first response that emits a path, and reuse it for the rest of the session. The surface cannot change mid-session, so a second read only confirms the first.
+- When it reads `claude-desktop`, emit each path as a markdown link carrying the path as its text and an absolute `file://` URI as its target, resolving a relative path against the main project root to build that target. The desktop file tree hides dotted folders, so a bare path into one names a file the reader cannot reach.
+- On every other value, including unset, emit the path bare. A terminal emulator makes it clickable through its own path detection, and link markup defeats that.
+- Both forms govern a path emitted in a response. A path written into a markdown file follows `.claude/standards/markdown.md` instead, which backticks a file reference and never repeats it as a link label.
 - Use the path the user's editor can resolve. The editor is rooted at the main project root.
-- In the main worktree: relative from `pwd` works because `pwd` equals the editor root
+- In the main worktree: relative from `pwd` works because `pwd` equals the editor root.
 - In a linked worktree (under `.claude/worktrees/<name>/`): use absolute paths. Relative paths from worktree `pwd` would not resolve against the editor's project root.
-- When the response covers multiple files, group paths under headers: `**Created:**`, `**Modified:**`, `**Deleted:**`. For single-file changes, the path on its own line is enough.
+- When the response covers multiple files, group paths under headers: `**Created:**`, `**Modified:**`, `**Deleted:**`. Every path under them takes the form the entrypoint selected rather than the first alone. For single-file changes, the path on its own line is enough.
 
 ## Key paths