From 3630488affa884ba2d87e75cf99fe268f55a53e0 Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Thu, 10 Sep 2026 21:11:54 +0000
Subject: [PATCH] docs(#4698): add openspec spec-implementation consistency
 check

Add a Spec-implementation consistency check subsection to the
boost workspace AGENTS.md, within the Specification-driven
development section. This new guidance instructs code agents to
verify that implementation matches the corresponding openspec spec
before committing -- re-reading behavioral contracts, updating
specs when deliberately diverging, and reconciling when writing
specs alongside new code.

This addresses the recurring spec-implementation divergence found
in PR #4574, where the spec described fail-closed behavior for
invalid caData but the code implemented fail-open, causing the
finding to persist across all 6 review rounds.

Closes #4698
---
 workspaces/boost/AGENTS.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/workspaces/boost/AGENTS.md b/workspaces/boost/AGENTS.md
index fd2f829629c..2f7e2f78193 100644
--- a/workspaces/boost/AGENTS.md
+++ b/workspaces/boost/AGENTS.md
@@ -80,6 +80,23 @@ only requires a non-empty string and MUST NOT enum-validate connector-name.
 
 When writing new scenarios or reviewing spec file changes, verify that every AND/THEN bullet is a concrete assertion, not contextual guidance for human readers.
 
+### Spec-implementation consistency check
+
+After implementing code that has a corresponding openspec spec file
+(under `openspec/specs/`), verify consistency before committing:
+
+1. Re-read each behavioral contract in the spec (GIVEN/WHEN/THEN
+   scenarios, prose requirements) and confirm the implementation
+   matches. Pay special attention to error paths, fallback behavior,
+   and edge cases — these are the most common sources of divergence.
+2. If the implementation deliberately diverges from the spec (e.g., a
+   different error-handling strategy), update the spec to match the
+   actual behavior. The spec is the behavior source of truth and must
+   not describe behavior the code does not implement.
+3. If creating a new spec alongside new code, write the spec after
+   the implementation is finalized, or re-read and reconcile the spec
+   against the final code before committing.
+
 ### Cancelling or removing an openspec component
 
 When a spec, epic, or task is cancelled, apply strikethrough to the cancelled item and then verify all cross-file references using this checklist. Each step must be checked before the cancellation PR is considered complete.