[ACP-HARDEN-310] SSOT freshness contractとdrift検出を追加する

[ootakazuhiko]

Parent: #3655
Depends on: ACP-HARDEN-120, ACP-HARDEN-220
Blocks: #3640
Codex lane: docs/ssot-freshness-contract

背景

主要SSOT文書にはlastVerifiedとverificationCommandがあるが、current source revision、next review date、関連path変更後のdriftを機械的に追跡する共通contractがない。文書が古いままでも、frontmatterのlastVerifiedだけでは現在mainとの関係を判断できない。

Private Matchのresearch recordではlast_verified_at、next_review_at、source statusを保持し、期限切れとHTTP availabilityを別warningとして扱った。同じ原則をarchitecture、policy、security、runbookへ適用する。

目的

SSOT文書の検証revision、対象path、verification command、next reviewを閉じたfrontmatter contractとして定義し、期限切れとsource driftを検出する。

Codex CLI preflight

• docs governance／consistency lint
• docRole: ssot|derived|narrative
• current architecture／Zero-Based Design／Assurance Model／CI policy／security docs
• generated docs indexes
• authority snapshot／artifact-ref contract
• Context Pack／Boundary Map

Proposed frontmatter

最低限:

docRole: ssot
owner: architecture-docs
lastVerified: 2026-07-22
nextReviewAt: 2026-10-22
verifiedAgainst:
  repository: itdojp/ae-framework
  revision: <40-char SHA>
  relevantPaths:
    - path: ...
      digest: sha256:...
verificationCommand:
  - pnpm ...

Derived documentはcanonical sourcesとsource digestsを保持する。

実装タスク

• docs/のdocRole／lastVerified／owner／verificationCommand inventoryを作る。
• SSOT freshness frontmatter Schemaまたはparser contractを追加する。
• date、revision、path、digest、commandを閉じる。
• nextReviewAt < todayをstale-review-dateとしてwarningまたはprofile-selected blockにする。
• verifiedAgainst.revision以降にrelevant pathが変更された場合をsource-driftとして検出する。
• current source path digestとfrontmatter digestの差異を検出する。
• derived documentのcanonical source欠落／driftを検出する。
• auto-fixでlastVerifiedやrevisionを更新しない。再検証commandの実行と人間reviewを要求する。
• routine narrative docsとsecurity／policy／architecture SSOTでseverity profileを分ける。
• error／warningへdocument path、stale date、changed source pathを含め、private dataを含めない。
• docs indexへfreshness status summaryをreport-onlyで追加する。
• [REL-200] Consent済み report-only live external pilotを1 repo / 約5 PRで実施する #3640 pilotでdocs onboarding driftを観測できるようにする。

Acceptance criteria

• expired nextReviewAtを検出する。
• revision後のrelevant path変更を検出する。
• content未確認のtimestamp-only更新でpassしない。
• derived docのcanonical source driftを検出する。
• unchanged source／valid dates／successful command Evidenceでpassするfixtureがある。
• severity profileがreport-only／strictを区別する。
• current major SSOTにowner、next review、verified revisionが設定される。

Validation

• frontmatter parse／Schema tests
• stale date／source drift／digest mismatch negative tests
• git history fixture or deterministic changed-path simulation
• docs consistency tests
• pnpm -s run check:doc-consistency
• pnpm -s run verify:lite

非目標

• 文書内容の意味的正しさをLLMだけで自動承認すること
• 全narrative documentをblockingにすること
• lastVerifiedの自動更新
• external web source freshnessの全面監視

Stop condition

• Draft PR
• report-only default、strict profile明示
• exact-head CI success
• unresolved review threads 0
• worktree clean