acstack 0.0.0-stage → 0.47.0

package/docs/adr/0014-reading-a-node-hides-its-generated-diagram.md

@@ -0,0 +1,29 @@
+# Reading a node hides its generated diagram
+
+`acstack node read` and `acstack node walk` strip generated blocks from their
+human-readable output, and `--visuals` puts them back. `--json` always carries
+the whole body.
+
+A generated block repeats what the map already holds. An agent that can call
+`acstack node frontier` gets those facts on demand, so a picture of them in
+every read spends the context twice.
+
+## Considered options
+
+Keeping the whole body is the honest default. It costs an agent a diagram on
+every read of every node. A map that draws one on each parent node makes that
+cost grow with the map.
+
+Stripping every mermaid fence would take the hand-drawn diagrams with it.
+Those are the explanation the node exists to give.
+
+## Consequences
+
+Only the markers decide what goes. A hand-drawn diagram never sits inside
+them, so the split is exact and needs no heuristic.
+
+A reader who wants the picture passes `--visuals`. A caller composing
+something parses `--json`, which never strips.
+
+A node body that documents the markers keeps them. A marker inside a fenced
+code block is prose about the markers, never a block.

package/docs/adr/0015-a-node-id-links-to-its-issue-through-an-anchor.md

@@ -0,0 +1,37 @@
+# A node id links to its issue through an anchor
+
+A generated diagram wraps each node id in an HTML anchor pointing at its
+issue. A reader clicks the id and lands on the node.
+
+The mermaid `click` directive does the same job and does not work here.
+GitHub renders at `securityLevel: strict`, and its Content Security Policy
+blocks the `frame-src` that directive needs.
+
+## Considered options
+
+Shipping the id as plain text works in every renderer and costs a reader one
+copy and one search per node.
+
+The `click` directive is the documented way to link a node. GitHub's Content
+Security Policy stops it.
+
+## Consequences
+
+GitHub documents none of this behaviour. A community thread reports it
+working since March 2024, and GitHub has broken it once already. A second
+break renders the label as literal `<a href=...>` text rather than plain
+text.
+
+The anchor wraps the id alone, never the whole label, so a link reads as a
+link.
+
+Its `href` takes single quotes, since the mermaid label is already
+double-quoted. Mermaid rewrites anything matching `#<word>;` into a
+private sentinel. So a quote inside a url becomes `&apos;` and never the
+numeric `&#39;`, and `escapeLabel` turns every `#` a label carries into
+`&num;`.
+
+The GitHub renderer needs `url` in the `gh issue list --json` field list. It
+has no other way to build the address, so that field is not optional.
+
+The files backend draws plain ids. A node on disk has no address to link to.

package/docs/adr/0016-the-map-root-carries-no-status-of-its-own.md

@@ -0,0 +1,21 @@
+# The map root carries no status of its own
+
+A map's root node has no status of its own. Its state follows its subtree: open while any node below it is open, fog, or claimed, and resolved otherwise.
+
+The frontier never returns the root. `archive` closes it when the map clears.
+
+Before this, the map skill created the root as resolved and nothing ever changed it. The field called the destination resolved while eleven nodes below it were still open.
+
+On GitHub, `gh issue create` opened the root issue and nothing closed it. The two backends disagreed, and the GitHub frontier returned its own root.
+
+## Considered options
+
+- Keep the root resolved at creation, and let the frontier skip it as a resolved node. Rejected: a green root on an open map misreads on every diagram. A closed issue at the top of an open map misreads on GitHub.
+- Store the derived status on the root and rewrite it after every resolution. Rejected: every writer would have to recompute the subtree, and one missed write leaves a stale field. Deriving it at read time cannot drift.
+
+## Consequences
+
+- The root is the one node whose stored status means nothing on its own. The diagram prints a count in its place, for example `#229 destination - 11 of 13 open`.
+- The frontier has one structural exception: the node with no `answers`. Both backends share it, because the diagram renderer runs the same function over GitHub nodes.
+- `archive` gains a step. After its gate passes, it resolves the root, then disposes of the map. Its gate ignores the root, or an open root would fail every map.
+- A root closed before this decision stays closed. Nothing reopens history.

package/docs/adr/0017-call-impeccable-copy-only-its-questions.md

@@ -0,0 +1,13 @@
+# Call impeccable's command line, and copy only its question sets
+
+acstack uses impeccable, a third-party design plugin, as an optional design gate. acstack calls five commands through impeccable's documented command-line contract: `detect`, `context`, `audit`, `polish`, and `document`. It copies only impeccable's stable question sets, into the map's frontend branch. It never copies impeccable's files and depends on no other surface.
+
+This project does not own impeccable, and impeccable moved three major versions in a year.
+
+## Considered options
+
+Copying impeccable into acstack turns every upstream release into a manual port. Naming all 23 commands ties acstack to names that change between versions. Putting the integration inside impeccable is not possible, since this project does not own that repo.
+
+## Consequences
+
+A copied question set can go stale, and a rename of one of the five called commands breaks the gate. The version floor (major 4, warn only) surfaces that without blocking a project, since the gate is optional. Commands that change a design's intent never run unattended; a human picks one in a grill round.

package/docs/adr/index.md

@@ -0,0 +1,17 @@
+- [0001](0001-ste-writing-standard.md) – One plain-language writing standard based on ASD-STE100
+- [0002](0002-version-gate-not-auto-bump.md) – A PR gate enforces the version bump; CI never bumps it
+- [0003](0003-handoff-ack-command.md) – Handoff acknowledgement is a CLI command, not a reply
+- [0004](0004-dev-setup-per-host.md) – Dev setup is declared per host, not per project
+- [0005](0005-two-orchestrators-per-host.md) – Two orchestrators coexist on one host, and a checkout's path names its owner
+- [0006](0006-document-opener-service.md) – A document opener service on the laptop, separate from the Playwriter bridge
+- [0007](0007-lead-check-reads-the-transcript.md) – A session's own transcript decides lead or child, not the environment
+- [0008](0008-cli-audits-skill-interviews.md) – The CLI audits, the skill interviews
+- [0009](0009-verify-the-write-not-the-writer.md) – The config writer verifies its result instead of predicting it
+- [0010](0010-promote-dev-to-main-by-fast-forward.md) – A labelled workflow fast-forwards main to dev, and nobody merges
+- [0011](0011-node-header-is-the-edge-encoding.md) – The node body header is the authoritative edge encoding on GitHub
+- [0012](0012-node-kind-is-a-closed-set-of-five.md) – A map node's kind is a closed set of five
+- [0013](0013-the-diagram-renderer-is-pure.md) – The diagram renderer takes nodes in and never calls gh
+- [0014](0014-reading-a-node-hides-its-generated-diagram.md) – Reading a node hides its generated diagram
+- [0015](0015-a-node-id-links-to-its-issue-through-an-anchor.md) – A node id links to its issue through an anchor
+- [0016](0016-the-map-root-carries-no-status-of-its-own.md) – The map root carries no status of its own
+- [0017](0017-call-impeccable-copy-only-its-questions.md) – Call impeccable's command line, and copy only its question sets