acstack 0.50.4 → 0.51.0

package/skills/writing/examples.md

@@ -1,153 +1,86 @@
 # Writing examples
 
-The `Write:` and `Not:` pair for each rule in `SKILL.md`, except rules 3 and 11, which keep theirs inline.
+These examples apply the shared communication standard in `../../output-styles/ac-writing-style.md` without prescribing one shape for every answer.
 
-### 1. Cap a descriptive sentence at 25 words, and an instruction at 20 words (ASD-STE100)
+## A short reply needs only the answer
 
-- Write: The SessionStart hook creates the symlink at `~/.claude/acstack/bin/acstack`.
-- Not: The SessionStart hook, which runs whenever a session begins and which the plugin installs for you, is responsible for creating the symlink that points at the CLI inside the current plugin cache.
+- Write: The build passes
+- Avoid: `## Context`, `## Problem`, and `## Solution` sections to report a successful build
 
-### 2. Give each sentence one instruction (ASD-STE100)
+## Preserve the reason when it changes the action
 
-- Write: Run the tests. Stage the spec files.
-- Not: Run the tests and stage the spec files, then check the baseline count.
+- Write: Don't cache the token; it expires in five minutes
+- Avoid: Don't cache the token
+    - The shorter version omits the constraint that explains the recommendation
+- Write: The hook writes the symlink
+- Avoid: The hook writes the symlink, which means the symlink gets created
+    - The second clause adds no information
 
-### 4. Break a paragraph at three sentences
+## Give each level one question to answer
 
-- Write: Three sentences, then a new paragraph, even mid-argument.
-- Not: A sixth sentence of setup inside the same block.
+- Write: The release is blocked by two failed checks
+    - The CLI build fails on a missing import
+    - The hook suite fails on malformed JSON
+- Avoid: The release is blocked by these items
+    - The CLI build fails on a missing import
+    - Run `npm test`
+    - Yesterday we considered changing the hook
 
-### 5. Open a paragraph with its point
+The first list names blockers at the same level.
+The second mixes a blocker, an action, and history.
 
-- Write: Spec sync runs at commit time. It maps changed files to domains, then rewrites each spec.
-- Not: Specs can drift. One option is to update them by hand. Spec sync runs at commit time.
+## Keep the overview connected to the detail
 
-### 6. Use one term for one meaning across a document (ASD-STE100)
+- Write: The SessionStart hook creates the CLI symlink
+    - `hooks/session-start.sh` links the bundled CLI to `~/.claude/acstack/bin/acstack`
+- Avoid: The startup mechanism prepares the launcher
+    - `hooks/session-start.sh` creates a symlink
 
-- Write: The map holds nodes. Each node has a status.
-- Not: The map holds nodes. Each item has a status.
+The first version ties the readable name to the file and its output.
+The second makes the reader guess whether the names identify the same thing.
 
-### 7. Define a term of art in plain words, before you first use it
+## Define unfamiliar terms before relying on them
 
-- Write: Work the frontier, the nodes ready to work now.
-- Not: Work the frontier, the unblocked open nodes the tracker returns.
+- Write: Work the frontier, meaning the nodes ready to work now
+- Avoid: Work the frontier returned by the tracker
+- Write: The map holds nodes; each node has a status
+- Avoid: The map holds nodes; each item has a status
 
-- Write: define `map` and `node`, then say what `/acstack:map` does
-- Not: say what `/acstack:map` does, then define `map` in the next subsection
+## Separate the current decision from its history
 
-### 8. Spell out an abbreviation at first use
+- Write: Use the files backend because it works offline
+    - Decision history: We rejected the issues backend because this deployment has no network access
+- Avoid: We first considered issues, then investigated files, and eventually chose files
 
-- Write: an architecture decision record (ADR)
-- Not: an ADR
+## Keep necessary qualifications and evidence
 
-### 9. Cap a noun string at three words (ASD-STE100)
+- Write: The unit tests pass; browser verification is blocked because Chrome is unavailable
+- Avoid: All checks pass
+- Write: The parser rejects duplicate keys
+- Avoid: The parser offers comprehensive validation
 
-- Write: the knowledge base for browser verification
-- Not: the browser verification knowledge base file
+## Choose clear words without enforcing word counts
 
-### 10. Keep the articles (ASD-STE100)
+- Write: Use the bundled CLI
+- Avoid: Utilize the bundled CLI
+- Write: The browser verification knowledge base records selectors that survived a page reload
+- Avoid: Removing a necessary term to meet a three-word noun limit
+- Write: The file was deleted before the hook ran
+- Avoid: Inventing an actor to force active voice when the logs do not identify who deleted the file
 
-- Write: Update the spec in the domain directory.
-- Not: Update spec in domain directory.
+## Show relationships without inventing containment
 
-### 12. Use the short form
+- Write: The API and worker both use the authentication module
+- Avoid: Nesting the worker under the API because both depend on authentication
+- Write: The parser exposes `parse(text)` and keeps tokenization internal
+- Avoid: Listing every tokenizer helper before explaining the parser's interface
 
-- Write: To stage the specs, run the commit skill. It warns because the cap is a heuristic.
-- Not: In order to stage the specs, run the commit skill. It warns due to the fact that the cap is a heuristic.
+## Use formatting to clarify the content
 
-### 13. Name the actor and put it in front of the verb (ASD-STE100)
-
-- Write: The task-checker runs the full suite.
-- Not: The full suite is run.
-
-### 14. Write descriptions in the present tense and procedures in the imperative (ASD-STE100)
-
-- Write: The hook writes the symlink. Run the hook after you install the plugin.
-- Not: The hook will have written the symlink. You should then probably run it.
-
-### 15. Make a claim once, at the strength the evidence supports
-
-- Write: The cap misfires inside tables.
-- Not: It may possibly be the case that the cap could sometimes misfire inside tables.
-
-### 16. Name the source of a claim
-
-- Write: ASD-STE100 caps a descriptive sentence at 25 words.
-- Not: Experts believe that shorter sentences read better.
-
-### 17. Describe a thing by what it does
-
-- Write: The tunnel forwards port 19988 to Chrome on the laptop.
-- Not: The tunnel offers a seamless, robust bridge to your browser.
-
-### 18. Name the file, the number, and the actor
-
-- Write: Three of the eleven skills restate these rules, `commit` among them.
-- Not: Several files restate these rules.
-
-### 19. Recommend one option and give the reason
-
-- Write: Use the files backend. It needs no network.
-- Not: There is a files backend and an issues backend. Both carry trade-offs.
-
-### 20. State what a thing is, then stop
-
-- Write: The skill holds the rules. The CLI checks them.
-- Not: The skill is not just a style guide but a contract.
-- Not: The hook writes the symlink rather than copying it.
-
-### 21. List as many items as there are
-
-- Write: The lint warns and never blocks.
-- Not: The lint is fast, focused, and forgiving.
-
-### 22. Name the thing a pronoun stands for
-
-- Write: Only `/acstack:map` creates a map.
-- Not: Only `/acstack:map` creates one.
-
-### 23. Write for a developer who has never seen this repository
-
-- Write: Node 14 asks which tracker backend ships first.
-- Not: The node from this morning's grill.
-
-- Write: the frontier, meaning the nodes you can work right now
-- Not: work the frontier
-
-### 24. State what you checked, and when
-
-- Write: `acstack lint-prose` does not exist yet, as of 2026-08-22.
-- Not: My knowledge has a cutoff, so this may have changed since.
-
-### 25. Connect clauses with a period or a comma, and set an aside off with an en dash
-
-- Write: The lint warns. It never blocks. The rule – a heuristic – misfires inside tables.
-- Not: The same two sentences joined by an em dash, or by a colon in mid sentence.
-
-- Write: proposals, designs, and tasks
-- Not: proposals, designs and tasks
-
-### 26. Write a heading in sentence case, and end a fragment with no period
-
-- Write: `## Before you finish`, and a table cell that reads `make sure`
-- Not: `## Before You Finish.`, and a table cell that reads `make sure.`
-
-### 27. Give a heading content that its paragraph does not repeat
-
-- Write: `## Sentences`
-- Not: `## This section covers the rules that apply to sentences`
-
-### 28. Bold a single term for emphasis
-
-- Write: **fog** names whatever nobody can state precisely yet.
-- Not: **ACStack** ships a **CLI** that **many** skills call.
-
-### 29. Carry the meaning in words
-
-- Write: Done. 12 tests pass.
-- Not: The same line with a tick emoji in front and a rocket after.
-
-### 30. End with the last fact
-
-- Write: The build passes. The baseline holds at 214 tests.
-- Not: Let me know if you would like me to help with anything else.
+- Use bullets for distinct checks and numbered steps for actions that must happen in order
+- Use a table when each option needs the same comparison fields
+- Keep a connected explanation in prose when splitting it would hide the causal relationship
+- Indent nested Markdown bullets four spaces and leave a blank line before a list
+- Write `## Before you finish`, not `## Before You Finish.`
+- Write `proposals, designs, and tasks`, with the Oxford comma
+- Report `12 tests pass` in words rather than relying on an icon

package/docs/adr/0001-ste-writing-standard.md

@@ -1,16 +0,0 @@
-# One plain-language writing standard based on ASD-STE100
-
-Every durable artifact an agent writes follows one standard. The standard lives in the `writing` skill and follows ASD-STE100 – Simplified Technical English, an aerospace standard for controlled technical writing. We adopt its rules: short sentences with a numeric cap, active voice, one instruction per sentence, one term for one meaning.
-
-We reject the "add voice" advice common in anti-AI-writing guides. Someone with no context reads the artifacts weeks later. Uniformity serves that reader better than personality.
-
-## Considered options
-
-- Adopt the Cursor `unslop` skill as is – a removal checklist plus "add soul" (first person, varied rhythm, deliberate imperfection). Rejected: removal framing tells an agent what not to do, and personality is noise in specs, ADRs and map nodes.
-- Keep the rules where they are today – restated in eight files in slightly different words. Rejected: they had already drifted, and no one could point at one file.
-
-## Consequences
-
-- The standard lives in one skill; every other skill points at it. Plugin prose must itself comply, so a sweep follows.
-- A deterministic lint, `acstack lint-prose`, checks what a grep can check. It warns and never blocks, because sentence-length heuristics misfire in tables and code.
-- The ASD-STE100 dictionary requires a license, so the plugin does not reproduce it; it ships its own short vocabulary table instead.

package/docs/adr/0002-version-gate-not-auto-bump.md

@@ -1,35 +0,0 @@
-# A PR gate enforces the version bump; CI never bumps it
-
-The Claude Code plugin cache is keyed by the version in
-`.claude-plugin/plugin.json`, so a merge to `main` that does not change the
-version is invisible to every installed copy. A pull request gate
-(`scripts/version-gate.sh`, run by the `version-gate` workflow) fails the check
-when a shipped path changed without a higher version, rather than CI bumping
-the version itself. The author decides the semver level, because deriving it
-from commit message prefixes is brittle and gets the level wrong exactly when
-it matters.
-
-## Considered options
-
-- **Auto-bump on push to `main`.** CI raises the patch version whenever shipped
-  files land. Removes the failure, but a feature or a breaking change ships as
-  a patch, and CI has to write to `main`.
-
-- **release-please.** Derives the level from Conventional Commit prefixes and
-  opens a release pull request. Correct only when every commit is labelled
-  correctly, which squashed merges and hand-written subjects do not guarantee.
-
-- **A pull request gate.** CI refuses the merge; a human sets the version.
-  Chosen.
-
-## Consequences
-
-- `main` needs branch protection with `version-gate` as a required status
-  check. Without it the gate is advisory.
-
-- A shipped change that genuinely should not roll out needs the `no-bump` label
-  on the pull request. A version that goes down fails even with the label.
-
-- Documentation-only paths are exempt, listed as `INERT_PATHS` in the script
-  and duplicated in CONTRIBUTING.md. The two lists have to be kept in sync by
-  hand.

package/docs/adr/0003-handoff-ack-command.md

@@ -1,19 +0,0 @@
-# Handoff acknowledgement is a CLI command, not a reply
-
-/acstack:handoff hands work to another agent and asks it to reply ACCEPT or DECLINE. The sender's watcher, `acstack handoff watch` (`cli/src/lib/ackwatch.ts`), grepped the receiver's transcript for that keyword, a convention an agent can drift from.
-
-The receiver now acknowledges by running `acstack handoff ack accept|decline --file <handoff-file> "<reason>"`. That command writes a sidecar `<handoff-file>.ack` file, which the watcher polls instead of the transcript.
-
-## Considered options
-
-- Wording only – tighten the ACCEPT/DECLINE prompt further. Rejected: it is still a convention, and the model can still drift from it.
-- Lenient transcript matching – match more patterns in the transcript. Rejected: it keeps the same drift risk.
-- A PreToolUse hook that blocks work until the sidecar exists – the only hard guarantee. Rejected for now: scoping the hook to handoff-launched sessions is separate work. Revisit if this failure recurs.
-
-## Consequences
-
-- The receiver can still read the handoff file first. It must run the ack command before any other tool use.
-- The watcher gains an **engaged** outcome. Engaged means no acknowledgement, but a tool call after the anchor read the handoff file or used Agent, Edit, Write, or Bash.
-- The sender sends one nudge after `ack_turns` turns, then restarts the watcher.
-- A final engaged outcome is reported as "proceeding, unacknowledged." The sender never relaunches the work elsewhere. Two agents on the same files is the one failure file ownership exists to prevent.
-- The transcript keyword match stays as a fallback, labelled `via: text`. It never writes the sidecar.

package/docs/adr/0004-dev-setup-per-host.md

@@ -1,13 +0,0 @@
-# Dev setup is declared per host, not per project
-
-A dev setup – the machine-level tools an ACStack session runs inside, such as which agent orchestrator hosts the terminal panes and git worktrees and which browser-verification modes work – is recorded in the ACStack CLI's global config (`~/.config/acstack/config.json`, keys under `host.*`), not in the project's `acstack/project.yaml`. The same repository is opened on several machines with different setups, so a per-project value would have to be wrong on all but one of them.
-
-## Considered options
-
-- `acstack/project.yaml`, like `frontend.browser.mode` – shareable and checked in, but forces one answer across every machine that opens the repo.
-- Host-level global config, with project.yaml keeping only a preference where one makes sense – chosen.
-- Both layers, with the project able to constrain the host – deferred; add only if a real conflict appears.
-
-## Consequences
-
-Skills that change behaviour on the dev setup read the global config first and then check the runtime environment to see what is actually active. The project's `frontend.browser.mode` becomes a preference resolved against what the host declares available. Host setup cannot be committed with the repo, so a fresh machine needs `/acstack:host` before worktree and browser skills behave fully.

package/docs/adr/0005-two-orchestrators-per-host.md

@@ -1,25 +0,0 @@
-# Two orchestrators coexist on one host, and a checkout's path names its owner
-
-An orchestrator is a tool that hosts agent terminal panes and git worktrees. Both herdr and Orca are orchestrators, and one host – a single developer machine – may run both at once.
-
-The host config declares each one as installed or not, at `host.orchestrators.herdr` and `host.orchestrators.orca`. A developer with both installed should not have to pick one, and the session environment already says which tool hosts a session.
-
-A session lives in the host that launched it and never moves. To continue work from the other host, open a new Claude session in the same checkout – one git worktree directory – from that host. ACStack's `/acstack:handoff` stays what it is, a handoff of a full context window.
-
-A checkout's path root names its owner. Orca owns `~/orca/workspaces/<repo>/`. Everything under herdr's worktree root, `~/.herdr/worktrees/<repo>/` by default, is herdr's.
-
-Any other path belongs to plain git. The session's host creates a checkout, and the owner removes it. The worktree skills check `orca worktree ps --json` and `herdr worktree list` before every removal, because neither tool sees the other's sessions.
-
-Orca lists herdr checkouts, and the paired phone lists them, once the repo's "show in worktree list" switch is on in the desktop app. No CLI sets it, so `/acstack:host` tells the user to.
-
-## Considered options
-
-- One declared orchestrator per host, the earlier `host.orchestrator` enum. Rejected: it forces a choice the developer does not want to make.
-- A feature that moves a running session to the other host. Rejected: neither tool offers one, and a new session in the same checkout reaches the same place.
-- Either tool removes any checkout. Rejected on pilot evidence from 2026-08-23: Orca's `rm` refuses a path outside its own root, and herdr's `remove` deletes any directory and keeps the branch.
-
-## Consequences
-
-The `teardown-worktree` skill picks the removal command from the checkout's path root, not from the session's host. It deletes the branch itself for a herdr checkout.
-
-The `new-worktree` skill never passes a path that crosses roots. A config that still sets the old `host.orchestrator` key fails `config check`, and `/acstack:host` re-declares both booleans.

package/docs/adr/0006-document-opener-service.md

@@ -1,89 +0,0 @@
-# A document opener service on the laptop, separate from the Playwriter bridge
-
-`acstack-open` sends a rendered page to the opener, a small HTTP service on
-the user's laptop. The opener stores the page and serves it back on an
-address only the laptop can reach (the loopback interface). It then hands
-that address to the user's default browser.
-
-The Playwriter bridge stays as it is, and it no longer shows a document to a
-person.
-
-A page renders on a development virtual machine, which has no browser of its
-own. The virtual machine already reaches the laptop through the bridge.
-
-The bridge is a Chrome extension plus a relay, meaning a small process on the
-laptop that the extension connects to. It lets an agent drive a real browser
-over the Chrome DevTools Protocol (CDP). Reusing it to show a page to a person
-looked like the cheaper answer.
-
-The two do not collapse into one. The bridge attaches one tab at a time, and
-only after someone clicks the extension icon. That click **arms** the tab.
-
-The bridge also drives a dedicated Chrome profile rather than the user's
-default browser. So it cannot satisfy "open this in my normal browser" at all,
-and every document through it costs an arming click first.
-
-The bridge exists so an agent can *drive* a browser. The opener exists so a
-person can *see* a page.
-
-## Considered options
-
-**Drive the existing bridge**. Rejected. Arming the bridge takes one click
-per tab, inside a separate Chrome profile.
-
-Rewriting a live page over CDP also detaches the extension outright. The
-bridge then stays down until the user arms it again by hand.
-
-**Forward a port and serve from the virtual machine**. Rejected. The user's
-terminal would open an address that a forwarded port carries back to a server
-on the virtual machine.
-
-The reverse tunnel the bridge already maintains runs the wrong way, so this
-needs a second forward. That forward comes from a `LocalForward` line in the
-user's own SSH host block, and nothing in setup writes it. The page also dies
-when the server on the virtual machine stops, which is the common case when a
-session ends.
-
-**Print a clickable hyperlink in the terminal**. Kept as the fallback, not as
-the answer.
-
-The terminal already prints one today. It costs a deliberate click for every
-single document. The requirement was to read one document after another
-without ceremony.
-
-**Open the document in the editor instead of a browser**. Rejected.
-
-The user is moving away from an editor-hosted terminal toward a plain one.
-The user asked specifically for the default browser.
-
-## Consequences
-
-A second always-on service now runs on the laptop, and every virtual machine
-gets one more tunnel task to carry it. This is deliberate.
-
-Setup already registers the relay and its tunnels as self-healing scheduled
-tasks. The opener inherits that machinery, its deployment, and its
-restart-on-change behaviour rather than inventing any.
-
-The opener gets its own tunnel rather than a second forward on the bridge's
-connection. `tunnel.ps1` passes `ExitOnForwardFailure=yes`, so one wedged
-port fails the whole `ssh` session. A stuck opener port would take the bridge
-down with it.
-
-The virtual machine can now ask the opener to restart the relay and to
-restart the tunnels. Those are two recovery actions the virtual machine could
-not perform before, and a human had to paste both into a shell. Arming stays
-manual, because it is behaviour of a third-party extension and nothing on
-either side can click it.
-
-The opener stores rendered documents on the laptop. They outlive the session
-that produced them. That is what makes a page still work after the virtual
-machine goes away.
-
-The opener prunes the store after a week.
-
-The service accepts a document and puts it on the user's screen, so a shared
-secret called the opener token guards it. Setup generates that token and
-copies it to the virtual machine. Loopback binding alone is not enough,
-because the reverse tunnel makes the port reachable by anything running on
-the virtual machine.

package/docs/adr/0007-lead-check-reads-the-transcript.md

@@ -1,87 +0,0 @@
-# A session's own transcript decides lead or child, not the environment
-
-The `handoff` and `compact-and-continue` skills run only in a **lead session**,
-because both write state the lead alone owns. An agent decides which it is by
-planting a random mark in its own transcript and then asking which transcript
-holds it.
-
-A hit under `~/.claude/projects/<project>/<session>/subagents/` means the agent
-is a subagent or a teammate. No environment variable takes part in that
-decision.
-
-The first version read `CLAUDE_CODE_CHILD_SESSION` instead. Claude Code sets
-that variable to `1` in the environment of every Bash tool subprocess, in every
-session. So the check was true unconditionally, and both skills refused to run
-everywhere (#146).
-
-The variable marks "spawned by Claude Code", and nothing finer.
-
-## Considered options
-
-- **A different environment variable.** Measured on Claude Code 2.1.241, an
-  in-process subagent and an in-process teammate both report the lead's exact
-  `CLAUDE_CODE_SESSION_ID`, `CLAUDE_PID` and `CLAUDE_CODE_ENTRYPOINT`. A child
-  runs inside the lead's own process, so no variable separates them. Ruled out
-  by measurement, not by preference.
-
-- **Drop the check and let a child run the skills.** Simplest, and wrong. A
-  child shares the lead's `CLAUDE_CODE_SESSION_ID`, so a child's quiet marker
-  silences a context-pressure nudge the lead still needs, and a child's
-  `acstack/HANDOFF.md` overwrites the lead's anchor.
-
-- **Read `taskKind` from the agent's `.meta.json`.** The host does write one
-  beside each agent transcript, naming `in_process_teammate` for a teammate and
-  omitting `taskKind` for a plain subagent. An agent cannot tell which of those
-  files is its own, so the file answers a question nobody can ask.
-
-- **Plant a mark, then find it.** Chosen. The mark is unique per agent, so the
-  answer is the agent's own and never a sibling's.
-
-## Consequences
-
-- The command polls for up to ten seconds rather than grepping once. The host
-  writes the record carrying a command while that command still runs, roughly
-  four seconds in.
-
-    A single grep therefore runs too early, finds nothing and answers
-    `lead` for everyone. A lead usually exits in about four seconds, as
-    soon as its own record lands.
-
-- The check reads a Claude Code internal layout that no public contract
-  describes. A host that renames the `subagents/` directory, or files agent
-  transcripts elsewhere, turns every child into a `lead` verdict.
-
-- Absence of evidence reads as `lead`. A host that persists no transcript
-  leaves the command empty-handed, and the skill proceeds. Failing closed is
-  what produced #146, so the failure now falls on the side that keeps the
-  skills runnable.
-
-- The agent transcripts alone decide. An agent's own mark reaches
-  `<session>.jsonl` whether it leads or not. So the loop reads that file only
-  as an early exit for a lead, never as evidence of a child.
-
-- The nonce placeholder stays angle-bracketed. `n=acstack-whoami-<nonce>` is a
-  bash syntax error, so an agent that pastes the block without substituting
-  fails loudly. A bare token would run instead. It would match every transcript
-  in the session that had already read the skill file, so the command would
-  answer `child` to a real lead.
-
-- The agent still chooses the nonce, and a language model samples randomness
-  badly. Two agents in one session that pick the same eight characters read
-  each other's transcripts. Generating the nonce at runtime cannot fix that.
-
-    The mark has to sit in the command text for the command to find it. A
-    value computed at runtime reaches the transcript only after the command
-    ends.
-
-- Both skills carry their own copy of the block, rather than calling a shared
-  script. `skills/new-worktree/detect-orchestrator.sh` shows the repo has that
-  pattern. No home exists for a script two skills share, though.
-
-    The repo also already repeats the context-pressure path expression in
-    three places. `tests/test-skill-gates.sh` asserts the two copies match
-    byte for byte. That assertion is what makes the duplication safe to keep.
-
-- `tests/test-skill-gates.sh` extracts the command from each `SKILL.md` and
-  runs it against fixture transcript layouts. The fixtures encode the layout
-  above, so they need revisiting whenever the host changes it.

package/docs/adr/0008-cli-audits-skill-interviews.md

@@ -1,37 +0,0 @@
-# The CLI audits, the skill interviews
-
-`acstack config check` is the only health check in ACStack. It reports what is
-wrong with a machine and a project. It changes nothing.
-
-`/acstack:setup` reads that report, then asks the user what to do about each
-failure. The skill writes the answers. Neither one does the other's job.
-
-The check reads `~/.claude/settings.json` and the two project settings files,
-even though Claude Code owns them and ACStack does not. A health check with a
-row it cannot see is a health check nobody can trust.
-
-## Considered options
-
-ACStack had two commands named `check`.
-
-The CLI's audited the host axes. The config skill's audited the project's
-infrastructure in prose. Neither called the other, and a user could not tell
-them apart by name.
-
-Leaving the split in place keeps ACStack's CLI reading only ACStack's own
-files. It also lets the two audits drift apart. It leaves the project half
-untestable, because continuous integration cannot run prose in a skill body.
-
-## Consequences
-
-The check grows a `--json` output, so the skill maps a failing row to the fix
-it offers. That output is an interface. Renaming a row identifier breaks the
-skill silently, so the row identifiers need tests.
-
-Every audit rule now lives in TypeScript and gets tested. No skill re-probes
-the machine with its own shell commands.
-
-A user who wants one setting changed runs `acstack config set <key> <value>`
-and answers no questions. The full key reference lives in
-`docs/config-reference.md`, because seventeen keys carry more nuance than a
-help string holds.

package/docs/adr/0009-verify-the-write-not-the-writer.md

@@ -1,51 +0,0 @@
-# The config writer verifies its result instead of predicting it
-
-`acstack config set` writes a key into `acstack/project.yaml` by splicing the
-new value over the old value's bytes, so a hand-edited file keeps its comments
-and its spacing. Before writing, it parses what it built and compares that data
-against what the YAML document interface would have produced. The two must
-agree, or the write falls back to the document interface.
-
-The writer verifies that fallback the same way. It parses the emitted text and
-compares it against the same data. A write neither path can verify refuses with
-exit 1 and leaves the file byte for byte as it was.
-
-The comparison covers the whole file, not the key that changed.
-
-## Considered options
-
-The first version predicted safety with guards on the node it was replacing.
-Three rounds of that shipped four ways to corrupt a user's file, each behind a
-green success message and exit code 0.
-
-A folded or literal block scalar's byte range runs past its trailing newline,
-so the splice ate the line break and destroyed the following key. An existing
-empty value has a zero-width range, so the write produced `test:npm test`.
-
-A new value spanning lines landed at column zero. A scalar inside a flow
-collection passed every guard, and a value holding a comma truncated the key
-and invented a second one beside it.
-
-Each guard was correct. Each author read the node and not the context around
-it. A user would have found the fifth shape.
-
-## Consequences
-
-The writer costs one extra parse per write, which nobody running a command by
-hand will notice.
-
-A key-only comparison passes every test in the suite and every input a 2020
-case sweep could reach. The writer compares the whole file anyway. Narrowing it
-means arguing about shapes nobody has constructed yet, and that argument has
-already been wrong four times.
-
-Do not narrow it to the changed key on the grounds that no test covers the
-difference. No test can.
-
-The document interface was the trusted baseline until a fifth shape broke it. A
-whitespace-only value over a block scalar with a sibling key after it emitted a
-content line no parser reads back. The value returned as the empty string,
-behind exit 0.
-
-The splice refused that write correctly and handed it to a fallback nobody
-checked. The writer checks both paths now.