Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(decisions): let agents record decisions as themselves and teach the review flow (#4672)

Raghav Chamadiya9463eed68a76
diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md
index ea7461901..9672b514b 100644
--- a/docs/architecture/ARCHITECTURE.md
+++ b/docs/architecture/ARCHITECTURE.md
@@ -1060,7 +1060,7 @@ are flagged as stale.
repowise decision add # interactive capture
repowise decision list # tabular list with filters
repowise decision show <id> # full detail
-repowise decision confirm # proposed → active
+repowise decision confirm <id> # candidate → accepted
repowise decision dismiss # dismiss proposed (sticky tombstone)
repowise decision deprecate # active → deprecated
repowise decision health # health summary
diff --git a/docs/layers/DECISIONS.md b/docs/layers/DECISIONS.md
index c23514b8a..7445ee374 100644
--- a/docs/layers/DECISIONS.md
+++ b/docs/layers/DECISIONS.md
@@ -158,6 +158,7 @@ repowise decision add --title T --decision D [--affects PATH ...] # no prompts
| `--affects`, `--tag` | A file or module it governs; a tag. Repeatable |
| `--evidence-commit` | A commit the decision was made in. Repeatable |
| `--kind` | `architectural` (default) or `agreement` |
+| `--agent`, `--session` | Record it as this agent's (source `agent`), with its session id. Needs the flags |
| `--format json` | Machine-readable output with the full id |
What gets stored depends on how you add it:
@@ -168,6 +169,9 @@ What gets stored depends on how you add it:
- Flags (`--title` and `--decision`) store a candidate (`proposed`). A person
answering the prompts has reviewed the decision; a script or agent inferring
one has not. Promote it with `repowise decision confirm ID`.
+- `--agent SLUG` marks a candidate an agent reasoned out itself. Unlike a
+ person's manual entry, accepting it needs an evidence reference
+ (`--evidence-commit` on add, or `--evidence` on confirm).
- `--kind agreement` records a rule about how the work is done ("never push
without review"). It governs the whole repository, needs no files, and
reaches an agent at session start.
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index dde523945..569e52d06 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -950,6 +950,7 @@ repowise decision list
repowise decision show ID
repowise decision add # interactive
repowise decision add --title T --decision D # no prompts, lands proposed
+repowise decision add --agent SLUG --title T --decision D --rationale R --affects PATH # an agent's own record
repowise decision candidates # awaiting review; these govern nothing
repowise decision confirm ID... # accept: this makes them govern
repowise decision dismiss ID... # tombstone (sticky; never re-proposed)
@@ -990,6 +991,8 @@ Every subcommand takes `--format` (`table` default, or `json`) and an optional `
| `--tag` | Tag. Repeatable. | |
| `--evidence-commit` | Commit it was made in. Repeatable. | |
| `--kind` | `architectural` governs code; `agreement` governs how work is done (no files, never checked against code). | `architectural` |
+| `--agent` | Record as this agent's (source `agent`, e.g. `claude_code`); acceptance then needs evidence. | |
+| `--session` | The agent session recording it. Needs `--agent`. | |
- `--title` plus `--decision`: no prompts, prints the new id. Any flag, or `--format json`, without both is refused.
- Flag-driven records land `proposed`, interactive `active`; promote with `repowise decision confirm <id>`.
diff --git a/packages/claude-mod/src/model/events.ts b/packages/claude-mod/src/model/events.ts
index 7ba3e07d1..87c867be6 100644
--- a/packages/claude-mod/src/model/events.ts
+++ b/packages/claude-mod/src/model/events.ts
@@ -33,9 +33,9 @@ const STANDING = /^\[repowise\] .+? is governed by a standing decision: (.+?)(?:
const MINED = /^\[repowise\] .+? has a decision recorded in it, mined but not reviewed: (.+?)(?: because .*)?\.$/;
const FIXES = /^\[repowise\] .+? has been bug-fixed (\d+)x in the last 6 months, last (.+?)(?: \(bug magnet\))?(?:; mostly in (.+?))?\.$/;
-/** Each "(confirmed across N sessions)" tail is the hook's; the title is what Lens shows. */
+/** Each "(seen in N sessions)" tail is the hook's; the title is what Lens shows. Older hooks wrote "confirmed across". */
function stripConfirmed(line: string): string {
- return line.replace(/ \(confirmed across \d+ sessions\)\.$/, ".");
+ return line.replace(/ \((?:seen in|confirmed across) \d+ sessions\)\.$/, ".");
}
/**
diff --git a/packages/claude-mod/test/margin.test.ts b/packages/claude-mod/test/margin.test.ts
index da9bee578..76f4f61c0 100644
--- a/packages/claude-mod/test/margin.test.ts
+++ b/packages/claude-mod/test/margin.test.ts
@@ -87,7 +87,7 @@ describe("notesFromAugment", () => {
expect(notesFromAugment([fixLine])).toEqual([{ kind: "fixes", count: 5, age: "2 weeks ago", symbol: "run_pipeline" }]);
});
- const standing = "[repowise] a.py is governed by a standing decision: Keep the cache bounded because memory is finite (confirmed across 3 sessions).";
+ const standing = "[repowise] a.py is governed by a standing decision: Keep the cache bounded because memory is finite (seen in 3 sessions).";
it("reads a standing decision without its rationale or confirmation tail", () => {
expect(notesFromAugment([standing])).toEqual([{ kind: "decision", reviewed: true, title: "Keep the cache bounded" }]);
diff --git a/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-decision.md b/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-decision.md
index 67ed73f44..49856e000 100644
--- a/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-decision.md
+++ b/packages/cli/src/repowise/cli/agent_targets/_data/codex_prompts/repowise-decision.md
@@ -31,22 +31,31 @@ unless the repository turns it on.
(`--format json` to parse it back), which is the form to use with no terminal.
The rest are optional: `--context`, `--rationale`, `--alternative`,
`--consequence`, `--affects`, `--tag`, `--evidence-commit`, the last five
- repeatable. A flag-driven record lands `proposed` for a person to `confirm`.
+ repeatable. A flag-driven record lands as a candidate for review; it never
+ governs until accepted. An agent recording a choice it reasoned out passes
+ `--agent <slug>` (e.g. `claude_code`, plus `--session <id>` if known) so the
+ record is the agent's, not a person's.
**Always state a reason** — pass `--rationale` (or `--context`); a record whose
body only restates its own title cannot be accepted. `--kind agreement` records
a working agreement: a rule about how the work is conducted, which names no
file and is not checked against the code. `--evidence-commit <sha>` ties the
record to the commit the choice was made in.
-- **confirm** — `repowise decision confirm` — review decisions auto-proposed from
- git history and accept or reject them.
+- **candidates** — `repowise decision candidates --format json` — records
+ awaiting review, each with its id and the `blockers` that stop it being accepted.
+- **confirm** — `repowise decision confirm <id>...` — accept candidates so they
+ govern. `--reason`, `--scope <path>` and `--evidence <commit|file|link>` fill
+ the blockers. An agent signs with `--agent <slug>`, which works only where
+ the repository has run `repowise decision config agent-acceptance --on`;
+ otherwise leave acceptance to a person.
- **deprecate / dismiss** — `repowise decision deprecate <id>` (optionally
- `--superseded-by <id>`) or `repowise decision dismiss <id>`.
+ `--superseded-by <id>`) or `repowise decision dismiss <id> --reason ...`.
+ An agent passes `--agent <slug>` here too.
## Notes
- For *querying* why code looks the way it does mid-task, prefer the `get_why`
MCP tool (the `architectural-decisions` skill) — it returns lineage and an
alignment score. This command is for *managing* the decision records themselves.
-- `confirm` is interactive, and so is `add` unless you pass `--title` and
- `--decision`; tell the user when a step needs their input.
+- `add` is interactive unless you pass `--title` and `--decision`; the other
+ subcommands take ids and flags and never prompt, except `dismiss` (pass `--yes`).
- If unsure of an exact subcommand or flag, run `repowise decision --help`.
diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/decision_inject.py b/packages/cli/src/repowise/cli/commands/augment_cmd/decision_inject.py
index d19ca1797..62d46e810 100644
--- a/packages/cli/src/repowise/cli/commands/augment_cmd/decision_inject.py
+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/decision_inject.py
@@ -585,12 +585,13 @@ _ACCEPTED_HEADER = (
"(accumulated from prior sessions; follow them unless the user says otherwise):"
)
-#: Candidates are mined, not agreed. The header carries the whole of that
+#: Candidates are proposed, not agreed. The header carries the whole of that
#: distinction in the transcript, so it says it in words rather than leaving an
-#: agent to infer a lane from a blank line.
+#: agent to infer a lane from a blank line. Source-neutral: candidates come
+#: from PRs, commits, comments and agents as well as sessions.
_CANDIDATE_HEADER = (
- "[repowise] Proposed but NOT accepted - mined from prior sessions and "
- "awaiting review. Weigh these; do not treat them as rules:"
+ "[repowise] Candidate decisions awaiting review, NOT accepted; weigh them, "
+ "do not treat them as rules. Review: repowise decision candidates"
)
@@ -849,7 +850,7 @@ def _edit_decision_notice(repo_path: Path, rel: str, session_id: str, state: dic
if why:
line += f" because {why}"
if sessions_n >= 2:
- line += f" (confirmed across {sessions_n} sessions)"
+ line += f" (seen in {sessions_n} sessions)"
line += "."
if session_id:
diff --git a/packages/cli/src/repowise/cli/commands/decision_batch.py b/packages/cli/src/repowise/cli/commands/decision_batch.py
index abe23dd98..463ce0de8 100644
--- a/packages/cli/src/repowise/cli/commands/decision_batch.py
+++ b/packages/cli/src/repowise/cli/commands/decision_batch.py
@@ -20,14 +20,22 @@ from repowise.cli.output import emit_json, emit_refusal
async def _open_store(repo_path: Path):
"""Yield a session factory on the repo's store; the engine is disposed after.
- A factory, so ``add`` can embed after its session commits.
+ A factory, so ``add`` can embed after its session commits. A locked or
+ unreadable store is reported as one line, not a SQL traceback.
"""
+ from sqlalchemy.exc import OperationalError
+
from repowise.core.persistence import create_engine, create_session_factory, init_db
engine = create_engine(get_db_url_for_repo(repo_path))
try:
await init_db(engine)
yield create_session_factory(engine)
+ except OperationalError as exc:
+ raise click.ClickException(
+ f"Could not use the index at {repo_path}: {exc.orig}. "
+ "If `repowise update` is running, retry once it finishes."
+ ) from exc
finally:
await engine.dispose()
@@ -97,15 +105,27 @@ class _PreviewRollbackError(Exception):
_ID_SHAPED = re.compile(r"[0-9a-fA-F]{4,64}\Z")
+def _require_ids(ids: list[str], verb: str, fmt: str) -> None:
+ """Refuse a run that names no decision, pointing at where ids come from."""
+ if not ids:
+ emit_refusal(
+ "no_decision_ids",
+ f"Name the decision ids to {verb}.",
+ fmt,
+ remedy="List candidates and their ids with `repowise decision candidates`.",
+ )
+
+
def _split_ids_and_path(tokens: tuple[str, ...]) -> tuple[list[str], str | None]:
"""Separate decision ids from the optional trailing repo path.
``confirm ID [PATH]`` shipped before batch arity, so the path is still a
positional. An id-shaped last token stays an id even when a directory of
that name happens to exist, because reading one as a path would drop it
- from the batch and still exit 0.
+ from the batch and still exit 0. A lone directory is the path, so
+ ``confirm .`` reports that no id was named rather than an unknown id.
"""
- last = tokens[-1] if len(tokens) > 1 else ""
+ last = tokens[-1] if tokens else ""
# An empty token would otherwise read as the current directory.
if last and not _ID_SHAPED.match(last) and Path(last).is_dir():
return list(tokens[:-1]), last
diff --git a/packages/cli/src/repowise/cli/commands/decision_cmd.py b/packages/cli/src/repowise/cli/commands/decision_cmd.py
index aa4a3ef7c..527303e77 100644
--- a/packages/cli/src/repowise/cli/commands/decision_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/decision_cmd.py
@@ -18,6 +18,7 @@ from repowise.cli.commands.decision_batch import (
_emit_lifecycle,
_emit_single,
_open_store,
+ _require_ids,
_resolve_decision_id,
_review_batch,
_split_ids_and_path,
@@ -269,6 +270,7 @@ class _DecisionFields:
show_default=True,
help="'architectural' governs the code; 'agreement' governs how the work is done.",
)
+@_signing_options
@format_option()
def decision_add(
path: str | None,
@@ -282,6 +284,8 @@ def decision_add(
tags: tuple[str, ...],
evidence_commits: tuple[str, ...],
kind: str,
+ agent: str,
+ agent_session: str,
fmt: str,
) -> None:
"""Add a decision, interactively or from flags.
@@ -296,13 +300,18 @@ def decision_add(
A person answering eight questions has reviewed the decision; a caller
inferring one from a diff has not, and the store should be able to tell
them apart. Promote with `repowise decision confirm <id>`.
+
+ `--agent <slug>` records the decision as that agent's (source `agent`),
+ so review can tell it from one a person typed. It needs the flags.
"""
+ signer = _signer(agent, agent_session)
non_interactive = bool(title and decision_text)
if not non_interactive:
_refuse_partial_flags(
fmt,
title, context, decision_text, rationale,
alternatives, consequences, affected, tags, evidence_commits,
+ agent, agent_session,
)
repo_path = _resolve_decision_repo(path, fmt)
@@ -325,7 +334,7 @@ def decision_add(
fields = _prompt_decision_fields(kind)
decision_id, stored_status = run_async(
- _persist_decision(repo_path, fields, status, list(evidence_commits))
+ _persist_decision(repo_path, fields, status, list(evidence_commits), signer)
)
if stored_status != "active" and not non_interactive:
console.print(
@@ -426,7 +435,11 @@ def _prompt_decision_fields(kind: str) -> _DecisionFields:
async def _persist_decision(
- repo_path: Path, fields: _DecisionFields, status: str, evidence_commits: list[str]
+ repo_path: Path,
+ fields: _DecisionFields,
+ status: str,
+ evidence_commits: list[str],
+ signer: _Signer,
) -> tuple[str, str]:
"""Write the record, accept it when the prompts earned that; return id and status."""
from repowise.core.persistence import get_session, upsert_decision, upsert_repository
@@ -452,9 +465,12 @@ async def _persist_decision(
# asks again next session for a commit already recorded.
evidence_commits=evidence_commits,
kind=fields.kind,
- source="cli",
+ # Not ``cli``: an agent's record gets no self-authored evidence
+ # exemption at acceptance.
+ source="agent" if signer.agent else "cli",
# No confidence: upsert_decision scores a manual entry.
)
+ await _note_agent_signer(session, rec, signer)
# An architectural decision needs files to govern, so without them
# it stays a candidate for ``confirm --scope``. An agreement names no
# file by definition; its scope is the repository.
@@ -470,6 +486,19 @@ async def _persist_decision(
return embed[0], stored_status
+async def _note_agent_signer(session, rec, signer: _Signer) -> None:
+ """Keep who proposed an agent's record in its review row; the record has no column for it.
+
+ A restated record keeps its first source, so only an agent's own is noted.
+ """
+ from repowise.core.persistence.crud.authority import upsert_candidate_meta
+
+ if signer.agent and rec.source == "agent":
+ await upsert_candidate_meta(
+ session, rec, grounding={"agent": signer.agent, "session": signer.session}
+ )
+
+
async def _accept_answered_prompts(session, rec, repo_path: Path) -> None:
"""Record the answered prompts as an acceptance, like any other."""
from repowise.core.analysis.decisions.accepter import resolve_accepter
@@ -817,7 +846,7 @@ _ACCEPT_REMEDY = "Supply the missing parts with --reason, --scope or --evidence.
@decision_group.command("confirm")
[email protected]("decision_ids", nargs=-1, required=True)
[email protected]("decision_ids", nargs=-1)
@click.option("--reason", default="", help="Rationale, or why the constraint needs none.")
@click.option(
"--scope",
@@ -863,6 +892,7 @@ def decision_confirm(
unless ``decision config agent-acceptance`` is on for this repository.
"""
ids, path = _split_ids_and_path(decision_ids)
+ _require_ids(ids, "accept", fmt)
repo_path = _resolve_decision_repo(path, fmt)
signer = _signer(agent, agent_session, accepter=accepter)
@@ -900,7 +930,7 @@ def decision_confirm(
@decision_group.command("dismiss")
[email protected]("decision_ids", nargs=-1, required=True)
[email protected]("decision_ids", nargs=-1)
@click.option("--yes", "-y", is_flag=True, default=False, help="Skip the confirmation prompt.")
@click.option("--reason", default="", help="Why it was tombstoned.")
@_signing_options
@@ -922,6 +952,7 @@ def decision_dismiss(
Takes one id or many, and an optional repository path after them.
"""
ids, path = _split_ids_and_path(decision_ids)
+ _require_ids(ids, "dismiss", fmt)
repo_path = _resolve_decision_repo(path, fmt)
signer = _signer(agent, agent_session)
diff --git a/packages/core/src/repowise/core/analysis/attention/compose.py b/packages/core/src/repowise/core/analysis/attention/compose.py
index d5604a337..b6a93bd4b 100644
--- a/packages/core/src/repowise/core/analysis/attention/compose.py
+++ b/packages/core/src/repowise/core/analysis/attention/compose.py
@@ -91,6 +91,13 @@ SOURCE_RANK: dict[str, int] = {
#: display length.
PER_SOURCE_CAP = 8
+#: How a proposed decision's description names who proposed it; any other
+#: source is a pipeline proposal.
+_PROPOSED_DESCRIPTIONS: dict[str, str] = {
+ "cli": "Decision recorded by hand, awaiting review",
+ "agent": "Decision recorded by an agent, awaiting review",
+}
+
#: How much an item matters *within* its own source, for breaking ties inside a
#: severity band. Comparable only against its own kind — a health finding's
#: impact and a drift finding's confidence are not the same quantity — which is
@@ -133,7 +140,8 @@ class DecisionAttentionInput:
producer without one passes the stale lane in whatever order it trusts.
``source`` is the record's provenance (see ``SOURCE_RANK``): ``"cli"`` is a
- human-authored manual entry, everything else is a pipeline proposal. Only
+ human-authored manual entry, ``"agent"`` an agent's own record, everything
+ else is a pipeline proposal. Only
the proposed lane reads it — the wording of the description differs.
"""
@@ -229,10 +237,8 @@ def decision_source(
"id": f"proposed-{d.id}",
"type": "proposed_decision",
"title": d.title,
- "description": (
- "Decision recorded by hand, awaiting review"
- if d.source == "cli"
- else "Auto-proposed decision awaiting review"
+ "description": _PROPOSED_DESCRIPTIONS.get(
+ d.source, "Auto-proposed decision awaiting review"
),
"severity": "medium",
"target_id": d.id,
diff --git a/packages/core/src/repowise/core/generation/templates/_editor_block.j2 b/packages/core/src/repowise/core/generation/templates/_editor_block.j2
index 857f4ab68..eb0eb452c 100644
--- a/packages/core/src/repowise/core/generation/templates/_editor_block.j2
+++ b/packages/core/src/repowise/core/generation/templates/_editor_block.j2
@@ -70,7 +70,7 @@ Fix first:
- **A zero carries its basis.** An empty `callers`/`callees`/`used_by` comes with a `*_basis` saying how much of that language's calls the graph resolved, so read it before concluding nothing calls a symbol. On `get_answer`, `_meta.scope_hint` names the areas the answer did not touch.
- **Pre-edit, not instead-of-edit.** These tools decide *which* files to read and edit. {{ read_note }}
- **Noisy commands** (tests, builds, `git log`/`diff`, searches, listings): prefer `repowise distill <cmd>`, the same command with its exit code preserved and errors-first output. A `[repowise#<ref>: N lines omitted]` marker is recoverable via `repowise expand <ref>` (add `-q <regex>` to filter); never re-run the command to see omitted output.
-- **Recording a decision** you had to reason out: `repowise decision add --title T --decision D` records it without prompting and prints the id (`--format json` to parse it back). It lands `proposed`, for a person to confirm.
+- **Recording a decision** you had to reason out: `repowise decision add --agent <your slug> --title T --decision D --rationale '<why, what you rejected>' --affects <path>` records it without prompting and prints the id (`--format json` to parse it back); the slug names you, e.g. `claude_code`. It lands as a candidate for review and never governs until accepted; `repowise decision candidates` lists what each candidate still needs.
{% elif 'how_to_work' in s %}
### How to work in this repo
@@ -80,7 +80,7 @@ Fix first:
- **No model on this index.** `get_answer` replies are low confidence by design, so open its top `best_guesses` / `candidate_files` rows; `search_codebase` is full-text only, so `[fts]` hits are normal. The user adds a model with a provider key and `{{ data.model_command }}`; suggest it, do not run it.
{% endif %}
- **Noisy commands** (tests, builds, `git log`/`diff`): prefer `repowise distill <cmd>`, same exit code, errors first. Recover a `[repowise#<ref>: N lines omitted]` marker with `repowise expand <ref>` (`-q <regex>` filters); never re-run the command.
-- **Record a decision** you reasoned out: `repowise decision add --title T --decision D` (lands `proposed` for a person to confirm).
+- **Record a decision** you reasoned out: `repowise decision add --agent <your slug> --title T --decision D --rationale '<why>' --affects <path>` (lands as a candidate for review).
{% endif %}
{% if 'tools' in s %}
diff --git a/packages/server/src/repowise/server/mcp_server/_helpers.py b/packages/server/src/repowise/server/mcp_server/_helpers.py
index b4310f618..410b61b91 100644
--- a/packages/server/src/repowise/server/mcp_server/_helpers.py
+++ b/packages/server/src/repowise/server/mcp_server/_helpers.py
@@ -566,7 +566,7 @@ def _compute_alignment(
"This file is ungoverned — it may be an outlier or simply undocumented."
if currencies
else "This index holds no accepted decisions, so no file is governed "
- "yet; a person accepts a candidate with `repowise decision confirm`."
+ "yet; a person accepts a candidate with `repowise decision confirm <id>`."
)
return {
"score": "none",
diff --git a/packages/server/src/repowise/server/mcp_server/_why_evidence.py b/packages/server/src/repowise/server/mcp_server/_why_evidence.py
index 8dba17f10..b2ea5c787 100644
--- a/packages/server/src/repowise/server/mcp_server/_why_evidence.py
+++ b/packages/server/src/repowise/server/mcp_server/_why_evidence.py
@@ -42,8 +42,9 @@ ProvenanceKind = Literal[
]
_HUMAN_SOURCES = frozenset({"adr", "cli", "session"})
+# ``agent`` is rationale its author stated, but the author is not a person.
_RATIONALE_SOURCES = frozenset(
- {"code_comment", "comment", "inline_marker", "rationale_comment"}
+ {"agent", "code_comment", "comment", "inline_marker", "rationale_comment"}
)
_HISTORICAL_SOURCES = frozenset(
{"changelog", "commit", "git_archaeology", "pr", "readme_mining"}
diff --git a/plugins/claude-code/commands/decision.md b/plugins/claude-code/commands/decision.md
index 6bb9d02aa..630b30e9a 100644
--- a/plugins/claude-code/commands/decision.md
+++ b/plugins/claude-code/commands/decision.md
@@ -32,22 +32,31 @@ unless the repository turns it on.
(`--format json` to parse it back), which is the form to use with no terminal.
The rest are optional: `--context`, `--rationale`, `--alternative`,
`--consequence`, `--affects`, `--tag`, `--evidence-commit`, the last five
- repeatable. A flag-driven record lands `proposed` for a person to `confirm`.
+ repeatable. A flag-driven record lands as a candidate for review; it never
+ governs until accepted. An agent recording a choice it reasoned out passes
+ `--agent <slug>` (e.g. `claude_code`, plus `--session <id>` if known) so the
+ record is the agent's, not a person's.
**Always state a reason** — pass `--rationale` (or `--context`); a record whose
body only restates its own title cannot be accepted. `--kind agreement` records
a working agreement: a rule about how the work is conducted, which names no
file and is not checked against the code. `--evidence-commit <sha>` ties the
record to the commit the choice was made in.
-- **confirm** — `repowise decision confirm` — review decisions auto-proposed from
- git history and accept or reject them.
+- **candidates** — `repowise decision candidates --format json` — records
+ awaiting review, each with its id and the `blockers` that stop it being accepted.
+- **confirm** — `repowise decision confirm <id>...` — accept candidates so they
+ govern. `--reason`, `--scope <path>` and `--evidence <commit|file|link>` fill
+ the blockers. An agent signs with `--agent <slug>`, which works only where
+ the repository has run `repowise decision config agent-acceptance --on`;
+ otherwise leave acceptance to a person.
- **deprecate / dismiss** — `repowise decision deprecate <id>` (optionally
- `--superseded-by <id>`) or `repowise decision dismiss <id>`.
+ `--superseded-by <id>`) or `repowise decision dismiss <id> --reason ...`.
+ An agent passes `--agent <slug>` here too.
## Notes
- For *querying* why code looks the way it does mid-task, prefer the `get_why`
MCP tool (the `architectural-decisions` skill) — it returns lineage and an
alignment score. This command is for *managing* the decision records themselves.
-- `confirm` is interactive, and so is `add` unless you pass `--title` and
- `--decision`; tell the user when a step needs their input.
+- `add` is interactive unless you pass `--title` and `--decision`; the other
+ subcommands take ids and flags and never prompt, except `dismiss` (pass `--yes`).
- If unsure of an exact subcommand or flag, run `repowise decision --help`.
diff --git a/plugins/claude-code/hooks/lens/lens.js b/plugins/claude-code/hooks/lens/lens.js
index 9a8f77b35..a853d8f02 100644
--- a/plugins/claude-code/hooks/lens/lens.js
+++ b/plugins/claude-code/hooks/lens/lens.js
@@ -3059,7 +3059,7 @@ var STANDING = /^\[repowise\] .+? is governed by a standing decision: (.+?)(?: b
var MINED = /^\[repowise\] .+? has a decision recorded in it, mined but not reviewed: (.+?)(?: because .*)?\.$/;
var FIXES = /^\[repowise\] .+? has been bug-fixed (\d+)x in the last 6 months, last (.+?)(?: \(bug magnet\))?(?:; mostly in (.+?))?\.$/;
function stripConfirmed(line2) {
- return line2.replace(/ \(confirmed across \d+ sessions\)\.$/, ".");
+ return line2.replace(/ \((?:seen in|confirmed across) \d+ sessions\)\.$/, ".");
}
function notesFromAugment(additionalContext) {
if (!Array.isArray(additionalContext)) return [];
diff --git a/plugins/claude-code/skills/architectural-decisions/SKILL.md b/plugins/claude-code/skills/architectural-decisions/SKILL.md
index a0ebe229a..1a23789aa 100644
--- a/plugins/claude-code/skills/architectural-decisions/SKILL.md
+++ b/plugins/claude-code/skills/architectural-decisions/SKILL.md
@@ -47,8 +47,9 @@ Call `get_why()` with no arguments to get the decision-health dashboard:
The same signals surface in the CLI via `repowise decision health` /
`/repowise:decision`, and you can query *why* mid-task with `repowise why` /
-`/repowise:why` (the `get_why` adapter). Review auto-proposed decisions with
-`repowise decision confirm`.
+`/repowise:why` (the `get_why` adapter). `repowise decision candidates --format json`
+lists proposed decisions with what each still needs; `repowise decision confirm <id>`
+accepts one (see `/repowise:decision`).
## When a file has decision markers
@@ -56,4 +57,10 @@ If you see `# WHY:`, `# DECISION:`, `# TRADEOFF:`, or `# ADR:` comments in code,
## Recording new decisions
-If the user makes an architectural decision during the conversation, suggest: "Want to record this decision? Add a `# DECISION:` comment in the relevant code, or run `repowise decision add` to capture it formally."
+When you settle an architectural choice yourself (you weighed options and picked one), record it:
+
+`repowise decision add --agent <your slug> --title "..." --decision "..." --rationale "<why, and what you rejected>" --affects <path>`
+
+Add `--evidence-commit <sha>` once it is committed. The record lands as a candidate: it never governs until accepted, so recording is safe. Accept it yourself with `repowise decision confirm <id> --agent <your slug>` only if the repository allows agent acceptance; otherwise leave it for a person and mention it.
+
+If the user states a decision, offer to record it the same way without `--agent`.
diff --git a/plugins/codex/skills/architectural-decisions/SKILL.md b/plugins/codex/skills/architectural-decisions/SKILL.md
index 98bebaa18..75ec5fcef 100644
--- a/plugins/codex/skills/architectural-decisions/SKILL.md
+++ b/plugins/codex/skills/architectural-decisions/SKILL.md
@@ -41,8 +41,9 @@ Call `get_why()` with no arguments to get the decision-health dashboard:
The same signals surface in the CLI via `repowise decision health` /
`/prompts:repowise-decision`, and you can query *why* mid-task with `repowise why` /
-`/prompts:repowise-why` (the `get_why` adapter). Review auto-proposed decisions with
-`repowise decision confirm`.
+`/prompts:repowise-why` (the `get_why` adapter). `repowise decision candidates --format json`
+lists proposed decisions with what each still needs; `repowise decision confirm <id>`
+accepts one (see `/prompts:repowise-decision`).
## When a file has decision markers
@@ -50,4 +51,10 @@ If you see `# WHY:`, `# DECISION:`, `# TRADEOFF:`, or `# ADR:` comments in code,
## Recording new decisions
-If the user makes an architectural decision during the conversation, suggest: "Want to record this decision? Add a `# DECISION:` comment in the relevant code, or run `repowise decision add` to capture it formally."
+When you settle an architectural choice yourself (you weighed options and picked one), record it:
+
+`repowise decision add --agent <your slug> --title "..." --decision "..." --rationale "<why, and what you rejected>" --affects <path>`
+
+Add `--evidence-commit <sha>` once it is committed. The record lands as a candidate: it never governs until accepted, so recording is safe. Accept it yourself with `repowise decision confirm <id> --agent <your slug>` only if the repository allows agent acceptance; otherwise leave it for a person and mention it.
+
+If the user states a decision, offer to record it the same way without `--agent`.
diff --git a/plugins/shared/commands/decision.md b/plugins/shared/commands/decision.md
index 46e1052b9..9dc300c2b 100644
--- a/plugins/shared/commands/decision.md
+++ b/plugins/shared/commands/decision.md
@@ -33,22 +33,31 @@ unless the repository turns it on.
(`--format json` to parse it back), which is the form to use with no terminal.
The rest are optional: `--context`, `--rationale`, `--alternative`,
`--consequence`, `--affects`, `--tag`, `--evidence-commit`, the last five
- repeatable. A flag-driven record lands `proposed` for a person to `confirm`.
+ repeatable. A flag-driven record lands as a candidate for review; it never
+ governs until accepted. An agent recording a choice it reasoned out passes
+ `--agent <slug>` (e.g. `claude_code`, plus `--session <id>` if known) so the
+ record is the agent's, not a person's.
**Always state a reason** — pass `--rationale` (or `--context`); a record whose
body only restates its own title cannot be accepted. `--kind agreement` records
a working agreement: a rule about how the work is conducted, which names no
file and is not checked against the code. `--evidence-commit <sha>` ties the
record to the commit the choice was made in.
-- **confirm** — `repowise decision confirm` — review decisions auto-proposed from
- git history and accept or reject them.
+- **candidates** — `repowise decision candidates --format json` — records
+ awaiting review, each with its id and the `blockers` that stop it being accepted.
+- **confirm** — `repowise decision confirm <id>...` — accept candidates so they
+ govern. `--reason`, `--scope <path>` and `--evidence <commit|file|link>` fill
+ the blockers. An agent signs with `--agent <slug>`, which works only where
+ the repository has run `repowise decision config agent-acceptance --on`;
+ otherwise leave acceptance to a person.
- **deprecate / dismiss** — `repowise decision deprecate <id>` (optionally
- `--superseded-by <id>`) or `repowise decision dismiss <id>`.
+ `--superseded-by <id>`) or `repowise decision dismiss <id> --reason ...`.
+ An agent passes `--agent <slug>` here too.
## Notes
- For *querying* why code looks the way it does mid-task, prefer the `get_why`
MCP tool (the `architectural-decisions` skill) — it returns lineage and an
alignment score. This command is for *managing* the decision records themselves.
-- `confirm` is interactive, and so is `add` unless you pass `--title` and
- `--decision`; tell the user when a step needs their input.
+- `add` is interactive unless you pass `--title` and `--decision`; the other
+ subcommands take ids and flags and never prompt, except `dismiss` (pass `--yes`).
- If unsure of an exact subcommand or flag, run `repowise decision --help`.
diff --git a/plugins/shared/skills/architectural-decisions.md b/plugins/shared/skills/architectural-decisions.md
index 482e7f116..b4476391c 100644
--- a/plugins/shared/skills/architectural-decisions.md
+++ b/plugins/shared/skills/architectural-decisions.md
@@ -55,8 +55,9 @@ Call `get_why()` with no arguments to get the decision-health dashboard:
The same signals surface in the CLI via `repowise decision health` /
`{{cmd:decision}}`, and you can query *why* mid-task with `repowise why` /
-`{{cmd:why}}` (the `get_why` adapter). Review auto-proposed decisions with
-`repowise decision confirm`.
+`{{cmd:why}}` (the `get_why` adapter). `repowise decision candidates --format json`
+lists proposed decisions with what each still needs; `repowise decision confirm <id>`
+accepts one (see `{{cmd:decision}}`).
## When a file has decision markers
@@ -64,4 +65,10 @@ If you see `# WHY:`, `# DECISION:`, `# TRADEOFF:`, or `# ADR:` comments in code,
## Recording new decisions
-If the user makes an architectural decision during the conversation, suggest: "Want to record this decision? Add a `# DECISION:` comment in the relevant code, or run `repowise decision add` to capture it formally."
+When you settle an architectural choice yourself (you weighed options and picked one), record it:
+
+`repowise decision add --agent <your slug> --title "..." --decision "..." --rationale "<why, and what you rejected>" --affects <path>`
+
+Add `--evidence-commit <sha>` once it is committed. The record lands as a candidate: it never governs until accepted, so recording is safe. Accept it yourself with `repowise decision confirm <id> --agent <your slug>` only if the repository allows agent acceptance; otherwise leave it for a person and mention it.
+
+If the user states a decision, offer to record it the same way without `--agent`.
diff --git a/tests/fixtures/lens/augment-edit-notices.txt b/tests/fixtures/lens/augment-edit-notices.txt
index 8b737caa1..33ec46558 100644
--- a/tests/fixtures/lens/augment-edit-notices.txt
+++ b/tests/fixtures/lens/augment-edit-notices.txt
@@ -1,3 +1,3 @@
-[repowise] src/core/auth.py is governed by a standing decision: Use JWT auth because session cookies broke the mobile clients (confirmed across 2 sessions).
+[repowise] src/core/auth.py is governed by a standing decision: Use JWT auth because session cookies broke the mobile clients (seen in 2 sessions).
[repowise] src/core/parser.py has a decision recorded in it, mined but not reviewed: Keep the parser allocation-free because reuse the buffer.
[repowise] src/core/pipeline.py has been bug-fixed 5x in the last 6 months, last 2 weeks ago (bug magnet); mostly in run_pipeline.
diff --git a/tests/unit/analysis/test_attention_compose.py b/tests/unit/analysis/test_attention_compose.py
index faa46cb2e..211874c49 100644
--- a/tests/unit/analysis/test_attention_compose.py
+++ b/tests/unit/analysis/test_attention_compose.py
@@ -110,9 +110,11 @@ def test_proposed_wording_names_a_hand_recorded_decision() -> None:
[
DecisionAttentionInput(id="d-manual", title="Manual", source="cli"),
DecisionAttentionInput(id="d-auto", title="Auto", source="inferred"),
+ DecisionAttentionInput(id="d-agent", title="Agent", source="agent"),
],
[],
)
descriptions = {item["target_id"]: item["description"] for item in result.items}
assert descriptions["d-manual"] == "Decision recorded by hand, awaiting review"
+ assert descriptions["d-agent"] == "Decision recorded by an agent, awaiting review"
assert descriptions["d-auto"] == "Auto-proposed decision awaiting review"
diff --git a/tests/unit/cli/test_augment_decision_inject.py b/tests/unit/cli/test_augment_decision_inject.py
index 4e380bec1..9cdc2562b 100644
--- a/tests/unit/cli/test_augment_decision_inject.py
+++ b/tests/unit/cli/test_augment_decision_inject.py
@@ -456,7 +456,7 @@ async def test_edit_notice_fires_once_per_decision(tmp_path):
assert "governed by a standing decision" in notice
assert "Use JWT auth" in notice
assert "because session cookies broke the mobile clients" in notice
- assert "confirmed across 2 sessions" in notice
+ assert "seen in 2 sessions" in notice
# Same decision again this session: silence.
assert decision_inject._edit_decision_notice(tmp_path, "src/core/auth.py", "s1", state) is None
@@ -1068,7 +1068,7 @@ async def test_the_candidate_lane_prefers_the_better_measured_tier(tmp_path, mon
_quiet_git(monkeypatch, dirty=["src/core/auth.py"])
block = decision_inject._session_decision_block(tmp_path, "sess-1")
assert block is not None
- lines = [ln for ln in block.splitlines() if "candidate" in ln.lower()]
+ lines = [ln for ln in block.splitlines() if "tier candidate" in ln]
assert lines and "Better tier candidate" in lines[0]
diff --git a/tests/unit/cli/test_decision_agent_acceptance.py b/tests/unit/cli/test_decision_agent_acceptance.py
index 964fdbba4..78bc905fa 100644
--- a/tests/unit/cli/test_decision_agent_acceptance.py
+++ b/tests/unit/cli/test_decision_agent_acceptance.py
@@ -179,3 +179,114 @@ def test_the_flag_is_checked_before_anything_is_written(
assert result.exit_code != 0
assert expected in result.output
assert json.loads(_run(repo, "show", "aaaa").output)["decision"]["signature"] is None
+
+
+# --- decision add --agent ----------------------------------------------------
+
+
+def _add(repo: Path, *extra: str, size: int = 512):
+ return _run(
+ repo,
+ "add",
+ "--title", f"Bound the cache at {size}",
+ "--decision", f"Cap the cache at {size} entries",
+ "--rationale", "unbounded growth ran a worker out of memory",
+ "--affects", "src/cache.py",
+ *extra,
+ )
+
+
+def _grounding(repo: Path, decision_id: str) -> dict:
+ import sqlite3
+
+ conn = sqlite3.connect(repo / ".repowise" / "wiki.db")
+ try:
+ row = conn.execute(
+ "SELECT grounding_json FROM decision_candidate_meta WHERE decision_id = ?",
+ (decision_id,),
+ ).fetchone()
+ finally:
+ conn.close()
+ return json.loads(row[0])
+
+
+def test_an_agent_records_a_decision_as_its_own(repo: Path) -> None:
+ added = _add(repo, "--agent", "claude_code", "--session", "s-9")
+ assert added.exit_code == 0, added.output
+ decision_id = json.loads(added.output)["decision"]["id"]
+
+ shown = json.loads(_run(repo, "show", decision_id).output)["decision"]
+ assert shown["source"] == "agent"
+ assert shown["status"] == "proposed"
+ assert _grounding(repo, decision_id) == {"agent": "claude_code", "session": "s-9"}
+
+
+def test_an_agent_record_gets_no_manual_entry_evidence_exemption(repo: Path) -> None:
+ """A person's typed record is its own evidence; an agent's is not."""
+ by_person = json.loads(_add(repo, size=256).output)["decision"]["id"]
+ by_agent = json.loads(_add(repo, "--agent", "claude_code").output)["decision"]["id"]
+
+ assert _run(repo, "confirm", by_person).exit_code == 0
+
+ refused = _run(repo, "confirm", by_agent)
+ assert refused.exit_code == 1, refused.output
+ assert any("evidence" in b for b in json.loads(refused.output)["blockers"])
+
+ accepted = _run(repo, "confirm", by_agent, "--evidence", "abc1234")
+ assert accepted.exit_code == 0, accepted.output
+
+
+ ("args", "expected"),
+ [
+ (("--session", "s-1"), "pass --agent too"),
+ (("--agent", "Claude Code"), "not a well-formed agent slug"),
+ ],
+)
+def test_add_checks_the_signing_flags_before_writing(
+ repo: Path, args: tuple[str, ...], expected: str
+) -> None:
+ result = _add(repo, *args)
+
+ assert result.exit_code != 0
+ assert expected in result.output
+ assert json.loads(_run(repo, "list").output)["total"] == 2
+
+
+def test_add_with_only_the_agent_flag_is_refused_not_prompted(repo: Path) -> None:
+ result = CliRunner().invoke(
+ cli, ["decision", "add", "--agent", "claude_code", str(repo)], input=""
+ )
+
+ assert result.exit_code != 0
+ assert "--title and --decision are both required" in result.output
+
+
+# --- confirm / dismiss with no ids -------------------------------------------
+
+
[email protected]("verb", ["confirm", "dismiss"])
+def test_a_review_verb_with_no_ids_points_at_the_candidates(repo: Path, verb: str) -> None:
+ result = _run(repo, verb)
+
+ assert result.exit_code == 1, result.output
+ payload = json.loads(result.output)
+ assert payload["error"] == "no_decision_ids"
+ assert "repowise decision candidates" in payload["remedy"]
+
+
+def test_a_locked_store_is_one_line_not_a_traceback(repo: Path, monkeypatch) -> None:
+ from sqlalchemy.exc import OperationalError
+
+ import repowise.core.persistence as persistence
+
+ async def _locked(engine):
+ raise OperationalError("PRAGMA", {}, Exception("database is locked"))
+
+ monkeypatch.setattr(persistence, "init_db", _locked)
+ result = CliRunner().invoke(cli, ["decision", "confirm", "aaaa", str(repo)])
+
+ assert result.exit_code == 1
+ assert "database is locked" in result.output
+ assert "retry once it finishes" in result.output
+ assert "Traceback" not in result.output
diff --git a/tests/unit/server/mcp/test_why_evidence_contract.py b/tests/unit/server/mcp/test_why_evidence_contract.py
index af59a1218..a1d049545 100644
--- a/tests/unit/server/mcp/test_why_evidence_contract.py
+++ b/tests/unit/server/mcp/test_why_evidence_contract.py
@@ -191,6 +191,7 @@ def sealed_evidence_fixture() -> tuple[list[SimpleNamespace], dict]:
def test_provenance_vocabulary_is_explicit_and_legacy_safe() -> None:
assert provenance_for_source("session") == "human_decision"
assert provenance_for_source("inline_marker") == "extracted_rationale"
+ assert provenance_for_source("agent") == "extracted_rationale"
assert provenance_for_source("git_archaeology") == "historical"
assert provenance_for_source("inferred") == "inferred"
assert provenance_for_source("future_extractor") == "unknown"