2.1 KiB
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
dev/ACTIVE_TASK.jsonselects exactly one versioned task packet and must agree with its task ID and revision.- Every active or future packet has a
base_repo_revisionthat resolves to an ancestor commit ofHEAD. - 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.
- Allowed paths use exact repository-relative paths, trailing
directory/**subtrees, or segment-local*and?globs. - Missing, malformed, ambiguous, escaping, non-ancestor or out-of-scope state fails closed.
- Promotion CI uses the active pointer. Explicit
-taskselection exists only for proposal/bootstrap diagnostics. .gitea/workflows/ci.yml,cmd/devctl/**, anddev/ACTIVE_TASK.jsonare Tier E protected paths.- Scope validation does not grant architecture authority and cannot self-certify a changed verifier. Tier E changes retain independent review requirements.
- 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.