SpecRunnerDocs
ドキュメント監査と証跡
GUIDE

監査と証跡

jobの現在状態、stepの判定根拠、artifactの入出力、利用量をrepository内の証跡から追跡します。

このページの内容

change folderを証跡の単位にする

state.jsonだけで実行履歴を判断したり、PR attestationだけで差分の正当性を証明したりしません。現在状態・実行履歴・成果物・利用量を別の証跡として照合します。

activeなjobはspecrunner/changes/<slug>/、archive後はspecrunner/changes/archive/YYYY-MM-DD-<slug>/にあります。主要な証跡はfolderと一緒に移動します。

証跡答える質問位置づけ
request.md何を、なぜ、どの受け入れ基準で依頼したかtrusted input
design.md / tasks.md / spec.mdどの設計と作業分解で実装したか設計artifact
*-result-*.md / review-feedback-*.md各gateが何を発見し、どの根拠を示したかstep output
events.jsonlどのstepが何回実行され、どう遷移・中断したかappend-only journal
state.json現在のstatus、step、branch、PR、resume情報は何か再構築可能なprojection
usage.jsonどのcommand・step・modelがtokenを使ったかbest-effort usage record
pipeline logprocess境界で何が起きたか診断用。job stateではない
Git commit / PR diff最終的に何がrepositoryへ入るか成果物の実体

一次情報。 step実行と遷移の一次情報はevents.jsonlです。state.jsonのstepsとhistoryはjournalからfoldされます。

最初にjob showで全体像を取る

job showはjobIdまたはslugを受け付けます。slugが複数jobに一致する場合は、更新時刻が最も新しいjobを表示します。main checkoutから実行してください。

terminal
npx specrunner job ls --all --json
npx specrunner job show <job-id>
HeaderJob ID、Status、Branch、Step、Created、Updated、Log
Journal integrity中間破損があればbannerを出し、lineageとcost表示を停止
Lineagestepごとのinputs / outputsとcontent hash
Cost by stepinput / output tokenと価格表から計算したUSD

StatusとStepは現在位置です。実行済みの全stepやiterationを確認する場合はLineageとresult file、原因調査ではLogを続けて読みます。

破損時もread-onlyの観測を優先します

Job ID指定のjob showとdoctorで確認します。slug一覧とpersist fast pathは一律fail-closedではないため、doctorが失敗している間はresumeしません。復元前の証拠保全はトラブル対応に従います。

Lineageでartifactの依存関係を追う

成功したstepの宣言済みreads()とwrites()を、完了時刻・step名・hashとともにjournalへ記録します。job showはこのjournal-only recordを表示します。

01declare

stepがinputs / outputsを宣言

02digest

local runtimeがSHA-256を計算

03append

events.jsonlへlineageを追記

04inspect

job showでpathとhashを照合

状況hash意味
localでfileを読めるsha256:...その時点で読んだcontentのdigest
missing / unreadablenullpathは残るが内容をdigestできなかった
managed runtimenulllocal filesystemを持たない構造上の制約
lineage追記失敗recordなしbest-effortのためstep完了は取り消さない

Lineageは「このstepが宣言した入出力」を示します。未宣言の因果関係やagentの思考過程を証明するものではありません。

Usageとrun統計を分けて読む

ONE CHANGEusage

invocation単位で確認

active changeを優先し、なければ最新日付のarchiveからusage.jsonを読みます。

  • timestamp、command、step
  • model別input / output / cache token
  • slug省略時はarchive全体を集計
ALL RUNSjob stats

run単位で比較

activeとarchivedのstateを読み、duration・convergence・cost・outcomeを並べます。

  • durationは最初のstartから最後のend
  • convergenceは非skipのreview実行回数
  • --jsonで機械集計可能
terminal
npx specrunner usage my-feature
npx specrunner usage
npx specrunner job stats
npx specrunner job stats --json
欠損表示解釈
usage.jsonなしslug別はno data、statsはcost null実行なしとは限らない
modelUsageなしno usage datamanaged runtimeなど取得不能
価格表にないmodelUSD不明または集計対象外token値と請求元を別途確認
step timestamp不足duration null0秒ではなく計算不能

costは運用上の概算です。実測分布、価格表、認証方式による違いはコスト目安と計測を参照してください。

2種類のAttestationを混同しない

名称生成時点用途
request-review-attestation.jsonrequest-review確認済みcode assertionを、request hashとsource revisionへ束縛
SpecRunner Attestation PR commentpr-createjournal hash、gate順、finding集計、model、costをPRへ要約

Request-review attestation

design stepが同じcode assertionを再確認するコストを減らすための内部artifactです。request本文またはsource revisionが変わる、revisionを取得できない、古い形式でrevisionがない場合はstaleとなり、designがすべて再確認します。file自体は任意出力です。

PR attestation

events.jsonlのraw contentからSHA-256を計算し、step attemptを開始時刻順に並べ、findings・model・usageをcommentへ出します。comment追加はbest-effortで、失敗してもPR作成は成功します。

hashの範囲。 journal hashは「そのcommentが参照したjournal bytes」を識別します。署名ではなく、PR diff・repository identity・verdictの正しさを単独で証明しません。

調査用セットを同じ順で集める

  1. 01
    現在状態

    job show <job-id>のHeader、integrity、Lineage、Costを保存。

  2. 02
    requestと成果物

    request.md、対象result file、PR diff、verification結果を照合。

  3. 03
    実行履歴

    events.jsonlの該当step、transition、interruptionを確認。

  4. 04
    利用量

    usage <slug>とjob stats --jsonで個別値と全体傾向を分離。

  5. 05
    診断log

    最後にlogを使い、stateに残らないprocess・network境界を補う。

共有範囲はtrust modelに合わせます。 request、finding、repository path、PR情報は内部情報を含み得ます。外部へ貼る前にsecretだけでなく、顧客名・未公開仕様・private repository情報も確認します。

証跡を単独の合否証明にしない

各fileは異なる質問へ答えます。PR attestationやjournal hashだけで、PR diff、repository identity、findingの正しさ、merge可否を証明しません。

質問現在の対応
現在のstatusと停止stepは何かjob showで確認できる
どのartifactを入出力したかLineageでbest-effort確認
どのgateが何回動いたかjournalとPR attestationで確認
token・時間・収束回数はどれくらいかusageとstatsで集計
mergeしてよいかrequest、PR diff、result、checks、journalを人が照合して判断

再開可否は再開と状態照合、現行のenforcement範囲は安全性と保証を正とします。

参照ソース 12件
src/cli/job-show.tsjob詳細・lineage・cost表示src/store/event-journal.tsappend-only event journalsrc/store/job-state-projection.tsstate projectionsrc/core/step/commit-orchestrator.tsusage・lineage記録src/core/runtime/local.tslocal artifact hashsrc/core/runtime/managed.tsmanaged lineage制約src/core/command/usage-show.tsslug別usagesrc/core/command/job-stats.tsrun統計src/core/factcheck-attestation.tsrequest-review attestationsrc/core/attestation/types.tsPR attestation contractsrc/core/attestation/render-comment.tsPR comment表示src/cli/command-registry.ts現行CLI surface