@tyhld/conductor 0.12.89 → 0.12.90

package/dist/headless.js

@@ -19,7 +19,7 @@ import { createInterface } from 'node:readline';
 import { createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { CENTRAL_BUSY_HOLD_MAX_MS, RELAY_DELIVER_MAX, RELAY_FETCH_TIMEOUT_MS, RELAY_HEARTBEAT_INTERVAL_MS, RELAY_RESTORE_ORPHANS_ENABLED, buildAnchor, buildSendText, canDeliver, completeWithReport, createRelayState, deliverJobEndFacts, deliveryReport, fetchCommand, fetchCommandStatus, fetchControl, fetchOrphans, flushPendingJobEndFacts, isTerminalCommandStatus, kindOf, markDelivered, noteCentralDown, noteCentralUp, noteDrain, noteReadiness, patchStatus, recoverStuckProcessedReports, reconnectDelayMs, reportPhase, selectOrphanToRestore, sendHeartbeat, } from './relay.js';
+import { CENTRAL_BUSY_HOLD_MAX_MS, RELAY_DELIVER_MAX, RELAY_FETCH_TIMEOUT_MS, RELAY_HEARTBEAT_INTERVAL_MS, RELAY_RESTORE_ORPHANS_ENABLED, buildAnchor, buildSendText, canDeliver, completeWithReport, createRelayState, deliverJobEndFacts, deliveryReport, fetchCommand, fetchCommandStatus, fetchControl, fetchOrphans, flushPendingJobEndFacts, isTerminalCommandStatus, kindOf, markDelivered, noteCentralDown, noteCentralUp, noteDrain, noteReadiness, patchStatus, recoverStuckProcessedReports, reconnectDelayMs, FINISH_GATE_KINDS, reportDelivery, selectOrphanToRestore, sendHeartbeat, } from './relay.js';
 import { claudePinPath, readClaudePinLine, } from './autoupdate-flags.js';
 const log = (msg) => {
     console.log(`[headless] ${msg}`);
@@ -558,13 +558,16 @@ export function shouldAbortForBodyHandoff(j) {
     return j.bodyHandoff === 'failed' && !j.stopped && !j.timedOut;
 }
 /**
- * 便の終わりの関門が残した「途中で終わった」理由の控え（便 7aa63a97）。
+ * 便の終わりの関門が残した「途中で終わった」理由の控え（便 7aa63a97・便 461be339 で欄を足した）。
  *
- * ★番人側（`scripts/hooks/finish_gate.py`）が、同じ理由で止める回数の上限に達したときだけ
- *   1行だけ書く。中継はそれを【読んで消すだけ】で、判定はしない（判定は関門が持つ）。
+ * ★番人側（`scripts/hooks/finish_gate.py`）が、同じ理由で止める回数の上限に達したときだけ書く。
+ *   中継はそれを【読んで消すだけ】で、判定はしない（判定は関門が持つ）。
  *   これが要るのは「管制には『途中で終わった』と分かる形で届く」ため。新しい状態は作らず、
- *   既にある「終了の事実」の `jobEndDetail` に相乗りする（管制の口を変えない）。
+ *   既にある「終了の事実」に相乗りする（管制の口を変えない）。
+ *   ・人向けの1行 … `jobEndDetail`（今までのまま）
+ *   ・機械で読む形 … `finishGate`（便 461be339 で足した。管制が知らないうちは黙って捨てられる）
  *   控えが無い便＝関門が止めずに済んだ便なので、今までどおり null。
+ * ★古い版の番人が書いた控え（JSON ではない1行）も読める＝入れ替えの途中でも落とさない。
  */
 export function takeFinishGateResidue(commandId, env = process.env) {
     const xdg = (env.XDG_STATE_HOME ?? '').trim();
@@ -573,9 +576,9 @@ export function takeFinishGateResidue(commandId, env = process.env) {
     if (!safe)
         return null;
     const file = path.join(root, 'conductor', 'finish-gate', `${safe}.residue`);
-    let text;
+    let raw;
     try {
-        text = readFileSync(file, 'utf8').trim();
+        raw = readFileSync(file, 'utf8').trim();
     }
     catch {
         return null;
@@ -585,7 +588,41 @@ export function takeFinishGateResidue(commandId, env = process.env) {
         unlinkSync(file);
     }
     catch { /* 消せなくても害は無い（同じ便の控えは1つだけ） */ }
-    return text.length > 0 ? text.slice(0, 500) : null;
+    if (raw.length === 0)
+        return null;
+    return parseFinishGateResidue(raw);
+}
+/** 控えの字面を読む（★純粋関数。JSON でなければ人向けの1行として扱う）。 */
+export function parseFinishGateResidue(raw) {
+    const text = String(raw ?? '').trim();
+    if (text.length === 0)
+        return null;
+    let got = null;
+    try {
+        got = JSON.parse(text);
+    }
+    catch {
+        return { text: text.slice(0, 500), facts: null }; // 古い形（1行だけ）
+    }
+    if (got === null || typeof got !== 'object' || Array.isArray(got)) {
+        return { text: text.slice(0, 500), facts: null };
+    }
+    const rec = got;
+    const line = typeof rec.text === 'string' ? rec.text.trim() : '';
+    if (line.length === 0)
+        return null;
+    const reasons = Array.isArray(rec.reasons)
+        ? FINISH_GATE_KINDS.filter((k) => rec.reasons.includes(k))
+        : [];
+    const countsRaw = (rec.counts ?? null);
+    const counts = {};
+    for (const k of FINISH_GATE_KINDS) {
+        const n = Number(countsRaw?.[k] ?? 0);
+        counts[k] = Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+    }
+    // ★「何が残っていたか」が読めない控えは、機械で読む形を作らない（作り話の事実を送らない）。
+    const facts = reasons.length > 0 ? { exhausted: true, reasons: reasons, counts } : null;
+    return { text: line.slice(0, 500), facts };
 }
 /**
  * いま画面なし方式が追っている便の指示ID（★回収の道から除く物・便 6ebba0d0 の b）。
@@ -1281,6 +1318,11 @@ async function checkRunningJob(cfg, state) {
                 authError: isAuthError(job),
                 exitCode: job.exitCode,
             });
+            // ★「報告を出せたか」はファイルの有無【と形】で見る（便 461be339）。
+            //   形が整っていない＝書きかけの報告は「届いた」と数えず、理由を添えて管制へ届ける。
+            //   ★本文の言葉は1文字も読まない（2026-09-23 の確定のまま。下書きの印は関門の側だけ）。
+            const delivery = reportDelivery(job.commandId);
+            const residue = takeFinishGateResidue(job.commandId);
             await deliverJobEndFacts(cfg, {
                 commandId: job.commandId,
                 site: cfg.site,
@@ -1288,16 +1330,20 @@ async function checkRunningJob(cfg, state) {
                 endKind,
                 exitCode: job.exitCode,
                 exitSignal: job.exitSignal,
-                reportDelivered: reportPhase(job.commandId) !== 'none',
+                reportDelivered: delivery.delivered,
                 // ★画面なし方式は中継が自分で立ち上げた処理なので、終わりを直接つかんでいる。
                 //   つかめていないときは false を送る（1-3 の「つかめていない」と同じ形）。
                 processEndObserved: job.finishedAt !== null,
                 startedAt: new Date(job.startedAt).toISOString(),
                 // ★終わりの関門が「途中で終わった」と残していれば、その理由を先に載せる（便 7aa63a97）。
                 //   本文を渡せなかった理由がいちばん強い（職人は何も受け取っていない）ので、それが先。
+                //   そのどちらも無く、報告の形が整っていないときは、その理由を載せる（便 461be339）。
                 detail: job.bodyHandoffError
-                    ?? takeFinishGateResidue(job.commandId)
+                    ?? residue?.text
+                    ?? delivery.note
                     ?? `attempt ${job.attempt}/${HEADLESS_MAX_ATTEMPTS}`,
+                // ★上限に達して「途中で終わった」便だけに付ける（管制が機械で見分けられる形）。
+                ...(residue?.facts != null ? { finishGate: residue.facts } : {}),
             }, { logLine: log });
         }
         if (job.timedOut) {

package/dist/relay.js

@@ -1475,6 +1475,81 @@ export function reportPhase(commandId, env) {
     }
     return 'none';
 }
+// ───────────────────────────────────────────────────────────────────────────
+// ★報告を「届いた」と数える条件＝ファイルが在る【かつ】形が整っている（便 461be339）
+//
+// 【なぜ要るか（実地 915694ac・前便 7aa63a97 で残った穴）】従来は reportPhase() が
+//   【ファイルの有無だけ】を見ていた。だから書きかけの報告でも「届いた」と数えられ、
+//   `processed/` へ移され、管制は「終わりました・✅」になった。合流も公開もしていなかった。
+//   便の終わりの関門（`scripts/hooks/finish_gate.py`）は職人が【きれいに手番を閉じたとき】に
+//   しか鳴らないので、処理が落ちた・上限時間で止められた便では書きかけが完了の材料になる道が
+//   残っていた。そこを、中継の側でも閉じる。
+//
+// 【★見るのは「形」だけ。本文の言葉は1文字も読まない】報告の中身の言葉で完了を判定しない
+//   （えふさん確定 2026-09-23）。見るのは parseReport() が返す `missing` だけ＝
+//   囲みが閉じている／5つの欄が在る／outcome が決まった語／evidence が1件以上／本文が空でない。
+//   「作成中」「TODO」などの下書きの印を見るのは関門の側だけ（正本は finish_gate.py）。
+//
+// 【★形の決まりの正本は1か所】`scripts/hooks/report-shape.json`。
+//   REQUIRED_REPORT_FIELDS / REPORT_OUTCOMES がその値と同じであることを
+//   `test/report-shape-gate.test.ts` が固定し、同じ `cases` を関門の試験とこちらで流す
+//   ＝2か所に同じ決まりを書かない。
+//
+// 【★形が整っていないときに何をするか】
+//   ・「届いた」と数えない（`reportDelivered: false` ＋ 理由を添えて管制へ届ける）
+//   ・ファイルは【消さない・processed/ へも移さない】＝職人が書き直せる・人が読める
+//   ・管制へ本文を渡さない（書きかけを完了の材料にしない）
+//
+// 【★例外は1つだけ】「作業なし・本文未着」の申告（isInstructionMissingReport・便 7d810bbb）。
+//   職人は本文を受け取っていないので囲みを書く材料が無い。実地 af960f79 の報告は囲みが無い。
+//   これを止めると「本文未着が管制に届かない」という直した障害が戻るので、形の確かめから外す。
+// ───────────────────────────────────────────────────────────────────────────
+/** 報告の「形」で足りない物（空なら整っている）。★本文の言葉は読まない。 */
+export function reportShapeMissing(raw) {
+    return parseReport(raw).missing;
+}
+/** 形が整っていないことを人へ伝える一言（★報告の中身は1文字も写さない）。 */
+export function reportShapeNote(missing) {
+    return `報告は在りますが形が整っていません（足りない: ${missing.join(', ')}）`;
+}
+/** その指示の報告の段と形を1回で見る（★未処理 → 処理済みの順・readParsedReport と同じ順）。 */
+export function reportDelivery(commandId, env) {
+    const groups = [
+        [pendingCandidates(commandId, env), 'pending'],
+        [processedCandidates(commandId, env), 'processed'],
+    ];
+    for (const [files, phase] of groups) {
+        for (const file of files) {
+            const raw = readIfFilled(file);
+            if (raw === null)
+                continue;
+            const instructionMissing = isInstructionMissingReport(raw);
+            const missing = instructionMissing ? [] : reportShapeMissing(raw);
+            const delivered = missing.length === 0;
+            return {
+                phase,
+                raw,
+                delivered,
+                missing,
+                instructionMissing,
+                note: delivered ? null : reportShapeNote(missing),
+            };
+        }
+    }
+    return {
+        phase: 'none',
+        raw: null,
+        delivered: false,
+        missing: [],
+        instructionMissing: false,
+        note: null,
+    };
+}
+/** 管制へ渡してよい報告の本文（形が整っていなければ null＝渡さない）。 */
+export function readDeliverableReport(commandId, env) {
+    const d = reportDelivery(commandId, env);
+    return d.delivered && d.raw !== null ? parseReport(d.raw).body : null;
+}
 /**
  * 管制へ渡し終えた報告を【処理済み】にする（★消さない・削除しない）。
  *   同じ置き場の `processed/` へ移すだけ。移した時刻を更新時刻に刻む（30日の数え始め）。
@@ -1611,6 +1686,7 @@ export async function sendPendingReportFiles(cfg, opts = {}) {
     const exclude = new Set(opts.exclude ?? []);
     const rejectCounts = opts.rejectCounts ?? new Map();
     const items = [];
+    let malformed = 0;
     for (const id of pendingReportIds(env, REPORT_FILES_MAX_PER_ROUND).ids) {
         for (const file of pendingCandidates(id, env)) {
             const raw = readIfFilled(file);
@@ -1619,6 +1695,17 @@ export async function sendPendingReportFiles(cfg, opts = {}) {
                 //   （便 7d810bbb）。完了の道はその便を完了にしないので、ここで送らないと管制に届かない。
                 if (exclude.has(id) && !isInstructionMissingReport(raw))
                     break;
+                // ★形が整っていない報告は送らない（便 461be339）。未処理のまま残すので、職人が書き直せば
+                //   次の周でそのまま届く。★本文の言葉は1文字も読まない（見るのは形だけ）。
+                if (!isInstructionMissingReport(raw)) {
+                    const missing = reportShapeMissing(raw);
+                    if (missing.length > 0) {
+                        malformed++;
+                        logLine(`site=${cfg.site} id=${id} ${reportShapeNote(missing)}` +
+                            '→管制へ送らず未処理のまま残します（職人が書き直せます）');
+                        break;
+                    }
+                }
                 items.push({ id, raw });
                 break;
             }
@@ -1690,10 +1777,12 @@ export async function sendPendingReportFiles(cfg, opts = {}) {
             }
         }
     }
-    if (items.length > 0) {
-        logLine(`site=${cfg.site} 報告ファイル: 送った ${sent} 件・処理済み ${processed} 件・未処理のまま ${kept} 件${rejected > 0 ? `・退けた ${rejected} 件` : ''}`);
+    if (items.length > 0 || malformed > 0) {
+        logLine(`site=${cfg.site} 報告ファイル: 送った ${sent} 件・処理済み ${processed} 件・未処理のまま ${kept} 件` +
+            `${rejected > 0 ? `・退けた ${rejected} 件` : ''}` +
+            `${malformed > 0 ? `・形が整っていない ${malformed} 件（未処理のまま残す）` : ''}`);
     }
-    return { sent, processed, kept, rejected };
+    return { sent, processed, kept, rejected, malformed };
 }
 /**
  * 古い控えを片付ける。★消すのは `processed/` の中だけ（未処理は何日たっても消さない）。
@@ -2620,17 +2709,22 @@ export async function patchStatus(cfg, id, status, report) {
  * 返り: 追跡を畳んでよいか（true = 便の終了状態が確定した／false = 書けていない＝次の周でやり直す）。
  */
 export async function completeWithReport(cfg, id, logLine = log) {
-    // ★①報告がどの段にあるか（送る工程の話）。②③の実行可否には使わない。
-    const phase = reportPhase(id);
+    // ★①報告がどの段にあるか＋形が整っているか（送る工程の話）。②③の実行可否には使わない。
+    //   ★形が整っていない報告は「届いた」と数えない（便 461be339）。ファイルは消さず・移さず残す。
+    const delivery = reportDelivery(id);
+    const phase = delivery.phase;
     // ★②便が終わっているか（確定の工程の話）。管制の真実だけを見る。
     const already = await fetchCommandStatus(cfg, id);
     if (isCentralFinished(already)) {
         // 既に終端（職人の conductor_complete・人の操作・failed 等）。★何も書かない。
         //   控えは消さずに処理済みとして残す（MCP 経由でも同じ控えが残る・えふさん確定 2026-09-21）。
-        if (phase === 'pending')
+        //   ★形が整っていない報告は未処理のまま置く（職人が書き直せる・人が読める）。
+        if (phase === 'pending' && delivery.delivered)
             markReportProcessed(id);
         logLine(`site=${cfg.site} id=${id} は管制で既に終わっています(status=${already})` +
-            '→relayからは送りません（報告は控えとして処理済みにしました）');
+            (phase === 'pending' && !delivery.delivered
+                ? `→relayからは送りません（${delivery.note}＝未処理のまま残します）`
+                : '→relayからは送りません（報告は控えとして処理済みにしました）'));
         return true;
     }
     if (phase === 'processed') {
@@ -2641,13 +2735,19 @@ export async function completeWithReport(cfg, id, logLine = log) {
         logLine(`site=${cfg.site} id=${id} done（報告は回収の道で渡し済み＝本文は添えない）`);
         return true;
     }
-    const report = readReport(id);
+    // ★形が整っていない報告は添えない（書きかけを完了の材料にしない）。便の確定は今までどおり行う
+    //   ＝現場を占有したままにしない。「報告が届いていない」ことは終了の事実で管制へ届く。
+    const report = delivery.delivered && delivery.raw !== null ? parseReport(delivery.raw).body : null;
     if (!(await patchStatus(cfg, id, 'done', report)))
         return false;
     if (report !== null)
         markReportProcessed(id); // ★消さずに処理済みへ（同じ報告を二度送らない）
     logLine(`site=${cfg.site} id=${id} done` +
-        (report !== null ? `（報告添付・${report.length}文字）` : '（報告ファイルなし＝完了のみ）'));
+        (report !== null
+            ? `（報告添付・${report.length}文字）`
+            : phase === 'none'
+                ? '（報告ファイルなし＝完了のみ）'
+                : `（${delivery.note}＝添えずに未処理のまま残します）`));
     return true;
 }
 /**
@@ -2957,6 +3057,8 @@ export async function sendHeartbeat(cfg, id, busy = false, liveness) {
         log(`site=${cfg.site} id=${id} heartbeat -> 失敗: ${err instanceof Error ? err.message : String(err)}（縮退で安全）`);
     }
 }
+/** 便の終わりの関門の種類（控えの数え方の見出し。★`finish_gate.py` の GATE_KINDS と同じ語）。 */
+export const FINISH_GATE_KINDS = ['report', 'pr', 'background'];
 /** 届けられなかった「終了の事実」の置き場。 */
 export function jobEndDir(env = process.env) {
     const base = (env.CONDUCTOR_STATE_DIR ?? '').trim();
@@ -2993,6 +3095,10 @@ export function jobEndFactsBody(f) {
         body.startedAt = f.startedAt;
     if (f.detail !== undefined && f.detail !== '')
         body.jobEndDetail = f.detail.slice(0, JOB_END_DETAIL_MAX);
+    // ★上限に達して「途中で終わった」便だけに付ける（付いていること自体が印）。
+    //   jobEndDetail の人向けの文は今までのまま残す（管制が知らないうちは黙って捨てられる）。
+    if (f.finishGate !== undefined)
+        body.finishGate = f.finishGate;
     return body;
 }
 /** 控えを手元に書く（★届くまで消さない）。書けたか返す。 */
@@ -3310,12 +3416,16 @@ export async function keepaliveTick(cfg, state, deps = {}) {
             return;
         }
         // 完了は従来の経路（画面の DONE 行）にそのまま乗せる。★報告は職人が書いたファイルから読む。
-        const report = readReport(ka.id);
+        //   ★形が整っていない報告は添えない・移さない（便 461be339）。
+        const kaDelivery = reportDelivery(ka.id);
+        const report = kaDelivery.delivered && kaDelivery.raw !== null
+            ? parseReport(kaDelivery.raw).body
+            : null;
         if (await complete(cfg, ka.id, report)) {
             if (report !== null)
                 markReportProcessed(ka.id); // ★消さずに処理済みへ（二度送らない）
             logLine(`site=${cfg.site} id=${ka.id} 見張り終了: 画面のDONEを検出し完了を報告` +
-                `${report != null ? '（報告添付）' : ''}`);
+                `${report != null ? '（報告添付）' : kaDelivery.phase === 'none' ? '' : `（${kaDelivery.note}）`}`);
             // ★終わったら必ず手を下ろす（挙げっぱなしにすると現場が長くふさがる）。
             noteBusyEdge(state, cfg.site, ka.id, false, logLine);
             state.keepalive = null;
@@ -3501,7 +3611,8 @@ export async function relayTick(cfg, state, hooks) {
                         endKind: 'not_started',
                         exitCode: null,
                         exitSignal: null,
-                        reportDelivered: reportPhase(state.pending.id) !== 'none',
+                        // ★「作業なし・本文未着」の申告は形の確かめから外してある（便 461be339）。
+                        reportDelivered: reportDelivery(state.pending.id).delivered,
                         processEndObserved: false,
                         detail: '配り役が本文未着と申告した便（職人の処理は中継が持っていない）',
                     }, { logLine: log });
@@ -3543,7 +3654,7 @@ export async function relayTick(cfg, state, hooks) {
                             endKind: 'completed',
                             exitCode: null,
                             exitSignal: null,
-                            reportDelivered: report != null || reportPhase(state.pending.id) !== 'none',
+                            reportDelivered: report != null || reportDelivery(state.pending.id).delivered,
                             processEndObserved: false,
                             detail: '配り役が完了の知らせで確かめた（職人の処理は中継が持っていない）',
                         }, { logLine: log });
@@ -3556,7 +3667,8 @@ export async function relayTick(cfg, state, hooks) {
             if (below !== null && hasStandaloneDone(below, cfg.site)) {
                 // ★報告は画面から読まない。職人が書いたファイルを読む（relayReportDirs / readReport）。
                 //   画面を読む方式は窓が 16〜34 行しかなく、9/5 以降 162 回すべて失敗していた（調査 d1d16a56）。
-                const reportThere = reportPhase(state.pending.id) !== 'none';
+                // ★「届いた」は形まで見る（便 461be339）。整っていなければ理由も一緒に届ける。
+                const doneDelivery = reportDelivery(state.pending.id);
                 const ok = await completeWithReport(cfg, state.pending.id, log);
                 if (ok) {
                     // ★終了の事実を同じ項目で届ける（便 915694ac・1-3）。画面へ貼る方式では実プロセスを
@@ -3568,9 +3680,10 @@ export async function relayTick(cfg, state, hooks) {
                         endKind: 'completed',
                         exitCode: null,
                         exitSignal: null,
-                        reportDelivered: reportThere,
+                        reportDelivered: doneDelivery.delivered,
                         processEndObserved: false,
-                        detail: '配り役が画面の完了の合図で確かめた（職人の処理は中継が持っていない）',
+                        detail: '配り役が画面の完了の合図で確かめた（職人の処理は中継が持っていない）'
+                            + (doneDelivery.note !== null ? `／${doneDelivery.note}` : ''),
                     }, { logLine: log });
                     state.pending = null;
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyhld/conductor",
-  "version": "0.12.89",
+  "version": "0.12.90",
   "description": "采配くん管制の見守りアプリ（conductor-agent）。各PCで常駐し、中央(devlog-tracker)へ定期的に生存報告(heartbeat)を送る常駐CLI。",
   "type": "module",
   "bin": {

package/sales-template/setup.sh

@@ -862,7 +862,9 @@ GUARD_FILES=(
   finish_gate.py              # stop_hook が使う「便の終わりの関門」の判定（便 7aa63a97）
 )
 GUARD_ENTRYPOINTS=(cc2_guard.py permission_request_hook.py stop_hook.py notification_hook.py)
-GUARD_CONFIGS=(safe_verbs.json network_allow.json)  # 任意・あれば同居させる
+# ★この一覧は scripts/update-guard.sh の INSTALL_CONFIGS と【同じ集合】にすること。
+#   report-shape.json … 報告の「形」の決まりの正本（finish_gate.py が実行時に読む・便 461be339）。
+GUARD_CONFIGS=(safe_verbs.json network_allow.json report-shape.json)  # 任意・あれば同居させる
 
 # --- ⑤-0 見本と「配る中身」がズレていないか機械照合する（★足し忘れの再発防止） ---
 # 見本が呼ぶ入口スクリプトが (a) 正本にあるか (b) 上の GUARD_FILES に入っているか を確かめる。

package/scripts/hooks/finish_gate.py

@@ -124,44 +124,153 @@ def read_report_text(command_id, env=None):
 
 # ─────────────────────────────────────────────────────────────────────────────
 # (2) 報告が無い・下書きのまま
+#
+# 【★形の決まりの正本は1か所（便 461be339）】
+#   「囲みが閉じている／5つの欄が在る／outcome が決まった語／evidence が1件以上／本文が空でない」は
+#   中継（src/relay.ts の parseReport / missingOf）も同じ判定をする。同じ決まりを2か所に書くと、
+#   片方だけ直して食い違う（＝関門は差し戻すのに中継は届いたと数える、またはその逆）。
+#   だから決まりは `report-shape.json`（この python と同じフォルダに配られる）だけに置き、
+#   ここは【読み手】にする。中継の側は定数がこの JSON と同じであることを試験で固定する。
+#   ★読めなかったときは形の判定をしない（fail open＝関門が足される前と同じ動き）。
+#
+# 【★本文の言葉だけは別】下書きの印（作成中・TODO など）は関門だけの決まり。
+#   報告の中身の言葉で完了を判定しない（えふさん確定 2026-09-23）ので、中継からは手が届かない
+#   ところ（この下の DRAFT_MARKERS）に置く。正本はここ1か所。
 # ─────────────────────────────────────────────────────────────────────────────
-#: 囲み（front matter）に要る欄。鉄則「便の終え方」②のとおり。
-REQUIRED_KEYS = ('instruction_id', 'site', 'outcome', 'created_at', 'evidence')
-#: `outcome` に書ける値。
-VALID_OUTCOMES = ('pushed', 'no_change', 'blocked')
 #: 「最終版で差し替える前」の印。★決まった字面の一覧だけを見る（文意は読まない）。
 DRAFT_MARKERS = ('作成中', '下書き', '差し替える', 'あとで書く', '（未記入）', '(未記入)', 'TODO', 'TBD')
 
+#: 形の決まりの正本（★この python と同じフォルダに配られる）。
+SHAPE_SPEC_NAME = 'report-shape.json'
+
+#: 足りない物の名前 → 職人へ見せる日本語。
+_SHAPE_JA = {
+    'instruction_id': 'instruction_id の欄',
+    'site': 'site の欄',
+    'outcome': 'outcome（pushed / no_change / blocked のどれか1つ）',
+    'created_at': 'created_at の欄',
+    'evidence': 'evidence（1件以上）',
+    'body': '囲みの下の本文',
+}
+
+
+def shape_spec_path():
+    """形の決まりの正本の置き場（自分と同じフォルダ）。"""
+    return os.path.join(os.path.dirname(os.path.abspath(__file__)), SHAPE_SPEC_NAME)
+
+
+def load_shape_spec(path=None):
+    """形の決まりを読む。読めない・形が違うなら None（＝形の判定をしない）。"""
+    try:
+        with open(path or shape_spec_path(), encoding='utf-8') as f:
+            got = json.load(f)
+    except Exception:  # noqa: BLE001
+        return None
+    if not isinstance(got, dict):
+        return None
+    fields = got.get('requiredFields')
+    outcomes = got.get('validOutcomes')
+    if not isinstance(fields, list) or not fields or not all(isinstance(k, str) for k in fields):
+        return None
+    if not isinstance(outcomes, list) or not outcomes or not all(isinstance(k, str) for k in outcomes):
+        return None
+    return got
+
+
+#: 読み込んだ正本（無ければ None）。
+SHAPE_SPEC = load_shape_spec()
 
-def report_residue(text):
-    """報告が「無い・下書きのまま」なら理由、出来上がっていれば None。★純粋関数。"""
+_KV_RE = re.compile(r'^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$')
+_BULLET_RE = re.compile(r'^\s*-\s+(.*)$')
+
+
+def _parse_report(text):
+    """報告を欄と本文に分ける（★中継の parseReport と同じ読み方）。
+
+    返り: (欄の辞書, evidence の一覧, 本文)。囲みが無い・閉じていないときは
+    欄も evidence も空で、全文が本文になる（中継と同じ倒れ方）。
+    """
+    raw = '' if text is None else str(text)
+    if raw.startswith(''):
+        raw = raw[1:]
+    lines = raw.split('\n')
+    i = 0
+    while i < len(lines) and lines[i].strip() == '':
+        i += 1
+    if i >= len(lines) or lines[i].strip() != '---':
+        return {}, [], raw.strip()
+    fields, evidence, last_key = {}, [], ''
+    j = i + 1
+    closed = False
+    while j < len(lines):
+        line = lines[j]
+        if line.strip() == '---':
+            closed = True
+            break
+        bullet = _BULLET_RE.match(line)
+        if bullet is not None:
+            if last_key == 'evidence' and bullet.group(1).strip() != '':
+                evidence.append(bullet.group(1).strip())
+            j += 1
+            continue
+        kv = _KV_RE.match(line)
+        if kv is None:
+            j += 1
+            continue
+        last_key = kv.group(1).lower()
+        value = kv.group(2).strip()
+        if last_key == 'evidence':
+            if value != '':
+                evidence.append(value)
+            j += 1
+            continue
+        fields[last_key] = value
+        j += 1
+    if not closed:
+        return {}, [], raw.strip()
+    return fields, evidence, '\n'.join(lines[j + 1:]).strip()
+
+
+def report_shape_missing(text, spec=None):
+    """報告の「形」で足りない物を並べる（空なら整っている）。★純粋関数。
+
+    ★正本が読めないときは [] を返す（形の判定をしない＝退行しない）。
+    """
+    rules = SHAPE_SPEC if spec is None else spec
+    if not rules:
+        return []
+    fields, evidence, body = _parse_report(text)
+    outcomes = tuple(rules['validOutcomes'])
+    out = []
+    for key in rules['requiredFields']:
+        if key == 'body':
+            if body.strip() == '':
+                out.append(key)
+        elif key == 'evidence':
+            if not evidence:
+                out.append(key)
+        elif key == 'outcome':
+            if (fields.get('outcome') or '').strip() not in outcomes:
+                out.append(key)
+        elif not (fields.get(key) or '').strip():
+            out.append(key)
+    return out
+
+
+def report_body(text):
+    """報告の本文（囲みの下）。囲みが無い・閉じていないときは全文。★純粋関数。"""
+    return _parse_report(text)[2]
+
+
+def report_residue(text, spec=None):
+    """報告が「無い・形が整っていない・下書きのまま」なら理由、出来上がっていれば None。"""
     if text is None or not text.strip():
         return '報告ファイルが無い（または空）'
-    lines = text.strip().splitlines()
-    if lines[0].strip() != '---':
-        return '報告の1行目に囲み（---）が無い'
-    try:
-        end = next(i for i in range(1, len(lines)) if lines[i].strip() == '---')
-    except StopIteration:
-        return '報告の囲みが閉じていない（2つめの --- が無い）'
-    head = lines[1:end]
-    body = '\n'.join(lines[end + 1:]).strip()
-    keys = {}
-    for ln in head:
-        m = re.match(r'^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$', ln)
-        if m:
-            keys[m.group(1)] = m.group(2).strip()
-    missing = [k for k in REQUIRED_KEYS if k not in keys]
+    missing = report_shape_missing(text, spec)
     if missing:
-        return f'報告の囲みに足りない欄がある（{"・".join(missing)}）'
-    if keys['outcome'] not in VALID_OUTCOMES:
-        return f'報告の outcome が pushed / no_change / blocked のどれでもない（{keys["outcome"] or "空"}）'
-    # evidence は「- 」で始まる行が1つ以上要る。
-    if not any(ln.strip().startswith('- ') for ln in head):
-        return '報告の evidence が1件も無い'
-    if not body:
-        return '報告の本文が空（囲みだけ）'
-    hit = next((m for m in DRAFT_MARKERS if m in body), None)
+        return ('報告の形が整っていない（足りない: '
+                + '・'.join(_SHAPE_JA.get(k, k) for k in missing) + '）')
+    hit = next((m for m in DRAFT_MARKERS if m in report_body(text)), None)
     if hit is not None:
         return f'報告が下書きのまま（本文に「{hit}」が残っている）'
     return None
@@ -306,13 +415,25 @@ def save_counts(command_id, counts, env=None):
         pass
 
 
-def save_residue(command_id, text, env=None):
-    """上限に達して終わらせた理由を残す（中継が終了の事実へ載せる）。"""
+def save_residue(command_id, record, env=None):
+    """上限に達して終わらせた理由を残す（中継が終了の事実へ載せる）。
+
+    record は `build_residue_record()` の辞書（人向けの1行＋機械が読む形）。
+    ★文字列を渡したときは人向けの1行だけとして扱う（古い呼び方も通る）。
+    """
+    if isinstance(record, str):
+        record = {'text': record}
+    text = str(record.get('text') or '').strip()[:500]
+    out = {'text': text}
+    if isinstance(record.get('reasons'), list):
+        out['reasons'] = [k for k in record['reasons'] if k in GATE_KINDS]
+    if isinstance(record.get('counts'), dict):
+        out['counts'] = {k: int(record['counts'].get(k, 0)) for k in GATE_KINDS}
     p = residue_path(command_id, env)
     try:
         os.makedirs(os.path.dirname(p), mode=0o700, exist_ok=True)
         with open(p, 'w', encoding='utf-8') as f:
-            f.write(text.strip()[:500])
+            json.dump(out, f, ensure_ascii=False)
     except Exception:  # noqa: BLE001
         return False
     return True
@@ -396,3 +517,20 @@ def build_reason(result):
 def build_residue_text(result):
     """上限に達して終わらせたときに控えへ残す1行（管制へ「途中で終わった」として届く）。"""
     return '途中で終わった（便の終わりの関門の上限）: ' + ' / '.join(result['reasons'])
+
+
+def build_residue_record(result):
+    """控えに残す中身（人向けの1行＋★管制が機械で読む形）。★純粋関数。
+
+    【なぜ機械で読む形も要るか（便 461be339）】上限に達して終わらせた便は、これまで
+      人向けの自由な文（`jobEndDetail`）にしか理由が乗らなかった。管制では「終わった」と
+      「途中で終わった」を機械で見分けられない（実地 7aa63a97 の残った穴）。
+      ★新しい状態は作らず、終了の事実に `finishGate` の欄を足して届ける。
+
+    返り: {'text': 人向けの1行, 'reasons': 残っていた種類, 'counts': 止めた回数}
+    """
+    return {
+        'text': build_residue_text(result),
+        'reasons': [k for k in GATE_KINDS if k in result['kinds']],
+        'counts': {k: int(result['counts'].get(k, 0)) for k in GATE_KINDS},
+    }

package/scripts/hooks/report-shape.json

@@ -0,0 +1,243 @@
+{
+  "_note": [
+    "★報告の「形」の決まりの正本。ここが1か所で、他に同じ決まりを書かない（便 461be339）。",
+    "  読む側は2つ。",
+    "   ① 中継（src/relay.ts の parseReport / missingOf）… 報告を「届いた」と数える条件。",
+    "      ★relay.ts の REQUIRED_REPORT_FIELDS / REPORT_OUTCOMES がこの値と同じであることを",
+    "        test/report-shape-gate.test.ts が固定する（食い違えば CI が赤くなる）。",
+    "   ② 便の終わりの関門（scripts/hooks/finish_gate.py）… 手番を閉じさせるかの判定。",
+    "      ★この JSON を実行時に読む（同じフォルダに配られる）。読めなければ形の判定はしない。",
+    "  ★cases は「同じ字面に同じ答えを出す」ことの答え合わせの正本。①②の両方の試験が流す。",
+    "★本文の言葉の印（「作成中」「TODO」など下書きの印）はここに置かない。",
+    "  報告の中身の言葉で完了を判定しない（えふさん確定 2026-09-23）ので、中継からは",
+    "  言葉の決まりに手が届かない形にしておく。下書きの印は関門だけの決まりで、",
+    "  正本は scripts/hooks/finish_gate.py の DRAFT_MARKERS。"
+  ],
+  "version": 1,
+  "_requiredFields_note": "★並び順まで中継の missingOf と同じにする（答え合わせを順序ごと比べる）。",
+  "requiredFields": [
+    "instruction_id",
+    "site",
+    "outcome",
+    "created_at",
+    "evidence",
+    "body"
+  ],
+  "validOutcomes": [
+    "pushed",
+    "no_change",
+    "blocked"
+  ],
+  "_cases_note": "text をこの決まりで読んだとき、足りない物が missing と1つも違わないこと。",
+  "cases": [
+    {
+      "name": "★最終版（これが基本の形）",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\n---\n\nやりました。",
+      "missing": []
+    },
+    {
+      "name": "no_change でも通る",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: no_change\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\n---\n\nやりました。",
+      "missing": []
+    },
+    {
+      "name": "blocked でも通る",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: blocked\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\n---\n\nやりました。",
+      "missing": []
+    },
+    {
+      "name": "空",
+      "text": "",
+      "missing": [
+        "instruction_id",
+        "site",
+        "outcome",
+        "created_at",
+        "evidence",
+        "body"
+      ]
+    },
+    {
+      "name": "空白と改行だけ",
+      "text": "   \n \n",
+      "missing": [
+        "instruction_id",
+        "site",
+        "outcome",
+        "created_at",
+        "evidence",
+        "body"
+      ]
+    },
+    {
+      "name": "囲みが無い（古い自由形式）",
+      "text": "作業しました。\n直したファイル: src/relay.ts\n",
+      "missing": [
+        "instruction_id",
+        "site",
+        "outcome",
+        "created_at",
+        "evidence"
+      ]
+    },
+    {
+      "name": "★囲みが閉じていない（書きかけで落ちた形）",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\n\nやりました。",
+      "missing": [
+        "instruction_id",
+        "site",
+        "outcome",
+        "created_at",
+        "evidence"
+      ]
+    },
+    {
+      "name": "★囲みだけ・本文が空（実地 47bdfe00 の形）",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\n---\n\n",
+      "missing": [
+        "body"
+      ]
+    },
+    {
+      "name": "本文が空白だけ",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\n---\n\n   \n  ",
+      "missing": [
+        "body"
+      ]
+    },
+    {
+      "name": "instruction_id の欄が無い",
+      "text": "---\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\n---\n\nやりました。",
+      "missing": [
+        "instruction_id"
+      ]
+    },
+    {
+      "name": "site が空",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: \noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\n---\n\nやりました。",
+      "missing": [
+        "site"
+      ]
+    },
+    {
+      "name": "outcome が決まった語でない",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: やりました\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\n---\n\nやりました。",
+      "missing": [
+        "outcome"
+      ]
+    },
+    {
+      "name": "outcome が空",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: \ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\n---\n\nやりました。",
+      "missing": [
+        "outcome"
+      ]
+    },
+    {
+      "name": "created_at の欄が無い",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\nevidence:\n  - PR https://example.invalid/1\n---\n\nやりました。",
+      "missing": [
+        "created_at"
+      ]
+    },
+    {
+      "name": "evidence の欄が在るが1件も無い",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n---\n\nやりました。",
+      "missing": [
+        "evidence"
+      ]
+    },
+    {
+      "name": "evidence の欄そのものが無い",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\n---\n\nやりました。",
+      "missing": [
+        "evidence"
+      ]
+    },
+    {
+      "name": "evidence が同じ行に書かれている（1件と数える）",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence: PR https://example.invalid/1\n---\n\nやりました。",
+      "missing": []
+    },
+    {
+      "name": "囲みの中も本文も空",
+      "text": "---\n---\n",
+      "missing": [
+        "instruction_id",
+        "site",
+        "outcome",
+        "created_at",
+        "evidence",
+        "body"
+      ]
+    },
+    {
+      "name": "★箇条書きが evidence の下でなければ evidence と数えない",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nnote:\n  - これは証拠ではない\n---\n\nやりました。",
+      "missing": [
+        "evidence"
+      ]
+    },
+    {
+      "name": "知らない欄が混じっていても通る",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\nbranch: fix/x\npr_number: 256\n---\n\nやりました。",
+      "missing": []
+    },
+    {
+      "name": "欄の名前が大文字でも通る",
+      "text": "---\nInstruction_Id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\n---\n\nやりました。",
+      "missing": []
+    },
+    {
+      "name": "囲みの前に空行があっても通る",
+      "text": "\n\n---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\n---\n\nやりました。",
+      "missing": []
+    },
+    {
+      "name": "先頭に BOM があっても通る",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\n---\n\nやりました。",
+      "missing": []
+    },
+    {
+      "name": "★本文に下書きの言葉が残っていても形としては通る（中継は本文の言葉を読まない）",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\n---\n\n# 便 915694ac 報告（作成中）\n\nこの見出しは最終版で差し替える。",
+      "missing": []
+    },
+    {
+      "name": "★続きの報告（詳しい中身を別の記録へ分けた形）も通る",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\n---\n\n結論だけ書きます。詳しい中身は開発履歴の「7aa63a97 報告 1/3」〜「3/3」。",
+      "missing": []
+    },
+    {
+      "name": "読めない行が混じっていても欄の解釈は壊れない",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\n（この行は欄ではない）\n====\n---\n\nやりました。",
+      "missing": []
+    },
+    {
+      "name": "「- 」だけの箇条書きは evidence と数えない",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - \n---\n\nやりました。",
+      "missing": [
+        "evidence"
+      ]
+    },
+    {
+      "name": "evidence の箇条書きがタブ区切りでも1件と数える",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: pushed\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n\t-\tPR https://example.invalid/2\n---\n\nやりました。",
+      "missing": []
+    },
+    {
+      "name": "同じ欄が2回あれば後が勝つ",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\nsite: demo\noutcome: やりました\ncreated_at: 2026-10-03T09:00:00+09:00\nevidence:\n  - PR https://example.invalid/1\noutcome: pushed\n---\n\nやりました。",
+      "missing": []
+    },
+    {
+      "name": "欄が足りず本文も空（複数同時）",
+      "text": "---\ninstruction_id: 7aa63a97-57e7-4c42-8b95-f3da87d88829\noutcome: pushed\nevidence:\n  - PR https://example.invalid/1\n---\n\n",
+      "missing": [
+        "site",
+        "created_at",
+        "body"
+      ]
+    }
+  ]
+}

package/scripts/hooks/stop_hook.py

@@ -307,7 +307,7 @@ def finish_gate_block(data, env=None):
         return finish_gate.build_reason(result)
     if result['kinds']:
         # 上限に達した＝これ以上止めない。理由だけ残して終わらせる。
-        finish_gate.save_residue(command_id, finish_gate.build_residue_text(result), env)
+        finish_gate.save_residue(command_id, finish_gate.build_residue_record(result), env)
     return None
 
 

package/scripts/hooks/test_finish_gate.py

@@ -194,6 +194,16 @@ check('★上限に達したら止めない（便が終わる）', d['block'], F
 check('★ただし「途中で終わった」と分かる（種類が残る）', d['kinds'], ['report'])
 truthy('控えの文に理由が入る', '途中で終わった' in finish_gate.build_residue_text(d))
 
+print('--- ★控えは「管制が機械で読める形」でも残す（便 461be339） ---')
+rec = finish_gate.build_residue_record(d)
+truthy('人向けの1行は今までどおり', '途中で終わった' in rec['text'])
+check('★残っていた種類が入る', rec['reasons'], ['report'])
+check('★止めた回数が3種類ぶん入る', rec['counts'], {'report': 3, 'pr': 0, 'background': 0})
+rec3 = finish_gate.build_residue_record(
+    finish_gate.decide({'report': 'a', 'pr': 'b', 'background': 'c'},
+                       {'report': 3, 'pr': 3, 'background': 3}, cap=3))
+check('3つ残ったまま終わったら3つとも入る', rec3['reasons'], ['report', 'pr', 'background'])
+
 check('残りが無ければ止めない', finish_gate.decide({}, {}, cap=3)['block'], False)
 check('残りが無ければ種類も空', finish_gate.decide({}, {'report': 1}, cap=3)['kinds'], [])
 
@@ -291,7 +301,10 @@ check('その後は止めない',
 rp = finish_gate.residue_path(JOB, ENV)
 truthy('理由の控えが残る', os.path.isfile(rp))
 with open(rp, encoding='utf-8') as f:
-    truthy('控えに「途中で終わった」と入っている', '途中で終わった' in f.read())
+    got = json.load(f)
+truthy('控えに「途中で終わった」と入っている', '途中で終わった' in got['text'])
+check('★控えの種類を中継が機械で読める', got.get('reasons'), ['report'])
+check('★控えの回数は上限ちょうど', (got.get('counts') or {}).get('report'), finish_gate.CAP_PER_KIND)
 
 print('--- ★便の本文が「合流は人が行う」なら PR を見ない ---')
 clear_counts()

package/scripts/hooks/test_report_shape.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""報告の「形」の判定が、決まりの正本どおりであることの検査（便 461be339）。
+
+  実行: python3 scripts/hooks/test_report_shape.py
+  1件でも期待と違えば exit 1。
+
+【なぜ要るか】形の決まりは2か所から読まれる。
+  ① 中継（`src/relay.ts`）… 報告を「届いた」と数える条件
+  ② 便の終わりの関門（`finish_gate.py`）… 手番を閉じさせるかの判定
+  同じ決まりを2か所に書くと、片方だけ直して食い違う（＝関門は差し戻すのに中継は届いたと数える、
+  またはその逆）。だから決まりは `report-shape.json` の1か所だけに置き、
+  **同じ字面に同じ答えを出すこと**を両方の試験で固定する。
+  ★中継の側は `test/report-shape-gate.test.ts` が、この同じ `cases` を流して突き合わせる。
+
+【ここで固定すること】
+  (A) 正本が読めること（配り忘れ・壊れた JSON に気づける）
+  (B) 正本の `cases` の答えと、関門の判定が1件も違わないこと
+  (C) 正本が読めないときは形の判定をしない（fail open＝関門が足される前と同じ動き）
+  (D) ★下書きの印（本文の言葉）は正本に載せない
+      ＝中継からは言葉の決まりに手が届かない（えふさん確定 2026-09-23）
+  (E) 形と下書きの印は別の理由として返る
+
+★空振り確認（隔離した worktree の中だけ）:
+  ・`report-shape.json` の `requiredFields` から1つ消す → (B) が落ちる
+  ・`report_shape_missing` の outcome の確かめを外す → (B) が落ちる
+"""
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import finish_gate  # noqa: E402
+
+failures = []
+
+
+def check(label, got, want):
+    ok = got == want
+    if not ok:
+        failures.append(f'{label}: got={got!r} want={want!r}')
+    print(f'{"OK " if ok else "NG "} {label:70} {str(got)[:40]}')
+
+
+def truthy(label, got):
+    ok = bool(got)
+    if not ok:
+        failures.append(f'{label}: got={got!r} want=真')
+    print(f'{"OK " if ok else "NG "} {label:70} {str(got)[:40]}')
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+print('=== (A) 形の決まりの正本が読めるか ===')
+# ─────────────────────────────────────────────────────────────────────────────
+path = finish_gate.shape_spec_path()
+check('正本の置き場は自分と同じフォルダ', os.path.basename(path), 'report-shape.json')
+truthy('正本が在る', os.path.isfile(path))
+spec = finish_gate.load_shape_spec()
+truthy('正本が読める', spec)
+check('★関門は読み込み済みの正本を使う', finish_gate.SHAPE_SPEC is not None, True)
+check('足りない物の並び順まで決まっている',
+      spec['requiredFields'],
+      ['instruction_id', 'site', 'outcome', 'created_at', 'evidence', 'body'])
+check('outcome に書ける語', spec['validOutcomes'], ['pushed', 'no_change', 'blocked'])
+truthy('答え合わせの cases が在る', isinstance(spec.get('cases'), list) and spec['cases'])
+
+# ─────────────────────────────────────────────────────────────────────────────
+print(f'\n=== (B) 正本の cases（{len(spec["cases"])}件）の答えと1件も違わない ===')
+# ─────────────────────────────────────────────────────────────────────────────
+for case in spec['cases']:
+    check(case['name'][:68], finish_gate.report_shape_missing(case['text']), case['missing'])
+
+# ─────────────────────────────────────────────────────────────────────────────
+print('\n=== (C) 正本が読めないときは形の判定をしない（退行しない） ===')
+# ─────────────────────────────────────────────────────────────────────────────
+check('正本が無い → 足りない物は並べない', finish_gate.report_shape_missing('やりました。', {}), [])
+check('正本が壊れていても落ちない', finish_gate.load_shape_spec('/nope/report-shape.json'), None)
+check('requiredFields が無い正本は使わない',
+      finish_gate.load_shape_spec(os.path.join(os.path.dirname(path), 'safe_verbs.json')), None)
+good = spec['cases'][0]['text']
+check('★正本が読めなくても「報告が無い」は今までどおり止める',
+      bool(finish_gate.report_residue(None, {})), True)
+check('★正本が読めないときは形で止めない（fail open）',
+      finish_gate.report_residue(good, {}), None)
+
+# ─────────────────────────────────────────────────────────────────────────────
+print('\n=== (D) ★下書きの印（本文の言葉）は正本に載せない ===')
+# ─────────────────────────────────────────────────────────────────────────────
+raw = open(path, encoding='utf-8').read()
+body_rules = json.loads(raw)
+for marker in ('作成中', '下書き', '差し替える', 'あとで書く', 'TODO', 'TBD'):
+    check(f'正本の決まりに「{marker}」が入っていない',
+          any(marker in json.dumps(body_rules.get(k), ensure_ascii=False)
+              for k in ('requiredFields', 'validOutcomes')),
+          False)
+truthy('下書きの印の正本は関門の側にある', finish_gate.DRAFT_MARKERS)
+
+# ─────────────────────────────────────────────────────────────────────────────
+print('\n=== (E) 形と下書きの印は別の理由として返る ===')
+# ─────────────────────────────────────────────────────────────────────────────
+draft = next(c for c in spec['cases'] if '下書きの言葉' in c['name'])
+check('★下書きの言葉が残った報告は、形としては整っている',
+      finish_gate.report_shape_missing(draft['text']), [])
+r = finish_gate.report_residue(draft['text'])
+truthy('それでも関門は下書きとして差し戻す', r)
+truthy('  理由は「下書き」だと分かる', '下書き' in (r or ''))
+broken = next(c for c in spec['cases'] if c['missing'] == ['body'])
+r2 = finish_gate.report_residue(broken['text'])
+truthy('形が整っていない報告は「形」の理由で差し戻す', r2)
+truthy('  理由は「形が整っていない」だと分かる', '形が整っていない' in (r2 or ''))
+truthy('  足りない物の名前が入る', '本文' in (r2 or ''))
+check('★最終版は差し戻さない', finish_gate.report_residue(good), None)
+check('本文の取り出しは囲みの下だけ', finish_gate.report_body(good).startswith('やりました'), True)
+check('囲みが無ければ全文が本文', finish_gate.report_body('ただの文'), 'ただの文')
+
+print('\n' + '=' * 72)
+if failures:
+    print(f'NG {len(failures)} 件')
+    for f in failures:
+        print('  ' + f)
+    sys.exit(1)
+print('すべて期待どおり')

package/scripts/update-guard.sh

@@ -438,7 +438,11 @@ INSTALL_FILES=(
   hook_datalink.py            # 各フックが使う管制との連絡線
   finish_gate.py              # stop_hook が使う「便の終わりの関門」の判定（便 7aa63a97）
 )
-INSTALL_CONFIGS=(safe_verbs.json network_allow.json)
+# ★番人と同居させる設定（任意・あれば一緒に置く）。この一覧は sales-template/setup.sh の
+#   GUARD_CONFIGS と【同じ集合】にすること（test/setup-installer.test.ts が同一を固定する）。
+#   report-shape.json … 報告の「形」の決まりの正本（finish_gate.py が実行時に読む・便 461be339）。
+#     配り忘れると関門が形を見られない（fail open＝書きかけを差し戻せない）。
+INSTALL_CONFIGS=(safe_verbs.json network_allow.json report-shape.json)
 ENTRYPOINTS=(cc2_guard.py permission_request_hook.py stop_hook.py notification_hook.py)
 
 # ①-0 見本と「配る中身」がズレていないか機械照合する（今回と同じ欠落事故の再発防止＝根治）。