Skip to content

feat(adr): create from flags writes an accepted decision's files - #950

Open
austinborn wants to merge 3 commits into
mainfrom
feat/adr-create-writes-its-files
Open

austinborn wants to merge 3 commits into
mainfrom
feat/adr-create-writes-its-files

Conversation

@austinborn

@austinborn austinborn commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Summary

actual adr create --title … --policy … saves a decision to Actual AI but writes nothing to the repository, so a decision accepted from a terminal isn't enforced locally until Actual AI's sync pull request merges. Now an accepted save also writes its decision doc into docs/adr/ and its rule file into .actual/rules/, laid out as adr new writes them and named for the decision's id as the sync names them, so plan-check and impl-check enforce it at once and the sync later rewrites the same files. create --file is unchanged.

  • The pair goes at the top of the checkout from any directory in it. A directory with no working tree, such as .git, gets none.
  • A draft gets none, since the sync deletes a merged file named for a decision that doesn't govern.
  • With --repo, the files are written only when the checkout's origin remote names that repository.
  • An existing file is never replaced. When the pair can't be written, the save still succeeds and says why (files_problem in --json).
  • An accepted save must first pass the local save check adr new runs. A refusal exits 1 with the check's reasons before anything is sent.
  • The output says to commit both files, or delete them before pulling the sync's merge, which git won't apply over untracked copies.

The risk is confined to the flags path of create. --json gains three optional keys: decision_file, rule_file and files_problem.

Verification: none, no web app or SQL change (a CLI change)
The tests in the plan below cover the change.

Test plan, sample output and the overlap with #943 and #951

Test plan

  • cargo test --lib -- cli::commands::adr adr::: 189 passed. An accepted save writes both files with the decision's id and accepted in each header, after a draft save in the same checkout wrote none, and a second save onto those files leaves them untouched. From a subdirectory the pair goes to the top of the checkout and the output says to commit it or delete it before pulling, and from inside .git the save says it found no working tree. --repo writes only into a checkout of that repository, says so in a checkout of another one, and names the error when the connected repositories can't be read. An accepted save that the local check refuses (a policy over two lines) sends nothing and returns the check's reason. checkout_top finds the top from a subdirectory and returns nothing inside .git or outside a repository.
  • cargo llvm-cov --lib -- cli::commands::adr adr::: cli/commands/adr/cloud.rs 2154/2154, cli/commands/adr/mod.rs 373/373 and cli/commands/adr/local.rs 739/739 lines.
  • cargo fmt --check, cargo clippy -- -D warnings and cargo check --no-default-features --lib --bins: clean.
  • The full cargo test --workspace --features integration run is left to CI.

Sample output (from the tests)

✔ Saved "Use Postgres for storage" in actual-software/actual-cli as accepted: 33333333-3333-4333-8333-333333333333
Actual AI opens a pull request that writes its rule files.
  wrote <checkout>/docs/adr/33333333-3333-4333-8333-333333333333-use-postgres-for-storage.md
  wrote <checkout>/.actual/rules/cross-cutting-use-postgres-storage-3333.md
  Commit both files with the change they govern, or delete them before you pull once that pull request merges.

In a checkout of another repository:

  note: The decision was saved, but its files weren't written: this directory isn't a checkout of actual-software/actual-cli.

Overlap with #943 and #951

#943 (adr discover and create --all) and #951, stacked on it, edit cloud.rs and mod.rs too. This change leaves CreateOutcome, RenameOutcome and the two test helpers #943 touches as they are, since the flags path reports through its own FlagsOutcome. Trial merges with #943's head (47639f3) and #951's (5828301) are clean.


Generated by the operator's software factory.
• City: city · Agent: local-core__builder-ci-wisp-nphse1
• On behalf of: @austinborn

@austinborn
austinborn enabled auto-merge November 18, 2026 15:06

@backlineint backlineint left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1. Files are written under the current directory, not the repository root (cloud.rs, run_create)

On the flags path root is dir.to_path_buf(). origin_remote_url runs git remote get-url from that directory, which succeeds from any subdirectory of the checkout. Running create from src/ therefore writes src/docs/adr/… and src/.actual/rules/…. The sync writes at the repository root, so once its PR merges there are two copies of the rule: the stray subdirectory one and the root one. The hooks search ancestors, so both would be enforced. Suggested fix: resolve the git toplevel (git rev-parse --show-toplevel) for the pair. Alternatively, refuse with a files_problem when dir isn't the toplevel.

2. The local save check runs after the server has accepted the decision (cloud.rs, saved_pair)

The decision is saved first, and only then does check_document run. If the local check refuses a decision the server accepted, for example a policy over two lines, the user has an accepted decision in Actual AI that isn't enforced locally. create_from_flags_writes_no_file_the_save_check_refuses pins this behavior. Suggested fix: for accepted saves, run check_document before the request and either fail early or warn. If the gap is deliberate, docs/ADR_COMMANDS.md should say that a server-valid decision can still end up without local files.

@benw5483 benw5483 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: from a subdirectory, the pair lands outside the paths the sync manages, and outlives the decision

Changed code: cloud.rs:313, cloud.rs:460

Evidence: For a create from flags, root is the current directory (None => dir.to_path_buf()), and write_pair joins docs/adr/ and .actual/rules/ onto it. The repository check doesn't catch a subdirectory: pick_repo reads git remote get-url origin, which git answers from anywhere inside the checkout, and the --repo check at line 445 does the same. A test run from src/ of a checkout of actual-software/actual-cli saved an accepted decision and wrote src/docs/adr/33333333-…-use-postgres-for-storage.md and src/.actual/rules/cross-cutting-use-postgres-storage-3333.md. load_rule_set on the checkout root then read 0 rule documents, and on src/ it read 1.

The sync manages only the root-level paths: MANAGED_ROOTS is .actual/rules and docs/adr (ruleFile.ts:135-137).

Impact: The PR's central promise, that the sync's pull request rewrites these same two files, holds only at the checkout root. From a subdirectory (common in a monorepo, and in an agent shell that has cd'd somewhere), the person gets:

  • a rule that root-level checks don't read until the sync PR merges, though the output says it was written;
  • a second pair at the root once the sync PR merges;
  • a subdirectory copy that the sync never updates or deletes. A check run from that subdirectory keeps enforcing it after the decision is edited, unpublished or archived.

Fix: For the flags path, write under the checkout's top level rather than the current directory. impl_check::checkout_root (impl_check.rs:599) already resolves it for hooks started in a subdirectory. The other option is to refuse with a files_problem when the current directory isn't the top level. Either way, ADR_COMMANDS.md item 6 ("They go into the directory the command runs in") and the CHANGELOG line need to match. A test that runs run_create from a subdirectory would pin it.

P3: a person who doesn't commit the pair can't pull the sync's merge

Changed code: cloud.rs:704, docs/ADR_COMMANDS.md:102

Evidence: The pair is written as untracked files, and the output says "Actual AI opens a pull request that writes its rule files", then lists the two paths. Nothing says to commit them. When the sync PR merges and the person runs git pull, git refuses to overwrite untracked files at the incoming paths, even when the bytes are identical. With git 2.50.1, an identical untracked .actual/rules/x.md stopped the pull with "The following untracked working tree files would be overwritten by merge … Aborting".

Impact: Every accepted create from a terminal leaves this in place by default. The way out is easy once someone reads git's message, which is to delete the two files and pull again. create --file's renamed pair has the same shape today. This PR makes it the normal path for flags.

Fix: One line in the output and in item 6: commit the two files with the change they govern, or delete them before pulling once the sync PR merges.

@austinborn
austinborn force-pushed the feat/adr-create-writes-its-files branch from f349428 to 7e11087 Compare November 18, 2026 16:23
@austinborn

Copy link
Copy Markdown
Contributor Author

@backlineint thanks for the review. Both points are fixed in 7e11087.

1. Files under the current directory. I took your first suggestion. The pair now goes at the top of the checkout (git rev-parse --show-toplevel), wherever in the checkout create runs, which is where the sync writes it, so a run from src/ no longer leaves a second copy for the hooks to enforce. A directory with no working tree, such as .git, still saves the decision and says its files weren't written. create_from_flags_writes_the_pair_at_the_top_of_the_checkout covers both cases. adr new still writes where it runs (or under --root), and I left it alone here. A pair it writes in a subdirectory can still end up beside the sync's copy once create --file renames it to the decision's id, which may want a change of its own.

2. The local save check ran after the save. I took the fail-early fix. An accepted save from flags now runs the local save check before anything is sent, and a decision it refuses exits 1 with the check's reasons, the same check and wording adr new uses, so nothing is saved. create_from_flags_sends_no_accepted_decision_the_save_check_refuses replaces the test that pinned the old order. Drafts and --file saves keep their current path, since no files follow them. docs/ADR_COMMANDS.md and the CHANGELOG entry describe both changes.

@benw5483's review added one more point, which bdc162c covers: create now says to commit the two files, or delete them before pulling the sync's merge.


Posted by the operator's software factory.
• City: city · Agent: local-core__builder-ci-wisp-nphse1
• On behalf of: @austinborn

@austinborn

Copy link
Copy Markdown
Contributor Author

@benw5483 thanks. Both points are fixed.

P2, the pair under a subdirectory. Fixed in 7e11087, together with @backlineint's first point. The pair goes at the top of the checkout from any directory inside it, and create_from_flags_writes_the_pair_at_the_top_of_the_checkout runs run_create from src/ to pin it. ADR_COMMANDS.md item 6 and the CHANGELOG line now say so. I looked at reusing impl_check::checkout_root, but it falls back to the directory itself outside a working tree. That suits the hook's path comparison, but here it would write the pair into .git or a bare repository. #945 also changes that function's signature line, so splitting it would collide with your branch. create has its own small lookup instead, checkout_top in adr/mod.rs. It returns nothing outside a working tree, which create reports as a files_problem, and it waits at most five seconds for git, like the origin-remote read beside it.

P3, pulling the sync's merge over untracked files. Fixed in bdc162c as you suggested. After the two wrote lines, create now prints "Commit both files with the change they govern, or delete them before you pull once that pull request merges." Item 6 says the same and gives the reason. git 2.43 also aborts the pull over an identical untracked file. create --file's renamed pair has the same shape, as you noted. I left its output alone because that behaviour predates this PR, and I can add the same line there if you'd like it in this one.


Posted by the operator's software factory.
• City: city · Agent: local-core__builder-ci-wisp-nphse1
• On behalf of: @austinborn

benw5483
benw5483 previously approved these changes Nov 18, 2026
…om flags

`actual adr create --title … --policy …` saved the decision and wrote nothing locally. An accepted save now writes its decision doc into docs/adr/ and its rule file into .actual/rules/, laid out as `adr new` writes them and named for the new decision's id as Actual AI's sync names them, so plan-check and impl-check enforce it at once and the sync's pull request rewrites those same files.

A draft gets no files, because the sync deletes a merged file named for a decision that doesn't govern. With --repo, the files are written only when the directory's origin remote names that repository. An existing file is never replaced. Any reason the pair wasn't written shows as a note, or as files_problem in --json, and the command still succeeds, since the decision is saved.

City: city · Agent: local-core__builder-ci-wisp-z8zi1o
…efore the save

From a subdirectory, an accepted `adr create` from flags wrote its pair under that directory, so once the sync's pull request merged, its copy at the repository root would sit beside a stray one that the hooks enforce too. The pair now goes at the top of the checkout (`git rev-parse --show-toplevel`), and a directory with no working tree, such as `.git`, gets a files_problem.

The local save check ran only after Actual AI had saved the decision, so a refusal there left an accepted decision with no local files. It now runs before anything is sent, and an accepted save it refuses exits 1 with its reasons, as `adr new` does.

City: city · Agent: local-core__builder-ci-wisp-nphse1
… the sync

The pair is written untracked, and git won't merge the sync pull request over untracked files at the same paths, even identical ones, so `git pull` aborts. create's output and docs/ADR_COMMANDS.md item 6 now say to commit both files with the change they govern, or delete them before pulling once that pull request merges.

City: city · Agent: local-core__builder-ci-wisp-nphse1
@austinborn

Copy link
Copy Markdown
Contributor Author

Rebased onto main at e25b639 to clear the CHANGELOG.md conflict from #954, which merged the two [Unreleased] "Changed" headings. #945 landed after that and is in the new base as well. The code and docs are unchanged: each commit keeps its patch-id, and the diff outside CHANGELOG.md is byte-identical to the one reviewed. CHANGELOG.md keeps main's [Unreleased] text as it is, with this PR's adr create line in the single "Changed" list where it sat before.

The commits cited in the replies above are now:

Before After
6880996 53de2ac
7e11087 1f3f957
bdc162c 786627f

On 786627f, cargo fmt --check, cargo clippy -- -D warnings, the --no-default-features check and clippy, and cargo test --workspace --features integration (5,585 passed) all ran clean locally, and CI is green. GitHub dismissed the approval given on bdc162c when the branch was force-pushed.


Posted by the operator's software factory.
• City: city · Agent: local-core__builder-ci-wisp-o3maiz
• On behalf of: @austinborn

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants