Repository navigation
docs: add decisions under docs/adr/ and sign in right after install - #948
Conversation
The README and Getting Started send new decisions to docs/adr/ through `actual adr new` or the pull request app.actual.ai opens, both of which write the rule file the checks read beside the decision. The hand-written rule-file example goes, since a decision typed into docs/adr/ by hand has no rule file and is never checked. Optional sign-in moves to the step right after installation. actual.ai/cli/docs is now a short quick start rather than a command reference, so the README and How It Works point at this repository's docs for the commands. City: city · Agent: local-core__builder-ci-wisp-1m3hdz
benw5483
left a comment
There was a problem hiding this comment.
P3: the original rule-file format is no longer documented anywhere
Changed code: README.md:51-61 (the section that replaces the ### Rules example)
Evidence: The README example was the only place that showed a rule file's body: a title, a sentence on where the rules apply, and a ### Rules list of **ID** LEVEL: statement lines. The CLI still reads that format with or without a v2 header. A hand-written file in exactly the removed shape, dropped into .actual/rules/ on 0.14.0, lists in actual rules ls as api-error-handling: MUST 1 · MUST_NOT 1 and is enforced. The docs still point at the format without defining it: HOW_IT_WORKS.md:83 says "files without one work as before", line 109 says "or the original format", and docs/SCOPE_INDEX.md:76 says the same. docs/ADR_COMMANDS.md names a "### Rules list with one rule per policy" but not the line syntax.
Impact: Teams that already keep hand-written rule files (the README's documented path until this PR) lose their only reference for the ID and level syntax. Someone editing a synced rule file by hand has nothing to check it against either. The PR's reasoning holds for decisions: a file typed into docs/adr/ by hand has no rule file and is never checked. It doesn't cover rule files written directly.
Fix: Keep the example, moved out of the quick start. One option is a collapsed "Writing a rule file by hand" block under Governance in HOW_IT_WORKS, which line 83 can then link to.
P3: the new step doesn't say to run actual adr new from the repository root
Changed code: README.md:53, docs/GETTING_STARTED.md:131
Evidence: adr new writes relative to the current directory (--root defaults to it, as docs/ADR_COMMANDS.md:42 says). Running the README's command from src/ with 0.14.0 at a terminal wrote src/docs/adr/<id>-use-grpc-internally.md and src/.actual/rules/cross-cutting-use-grpc-internally-<hash>.md, then printed "It is accepted, so plan-check and impl-check enforce it now." actual rules ls at the repository root doesn't list that rule.
Impact: This PR makes adr new the first way the docs offer to add a decision, and the text says it writes the decision "there", meaning docs/adr/. Someone whose shell is in a subdirectory gets a decision that is never checked from the root, along with a message saying it's enforced.
Fix: Add "from your repository root" to both sentences, or mention --root. The misleading success message is CLI behaviour and out of scope here.
backlineint
left a comment
There was a problem hiding this comment.
Intent is clear, and the README and Getting Started changes match docs/ADR_COMMANDS.md. Two things to fix and one to track.
1. Duplicate ### Changed heading in Unreleased (CHANGELOG.md, ~line 19)
Unreleased already has a ### Changed section with two bullets, and this PR adds a second ### Changed heading below it. Keep a Changelog expects one heading per type per release. Please append the new bullet to the existing section.
2. The draft caveat doesn't say how to make a draft accepted (README.md and docs/GETTING_STARTED.md, "Adding decisions")
Both say a draft written from an agent's shell is read by no check "until its status is accepted", but neither says how to make it accepted. Someone running this from an agent shell ends up with a rule that never fires and no pointer to the fix. Please name the step, such as --status accepted at creation or editing the status in the file's header, whichever is correct.
3. Follow-up for the repeated README sentence (README.md, paragraph after "Adding decisions")
That paragraph opens with "actual adr new writes a decision and its rule file from the terminal…", which now repeats the new section. The PR description defers this until #943 lands. Please track it, for example with a follow-up issue, so it isn't forgotten.
|
Follow-up to this review: #954 makes the first two changes. Unreleased keeps one The third point, the repeated
|
Summary
The README and Getting Started now send people to
docs/adr/for their architecture decisions, through the two paths that also write the rule file the checks read:actual adr newfrom their own terminal, or the pull request app.actual.ai opens. The hand-written rule-file example comes out: a decision typed intodocs/adr/by hand has no rule file, so it's never checked..actual/rules/now shows up only where the docs say what the checks read.Optional sign-in moves to the step right after installing the plugin and the CLI, in both files. actual.ai/cli/docs is now a short quick start, so the README drops its "Command reference" link and How It Works points at Getting Started's command list. A changelog bullet under Unreleased records the change.
actual adr newfirst shipped in 0.14.0, which is out on GitHub, npm and Homebrew, so nothing holds the merge. It's Markdown only, so the risk is low. The README paragraph on theactual adrcommands stays byte-identical because #943 rewrites it (this branch merges cleanly with #943). Once both land, that paragraph's first clause repeats the new step, and it'd be worth trimming then.Test plan and supporting detail
Test plan
docs/adr/<id>-use-postgres-for-storage.mdand.actual/rules/cross-cutting-use-postgres-storage-<hash>.mdwithstatus: accepted, andactual rules lslisted one enforcedMUSTrule. With standard input not a terminal, as in an agent's shell, it wrote the same pair withstatus: draftand printed "It is a draft, which no check reads until its status is accepted";rules lsmarked the rule "draft, not enforced".actual adrfirst ships in v0.14.0, published 2026-11-16 on the GitHub release (four archives,SHA256SUMSand its signature), as npmlatestand in the Homebrew formula. v0.13.0's argument parser has noadrsubcommand, so the docs name 0.14.0 beside the command.#adding-rulesanchor, in Getting Started, went with the paragraph it sat in, and no link in this repository or in actual-skill points at a README anchor. One broken anchor predates this branch, indocs/CHECK_OVERRIDE_HOOK.md.git merge-treeagainst all 13 open pull requests that touch these four files: fix(adr-bot): keep config changes made while a run is in progress #923, fix(adr-bot): stop the nav poller while a TUI prompt reads keys #924, feat(auth): whoami --check asks the server whether the sign-in works #914, feat(rules): split the judge verdict conforming into followed and not_applicable #940 and feat(adr): add adr discover and adr create --all #943 merge cleanly with this branch, as they do with main. feat(advisor): stream the answer over SSE instead of polling #797, Add ARCHITECTURE.md: agent-facing reference doc #812, feat(cli): judge a diff too big for one prompt in parts #869, feat(rules): score false injection and a full-corpus model arm in rules eval #913, feat(hooks): add --codex-hook modes for Codex #930, feat(telemetry): send each judged ADR's verdict on actual.adr.detected #941, feat(telemetry): local debug log of every event sent (ACTUAL_TELEMETRY_DEBUG=1) #944 and feat(rules): ask the agent which ADRs it used each turn, and check its answer #945 already conflict with main, and this branch adds no conflict to any of them.Not exercised
The sync pull request from app.actual.ai writes the same two files for each accepted decision, as
docs/ADR_COMMANDS.mddescribes; that path wasn't run for this change.