ci: point the weekly architecture reminder at the root ARCHITECTURE.md

[bmdhodl]

Summary

• ops-cadence.yml now measures the age of the root ARCHITECTURE.md and names it in the weekly "any boundary changes?" reminder. The root file owns module boundaries and data flow (ARCHITECTURE.md:116), and AGENTS.md and CLAUDE.md already check its age.
• The PR template does not change: ops/02-ARCHITECTURE.md holds the table of the 52 exports from sdk/agentguard/__init__.py, so export changes still go there.
• ops/FOLLOWUP.md: resolves the open question from docs: fix stale and broken agent instructions from prompt audit #842, and records a defect in the disabled workflow's price check.

Goal: one architecture file per question. Scope: two lines in ops-cadence.yml, one follow-up note. Non-goals: re-enabling the workflow, fixing its price check, changing ops/02 or the PR template. Done: the reminder names the root file, the checks below pass, and the proof is saved (ops/04-DEFINITION_OF_DONE.md).

Related Issues

Follow-up from #842.

Proof

Saved under proof/architecture-doc-pointers/ (Windows 11, Python 3.13.2, Git Bash 5.2.37; make is not installed, so each command ran directly).

Command	Result
run block of ops-cadence.yml, gh stubbed, Monday forced	exit 0; arch_age=8 today; at +30 days the reminder names ARCHITECTURE.md
python scripts/sdk_preflight.py	exit 0 (no SDK-relevant changes)
python scripts/review_readiness_guard.py	exit 0
python scripts/ci_tools_requirements_guard.py	exit 0
pytest sdk/tests/test_architecture.py	9 passed
pytest sdk/tests/test_review_readiness_guard.py	14 passed
python scripts/sdk_release_guard.py	Release guard passed
python proof/architecture-doc-pointers/verify.py	fails on the old tree; passes now

showwork session architecture-doc-pointers: VERIFIED, 7/7 checks green, with verify.py as the declared acceptance check.

Review Readiness

• Public positioning claims have a source/fact ledger. N/A, no positioning change.
• State, lock, file, or process-concurrency changes include cross-platform failure proof. N/A.
• External API collectors include response-shape, pagination, null, and partial-failure tests. N/A.
• Proof artifacts include command, exit code, platform, and regenerated-after-review status. Yes, as listed above; not yet regenerated after review.
• Workflow changes explain trigger scope, timeouts, concurrency, artifacts, and spend impact. Only the file path that one step reads changes. Trigger (weekday cron plus manual dispatch), timeouts, concurrency, artifacts and spend do not change. The workflow is disabled_manually (last run 2026-06-11), so nothing runs until someone turns it on.

Risk And Rollback

Low. When the workflow is turned on again, the reminder tracks the root file. To roll back, revert this commit.

Note: the first local run of the step did not use the gh stub (a Windows path in PATH hid it), and the real gh opened issues #844 and #845. Both are closed as not planned with a note. The saved run uses a guarded stub.

Scope

• Related ops/doc(s): ARCHITECTURE
• Does this change the public API? No.
• Does this shift roadmap priority? No.

Checklist

• make check passes: not run in full. No SDK file changed, and preflight found nothing to run.
• make structural passes (9 passed)
• make security passes: not run, no SDK code changed
• New functionality has tests: verify.py and the stubbed workflow-step run
• No new hard dependencies in core SDK
• No hardcoded absolute paths
• If __init__.py exports changed, ops/02-ARCHITECTURE.md updated. N/A.

🤖 Generated with Claude Code

---

Note

Low Risk
Two-line workflow path/text change with no SDK or API impact; workflow is manually disabled until re-enabled.

Overview
Aligns the ops-cadence staleness job with the root ARCHITECTURE.md (boundaries/data flow): arch_age and the Monday reminder now reference that file instead of ops/02-ARCHITECTURE.md. The PR template and export table in ops/02-ARCHITECTURE.md are unchanged.

ops/FOLLOWUP.md closes the follow-up from #842 (whether cadence should track ops/02) and documents that the workflow has been off since 2026-06-11, plus a separate defect: the price step still parses a literal LAST_UPDATED in cost.py and will false-alarm until it reads price_table.py.

Adds proof/architecture-doc-pointers/ (verify.py, stubbed workflow-step capture, guard runs) and showwork receipts so the pointer change stays enforced.

^{Reviewed by Cursor Bugbot for commit 1165e17. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: c87e4ff5-5918-476e-b982-08cbe2286f78)

[github-actions]

🤖 Claude review

Review

Core change (ops-cadence.yml): The two-line fix is correct — git log --format=%ct -- ARCHITECTURE.md and the reminder body both now point at the root file. No logic issues.

---

Minor issues

proof/architecture-doc-pointers/verify.py:23 — fragile string anchor

require("git log -1 --format=%ct -- ARCHITECTURE.md)" in workflow, ...)

The trailing ) is borrowed from the surrounding shell arithmetic $((...)). If the workflow indentation or quoting is ever reformatted, this check silently breaks. A more robust anchor would be the distinct substring -- ARCHITECTURE.md)) (the closing double-paren of the arithmetic expression), or a regex like re.search(r'git log.*-- ARCHITECTURE\.md\b', workflow).

---

proof/architecture-doc-pointers/README.md — real GitHub issues created during testing

The real gh opened issues #844 and #845. Both are closed as not planned with a note.

Noted and disclosed, but this is process noise worth preventing. The test harness should have validated that gh resolved to the stub before running; the README says the fixed harness does this. Not blocking, but the root cause (PATH ordering on Windows hiding the stub) is worth a comment in the test script so the next author knows what to watch for.

---

ops/FOLLOWUP.md — price-check defect deferred correctly

The sed-vs-DEFAULT_PRICE_TABLE mismatch is real and accurately described. Deferral is fine since the workflow is disabled, but the item should be paired with a re-enable plan or the workflow should stay off explicitly to avoid a silent false-alarm flood when it's eventually re-enabled.

---

No blocking issues. The core fix is minimal and correct; the proof is thorough.

[bmdhodl]

Replies to the Claude review above:

1. verify.py anchor: no change. If someone reformats the workflow, require() raises ValueError and the check fails loudly; it cannot pass silently. The -- prefix in the anchor is what tells the root ARCHITECTURE.md apart from ops/02-ARCHITECTURE.md, and the suggested )) anchor would break under the same reformat.
2. Issues [ops-cadence] Docs need refresh #844 and [ops-cadence] Docs need refresh #845: fixed in 1165e17. The test harness was a scratch script, not a committed file, so the lesson now lives in the proof README: convert stub folders with cygpath -u before you add them to PATH, and stop if command -v gh does not print the stub path.
3. Price-check defect: no change. The ops/FOLLOWUP.md entry already pairs it with re-enabling ("Before it runs again, fix its price check"), and the workflow stays disabled_manually until then.

🤖 Addressed by Claude Code

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 59a49d7f-d045-46b1-9e75-cb868f1cc403)

[github-actions]

🤖 Claude review

LGTM - no blocking issues.

One non-blocking note: verify.py:37 calls text("AGENTS.md") (and "CLAUDE.md") inside a require() — if either file is absent, Path.read_text() raises FileNotFoundError rather than a clean validation error from require(). Fine for a proof script, but worth wrapping in a try/except if this script is ever reused as a real gate.

[bmdhodl]

Re the verify.py note: no change. A missing AGENTS.md or CLAUDE.md raises FileNotFoundError, which exits non-zero with the path in the traceback, so the gate still fails loudly. A try/except would only reword the same failure.

🤖 Addressed by Claude Code