36 lines
2.1 KiB
Markdown
36 lines
2.1 KiB
Markdown
# 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.
|