acstack 0.50.4 → 0.52.0

package/docs/adr/0010-promote-dev-to-main-by-fast-forward.md

@@ -1,115 +0,0 @@
-# A labelled workflow fast-forwards main to dev, and nobody merges
-
-ACStack promotes `dev` to `main` by fast-forward. Open a pull request with base
-`main` and head `dev`. Review it, then add the `promote-to-main` label.
-`.github/workflows/promote.yml` checks six preconditions and moves
-`refs/heads/main` to the commit the pull request carries.
-
-GitHub then closes the pull request as merged on its own. `main` reaches every
-commit on `dev`, which is what GitHub reads as merged. The workflow pushes with
-`GITHUB_TOKEN`, so no credential sits at rest in this repository.
-
-GitHub offers no fast-forward merge. Its three options are a merge commit, a
-squash, and a rebase. Each one writes a commit to `main` that `dev` can never
-contain, and that commit forces a back-merge afterwards.
-
-Commits `ee41411` and `04602c7` are the last two the old flow cost. The open
-question was how to stop a person merging into `main`. `GITHUB_TOKEN` bypasses
-nothing, which rules out the usual answer.
-
-## Considered options
-
-A GitHub App can hold a bypass on a ruleset, so an App blocks the Merge button
-outright. We rejected it for two reasons. Its private key would sit in a
-repository secret and need rotating by hand, and this repository has one person
-in it.
-
-We rejected a fine-grained personal access token for two other reasons. It
-expires silently. Its bypass would also come from the owner's admin role, which
-leaves the Merge button open to the very person the rule binds.
-
-We chose `GITHUB_TOKEN`. Nothing sits in a secret, the token expires when the
-job ends, and GitHub scopes it to this repository.
-
-That choice rules out a bypass, so the block comes from somewhere else. It comes
-from a required check that no ordinary pull request ever gets: `promotion-gate`.
-Only `promote.yml` creates it.
-
-A pull request into `main` without the label is missing that check and cannot
-merge. `enforce_admins` extends that to admins. The workflow posts the check
-green immediately before it moves the ref, then flips it to failed if the push
-does not land.
-
-A personal repository could not have taken the App route anyway. The rulesets
-API rejects the GitHub Actions integration as a bypass actor. Classic branch
-protection rejects a bypass list outright.
-
-Both errors came from this repository, and `promote.yml` quotes both messages.
-
-## Consequences
-
-`main` stays an ancestor of `dev` by construction. The next promotion therefore
-fast-forwards too, and nothing is ever stranded on `main`.
-
-Three things follow as rules rather than preferences. No merge commit, squash,
-or rebase onto `main`. No cherry-pick onto `main`, since a new SHA makes the two
-graphs diverge for good.
-
-No back-merge of `main` into `dev` either. A fast-forward strands nothing there.
-
-The Merge button works for about a second per promotion. That is the gap between
-`promotion-gate` going green and the ref moving, inside a run an admin
-triggered. Pressing it there writes a merge commit to `main`, and the
-fast-forward then refuses and says so.
-
-The gate step therefore sits as late in the job as it can. Every new
-precondition belongs above it.
-
-A push made with `GITHUB_TOKEN` starts no workflow runs. `tag-release.yml` would
-never fire, and a promotion would tag nothing. `promote.yml` dispatches it
-explicitly through `workflow_dispatch`. GitHub documents that event as always
-creating a run.
-
-Nothing enforces that coupling. Add any future workflow that triggers on a push
-to `main` to the dispatch step by hand.
-
-`tag-release.yml` no longer compares `HEAD` against `HEAD~1`. A fast-forward
-carries every commit `dev` collected, so `HEAD~1` is the second-newest `dev`
-commit rather than `main`'s previous tip.
-
-Most of those commits leave the version alone, so the old comparison would read
-"unchanged" and skip the tag. The workflow now tags whatever version `main`
-holds, unless that tag already exists.
-
-The label that starts a promotion used to sabotage it. `version-gate.yml`
-triggers on `labeled` and `unlabeled`, so adding `promote-to-main` started a
-fresh `version-gate` run on the same commit.
-
-That run is pending while the promotion reads the checks and pushes, and branch
-protection refuses a push whose required check is pending. Removing and re-adding
-the label fired the gate twice more, so the advice for a stuck promotion made it
-permanent.
-
-`version-gate.yml` now skips every label event except `no-bump`. That is the one
-label which changes its verdict. A skipped job reports as passing, so the earlier
-green run still stands.
-
-`promote.yml` also waits up to ten minutes on a pending or absent check, rather
-than refusing it.
-
-The close step looks the gate up by name on the commit, not by the id the open
-step captured. A `POST` can land while `gh` still exits non-zero on a dropped
-response read. Trusting that id would leave the gate green and the pull request
-mergeable by hand.
-
-One hole stays open. A runner killed between the gate opening and the ref moving
-leaves `promotion-gate` green with no job left to close it. Close the pull
-request, or set that check run to `failure` by hand.
-
-An admin can still turn branch protection off in the repository settings. No
-configuration prevents that on any plan. This decision makes merging into `main`
-impossible, not repository administration.
-
-`promote.yml` names five CI checks by their `name:` values in `ci.yml`,
-`tests.yml`, and `version-gate.yml`. Rename a job in one place without the
-other, and every promotion blocks. The workflow says so when it happens.

package/docs/adr/0011-node-header-is-the-edge-encoding.md

@@ -1,20 +0,0 @@
-# The node body header is the authoritative edge encoding on GitHub
-
-Every map node on the GitHub tracker opens its body with one header line. It names the node's map, its root, its `answers` parent, its `blocked-by` ids, and its short `label`. Every composed query reads its edges from that line.
-
-The tracker still writes GitHub's native sub-issue and dependency links. Those links drive GitHub's own interface, and no query reads them.
-
-The header costs one `gh issue list` call to read the whole graph, because `body` is one of the fields that command returns.
-
-## Considered options
-
-- Read the edges from GitHub's native links. Rejected: the parent needs a GraphQL query and the blockers need a REST call, both per issue. A forty-node map would spend eighty calls on every frontier recompute.
-- Drop the native links and keep only the header. Rejected: the links render a map inside GitHub's own issue interface. That is half the reason to pick this tracker.
-- Give the files backend the same header. Rejected: its frontmatter already holds `answers` and `blocked-by`, and its directory name is the map. A header there would copy data the CLI owns, free to drift from it.
-
-## Consequences
-
-- One edge lives in two places on GitHub. The tracker doc states the dual write as a single step, for adding an edge and for removing one. A write that updates one copy alone leaves the two out of step.
-- A degraded remote, meaning one where GitHub's link features are off, now loses only the link interface. Every query keeps working. The tracker needs no second encoding and no per-map choice between them.
-- A reader landing on an issue from a notification sees which map it belongs to and what sits above it. The issue title alone never told them.
-- The two backends no longer share one body shape. A header line on GitHub, frontmatter on files.

package/docs/adr/0012-node-kind-is-a-closed-set-of-five.md

@@ -1,31 +0,0 @@
-# A map node's kind is a closed set of five
-
-A map node carries one `kind`. It is one of `destination`, `notes`, `decision`, `research`, or `work`.
-
-The CLI enforces the set with a zod enum. It rejects anything else at create, at update, and on reading a stored file. Before this, `kind` was free text that the CLI called advisory only.
-
-The five split in two. `destination` and `notes` are records rather than questions. `decision`, `research`, and `work` are things still to settle.
-
-The two records resolve differently. `notes` resolves the moment someone writes it. `destination` is the root, and it carries no status of its own.
-
-The root's state follows its subtree. It stays open while any node below it still needs work. `archive` resolves it when the map clears.
-
-Each has one test.
-
-- `destination` is the root, one per map
-- `notes` holds no question, and it binds every other node
-- `decision` has two or more defensible answers
-- `research` has one findable answer
-- `work` ends in a diff
-
-## Considered options
-
-- Keep `kind` free text and let the generated legend list only the kinds a map happens to contain. Rejected: `kind` now picks a node's shape in the map diagram, and an unknown value has no drawing.
-- Fix a set of six, to leave one slot spare. Rejected: every candidate sixth landed inside an existing kind. A bug is `work`, a spike is `research`, and a glossary term is a `decision` about what a word means.
-
-## Consequences
-
-- Five kinds map to five distinct mermaid shapes, so shape carries kind and the other channels are free for status, mode, and the frontier.
-- Every node must name a kind, and nothing can clear it. A node with no kind has no shape, so the field cannot be optional.
-- The enum rejects any map still carrying an older kind such as `grilling` or `task`. That is acceptable, because nodes are transient working state a map throws away at archive.
-- `kind` and `mode` will agree most of the time, and the disagreements are the point. A `decision` node marked `afk` draws as a dashed rhombus, which is an agent about to settle something that was the human's.

package/docs/adr/0013-the-diagram-renderer-is-pure.md

@@ -1,23 +0,0 @@
-# The diagram renderer takes nodes in and never calls gh
-
-`acstack node diagram` reads nodes and writes mermaid. It reads them from disk for a named map, or as JSON on stdin. It makes no network call and needs no authentication.
-
-On the GitHub backend the agent runs the pipe itself:
-
-```bash
-gh issue list --label "map:<name>" --state all --limit 500 \
-  --json number,title,body,state,stateReason,labels,url \
-  | acstack node diagram --stdin
-```
-
-## Considered options
-
-- Have the CLI run `gh issue list` itself behind a `--tracker github` flag. Rejected: the invocation would then live in both `cli/src/` and `skills/map/trackers/github.md`, and this repository's own rule is that one fact gets one home. It is also nicer for the agent, which is the whole case for it.
-- Give the CLI a real GitHub backend that speaks to the API. Rejected: far larger than this effort needs, and it would put authentication inside a renderer.
-
-## Consequences
-
-- The renderer's tests are JSON fixtures. No subprocess, no network, no token, and 59 tests run in the same suite as everything else.
-- Both backends reach one rendering path. One line branches on the backend, and the specification demands it: a node id wraps in an anchor when the node carries a URL.
-- The agent runs two commands instead of one. `skills/map/trackers/github.md` states the pipe verbatim, so nobody composes it from memory.
-- The CLI gained `readStdin`, because `readFileSync(0, 'utf-8')` fails with EAGAIN when a parent process hands over a non-blocking fd 0. An agent harness does exactly that.

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

@@ -1,29 +0,0 @@
-# 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

@@ -1,37 +0,0 @@
-# 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

@@ -1,21 +0,0 @@
-# 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

@@ -1,13 +0,0 @@
-# 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/0018-alignment-packs-use-local-viewers.md

@@ -1,11 +0,0 @@
-# Alignment packs use local viewers
-
-Alignment packs must not depend on a remote viewer or remote script. ACStack can open a generated pack in a local browser, including through a localhost server.
-
-## Considered options
-
-A pinned remote viewer keeps generated files smaller. It also makes review depend on network access and trust in a hosted script.
-
-## Consequences
-
-ACStack must inline or vendor the viewer code it needs. A Herdr-style terminal view can follow later if a clean graph viewer exists.

package/docs/adr/index.md

@@ -1,18 +0,0 @@
-- [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
-- [0018](0018-alignment-packs-use-local-viewers.md) – Alignment packs use local viewers