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): tell a working agreement apart from a decision about the code (#2405)

Raghav Chamadiyad3889fe8964b
diff --git a/packages/core/alembic/versions/0067_decision_kind.py b/packages/core/alembic/versions/0067_decision_kind.py
new file mode 100644
index 000000000..5085287bf
--- /dev/null
+++ b/packages/core/alembic/versions/0067_decision_kind.py
@@ -0,0 +1,45 @@
+"""Add decision_records.kind, splitting agreements from architectural decisions.
+
+A working agreement ("never commit to main") and an architectural decision
+("get_why never calls an LLM") were one noun. They are not the same object: a
+diff can violate the second and can never violate the first, which is why an
+agreement could not satisfy the acceptance contract's scope requirement at all.
+
+Additive, and ``architectural`` for every existing row, so a store that has not
+been reclassified behaves exactly as it did. Classification happens in the
+runtime migration rather than here, because a data fix that lives in a
+migration and a data fix that lives in the code eventually disagree, and only
+one of them runs on an existing store.
+
+Revision ID: 0067
+Revises: 0066
+Create Date: 2026-09-18
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0067"
+down_revision: str | None = "0066"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+ op.add_column(
+ "decision_records",
+ sa.Column(
+ "kind",
+ sa.String(16),
+ nullable=False,
+ server_default="architectural",
+ ),
+ )
+
+
+def downgrade() -> None:
+ op.drop_column("decision_records", "kind")
diff --git a/packages/core/src/repowise/core/analysis/decisions/extractor.py b/packages/core/src/repowise/core/analysis/decisions/extractor.py
index b9da3a873..7da30471b 100644
--- a/packages/core/src/repowise/core/analysis/decisions/extractor.py
+++ b/packages/core/src/repowise/core/analysis/decisions/extractor.py
@@ -47,6 +47,7 @@ from typing import Any
import structlog
from repowise.core.analysis.decisions.gate import apply_substring_gate
+from repowise.core.analysis.decisions.lifecycle import ARCHITECTURAL_KIND
from repowise.core.analysis.decisions.policy import (
INDEX_SOURCE_KEYS,
DecisionPolicy,
@@ -150,6 +151,11 @@ class ExtractedDecision:
evidence_line: int | None = None
confidence: float = 0.5
status: str = "proposed"
+ # Which of the two nouns this is. Defaulted rather than classified per
+ # extractor: every other source reads an artifact already written about the
+ # code, and only the session lane mines the prose where an agreement about
+ # conducting the work gets stated.
+ kind: str = ARCHITECTURAL_KIND
# The verbatim claimed quote (LLM/parser output) and the verdict from the
# anti-hallucination substring gate (Phase 1D).
source_quote: str = ""
diff --git a/packages/core/src/repowise/core/analysis/decisions/kinds.py b/packages/core/src/repowise/core/analysis/decisions/kinds.py
new file mode 100644
index 000000000..f082d6022
--- /dev/null
+++ b/packages/core/src/repowise/core/analysis/decisions/kinds.py
@@ -0,0 +1,91 @@
+"""Telling a working agreement from an architectural decision.
+
+Deterministic and deliberately one-sided. A match means the claim is about an
+act of conducting work rather than about the code, and anything unmatched stays
+architectural, because the two errors do not cost the same: a decision wrongly
+left architectural keeps exactly the contract it already had, while one wrongly
+called an agreement stops being checked against the code at all.
+
+No model call. This runs on the keyless path and inside the migration, neither
+of which has a provider, and a keyword list fitted to one repository's English
+is the mistake the staleness score already made once. So the patterns name acts
+a repository cannot contain rather than topics it happens to discuss: branching,
+committing, authoring a pull request body, running a formatter.
+
+Ceiling, measured over 137 hand-classified records against two independent
+raters: 93.3% precision at 46.7% recall. Both misses are records that bundle an
+architectural claim with an attribution one, and neither the primary clause nor
+the ``needs_split`` flag separates them, so they are a known cost rather than an
+open bug. Recall is half on purpose; the unmatched half is not misfiled, it is
+left in the class that still gets checked.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .lifecycle import AGREEMENT_KIND, ARCHITECTURAL_KIND
+
+__all__ = ["classify_kind"]
+
+#: The sources that mine conversational prose, which is the only place an
+#: agreement about conducting the work is ever stated. ``session_discovery``
+#: reads the same transcripts through a broader gate, so it sees the same
+#: sentences.
+_PROSE_SOURCES: frozenset[str] = frozenset({"session", "session_discovery"})
+
+#: Acts of conducting work, grouped by what they name. Each is something a
+#: person does to the repository or around it, never something the repository
+#: holds, which is what makes a diff unable to violate any of them.
+_AGREEMENT_PATTERNS: tuple[re.Pattern[str], ...] = tuple(
+ re.compile(p, re.IGNORECASE)
+ for p in (
+ # Version control: the branch, the staging area, the push. "commit to"
+ # is narrowed to a branch name on purpose, because a decision that
+ # "commits to one source of truth" is ordinary prose and not VCS.
+ r"\bgit (add|commit|push|pull|branch|checkout|stash|reset)\b"
+ r"|\bcommit (directly )?to (the )?[`'\"]?(main|master|trunk)\b"
+ r"|\bbranch(es)? (from|off) (the )?[`'\"]?(main|master|trunk)\b"
+ r"|\bworktrees?\b"
+ r"|\bpull request(s)? (bod|without|for)|\bopen(ing)? a pull request\b"
+ r"|\bmerg(e|ing) (a |the )?(contributor )?PRs?\b",
+ # What a commit message or a pull request body may say. Not repository
+ # files, which is precisely why these are agreements and a rule about
+ # user-facing product text is not.
+ r"co-authored-by"
+ r"|\b(commit|PR|pull request|Claude|AI) attribution\b"
+ r"|\bAI references\b"
+ r"|\battribution (in|to|from) (commits|pull request)",
+ # Commands that are run rather than code that is written.
+ r"\bruff format\b|\bprettier\b|\buv sync\b|\bredeploy\b"
+ r"|\brun (only )?the (full )?test suite\b",
+ # Which checkout may be touched at all.
+ r"\b(main checkout|primary checkout)\b"
+ r"|\bdo not (touch|modify|edit) (the )?(frontend|backend)"
+ r"|\bnever modify\b.*\b(frontend|backend)",
+ )
+)
+
+
+def classify_kind(
+ title: str, decision: str, rationale: str = "", *, source: str = ""
+) -> str:
+ """Which noun *title* and *decision* describe.
+
+ Returns the architectural kind unless the text names an act of conducting
+ work, so a caller that cannot tell is never the reason a record stops being
+ checked against the code.
+
+ Only :data:`_PROSE_SOURCES` is asked at all. Every other source reads an
+ artifact somebody already wrote *about* the code, where the same words mean
+ something else: a comment saying "keep package attribution in one place" is
+ about attributing code to packages, not about who signs a commit. Measured
+ on the dev store, asking the other sources produced two hits and both were
+ wrong.
+ """
+ if source not in _PROSE_SOURCES:
+ return ARCHITECTURAL_KIND
+ text = f"{title} {decision} {rationale}"
+ if any(p.search(text) for p in _AGREEMENT_PATTERNS):
+ return AGREEMENT_KIND
+ return ARCHITECTURAL_KIND
diff --git a/packages/core/src/repowise/core/analysis/decisions/lifecycle.py b/packages/core/src/repowise/core/analysis/decisions/lifecycle.py
index 9a70868e5..b1c32ae28 100644
--- a/packages/core/src/repowise/core/analysis/decisions/lifecycle.py
+++ b/packages/core/src/repowise/core/analysis/decisions/lifecycle.py
@@ -16,8 +16,12 @@ from dataclasses import dataclass
__all__ = [
"ACCEPTANCE_ACTIONS",
+ "AGREEMENT_KIND",
+ "AGREEMENT_SCOPE",
+ "ARCHITECTURAL_KIND",
"CANDIDATE_REVIEW_STATES",
"DECISION_CURRENCIES",
+ "DECISION_KINDS",
"DECISION_STATUS_ORDER",
"NEEDS_REVIEW_STALENESS",
"REVIEW_LANES",
@@ -31,6 +35,24 @@ __all__ = [
"status_rank",
]
+#: The two nouns the store holds. An *architectural* decision is a claim about
+#: the code, and a diff can violate it. An *agreement* is a claim about how the
+#: work is conducted — the branch to commit on, what a pull request body may
+#: say, which command never runs — and no diff can violate it, because it is
+#: not about the code at all. They were one noun until now, which cost both:
+#: an agreement could not be accepted, and it diluted the records that a diff
+#: can be checked against.
+ARCHITECTURAL_KIND = "architectural"
+AGREEMENT_KIND = "agreement"
+DECISION_KINDS: tuple[str, ...] = (ARCHITECTURAL_KIND, AGREEMENT_KIND)
+
+#: The scope an agreement governs. An agreement names no file, but "no scope"
+#: and "the whole repository" are different claims, and only the second is
+#: true of it. Stating it keeps the acceptance contract's rule intact — nothing
+#: is accepted without a scope — instead of carving an exemption out of it,
+#: and it is what the ``scope_json`` CHECK on an acceptance row stores.
+AGREEMENT_SCOPE = "<repository>"
+
#: What a decision's authority currently amounts to. Replaces the numeric
#: staleness threshold as the *product* answer; the score stays an internal
#: supporting fact that feeds ``needs_review``.
@@ -128,6 +150,7 @@ def effective_currency(
*,
has_scope: bool,
staleness: float,
+ repo_wide: bool = False,
) -> str:
"""The currency to show for a decision stored at *stored*.
@@ -135,9 +158,16 @@ def effective_currency(
states a person set, and the code cannot argue with them. An ``active``
decision is re-read against the repository: one that names nothing cannot be
checked at all, and one whose files have moved is worth looking at again.
+
+ Neither question can be put to an agreement. *repo_wide* says so: it names
+ no file, which makes ``uncheckable`` a complaint about it being what it is,
+ and it has no files that can move, which makes ``needs_review`` a reading of
+ a staleness score measured over nothing.
"""
if stored != "active":
return stored if stored in DECISION_CURRENCIES else "active"
+ if repo_wide:
+ return "active"
if not has_scope:
return "uncheckable"
if staleness >= NEEDS_REVIEW_STALENESS:
diff --git a/packages/core/src/repowise/core/analysis/decisions/manifest.py b/packages/core/src/repowise/core/analysis/decisions/manifest.py
index 499bf3dc7..b158db664 100644
--- a/packages/core/src/repowise/core/analysis/decisions/manifest.py
+++ b/packages/core/src/repowise/core/analysis/decisions/manifest.py
@@ -23,6 +23,10 @@ from typing import Any
import yaml
+from repowise.core.analysis.decisions.lifecycle import (
+ ARCHITECTURAL_KIND,
+ DECISION_KINDS,
+)
from repowise.core.fsutils import atomic_write_text
__all__ = [
@@ -66,6 +70,10 @@ class ManifestDecision:
accepted_artifact: str = ""
currency: str = "active"
source: str = "cli"
+ #: Which noun. Written only for an agreement, so a file holding nothing but
+ #: architectural decisions renders exactly as it did before the split and a
+ #: store that has not changed still writes no bytes.
+ kind: str = ARCHITECTURAL_KIND
evidence: list[str] = field(default_factory=list)
superseded_by: str = ""
aliases: list[str] = field(default_factory=list)
@@ -87,6 +95,8 @@ class ManifestDecision:
"source": self.source,
"accepted_at": self.accepted_at,
}
+ if self.kind != ARCHITECTURAL_KIND:
+ out["kind"] = self.kind
if self.accepted_by:
out["accepted_by"] = self.accepted_by
if self.accepted_artifact:
@@ -120,6 +130,13 @@ class ManifestDecision:
accepted_artifact=_text("accepted_artifact"),
currency=_text("currency") or "active",
source=_text("source") or "cli",
+ # A hand-edited file is a trust boundary: an unrecognised
+ # noun reads as the checkable one rather than being stored.
+ kind=(
+ _text("kind")
+ if _text("kind") in DECISION_KINDS
+ else ARCHITECTURAL_KIND
+ ),
evidence=_list("evidence"),
superseded_by=_text("superseded_by"),
aliases=_list("aliases"),
diff --git a/packages/core/src/repowise/core/persistence/crud/authority.py b/packages/core/src/repowise/core/persistence/crud/authority.py
index 68c99af1d..92e5c789c 100644
--- a/packages/core/src/repowise/core/persistence/crud/authority.py
+++ b/packages/core/src/repowise/core/persistence/crud/authority.py
@@ -22,6 +22,8 @@ from sqlalchemy.ext.asyncio import AsyncSession
from repowise.core.analysis.decisions.lifecycle import (
ACCEPTANCE_ACTIONS,
+ AGREEMENT_KIND,
+ AGREEMENT_SCOPE,
NO_SCOPE_BLOCKER,
STORED_CURRENCIES,
AcceptanceRequirement,
@@ -220,6 +222,7 @@ async def decision_currencies(
currency,
has_scope=bool(_record_scope(record)),
staleness=record.staleness_score,
+ repo_wide=_is_repo_wide(record),
)
return out
@@ -249,6 +252,7 @@ async def count_decisions_by_lane(
DecisionRecord.affected_files_json,
DecisionRecord.affected_modules_json,
DecisionRecord.staleness_score,
+ DecisionRecord.kind,
).where(
DecisionRecord.repository_id == repository_id,
# Tombstoned candidates are excluded; a decision that was
@@ -296,16 +300,22 @@ async def count_decisions_by_lane(
"governing": 0,
"total": len(rows),
}
- for did, files_json, modules_json, staleness in rows:
+ for did, files_json, modules_json, staleness, kind in rows:
acceptance = stored.get(did)
if acceptance is None:
counts["candidates"] += 1
continue
- has_scope = bool(json.loads(files_json or "[]")) or bool(
- json.loads(modules_json or "[]")
+ # The same blank handling as _named_scope: a whitespace-only path is
+ # not a scope, and these two computations of one partition must not
+ # disagree about that.
+ named = _non_blank(_json_list(files_json)) or _non_blank(
+ _json_list(modules_json)
)
currency = effective_currency(
- acceptance, has_scope=has_scope, staleness=staleness or 0.0
+ acceptance,
+ has_scope=bool(named) or kind == AGREEMENT_KIND,
+ staleness=staleness or 0.0,
+ repo_wide=kind == AGREEMENT_KIND and not named,
)
counts["history" if currency in ("superseded", "dismissed") else currency] += 1
if is_governing(currency):
@@ -323,6 +333,7 @@ async def current_currency(session: AsyncSession, record: DecisionRecord) -> str
acceptance.currency,
has_scope=has_scope,
staleness=record.staleness_score,
+ repo_wide=_is_repo_wide(record),
)
@@ -365,7 +376,8 @@ def _non_blank(values: list[str]) -> list[str]:
return [v for v in values if v and v.strip()]
-def _record_scope(record: DecisionRecord) -> list[str]:
+def _named_scope(record: DecisionRecord) -> list[str]:
+ """The files or modules *record* actually names, blanks dropped."""
# Blank entries fall through to the modules rather than short-circuiting on
# them, so this agrees with the TypeScript mirror about a whitespace path.
return _non_blank(_json_list(record.affected_files_json)) or _non_blank(
@@ -373,6 +385,33 @@ def _record_scope(record: DecisionRecord) -> list[str]:
)
+def _is_repo_wide(record: DecisionRecord) -> bool:
+ """Whether *record* governs the repository as a whole rather than part of it.
+
+ Both halves are needed. An agreement that names files has been given a real
+ scope by something, and the ordinary rules apply to it: the noun says the
+ record is *allowed* to name nothing, not that anything it does name should
+ be ignored. Keying this off the kind alone would take a record with real
+ files out of staleness checking for good, and the classifier is a regex
+ with a measured false-positive rate.
+ """
+ return record.kind == AGREEMENT_KIND and not _named_scope(record)
+
+
+def _record_scope(record: DecisionRecord) -> list[str]:
+ """What *record* claims to govern, for every reader of the contract.
+
+ An agreement naming no file governs the repository rather than part of it,
+ so it reports that scope instead of an empty one. Written here rather than
+ at the three call sites because they are the acceptance contract, the review
+ flag and the currency, and those three disagreeing about what an agreement
+ governs is the failure :func:`accepted_predicate` exists to describe.
+ """
+ return _named_scope(record) or (
+ [AGREEMENT_SCOPE] if record.kind == AGREEMENT_KIND else []
+ )
+
+
def _record_evidence(record: DecisionRecord) -> list[str]:
evidence = _json_list(record.evidence_commits_json)
if record.evidence_file:
diff --git a/packages/core/src/repowise/core/persistence/crud/decisions.py b/packages/core/src/repowise/core/persistence/crud/decisions.py
index d970b86d9..434f993cf 100644
--- a/packages/core/src/repowise/core/persistence/crud/decisions.py
+++ b/packages/core/src/repowise/core/persistence/crud/decisions.py
@@ -16,7 +16,12 @@ from sqlalchemy import case, delete, func, or_, select
from sqlalchemy.ext.asyncio import AsyncSession
from repowise.core import __version__
-from repowise.core.analysis.decisions.lifecycle import DECISION_STATUS_ORDER, status_rank
+from repowise.core.analysis.decisions.lifecycle import (
+ ARCHITECTURAL_KIND,
+ DECISION_KINDS,
+ DECISION_STATUS_ORDER,
+ status_rank,
+)
from repowise.core.analysis.decisions.provenance import (
SOURCE_RANK,
completeness,
@@ -96,6 +101,17 @@ def _merge_status(existing: str, incoming: str) -> str:
return incoming
+def _extraction_kind(incoming: str | None) -> str:
+ """The kind extraction is allowed to write.
+
+ Unrecognised falls to ``architectural`` rather than being stored: the
+ vocabulary has no CHECK behind it, every reader tests ``== AGREEMENT_KIND``,
+ and a junk value that merely happens to read as architectural everywhere is
+ safe by luck. Normalising here makes it safe by construction.
+ """
+ return incoming if incoming in DECISION_KINDS else ARCHITECTURAL_KIND
+
+
def _dedup_query(
repository_id: str,
title: str,
@@ -1204,6 +1220,7 @@ async def bulk_upsert_decisions(
repository_id=repository_id,
title=headline_title,
status=_extraction_status(headline.get("status", "proposed")),
+ kind=_extraction_kind(headline.get("kind")),
context=headline.get("context") or "",
decision=headline.get("decision") or "",
rationale=headline.get("rationale") or "",
@@ -1230,6 +1247,14 @@ async def bulk_upsert_decisions(
# headline → promote its fields (provenance still accretes below).
rec.title = headline.get("title", rec.title)
rec.status = _merge_status(rec.status, headline.get("status", rec.status))
+ # ``kind`` is deliberately absent: the noun is decided when the
+ # record is created and re-extraction does not revisit it. Most
+ # sources default the field rather than deciding it, so an incoming
+ # value is usually the absence of a judgement; and this branch runs
+ # on accepted records too, where flipping the noun would change what
+ # a record governs behind the person who accepted it. The migration
+ # refuses that for the same reason, and the manifest is where a
+ # person changes it deliberately.
rec.context = headline.get("context") or rec.context
rec.decision = headline.get("decision") or rec.decision
rec.rationale = headline.get("rationale") or rec.rationale
diff --git a/packages/core/src/repowise/core/persistence/decision_dedupe.py b/packages/core/src/repowise/core/persistence/decision_dedupe.py
index 8e8397039..fa08d4eea 100644
--- a/packages/core/src/repowise/core/persistence/decision_dedupe.py
+++ b/packages/core/src/repowise/core/persistence/decision_dedupe.py
@@ -58,6 +58,7 @@ from dataclasses import dataclass, field
from sqlalchemy import delete, select, update
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.analysis.decisions.lifecycle import ARCHITECTURAL_KIND
from repowise.core.analysis.decisions.provenance import rank_for_source
from repowise.core.analysis.decisions.semantic_match import (
DECISION_VECTOR_PREFIX,
@@ -330,6 +331,11 @@ async def apply_dedupe(
continue
for column, name in _UNION_FIELDS:
union[name] |= set(_json_list(getattr(folded, column)))
+ # The checkable noun wins a fold. An agreement that absorbs a
+ # record about the code is about the code too, and being checked
+ # against files it does name is the recoverable error of the two.
+ if folded.kind == ARCHITECTURAL_KIND:
+ canonical.kind = ARCHITECTURAL_KIND
await _absorb_evidence(session, canonical.id, folded.id)
await _repoint_references(session, canonical.id, folded.id)
await _add_alias(session, folded.id, canonical.id, reason="merged")
diff --git a/packages/core/src/repowise/core/persistence/decision_manifest.py b/packages/core/src/repowise/core/persistence/decision_manifest.py
index 7d763f874..d61e23437 100644
--- a/packages/core/src/repowise/core/persistence/decision_manifest.py
+++ b/packages/core/src/repowise/core/persistence/decision_manifest.py
@@ -15,7 +15,12 @@ from pathlib import Path
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
-from repowise.core.analysis.decisions.lifecycle import STORED_CURRENCIES
+from repowise.core.analysis.decisions.lifecycle import (
+ AGREEMENT_KIND,
+ AGREEMENT_SCOPE,
+ ARCHITECTURAL_KIND,
+ STORED_CURRENCIES,
+)
from repowise.core.analysis.decisions.manifest import (
MANIFEST_FILENAME,
ManifestDecision,
@@ -45,6 +50,33 @@ def _stored_currency(value: str) -> str:
return value if value in STORED_CURRENCIES else "active"
+def _scope_files(scope: list[str]) -> list[str]:
+ """The entries of *scope* that name code.
+
+ An agreement's scope is the repository, which is a claim rather than a
+ path. Storing the marker in ``affected_files_json`` would put it in front of
+ staleness and git archaeology as a file that has never existed, and every
+ such file counts as changed.
+ """
+ return [s for s in scope if s != AGREEMENT_SCOPE]
+
+
+def _entry_scope(entry: ManifestDecision) -> list[str]:
+ """The scope *entry* states, read against the noun it claims to be.
+
+ The repo-wide marker is a scope for an agreement and nothing at all for a
+ decision. Read once here so the skip gate and the acceptance cannot
+ disagree: taking the marker as a scope for an architectural entry would
+ accept a record governing no code, which is the one thing the contract is
+ there to refuse. A file naming the marker without saying ``kind:
+ agreement`` is the realistic version of that, since the marker is now
+ written into every export that holds one.
+ """
+ if entry.kind == AGREEMENT_KIND:
+ return sorted(entry.scope)
+ return sorted(_scope_files(entry.scope))
+
+
def _json_list(raw: str) -> list[str]:
try:
parsed = json.loads(raw or "[]")
@@ -117,6 +149,7 @@ async def export_manifest(
accepted_artifact=acceptance.artifact,
currency=acceptance.currency,
source=rec.source,
+ kind=rec.kind,
evidence=_json_list(acceptance.evidence_json),
superseded_by=rec.superseded_by or "",
aliases=await _aliases_for(session, rec.id),
@@ -160,6 +193,10 @@ def _differs(
or _stored_currency(entry.currency) != acceptance.currency
or entry.title != record.title
or entry.decision != record.decision
+ # Without this a file whose only edit is the noun reads as unchanged,
+ # and the committed file becomes unable to express the one thing this
+ # column exists for.
+ or entry.kind != record.kind
)
@@ -189,7 +226,8 @@ async def _apply_entry(
_rederive_headline(record, evidence)
else:
record.confidence = _entry_confidence(entry)
- record.affected_files_json = json.dumps(sorted(entry.scope))
+ record.kind = entry.kind or ARCHITECTURAL_KIND
+ record.affected_files_json = json.dumps(sorted(_scope_files(entry.scope)))
# The successor is an id the file wrote down, and the file can be older
# than the store it is being read into. Storing it unresolved would put a
# retired id back into the column.
@@ -228,7 +266,7 @@ async def import_manifest(
if not entry.reason.strip():
outcome.skipped.append((entry.id, "no reason recorded"))
continue
- if not [s for s in entry.scope if s.strip()]:
+ if not [s for s in _entry_scope(entry) if s.strip()]:
outcome.skipped.append((entry.id, "no scope recorded"))
continue
@@ -267,7 +305,8 @@ async def import_manifest(
decision=entry.decision,
rationale=entry.reason,
source=entry.source or "cli",
- affected_files_json=json.dumps(sorted(entry.scope)),
+ kind=entry.kind or ARCHITECTURAL_KIND,
+ affected_files_json=json.dumps(sorted(_scope_files(entry.scope))),
evidence_commits_json=json.dumps(sorted(entry.evidence)),
superseded_by=entry.superseded_by or None,
confidence=_entry_confidence(entry),
@@ -286,7 +325,7 @@ async def import_manifest(
action="accepted",
currency=_stored_currency(entry.currency),
reason=entry.reason,
- scope=sorted(entry.scope),
+ scope=_entry_scope(entry),
evidence=sorted(entry.evidence) or [artifact],
accepter=entry.accepted_by,
artifact=entry.accepted_artifact or artifact,
diff --git a/packages/core/src/repowise/core/persistence/decision_migration.py b/packages/core/src/repowise/core/persistence/decision_migration.py
index 4203f4f45..d8dc74adf 100644
--- a/packages/core/src/repowise/core/persistence/decision_migration.py
+++ b/packages/core/src/repowise/core/persistence/decision_migration.py
@@ -23,7 +23,11 @@ from dataclasses import dataclass, field
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
-from repowise.core.analysis.decisions.lifecycle import currency_for_legacy_status
+from repowise.core.analysis.decisions.kinds import classify_kind
+from repowise.core.analysis.decisions.lifecycle import (
+ AGREEMENT_KIND,
+ currency_for_legacy_status,
+)
from .crud.authority import (
AcceptanceRefusedError,
@@ -67,6 +71,12 @@ class RowPlan:
reason: str
review_state: str = "open"
duplicate_of: str | None = None
+ #: Which noun this row is, or blank where the migration does not reclassify
+ #: it. Blank for a row already carrying an acceptance or a review state,
+ #: because changing the noun of a record somebody already ruled on would
+ #: change what it governs behind them, and blank for a tombstone, whose
+ #: noun nothing reads.
+ kind: str = ""
@dataclass(slots=True)
@@ -97,6 +107,7 @@ class MigrationPlan:
"reason": r.reason,
"review_state": r.review_state,
"duplicate_of": r.duplicate_of,
+ "kind": r.kind,
}
for r in self.rows
],
@@ -225,6 +236,14 @@ async def plan_migration(
)
continue
+ # Only the rows still in play reach this: the branches above return a
+ # row already accepted, already reviewed or retired, and changing the
+ # noun of one of those would change what it governs behind the person
+ # who ruled on it.
+ kind = classify_kind(
+ rec.title, rec.decision, rec.rationale, source=rec.source
+ )
+
currency = currency_for_legacy_status(rec.status)
if currency is None:
plan.rows.append(
@@ -236,6 +255,7 @@ async def plan_migration(
"candidate",
"never accepted: it was awaiting review",
duplicate_of=dup_of,
+ kind=kind,
)
)
continue
@@ -251,10 +271,18 @@ async def plan_migration(
f"{rec.status} by recurrence, not by a person: "
f"a {rec.source} row carries no acceptance event",
duplicate_of=dup_of,
+ kind=kind,
)
)
continue
+ # Only a self-accepting source reaches here, and no self-accepting
+ # source can be classified as an agreement: ``_SELF_ACCEPTING_SOURCES``
+ # and the classifier's prose sources are disjoint. That disjointness is
+ # load-bearing rather than incidental. Were it broken, a row classified
+ # an agreement on the first run would report a scope on the second (the
+ # contract answers with the repo-wide marker) and be auto-accepted under
+ # ``migration:<source>``, and this runs on every index.
gaps: list[str] = []
if not (rec.rationale.strip() or rec.decision.strip()):
gaps.append("no rationale")
@@ -270,6 +298,7 @@ async def plan_migration(
"candidate",
f"authored via {rec.source} but {' and '.join(gaps)}",
duplicate_of=dup_of,
+ kind=kind,
)
)
continue
@@ -283,6 +312,7 @@ async def plan_migration(
"decision",
f"authored via {rec.source}, with a reason and a scope",
duplicate_of=dup_of,
+ kind=kind,
)
)
return plan
@@ -318,6 +348,8 @@ async def apply_migration(
rec = records.get(row.decision_id)
if rec is None or row.outcome == "already_migrated":
continue
+ if row.kind:
+ rec.kind = row.kind
if rec.status in _RETIRED_STATUSES and row.outcome != "decision":
# Record the tombstone without touching the status that carries the
# retirement.
@@ -384,6 +416,15 @@ def render_plan(plan: MigrationPlan, *, limit: int = 10) -> str:
f" Dismissed tombstones {counts.get('tombstone', 0):>5}",
f" Already migrated {counts.get('already_migrated', 0):>5}",
]
+ agreements = sum(1 for r in plan.rows if r.kind == AGREEMENT_KIND)
+ if agreements:
+ lines += [
+ "",
+ f" Classified as working agreements {agreements:>5}",
+ " Repo-wide rules about how the work is done, not about the",
+ " code. They stop being counted as naming no scope, and can",
+ " be accepted, which a record naming no files could not be.",
+ ]
if plan.duplicate_clusters:
clustered = sum(len(v) for v in plan.duplicate_clusters.values())
lines += [
diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.py
index 757b59646..93c09a6f8 100644
--- a/packages/core/src/repowise/core/persistence/models.py
+++ b/packages/core/src/repowise/core/persistence/models.py
@@ -897,6 +897,13 @@ class DecisionRecord(Base):
status: Mapped[str] = mapped_column(
String(32), nullable=False, default="proposed"
) # proposed | active | deprecated | superseded | dismissed
+ # Which of the two nouns this is. ``architectural`` is the default because
+ # it is the checkable one: a record wrongly left here keeps the contract it
+ # already had, while one wrongly called an agreement stops being checked
+ # against the code at all.
+ kind: Mapped[str] = mapped_column(
+ String(16), nullable=False, default="architectural"
+ ) # architectural | agreement
context: Mapped[str] = mapped_column(Text, nullable=False, default="")
decision: Mapped[str] = mapped_column(Text, nullable=False, default="")
rationale: Mapped[str] = mapped_column(Text, nullable=False, default="")
diff --git a/packages/core/src/repowise/core/sessions/miners/decisions.py b/packages/core/src/repowise/core/sessions/miners/decisions.py
index d15ec7704..9aab3a011 100644
--- a/packages/core/src/repowise/core/sessions/miners/decisions.py
+++ b/packages/core/src/repowise/core/sessions/miners/decisions.py
@@ -58,6 +58,7 @@ import structlog
from repowise.core.analysis.decisions.discovery.spans import SpanCollector
from repowise.core.analysis.decisions.extractor import ExtractedDecision
+from repowise.core.analysis.decisions.kinds import classify_kind
from repowise.core.analysis.decisions.policy import DEFAULT_HARNESSES, resolve_policy
from repowise.core.analysis.decisions.provenance import (
completeness,
@@ -792,6 +793,15 @@ def promotion_decisions(
),
)
sessions = row["sessions"][-_MAX_EVIDENCE_SESSIONS:] or [None]
+ # Classified here rather than at staging, for the same reason binding is:
+ # a candidate staged before the split existed is classified on its way out
+ # instead of staying one noun forever.
+ kind = classify_kind(
+ row["title"],
+ structured.get("decision", ""),
+ structured.get("rationale", "") or "",
+ source="session",
+ )
return [
ExtractedDecision(
title=row["title"],
@@ -803,6 +813,7 @@ def promotion_decisions(
evidence_commits=[sid] if sid else [],
confidence=confidence,
status="proposed",
+ kind=kind,
source_quote=structured.get("source_quote", ""),
verification=structured.get("verification", "unverified"),
lane=lane,
diff --git a/packages/server/src/repowise/server/schemas/decisions.py b/packages/server/src/repowise/server/schemas/decisions.py
index 2b5871640..66949d3c8 100644
--- a/packages/server/src/repowise/server/schemas/decisions.py
+++ b/packages/server/src/repowise/server/schemas/decisions.py
@@ -41,6 +41,9 @@ class DecisionRecordResponse(BaseModel):
confidence: float
staleness_score: float
verification: str = "unverified"
+ # Which noun this is. Defaulted so a payload from a store written before
+ # the split reads as the checkable kind rather than as an unknown one.
+ kind: str = "architectural"
# Derived granularity: file | module | cross-module, or None when the
# record has no code linkage at all. Computed at serialization time from
# the linkage fields, so old records get it too.
@@ -70,6 +73,7 @@ class DecisionRecordResponse(BaseModel):
repository_id=obj.repository_id, # type: ignore[attr-defined]
title=obj.title, # type: ignore[attr-defined]
status=obj.status, # type: ignore[attr-defined]
+ kind=getattr(obj, "kind", None) or "architectural",
context=obj.context, # type: ignore[attr-defined]
# Body fallback: the substring gate can clear a paraphrased
# ``decision`` while an evidence quote keeps the record alive,
diff --git a/packages/types/__tests__/decisions-vocabulary.test.ts b/packages/types/__tests__/decisions-vocabulary.test.ts
index 14c9af9ed..5acdd85a3 100644
--- a/packages/types/__tests__/decisions-vocabulary.test.ts
+++ b/packages/types/__tests__/decisions-vocabulary.test.ts
@@ -16,6 +16,7 @@ import {
DECISION_SOURCES,
DECISION_CURRENCY_DESCRIPTIONS,
DECISION_CURRENCY_LABELS,
+ DECISION_KINDS,
DECISION_LANES,
DECISION_PRESETS,
DECISION_SOURCE_LABELS,
@@ -59,6 +60,10 @@ describe("decision vocabulary matches the engine", () => {
expect(labelled).toEqual(expected);
});
+ it("names the same kinds", () => {
+ expect([...DECISION_KINDS]).toEqual(fixture.kinds);
+ });
+
it("names the same review lanes, in the same order", () => {
expect([...DECISION_LANES]).toEqual(fixture.review_lanes);
});
diff --git a/packages/types/src/decisions.ts b/packages/types/src/decisions.ts
index 8ff84d5f9..26a844bf6 100644
--- a/packages/types/src/decisions.ts
+++ b/packages/types/src/decisions.ts
@@ -51,6 +51,22 @@ export const DECISION_STATUS_LABELS: Record<DecisionStatus, string> = {
dismissed: "Dismissed",
};
+/**
+ * The two nouns the store holds. An `architectural` decision is a claim about
+ * the code that a diff can violate. An `agreement` is a claim about how the
+ * work is conducted, which no diff can violate, so it names no file and is
+ * never checked against one.
+ */
+export const DECISION_KINDS = ["architectural", "agreement"] as const;
+
+export type DecisionKind = (typeof DECISION_KINDS)[number];
+
+/** The word for a kind. Presentation, so the fixture pins coverage only. */
+export const DECISION_KIND_LABELS: Record<DecisionKind, string> = {
+ architectural: "Decision",
+ agreement: "Working agreement",
+};
+
/** Sort key for a status. An unknown status sorts after every known one. */
export function decisionStatusRank(status: string): number {
const i = (DECISION_STATUSES as readonly string[]).indexOf(status);
@@ -228,6 +244,12 @@ export interface DecisionRecord {
last_code_change: string | null;
/** Trust tier of the decision's primary supporting evidence. Optional for back-compat. */
verification?: DecisionVerification;
+ /**
+ * Which noun this record is. An `agreement` names no file on purpose, so it
+ * is never shown as missing a scope. Optional for back-compat with a backend
+ * written before the split; absent reads as `architectural`.
+ */
+ kind?: DecisionKind;
/**
* Derived granularity level. Optional for back-compat with older backends;
* null when the record has no code linkage at all.
@@ -456,6 +478,7 @@ export function decisionAcceptanceBlockers(record: {
evidence_commits?: string[];
evidence_file?: string | null;
source?: string;
+ kind?: string;
}): string[] {
const blockers: string[] = [];
const nonBlank = (values: (string | null | undefined)[]) =>
@@ -464,7 +487,11 @@ export function decisionAcceptanceBlockers(record: {
if (!nonBlank([record.rationale, record.context])) {
blockers.push("no rationale or explicit constraint reason");
}
+ // An agreement governs the repository rather than part of it, so naming no
+ // file is what it is rather than a gap in it. The server states that scope
+ // explicitly on the acceptance row; here it just means no blocker.
if (
+ record.kind !== "agreement" &&
!nonBlank(record.affected_files ?? []) &&
!nonBlank(record.affected_modules ?? [])
) {
diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.ts
index 7e485e291..6f77eb166 100644
--- a/packages/types/src/generated/http.ts
+++ b/packages/types/src/generated/http.ts
@@ -888,6 +888,7 @@ export interface DecisionRecordResponse {
confidence: number;
staleness_score: number;
verification?: string;
+ kind?: string;
scope?: string | null;
superseded_by: string | null;
last_code_change: string | null;
diff --git a/packages/ui/src/decisions/decision-review-lanes.tsx b/packages/ui/src/decisions/decision-review-lanes.tsx
index c68a01858..eae3bb73f 100644
--- a/packages/ui/src/decisions/decision-review-lanes.tsx
+++ b/packages/ui/src/decisions/decision-review-lanes.tsx
@@ -4,6 +4,7 @@ import * as React from "react";
import {
DECISION_CURRENCY_DESCRIPTIONS,
DECISION_CURRENCY_LABELS,
+ DECISION_KIND_LABELS,
DECISION_LANES,
DECISION_SOURCES,
decisionAcceptanceBlockers,
@@ -273,6 +274,10 @@ function DecisionLaneRow({
const currency = d.currency ?? null;
const evidence = d.evidence_preview;
const scope = [...d.affected_files, ...d.affected_modules];
+ // An agreement governs the repository rather than part of it, so naming no
+ // file is what it is. Saying "names nothing" about one reports the defining
+ // property of the noun as a gap in the record.
+ const isAgreement = d.kind === "agreement";
// The same four checks the engine refuses on, asked before the button is
// drawn. A candidate that names nothing already renders "names nothing"
// beside an Accept that could only fail; predicting the refusal is what
@@ -331,11 +336,13 @@ function DecisionLaneRow({
list on the title, because the alternative is a row whose
primary label is crowded off by its own metadata. */}
<span className={MICRO_LABEL} title={scope.join(", ")}>
- {scope.length === 0
- ? "names nothing"
- : scope.length === 1
- ? scope[0]
- : `${scope.length} paths`}
+ {isAgreement && scope.length === 0
+ ? DECISION_KIND_LABELS.agreement.toLowerCase()
+ : scope.length === 0
+ ? "names nothing"
+ : scope.length === 1
+ ? scope[0]
+ : `${scope.length} paths`}
</span>
{staleness.kind === "moved" && (
<span className={MICRO_LABEL} title={staleness.sentence}>
diff --git a/packages/ui/src/decisions/decision-staleness.ts b/packages/ui/src/decisions/decision-staleness.ts
index e9cd902ac..dd5af61d0 100644
--- a/packages/ui/src/decisions/decision-staleness.ts
+++ b/packages/ui/src/decisions/decision-staleness.ts
@@ -30,6 +30,8 @@ import type { DecisionRecord } from "@repowise-dev/types/decisions";
*/
export type DecisionStalenessKind =
| "unscoped"
+ /** An agreement: no files by design, so nothing went unchecked. */
+ | "repo_wide"
| "unscored"
| "unchanged"
| "moved";
@@ -67,6 +69,7 @@ export function describeStaleness(
affectedFiles: readonly string[] | null | undefined,
stalenessScore: number | null | undefined,
status?: string | null,
+ kind?: string | null,
): DecisionStaleness {
const fileCount = affectedFiles?.length ?? 0;
const score = Number.isFinite(stalenessScore) ? (stalenessScore as number) : 0;
@@ -81,6 +84,20 @@ export function describeStaleness(
};
}
+ // An agreement governs the repository rather than part of it, so it has no
+ // files by design and nothing about it has gone unchecked. Reporting it as
+ // unscoped states the defining property of the noun as a gap in the record.
+ if (kind === "agreement" && fileCount === 0) {
+ return {
+ kind: "repo_wide",
+ fileCount: 0,
+ changedCount: 0,
+ sentence:
+ "This is a working agreement, so it governs the whole repository rather than particular files.",
+ short: "repository-wide",
+ };
+ }
+
if (fileCount === 0) {
return {
kind: "unscoped",
@@ -136,12 +153,13 @@ export function describeStaleness(
export function describeRecordStaleness(
decision: Pick<
DecisionRecord,
- "affected_files" | "staleness_score" | "status"
+ "affected_files" | "staleness_score" | "status" | "kind"
>,
): DecisionStaleness {
return describeStaleness(
decision.affected_files,
decision.staleness_score,
decision.status,
+ decision.kind,
);
}
diff --git a/tests/fixtures/decision_vocabulary.json b/tests/fixtures/decision_vocabulary.json
index 446ae458d..c0aac4c99 100644
--- a/tests/fixtures/decision_vocabulary.json
+++ b/tests/fixtures/decision_vocabulary.json
@@ -69,6 +69,10 @@
"balanced",
"full"
],
+ "kinds": [
+ "architectural",
+ "agreement"
+ ],
"review_lanes": [
"active",
"candidates",
diff --git a/tests/unit/analysis/test_decision_vocabulary_contract.py b/tests/unit/analysis/test_decision_vocabulary_contract.py
index 1c5e286d2..0a190eb3e 100644
--- a/tests/unit/analysis/test_decision_vocabulary_contract.py
+++ b/tests/unit/analysis/test_decision_vocabulary_contract.py
@@ -77,6 +77,10 @@ def test_review_states_and_actions_match_lifecycle() -> None:
assert _FIXTURE["acceptance_actions"] == list(lifecycle.ACCEPTANCE_ACTIONS)
+def test_kinds_match_lifecycle() -> None:
+ assert _FIXTURE["kinds"] == list(lifecycle.DECISION_KINDS)
+
+
def test_review_lanes_match_lifecycle() -> None:
assert _FIXTURE["review_lanes"] == list(lifecycle.REVIEW_LANES)
@@ -131,6 +135,7 @@ def test_typescript_declares_the_same_words() -> None:
("DECISION_STATUSES", "statuses"),
("DECISION_CURRENCIES", "currencies"),
("CANDIDATE_REVIEW_STATES", "candidate_review_states"),
+ ("DECISION_KINDS", "kinds"),
("DECISION_LANES", "review_lanes"),
("DECISION_PRESETS", "presets"),
):
diff --git a/tests/unit/persistence/test_decision_dedupe.py b/tests/unit/persistence/test_decision_dedupe.py
index 149cd939a..54c90dfc4 100644
--- a/tests/unit/persistence/test_decision_dedupe.py
+++ b/tests/unit/persistence/test_decision_dedupe.py
@@ -77,6 +77,7 @@ async def _seed(session, store, repo_id, specs: list[dict]) -> list[DecisionReco
rationale=spec.get("rationale", ""),
context="",
source=spec.get("source", "pr"),
+ kind=spec.get("kind", "architectural"),
confidence=spec.get("confidence", 0.5),
affected_files_json=json.dumps(spec.get("files", [])),
affected_modules_json=json.dumps([]),
@@ -217,6 +218,42 @@ async def test_fold_moves_evidence_without_downgrading_the_canonical(async_sessi
assert by_key[("pr", "a.py")].confidence == pytest.approx(0.8)
+async def test_a_fold_moves_the_canonical_to_the_checkable_noun(
+ async_session, repo_id
+):
+ """An agreement that absorbs a record about the code is about the code too.
+
+ The union gives the canonical the folded record's files, and a record that
+ names files is one being checked against them, so the noun has to follow or
+ the canonical claims to govern the repository while naming part of it.
+ """
+ store = _store()
+ canonical, _duplicate = await _seed(
+ async_session,
+ store,
+ repo_id,
+ [
+ # session outranks comment, so the agreement is the canonical and
+ # the record about the code is what folds into it.
+ {
+ "title": "Never commit to main @a",
+ "kind": "agreement",
+ "source": "session",
+ },
+ {
+ "title": "Never commit to trunk @a",
+ "source": "comment",
+ "files": ["src/app.py"],
+ },
+ ],
+ )
+ await apply_dedupe(async_session, repo_id, vector_store=store, tau=TAU)
+
+ survivor = await async_session.get(DecisionRecord, canonical.id)
+ assert survivor.kind == "architectural"
+ assert json.loads(survivor.affected_files_json) == ["src/app.py"]
+
+
async def test_folded_id_still_resolves_and_its_files_survive(async_session, repo_id):
store = _store()
canonical, duplicate = await _seed(
diff --git a/tests/unit/persistence/test_decision_kinds.py b/tests/unit/persistence/test_decision_kinds.py
new file mode 100644
index 000000000..fbe58fb0e
--- /dev/null
+++ b/tests/unit/persistence/test_decision_kinds.py
@@ -0,0 +1,427 @@
+"""A working agreement is a different noun from an architectural decision.
+
+The contract under test: an agreement governs the repository rather than part
+of it, so naming no file is what it *is* rather than a gap in it. Before the
+split that made it unacceptable outright, because the acceptance contract and
+the ``scope_json`` CHECK both demand a scope, and an agreement has no file to
+name. Nothing here may loosen that contract for an architectural decision,
+which still has to say what it governs.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+from sqlalchemy import select
+
+from repowise.core.analysis.decisions.kinds import classify_kind
+from repowise.core.analysis.decisions.lifecycle import (
+ AGREEMENT_KIND,
+ AGREEMENT_SCOPE,
+ ARCHITECTURAL_KIND,
+ effective_currency,
+)
+from repowise.core.analysis.decisions.manifest import manifest_path
+from repowise.core.persistence.crud import bulk_upsert_decisions
+from repowise.core.persistence.crud.authority import (
+ AcceptanceRefusedError,
+ accept_decision,
+ candidate_review_signals,
+ count_decisions_by_lane,
+ current_currency,
+)
+from repowise.core.persistence.crud.decisions import _extraction_kind
+from repowise.core.persistence.decision_manifest import export_manifest, import_manifest
+from repowise.core.persistence.models import DecisionAcceptance, DecisionRecord
+from tests.unit.persistence.helpers import insert_repo
+
+
+def _dict(title: str, **overrides) -> dict:
+ base = {
+ "title": title,
+ "decision": f"{title}: do the thing",
+ "rationale": "because the alternative was measured slower",
+ "source": "session",
+ "status": "proposed",
+ "affected_files": ["src/app.py"],
+ "evidence_file": "src/app.py",
+ "confidence": 0.7,
+ "verification": "exact",
+ "source_quote": f"{title}: do the thing",
+ }
+ base.update(overrides)
+ return base
+
+
+async def _seed(session, repo_id: str, *payloads: dict) -> list[DecisionRecord]:
+ await bulk_upsert_decisions(session, repo_id, list(payloads))
+ rows = (
+ (
+ await session.execute(
+ select(DecisionRecord).where(DecisionRecord.repository_id == repo_id)
+ )
+ )
+ .scalars()
+ .all()
+ )
+ by_title = {r.title: r for r in rows}
+ return [by_title[p["title"]] for p in payloads]
+
+
+# ---------------------------------------------------------------------------
+# Classification
+# ---------------------------------------------------------------------------
+
+
+ "title,decision",
+ [
+ ("Never commit to main", "Do not commit to the main branch."),
+ ("Never stage all changes", "Do not use `git add -A`."),
+ ("Omit Co-Authored-By lines", "Do not include Co-Authored-By lines."),
+ ("Never run Ruff format", "Do not run `ruff format` on the codebase."),
+ ("Only read the main checkout", "Do not modify the main checkout."),
+ ],
+)
+def test_an_act_of_conducting_work_is_an_agreement(title, decision):
+ assert classify_kind(title, decision, source="session") == AGREEMENT_KIND
+
+
+ "title,decision",
+ [
+ ("Keep `why` free of LLM calls", "Do not add an LLM call to the why flow."),
+ ("Keep the health layer deterministic", "Do not make model calls there."),
+ ("Keep SnapshotResponse narrow", "Do not widen SnapshotResponse."),
+ ("Do not import Next", "Do not add `next` imports."),
+ ],
+)
+def test_a_claim_about_the_code_stays_architectural(title, decision):
+ """These name no file either, which is exactly why scope cannot classify."""
+ assert classify_kind(title, decision, source="session") == ARCHITECTURAL_KIND
+
+
+def test_only_a_prose_source_is_asked():
+ """The same words mean something else in an artifact written about the code.
+
+ A comment saying "keep package attribution in one place" is about attributing
+ code to packages, not about who signs a commit, so the question is not put to
+ it at all rather than answered badly.
+ """
+ title, decision = "Never stage all changes", "Do not use `git add -A`."
+ assert classify_kind(title, decision, source="session") == AGREEMENT_KIND
+ assert classify_kind(title, decision, source="comment") == ARCHITECTURAL_KIND
+ assert classify_kind(title, decision, source="pr") == ARCHITECTURAL_KIND
+ # An unnamed caller gets the kind that keeps being checked, per the module's
+ # asymmetry: the default must not be the permissive one.
+ assert classify_kind(title, decision) == ARCHITECTURAL_KIND
+
+
+# ---------------------------------------------------------------------------
+# The acceptance contract
+# ---------------------------------------------------------------------------
+
+
+async def test_an_agreement_naming_no_file_can_be_accepted(async_session):
+ repo = await insert_repo(async_session)
+ (rec,) = await _seed(
+ async_session,
+ repo.id,
+ _dict("Never commit to main", affected_files=[], kind=AGREEMENT_KIND),
+ )
+ assert rec.kind == AGREEMENT_KIND
+
+ _, scope_unresolved = candidate_review_signals(rec)
+ assert scope_unresolved is False
+
+ await accept_decision(async_session, rec, accepter="tester")
+ acceptance = (
+ await async_session.execute(
+ select(DecisionAcceptance).where(DecisionAcceptance.decision_id == rec.id)
+ )
+ ).scalar_one()
+ # Stated, not exempted: the CHECK still refuses an empty scope, and what is
+ # recorded is the scope an agreement actually has.
+ assert acceptance.scope_json == f'["{AGREEMENT_SCOPE}"]'
+
+
+async def test_an_architectural_record_naming_no_file_is_still_refused(async_session):
+ """The no-regression half. The contract did not get looser for a decision."""
+ repo = await insert_repo(async_session)
+ (rec,) = await _seed(
+ async_session,
+ repo.id,
+ _dict("Use Redis", affected_files=[], kind=ARCHITECTURAL_KIND),
+ )
+ _, scope_unresolved = candidate_review_signals(rec)
+ assert scope_unresolved is True
+
+ with pytest.raises(AcceptanceRefusedError) as exc:
+ await accept_decision(async_session, rec, accepter="tester")
+ assert "no scope" in str(exc.value)
+
+
+# ---------------------------------------------------------------------------
+# Currency. An agreement has no files, so neither question can be put to it.
+# ---------------------------------------------------------------------------
+
+
+def test_a_repo_wide_record_is_never_uncheckable_or_needs_review():
+ assert (
+ effective_currency("active", has_scope=False, staleness=0.0, repo_wide=True)
+ == "active"
+ )
+ assert (
+ effective_currency("active", has_scope=True, staleness=1.0, repo_wide=True)
+ == "active"
+ )
+ # Unchanged for everything else.
+ assert effective_currency("active", has_scope=False, staleness=0.0) == "uncheckable"
+ assert effective_currency("active", has_scope=True, staleness=1.0) == "needs_review"
+
+
+async def test_an_accepted_agreement_is_active_despite_inherited_staleness(
+ async_session,
+):
+ """Staleness is measured over files. An agreement has none, so the score
+ it carries from before the split says nothing about it."""
+ repo = await insert_repo(async_session)
+ (rec,) = await _seed(
+ async_session,
+ repo.id,
+ _dict("Never run ruff format", affected_files=[], kind=AGREEMENT_KIND),
+ )
+ rec.staleness_score = 1.0
+ await async_session.flush()
+
+ await accept_decision(async_session, rec, accepter="tester")
+ assert await current_currency(async_session, rec) == "active"
+
+
+async def test_the_lane_counts_agree_with_the_currency(async_session):
+ """Two implementations of the same partition, and they must not disagree."""
+ repo = await insert_repo(async_session)
+ (rec,) = await _seed(
+ async_session,
+ repo.id,
+ _dict("Pause before pushing", affected_files=[], kind=AGREEMENT_KIND),
+ )
+ rec.staleness_score = 1.0
+ await async_session.flush()
+ await accept_decision(async_session, rec, accepter="tester")
+
+ counts = await count_decisions_by_lane(async_session, repo.id)
+ assert counts["active"] == 1
+ assert counts["uncheckable"] == 0
+ assert counts["needs_review"] == 0
+ assert await current_currency(async_session, rec) == "active"
+
+
+async def test_an_agreement_that_names_files_is_still_checked(async_session):
+ """The noun says a record *may* name nothing, not that files it does name
+ should be ignored. The classifier is a regex with a measured false-positive
+ rate, so a misclassified record must not fall out of staleness checking."""
+ repo = await insert_repo(async_session)
+ (rec,) = await _seed(
+ async_session,
+ repo.id,
+ _dict("Never stage all changes", affected_files=["src/app.py"]),
+ )
+ rec.kind = AGREEMENT_KIND
+ rec.staleness_score = 1.0
+ await async_session.flush()
+
+ await accept_decision(async_session, rec, accepter="tester")
+ assert await current_currency(async_session, rec) == "needs_review"
+
+ counts = await count_decisions_by_lane(async_session, repo.id)
+ assert counts["needs_review"] == 1
+ assert counts["active"] == 0
+
+
+async def test_the_five_lanes_still_partition_with_an_agreement_present(async_session):
+ """The property the lanes actually promise: every record in exactly one."""
+ repo = await insert_repo(async_session)
+ agreement, decision, _candidate = await _seed(
+ async_session,
+ repo.id,
+ _dict("Never commit to main", affected_files=[], kind=AGREEMENT_KIND),
+ _dict("Use Redis"),
+ _dict("Use Postgres"),
+ )
+ await accept_decision(async_session, agreement, accepter="tester")
+ await accept_decision(async_session, decision, accepter="tester")
+
+ counts = await count_decisions_by_lane(async_session, repo.id)
+ lanes = ["active", "candidates", "needs_review", "uncheckable", "history"]
+ assert sum(counts[lane] for lane in lanes) == counts["total"] == 3
+ # Which lane, not just how many: the sum alone cannot tell this apart from
+ # a partition where the agreement fell into candidates or uncheckable.
+ assert counts["active"] == 2
+ assert counts["candidates"] == 1
+ assert counts["uncheckable"] == 0
+ assert counts["needs_review"] == 0
+ assert counts["history"] == 0
+
+
+# ---------------------------------------------------------------------------
+# The noun survives the paths that rewrite a record
+# ---------------------------------------------------------------------------
+
+
+async def test_re_extraction_does_not_change_the_noun(async_session):
+ """The noun is decided at creation. Re-extraction must not revisit it, in
+ either direction, because this path runs on accepted records too and
+ flipping the noun there changes what a record governs behind the person who
+ accepted it."""
+ repo = await insert_repo(async_session)
+ (agreement,) = await _seed(
+ async_session,
+ repo.id,
+ _dict("Never commit to main", affected_files=[], kind=AGREEMENT_KIND),
+ )
+ (decision,) = await _seed(async_session, repo.id, _dict("Use Redis"))
+ await accept_decision(async_session, decision, accepter="tester")
+
+ # A corroborating source defaults the field rather than deciding it.
+ await bulk_upsert_decisions(
+ async_session,
+ repo.id,
+ [_dict("Never commit to main", affected_files=[], source="pr")],
+ )
+ # And a re-mined session record whose text now trips the classifier must
+ # not pull an accepted decision out of checking.
+ await bulk_upsert_decisions(
+ async_session,
+ repo.id,
+ [_dict("Use Redis", kind=AGREEMENT_KIND)],
+ )
+
+ await async_session.refresh(agreement)
+ await async_session.refresh(decision)
+ assert agreement.kind == AGREEMENT_KIND
+ assert decision.kind == ARCHITECTURAL_KIND
+
+
+def test_a_junk_kind_is_normalized_rather_than_stored():
+ """Nothing enforces the vocabulary at the database, so the write path does."""
+ assert _extraction_kind("Agreement") == ARCHITECTURAL_KIND
+ assert _extraction_kind("") == ARCHITECTURAL_KIND
+ assert _extraction_kind(None) == ARCHITECTURAL_KIND
+ assert _extraction_kind(AGREEMENT_KIND) == AGREEMENT_KIND
+
+
+async def test_an_agreement_round_trips_through_the_manifest(tmp_path, async_session):
+ """The committed file is the recovery path, so it must not turn the scope
+ marker into a file path or lose the noun on the way back in."""
+ repo = await insert_repo(async_session)
+ (rec,) = await _seed(
+ async_session,
+ repo.id,
+ _dict("Never commit to main", affected_files=[], kind=AGREEMENT_KIND),
+ )
+ await accept_decision(async_session, rec, accepter="tester")
+
+ await export_manifest(async_session, repo.id, tmp_path)
+ text = manifest_path(tmp_path).read_text(encoding="utf-8")
+ assert "kind: agreement" in text
+
+ await async_session.delete(rec)
+ await async_session.flush()
+
+ await import_manifest(async_session, repo.id, tmp_path)
+ restored = (
+ await async_session.execute(
+ select(DecisionRecord).where(DecisionRecord.title == "Never commit to main")
+ )
+ ).scalar_one()
+ assert restored.kind == AGREEMENT_KIND
+ # The marker is what it governs, not a file. Storing it here would put a
+ # path that cannot exist in front of staleness, where it counts as changed.
+ assert json.loads(restored.affected_files_json) == []
+ assert await current_currency(async_session, restored) == "active"
+
+
+async def test_changing_the_noun_in_the_file_reaches_the_store(tmp_path, async_session):
+ """The reaffirm branch, not the create one. If the file cannot express a
+ change to the noun, the committed file cannot correct a misclassification,
+ which for an already-accepted record is the only correction there is."""
+ repo = await insert_repo(async_session)
+ (rec,) = await _seed(
+ async_session,
+ repo.id,
+ _dict("Never commit to main", affected_files=[], kind=AGREEMENT_KIND),
+ )
+ await accept_decision(async_session, rec, accepter="tester")
+ await export_manifest(async_session, repo.id, tmp_path)
+
+ path = manifest_path(tmp_path)
+ # A person decides it was really a claim about the code, and says so by
+ # naming what it governs instead of the repository.
+ path.write_text(
+ path.read_text(encoding="utf-8")
+ .replace(" kind: agreement\n", "")
+ .replace(f" - {AGREEMENT_SCOPE}\n", " - src/app.py\n"),
+ encoding="utf-8",
+ )
+
+ outcome = await import_manifest(async_session, repo.id, tmp_path)
+ assert rec.id in outcome.reaffirmed
+ await async_session.refresh(rec)
+ assert rec.kind == ARCHITECTURAL_KIND
+ assert json.loads(rec.affected_files_json) == ["src/app.py"]
+
+
+async def test_a_noun_only_edit_is_not_read_as_unchanged(tmp_path, async_session):
+ """The scope is identical and only the noun moves, so nothing but the kind
+ comparison can notice. Without it the committed file silently cannot
+ correct a misclassification on a record that names real files."""
+ repo = await insert_repo(async_session)
+ (rec,) = await _seed(
+ async_session,
+ repo.id,
+ _dict("Never stage all changes", affected_files=["src/app.py"]),
+ )
+ await accept_decision(async_session, rec, accepter="tester")
+ await export_manifest(async_session, repo.id, tmp_path)
+
+ path = manifest_path(tmp_path)
+ assert "kind:" not in path.read_text(encoding="utf-8")
+ path.write_text(
+ path.read_text(encoding="utf-8").replace(
+ " source: session\n", " source: session\n kind: agreement\n"
+ ),
+ encoding="utf-8",
+ )
+
+ outcome = await import_manifest(async_session, repo.id, tmp_path)
+ assert rec.id in outcome.reaffirmed
+ await async_session.refresh(rec)
+ assert rec.kind == AGREEMENT_KIND
+
+
+async def test_the_marker_alone_does_not_accept_a_decision(tmp_path, async_session):
+ """The marker is a scope for an agreement and nothing for a decision. A
+ file that names it without saying which noun must not produce an accepted
+ record governing no code, which is what the contract exists to refuse."""
+ repo = await insert_repo(async_session)
+ (rec,) = await _seed(
+ async_session,
+ repo.id,
+ _dict("Never commit to main", affected_files=[], kind=AGREEMENT_KIND),
+ )
+ await accept_decision(async_session, rec, accepter="tester")
+ await export_manifest(async_session, repo.id, tmp_path)
+
+ path = manifest_path(tmp_path)
+ path.write_text(
+ path.read_text(encoding="utf-8").replace(" kind: agreement\n", ""),
+ encoding="utf-8",
+ )
+ await async_session.delete(rec)
+ await async_session.flush()
+
+ outcome = await import_manifest(async_session, repo.id, tmp_path)
+ assert [reason for _id, reason in outcome.skipped] == ["no scope recorded"]
+ assert outcome.created == []
diff --git a/tests/unit/persistence/test_decision_migration.py b/tests/unit/persistence/test_decision_migration.py
index 51e0d1d86..18bcea0b3 100644
--- a/tests/unit/persistence/test_decision_migration.py
+++ b/tests/unit/persistence/test_decision_migration.py
@@ -9,6 +9,7 @@ from __future__ import annotations
from sqlalchemy import select
+from repowise.core.persistence.crud import bulk_upsert_decisions
from repowise.core.persistence.crud.authority import (
accept_decision,
is_accepted,
@@ -210,3 +211,59 @@ async def test_the_report_accounts_for_every_row(async_session):
assert sum(plan.counts().values()) == len(plan.rows) == 3
assert "Total legacy records" in report
assert all(row.reason for row in plan.rows)
+
+
+async def test_the_migration_classifies_the_noun_it_can_and_leaves_the_rest(
+ async_session,
+):
+ """A session row that names an act of conducting work is an agreement; one
+ that names the code is not; and a row somebody already ruled on is left
+ alone, because changing its noun would change what it governs behind them."""
+ repo = await insert_repo(async_session)
+ await bulk_upsert_decisions(
+ async_session,
+ repo.id,
+ [
+ {
+ "title": "Never commit to main",
+ "decision": "Do not commit to the main branch.",
+ "rationale": "the branch is protected",
+ "source": "session",
+ "status": "proposed",
+ },
+ {
+ "title": "Keep why free of LLM calls",
+ "decision": "Do not add an LLM call to the why flow.",
+ "rationale": "it must stay cheap",
+ "source": "session",
+ "status": "proposed",
+ "affected_files": ["src/why.py"],
+ },
+ ],
+ )
+ plan = await plan_migration(async_session, repo.id)
+ by_title = {r.title: r for r in plan.rows}
+ assert by_title["Never commit to main"].kind == "agreement"
+ assert by_title["Keep why free of LLM calls"].kind == "architectural"
+
+ await apply_migration(async_session, repo.id, plan=plan)
+ rows = {
+ r.title: r
+ for r in (
+ (
+ await async_session.execute(
+ select(DecisionRecord).where(
+ DecisionRecord.repository_id == repo.id
+ )
+ )
+ )
+ .scalars()
+ .all()
+ )
+ }
+ assert rows["Never commit to main"].kind == "agreement"
+ assert rows["Keep why free of LLM calls"].kind == "architectural"
+
+ # Idempotent: a second run reclassifies nothing and grants no authority.
+ second = await apply_migration(async_session, repo.id)
+ assert second.counts().get("decision", 0) == 0
diff --git a/tests/unit/persistence/test_schema_reconciliation.py b/tests/unit/persistence/test_schema_reconciliation.py
index ee6e40e2b..34476efc4 100644
--- a/tests/unit/persistence/test_schema_reconciliation.py
+++ b/tests/unit/persistence/test_schema_reconciliation.py
@@ -167,12 +167,12 @@ async def test_reconciler_preserves_existing_row_data(tmp_path: Path) -> None:
db_path,
"""
INSERT INTO decision_records
- (id, repository_id, title, status, context, decision, rationale,
+ (id, repository_id, title, status, kind, context, decision, rationale,
alternatives_json, consequences_json, affected_files_json,
affected_modules_json, tags_json, evidence_commits_json,
source, confidence, staleness_score, created_at, updated_at)
VALUES
- ('rec-1', 1, 't', 'active', '', 'd', '',
+ ('rec-1', 1, 't', 'active', 'architectural', '', 'd', '',
'[]', '[]', '[]',
'[]', '[]', '[]',
'inline', 0.5, 0.0, '2026-01-01', '2026-01-01')