Files
Assistant/architecture/adrs/ADR-0004-exact-diff-scope-guardrail.md
m 111ad75dea
CI / test (push) Successful in 11s
feat: enforce exact task diff scope
2026-08-16 16:47:06 +03:00

2.1 KiB

ADR-0004: Exact Diff-to-Task Scope Guardrail

Status: Accepted

Date: 2026-08-16

Decision authority: explicit user continuation after ARCH-000003

Context

Architecture preflight validates declared task authority but did not compare it with the complete Git change set. Promotion could therefore not prove that every changed path was explicitly authorized by one reviewed task packet.

Decision

  1. dev/ACTIVE_TASK.json selects exactly one versioned task packet and must agree with its task ID and revision.
  2. Every active or future packet has a base_repo_revision that resolves to an ancestor commit of HEAD.
  3. The guardrail evaluates tracked, staged, unstaged, untracked and deleted paths from the task base. Rename detection is disabled so source and destination are evaluated independently.
  4. Allowed paths use exact repository-relative paths, trailing directory/** subtrees, or segment-local * and ? globs.
  5. Missing, malformed, ambiguous, escaping, non-ancestor or out-of-scope state fails closed.
  6. Promotion CI uses the active pointer. Explicit -task selection exists only for proposal/bootstrap diagnostics.
  7. .gitea/workflows/ci.yml, cmd/devctl/**, and dev/ACTIVE_TASK.json are Tier E protected paths.
  8. Scope validation does not grant architecture authority and cannot self-certify a changed verifier. Tier E changes retain independent review requirements.
  9. Inactive historical task packets are preserved. If activated, they must satisfy the current rules.

Consequences

  • Multi-commit tasks remain bounded by their immutable start revision.
  • CI requires complete history containing the declared base.
  • Task activation is a visible reviewed repository change.
  • Guardrail control surfaces cannot be changed by an ordinary feature task.
  • A new task begins by updating the active pointer and declaring both the pointer and its own packet in scope.

Verification

devctl check-diff is covered by isolated Git-repository fixtures for valid matching and fail-closed cases. Promotion invokes both active-task preflight and exact diff validation before the existing build checks.