Enforce registered specification artifact change-set operations in ears-manager check

Start in ears-manager/internal/cli/state.go, where checkState() runs checkProposedBaseFreshness, and see how snapshot.Config.Artifacts and the proposed change sets are loaded. The new check compares registered artifacts against the default branch and requires a proposed ArtifactOperation with a matching artifact ID. Tests belong in ears-manager/internal/cli/selfhost_test.go or specvalidation/. Done when the hand-edit case fails with exit code 4 and the artifact-put case passes with exit code 0.

What happened

On PR #246 (implementing Issue #244), the repository codified governance rules to ensure that registered specification artifacts (docs/vision.md, docs/architecture.md) are never edited by hand and must only be modified via ears-manager artifact put within an active proposed change set.

Because ears-manager check only validated that the working tree file SHA-256 matched the recorded digest in .protobot/project.yaml, it had no mechanism to verify whether a modified artifact was associated with an active change set. To compensate, PR #246 drafted an intricate, 50-line natural language verification procedure into AGENTS.md Rule 6 and .agents/skills/review-pr/SKILL.md.

This procedure mandated that LLM review agents manually:

1. Resolve artifacts[].id in .protobot/project.yaml for modified or stale registered specification paths.
2. Require a change-set manifest under .protobot/change-sets/.
3. Verify that ears-manager change-set show (no --at) after checking out the PR head reports proposed iff the manifest path is absent from the default-branch tree.
4. If show --at <pr-head> is used, verify path-absence from default-branch in addition to proposed (since unmerged PR commits report all change sets as proposed under --at).
5. Verify an artifact_operations[] entry with matching artifact_id.
6. Bind ears-manager check to a required checkout or worktree of the PR head.

Drafting and refining this manual review procedure required 7 fix iterations (commits 002eb9c, 29b2214, a3b4d9a, ea5325e, c8f98ce, 48fcfcd, f0cd1b4) and 8 review runs because the code/fix and review agents repeatedly struggled to formalize subtle Git ancestry semantics, non-existent YAML fields (status: proposed), and CLI flags in English prose. Because AGENTS.md Rule 4 requires identical terminology restatements between requirement and consequence clauses, every incremental adjustment required updating the 25-line parenthesized clause twice verbatim.

What could go better

This incident illustrates the pitfall of using complex prompt engineering and natural-language rules to enforce deterministic specification invariants that belong in tooling.

1. Rework rate and agent thrashing: Seven iterations were spent debating the exact English phrasing of CLI invocations, Git worktree checkouts, and manifest list filtering.
2. Review cost and fragility on future PRs: Under the current design, every future PR modifying docs/vision.md or docs/architecture.md forces LLM review agents to execute this 5-step manual inspection protocol, consuming tokens and risking false positives or missed hand edits.
3. CI blind spot: A PR modifying a registered specification artifact by hand and updating the digest in .protobot/project.yaml by hand still passes the CI Specification store check job (ears-manager check) as long as the digest matches the file content, because CI does not execute AGENTS.md Rule 6.

This pattern directly parallels Issue #237 (resolved in PR #238), where change-set base_commit freshness was moved out of human/bot review and directly into ears-manager check (checkProposedBaseFreshness in ears-manager/internal/cli/state.go). The identical principle applies to registered artifact governance.

Confidence: High. ears-manager check already inspects artifacts and loads proposed change sets in checkState(). Verifying that modified registered artifacts correspond to proposed change set operations is straightforward and deterministic.

Proposed change

In redhat-et/ProtoBot:

1. Extend ears-manager check to validate registered artifact operations:
   In ears-manager/internal/cli/state.go (or ears-manager/internal/specvalidation/), add a verification function (e.g. checkRegisteredArtifactOperations) called during checkState() alongside checkProposedBaseFreshness:

   • Inspect registered artifacts defined in snapshot.Config.Artifacts.
   • Compare each registered artifact against the project's target default branch (defaultBranchHead(root, snapshot.Config.Repository)). If an artifact file's content or digest differs from the default branch, or if a new registered artifact path is added:
     • Require that at least one proposed change-set manifest in snapshot.ChangeSets (where proposed[document.Value.ID] is true) contains an ArtifactOperation whose ArtifactID matches the registered artifact's id.
     • If no matching proposed ArtifactOperation exists, emit a structured validation diagnostic (e.g. artifact.operation_missing, exit code 4) indicating that the registered artifact was modified without an ears-manager artifact put operation in an active change set.

2. Simplify AGENTS.md Rule 6 and review-pr skill:
   Replace the monolithic 50-line manual verification procedure in AGENTS.md Rule 6 and .agents/skills/review-pr/SKILL.md with a clean instruction to run and verify ears-manager check on the PR head worktree:

   • Rule 6 will simply state: When a PR creates or modifies a registered specification artifact, or when Rule 4 identifies staleness in one, verify that changes were applied through ears-manager artifact put in an active change set and that ears-manager check passes on a checkout or worktree of the PR head without artifact.operation_missing or artifact.digest_mismatch.

Validation criteria

1. Automated unit/integration tests in ears-manager:
   Add tests in ears-manager/internal/cli/selfhost_test.go or specvalidation/:
   • Test A (Hand-edit rejection): Modify docs/architecture.md and manually update its SHA-256 digest in .protobot/project.yaml on a test branch without adding an artifact_operation to an active change set. Verify ears-manager check fails with exit code 4 and a diagnostic naming the artifact ID.
   • Test B (Valid operation pass): Update docs/architecture.md via ears-manager artifact put within an active proposed change set. Verify ears-manager check passes cleanly with exit code 0.
2. CI enforcement:
   The Specification store check CI job (spec in .github/workflows/ci-workflow.yaml) catches hand-edited registered artifacts deterministically within seconds.
3. Review stability:
   Across the next 5 PRs modifying registered specification artifacts, zero review iterations are spent debating or executing manual change-set manifest and Git tree inspection algorithms.

Generated by retro agent from https://github.com/redhat-et/ProtoBot/pull/246