feat(framework): audit-prompt v1.1 — verification fidelity (fw-4.32.0, closes #303) (#337)

montfort · claude · web-flow · commit 9862e90b849c · 2026-06-28T19:37:33.000-06:00
A verification-fidelity pass on the unified audit prompt (EN + es), resyncing it with what the framework learned since the v1 hardening (#261). Schema and the four finding categories are unchanged; the changes are additive guidance. No CLI or core change. Three changes: - Audit object vs. truth oracle + cross-boundary contracts (closes #303). STRICT scope now separates *where you report defects* from *what you may read to validate them*; a client-auditing run must cross-check API/IPC/contract calls against the real server-side definition even outside the git_range. A client↔server mismatch is an auditable defect of the client; green client-side tests do not absolve it (mocks encode the client's assumption). - Verification fidelity in Step 2 (addresses #306). For each "verified/resolved/done" claim, ask *against which reality* it was checked (the condition that matters vs. a proxy: local test, mock, the doc itself), open the artifact instead of trusting a downstream summary, and flag a contract consumer that does not reference its defining decision. - Follow-ups registry as the canonical real_debt destination (was a loose "TDE doc"), with TDE promotion via `straymark followups promote`. Bumps fw-4.32.0 (dist-manifest, governance footers ×3 langs, version tables, CHANGELOG). Audit-prompt v1 → v1.1. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,33 @@ and this project uses [independent versioning](README.md#versioning) for Framewo
 
 ---
 
+## Framework 4.32.0 — 2026-06-28
+
+Audit-prompt **v1.1**: a verification-fidelity pass on the unified audit prompt
+(`.straymark/audit-prompts/audit-prompt.md`, EN + es), resynced with what the
+framework learned since the v1 hardening (#261). The schema and the four finding
+categories are unchanged; the changes are additive guidance.
+
+### Changed (Framework)
+
+- **Audit object vs. truth oracle + cross-boundary contracts** (closes #303). The
+  `## STRICT scope` section now distinguishes *where you report defects* (the
+  audit object) from *what you may read to validate them* (a truth oracle), and
+  requires a client-auditing run to cross-check API/IPC/contract calls against
+  the **real server-side definition** even when it is outside the `git_range`. A
+  client↔server contract mismatch is an auditable defect of the client; green
+  client-side tests do not absolve it (mocks encode the client's assumption).
+- **Verification fidelity in Step 2** (addresses #306). For each
+  "verified/resolved/done" claim, the auditor now asks *against which reality* it
+  was checked — the condition that matters vs. a convenient proxy (local test,
+  mock, the doc's own assertion) — opens the artifact rather than trusting a
+  downstream summary, and flags a contract consumer that does not reference the
+  decision defining its contract.
+- **Follow-ups registry as the canonical `real_debt` destination**. The
+  `real_debt` finding category now points to the follow-ups backlog registry
+  (first-class since fw-4.21.0) with TDE promotion (`straymark followups
+  promote`), instead of a loose "post-audit TDE doc".
+
 ## Framework 4.31.0 / CLI 3.30.0 — 2026-06-28
 
 Graduate the Baton experiment's declared work-classification fields to the
diff --git a/README.md b/README.md
@@ -277,7 +277,7 @@ StrayMark uses independent version tags for each component:
 
 | Component | Tag prefix | Example | Includes |
 | --- | --- | --- | --- |
-| Framework | `fw-` | `fw-4.31.0` | Templates (12 types), governance, directives, Charter template + schema |
+| Framework | `fw-` | `fw-4.32.0` | Templates (12 types), governance, directives, Charter template + schema |
 | CLI | `cli-` | `cli-3.30.0` | The `straymark` binary |
 | Loom (EXPERIMENTAL) | `loom-` | `loom-0.4.2` | The `straymark-loom` visualization server, downloaded on demand by `straymark loom serve` |
 
diff --git a/dist/.straymark/00-governance/AGENT-RULES.md b/dist/.straymark/00-governance/AGENT-RULES.md
@@ -412,4 +412,4 @@ When a project accumulates a high volume of AILOGs across multiple Charters and
 
 ---
 
-*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.32.0 | [Strange Days Tech](https://strangedays.tech)*
diff --git a/dist/.straymark/00-governance/C4-DIAGRAM-GUIDE.md b/dist/.straymark/00-governance/C4-DIAGRAM-GUIDE.md
@@ -234,4 +234,4 @@ Use a Level 1 (Context) diagram to illustrate:
 
 ---
 
-*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.32.0 | [Strange Days Tech](https://strangedays.tech)*
diff --git a/dist/.straymark/00-governance/DOCUMENTATION-POLICY.md b/dist/.straymark/00-governance/DOCUMENTATION-POLICY.md
@@ -319,4 +319,4 @@ See also [ADR-2025-01-20-001] for architectural context.
 
 ---
 
-*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.32.0 | [Strange Days Tech](https://strangedays.tech)*
diff --git a/dist/.straymark/00-governance/FOLLOW-UPS-BACKLOG-PATTERN.md b/dist/.straymark/00-governance/FOLLOW-UPS-BACKLOG-PATTERN.md
@@ -316,4 +316,4 @@ Contributed via [issue #111](https://github.com/StrangeDaysTech/straymark/issues
 
 ---
 
-*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.32.0 | [Strange Days Tech](https://strangedays.tech)*
diff --git a/dist/.straymark/00-governance/QUICK-REFERENCE.md b/dist/.straymark/00-governance/QUICK-REFERENCE.md
@@ -262,4 +262,4 @@ Mark `review_required: true` when:
 
 ---
 
-*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.32.0 | [Strange Days Tech](https://strangedays.tech)*
diff --git a/dist/.straymark/00-governance/i18n/es/AGENT-RULES.md b/dist/.straymark/00-governance/i18n/es/AGENT-RULES.md
@@ -412,4 +412,4 @@ Cuando un proyecto acumula un volumen alto de AILOGs a lo largo de múltiples Ch
 
 ---
 
-*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.32.0 | [Strange Days Tech](https://strangedays.tech)*
diff --git a/dist/.straymark/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md b/dist/.straymark/00-governance/i18n/es/C4-DIAGRAM-GUIDE.md
@@ -234,4 +234,4 @@ Usar un diagrama de Nivel 1 (Contexto) para ilustrar:
 
 ---
 
-*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.32.0 | [Strange Days Tech](https://strangedays.tech)*
diff --git a/dist/.straymark/00-governance/i18n/es/DOCUMENTATION-POLICY.md b/dist/.straymark/00-governance/i18n/es/DOCUMENTATION-POLICY.md
@@ -312,4 +312,4 @@ Ver también [ADR-2025-01-20-001] para contexto arquitectónico.
 
 ---
 
-*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.32.0 | [Strange Days Tech](https://strangedays.tech)*
diff --git a/dist/.straymark/00-governance/i18n/es/FOLLOW-UPS-BACKLOG-PATTERN.md b/dist/.straymark/00-governance/i18n/es/FOLLOW-UPS-BACKLOG-PATTERN.md
@@ -316,4 +316,4 @@ Contribuido vía [issue #111](https://github.com/StrangeDaysTech/straymark/issue
 
 ---
 
-*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.32.0 | [Strange Days Tech](https://strangedays.tech)*
diff --git a/dist/.straymark/00-governance/i18n/es/QUICK-REFERENCE.md b/dist/.straymark/00-governance/i18n/es/QUICK-REFERENCE.md
@@ -234,4 +234,4 @@ Marcar `review_required: true` cuando:
 
 ---
 
-*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.32.0 | [Strange Days Tech](https://strangedays.tech)*
diff --git a/dist/.straymark/00-governance/i18n/zh-CN/AGENT-RULES.md b/dist/.straymark/00-governance/i18n/zh-CN/AGENT-RULES.md
@@ -407,4 +407,4 @@ confidence: high | medium | low
 
 ---
 
-*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.32.0 | [Strange Days Tech](https://strangedays.tech)*
diff --git a/dist/.straymark/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md b/dist/.straymark/00-governance/i18n/zh-CN/C4-DIAGRAM-GUIDE.md
@@ -234,4 +234,4 @@ Rel(api, db, "Reads/Writes", "SQL")
 
 ---
 
-*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.32.0 | [Strange Days Tech](https://strangedays.tech)*
diff --git a/dist/.straymark/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md b/dist/.straymark/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md
@@ -311,4 +311,4 @@ review_outcome: approved                # approved | revisions_requested | rejec
 
 ---
 
-*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.32.0 | [Strange Days Tech](https://strangedays.tech)*
diff --git a/dist/.straymark/00-governance/i18n/zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md b/dist/.straymark/00-governance/i18n/zh-CN/FOLLOW-UPS-BACKLOG-PATTERN.md
@@ -316,4 +316,4 @@ straymark followups promote FU-NNN        # 自动化 FU → TDE 提升(见上
 
 ---
 
-*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.32.0 | [Strange Days Tech](https://strangedays.tech)*
diff --git a/dist/.straymark/00-governance/i18n/zh-CN/QUICK-REFERENCE.md b/dist/.straymark/00-governance/i18n/zh-CN/QUICK-REFERENCE.md
@@ -234,4 +234,4 @@ risk_level: low | medium | high | critical
 
 ---
 
-*StrayMark fw-4.31.0 | [Strange Days Tech](https://strangedays.tech)*
+*StrayMark fw-4.32.0 | [Strange Days Tech](https://strangedays.tech)*
diff --git a/dist/.straymark/audit-prompts/audit-prompt.md b/dist/.straymark/audit-prompts/audit-prompt.md
@@ -1,5 +1,5 @@
 <!--
-StrayMark unified audit prompt — v1 (EN canonical).
+StrayMark unified audit prompt — v1.1 (EN canonical).
 
 This file is a TEMPLATE. `straymark charter audit <CHARTER-ID>` resolves the
 placeholders below against the Charter's content + git range + originating
@@ -115,6 +115,15 @@ The authoritative source of scope is the Charter file at `{{charter_path}}`. Rea
   - Missing integration tests when the test task belongs to another Charter.
   - Files that do not exist but whose task is marked as `[ ]` (pending) in the Charter.
 
+### Audit object vs. truth oracle
+
+The scope rules above bound **where you report defects** (the *audit object* — the Charter's files / the `git_range`). They do **not** bound **what you may read to validate that object**. These are two different roles:
+
+- **Audit object** — code in scope, where findings are reported.
+- **Truth oracle** — any code you read to *verify* the in-scope object, even if it is outside the diff and undeclared. Reading an oracle is never out of scope.
+
+**Cross-boundary contracts.** When the audited code is a *client* that consumes an API / IPC / RPC / contract **served by a component elsewhere in this repo**, you MUST cross-check each call — route, request body, response shape, enum values, field names — against the **real server-side definition** (handler structs, proto, schema, migration). Read the server as a *truth oracle* to validate the client, even though it is not in the `git_range` and not declared in the Charter. A client↔server contract mismatch is an **auditable defect of the client** (`implementation_gap` or `real_debt`), **not** an out-of-scope note. Green client-side tests do **NOT** absolve this: mocks and stubs routinely encode the client's *assumption* about the contract, not the real contract — so they pass against the same wrong shape. If an operator note marks generated types or a contract as a "deferred stub", scrutinize them *more*, not less.
+
 ### Originating AILOGs
 
 These AILOGs document the rationale and the emergent risks during execution. **Read them before auditing** — the `R<N>` risks already documented there are NOT new findings, they are consciously accepted trade-offs.
@@ -167,6 +176,7 @@ For EACH task in the Charter, perform these steps in order:
 3. **Trace execution flow**: for key functions, follow the full chain (handler → service → repository → SQL/storage, or the equivalent in the project's stack). Verify that parameters propagate correctly through each layer.
 4. **Verify tests**: locate the corresponding tests. Read at least 2 test cases to confirm they cover the happy path and at least one edge case.
 5. **Compare against the task**: does the implementation match what the task describes? If there are discrepancies, report with evidence (`file:line`).
+6. **Check verification fidelity**: for each "verified / resolved / done" claim you meet (in the Charter or the originating AILOGs), ask *against which reality* it was checked — the **condition that actually matters** (real CI, production-shaped data, the live source or contract) or a **convenient proxy** (a local test, a mock, the doc's own assertion). A claim verified only against a proxy is not yet trustworthy: flag it, and re-verify against the real condition where your tools allow. Do **not** trust a downstream summary of an artifact — if a claim rests on "the AILOG says it was done", open the artifact (file / function / migration) and confirm it yourself. And when the in-scope code consumes a contract defined by a decision elsewhere (an AILOG / AIDEC / PM-backlog / spec), check that it explicitly references that defining decision; a consumer with no pointer to the decision that defines its contract is a drift smell worth a finding.
 
 > **Evidence discipline.** You may only opine on files you have opened via a tool call (Read, Grep, etc.). Any finding you produce must cite `file:line` of the specific files you opened. Findings without citations are treated as low confidence by the consolidated review and may be dropped. If you did not open a file, you cannot infer behavior, structure, or correctness about it.
 
@@ -220,7 +230,7 @@ Each finding falls into one of these four categories. The consolidated review us
 
 - **`hallucination`** — the Charter or the implementation references something that does not exist (an API, a function, a field, a behavior). The agent invented it. Verify by opening the actual file or API.
 - **`implementation_gap`** — the Charter declared work the diff did not deliver, OR the diff delivered work the Charter did not declare, **without** being documented as a risk in the AILOG. (If it is documented in `## Risk` as `R<N+1>` in some AILOG, that is NOT a gap — it is an accepted trade-off.)
-- **`real_debt`** — a code-level concern that is correct with respect to the Charter but introduces technical debt or a subtle defect (a missing error path, a leaked resource, a non-idempotent operation). The adopter should capture this as a post-audit TDE doc.
+- **`real_debt`** — a code-level concern that is correct with respect to the Charter but introduces technical debt or a subtle defect (a missing error path, a leaked resource, a non-idempotent operation). The adopter should capture this in the **follow-ups backlog registry** (`.straymark/follow-ups-backlog.md` — the canonical "what's pending" ledger since fw-4.21.0), and promote it to a TDE doc if it qualifies as cross-cutting debt (`straymark followups promote FU-NNN`). Recording it only inside the consolidated review leaves it invisible to the registry.
 - **`false_positive`** — what initially looked like a finding but, on closer inspection of the AILOG or the diff, is not. Document it anyway; the consolidated review uses these to recognize patterns where one auditor over-reports.
 
 ---
@@ -334,4 +344,4 @@ Does the implementation meet the closure criterion declared by `{{charter_id}}`?
 
 ---
 
-*StrayMark unified audit template v1. The seven universal sections (ABSOLUTE RULE, Your role, Scope rules, Step 2 mandatory verification, Step 5 severity calibration, What you must NOT do, Output format) come from the `audit/SKILL.md` skill mature pre-StrayMark in Sentinel, contributed via issue #102 by José Villaseñor Montfort (StrangeDaysTech). Sentinel-specific hardcodes (spec paths, Etapa headings, internal modules) were parameterized against the Charter doc, originating AILOGs, git range, and project context.*
+*StrayMark unified audit template v1.1 (adds: audit-object-vs-truth-oracle + cross-boundary contract checks #303, verification-fidelity #306, follow-ups registry as the canonical real_debt destination). The seven universal sections (ABSOLUTE RULE, Your role, Scope rules, Step 2 mandatory verification, Step 5 severity calibration, What you must NOT do, Output format) come from the `audit/SKILL.md` skill mature pre-StrayMark in Sentinel, contributed via issue #102 by José Villaseñor Montfort (StrangeDaysTech). Sentinel-specific hardcodes (spec paths, Etapa headings, internal modules) were parameterized against the Charter doc, originating AILOGs, git range, and project context.*
diff --git a/dist/.straymark/audit-prompts/i18n/es/audit-prompt.md b/dist/.straymark/audit-prompts/i18n/es/audit-prompt.md
diff --git a/dist/dist-manifest.yml b/dist/dist-manifest.yml
diff --git a/docs/adopters/CLI-REFERENCE.md b/docs/adopters/CLI-REFERENCE.md
diff --git a/docs/i18n/es/README.md b/docs/i18n/es/README.md
diff --git a/docs/i18n/es/adopters/CLI-REFERENCE.md b/docs/i18n/es/adopters/CLI-REFERENCE.md
diff --git a/docs/i18n/zh-CN/README.md b/docs/i18n/zh-CN/README.md
diff --git a/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md b/docs/i18n/zh-CN/adopters/CLI-REFERENCE.md

Original file line number	Diff line number	Diff line change
`@@ -412,4 +412,4 @@ When a project accumulates a high volume of AILOGs across multiple Charters and`
`412`	`412`
`413`	`413`	`---`
`414`	`414`
`415`		`-StrayMark fw-4.31.0 \| [Strange Days Tech](https://strangedays.tech)`
	`415`	`+StrayMark fw-4.32.0 \| [Strange Days Tech](https://strangedays.tech)`
Original file line number	Diff line number	Diff line change
`@@ -234,4 +234,4 @@ Use a Level 1 (Context) diagram to illustrate:`
`234`	`234`
`235`	`235`	`---`
`236`	`236`
`237`		`-StrayMark fw-4.31.0 \| [Strange Days Tech](https://strangedays.tech)`
	`237`	`+StrayMark fw-4.32.0 \| [Strange Days Tech](https://strangedays.tech)`
Original file line number	Diff line number	Diff line change
`@@ -319,4 +319,4 @@ See also [ADR-2025-01-20-001] for architectural context.`
`319`	`319`
`320`	`320`	`---`
`321`	`321`
`322`		`-StrayMark fw-4.31.0 \| [Strange Days Tech](https://strangedays.tech)`
	`322`	`+StrayMark fw-4.32.0 \| [Strange Days Tech](https://strangedays.tech)`
Original file line number	Diff line number	Diff line change
`@@ -316,4 +316,4 @@ Contributed via [issue #111](https://github.com/StrangeDaysTech/straymark/issues`
`316`	`316`
`317`	`317`	`---`
`318`	`318`
`319`		`-StrayMark fw-4.31.0 \| [Strange Days Tech](https://strangedays.tech)`
	`319`	`+StrayMark fw-4.32.0 \| [Strange Days Tech](https://strangedays.tech)`
Original file line number	Diff line number	Diff line change
@@ -262,4 +262,4 @@ Mark `review_required: true` when:
`262`	`262`
`263`	`263`	`---`
`264`	`264`
`265`		`-StrayMark fw-4.31.0 \| [Strange Days Tech](https://strangedays.tech)`
	`265`	`+StrayMark fw-4.32.0 \| [Strange Days Tech](https://strangedays.tech)`
Original file line number	Diff line number	Diff line change
`@@ -412,4 +412,4 @@ Cuando un proyecto acumula un volumen alto de AILOGs a lo largo de múltiples Ch`
`412`	`412`
`413`	`413`	`---`
`414`	`414`
`415`		`-StrayMark fw-4.31.0 \| [Strange Days Tech](https://strangedays.tech)`
	`415`	`+StrayMark fw-4.32.0 \| [Strange Days Tech](https://strangedays.tech)`
Original file line number	Diff line number	Diff line change
`@@ -234,4 +234,4 @@ Usar un diagrama de Nivel 1 (Contexto) para ilustrar:`
`234`	`234`
`235`	`235`	`---`
`236`	`236`
`237`		`-StrayMark fw-4.31.0 \| [Strange Days Tech](https://strangedays.tech)`
	`237`	`+StrayMark fw-4.32.0 \| [Strange Days Tech](https://strangedays.tech)`
Original file line number	Diff line number	Diff line change
`@@ -312,4 +312,4 @@ Ver también [ADR-2025-01-20-001] para contexto arquitectónico.`
`312`	`312`
`313`	`313`	`---`
`314`	`314`
`315`		`-StrayMark fw-4.31.0 \| [Strange Days Tech](https://strangedays.tech)`
	`315`	`+StrayMark fw-4.32.0 \| [Strange Days Tech](https://strangedays.tech)`