phasegate 0.162.0 → 0.165.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.165.0] - 2026-07-05
+
+### Added
+
+- **WI-224 — 手1 signed-attestation PoC (`attestation` unit, unsigned-poc mode)** — adds a new additive `attestation` unit (Clean Architecture: domain / application / infrastructure / presentation) that produces and mechanically re-verifies a content-addressed attestation document for a `phasegate:ci-check` gate run. Purely additive: it does not modify or run inside any existing gate (ADR-020 compliant).
+  - **2 つの opt-in CLI コマンド**: `phasegate:attest`（`phasegate:ci-check` の結果から署名付き attestation ドキュメントを生成）/ `phasegate:verify-attestation <file>`（生成済みドキュメントを鍵なしで機械的に再検証）。既存ゲートの経路には注入しない独立コマンド。
+  - **記録内容**: validator-set + per-validator result（`{ validatorId, passed, skipped }`）+ 入力 digest（`phasegate.config.json` / requirement-test-matrix / git SHA）+ **granularity / known-limitations ブロック**。granularity は L3-004 のトレーサビリティが **FILE-LEVEL（per-AC ではない）** であることを機械的に記録し、粗い green を細かい保証として詐称（laundering）できないようにする。
+  - **`unsigned-poc` signature モード**: content-addressed self-digest（`attestationDigest`）で **改竄検知 / INTEGRITY のみ** を証明する（発行者の真正性 / AUTHENTICITY は証明しない）。`signature.mode` discriminator を予約し、後から本物の ed25519 署名を差し込めるようにした。`--mode signed` は現状 "not yet implemented"（exit 2）。
+  - **決定論**: `attestationDigest` は signature ブロックと volatile な metadata（`producedAt` / `gitCommit`）を除去した canonical payload 上で算出するため verify が再現可能。attestation の既定出力先は `.harness/attestation.json`（gitignore 済み）。
+  - ストーリー H16-01 / H16-02 を追加。L3-004 のトレーサビリティは引き続き green（Missing tests: 0）。
+
 ## [0.162.0] - 2026-07-04
 
 ### Fixed

package/docs/ADR/019-ai-independence-boundary.md

@@ -0,0 +1,63 @@
+---
+adr_id: "019"
+title: "「AI 非依存」の境界 — trust 境界は機械的、AI は生成のみ"
+status: Accepted
+date: 2026-07-05
+---
+
+# 「AI 非依存」の境界 — trust 境界は機械的、AI は生成のみ
+
+## Context
+
+ADR-006（エージェント非依存設計原則）は、全バリデータが **ファイルシステムに書き込まれた成果物のみ**（path / 内容 / AST）を検査対象とし、エージェント固有の API に依存しないことを定めた。
+
+2026-07-04 の監査メモ（`docs/inception/_shared/security_audit_2026-07-04.md` §1）は、この「AI 非依存」の**粒度が曖昧**であることを指摘した。
+
+- 「品質ルールが agent 非依存」は真である。
+- しかし「全機能が agent 非依存」は偽である。phasegate 自身が、意味のある成果物を **生成する** ための AI 駆動・phasegate 固有スキル（`story-implementor`, `quick-implementor` など）を既に同梱しており、これらは AI エージェントが実行する。すなわち **生成側には既に AI が存在する**。
+
+一方、汎用化ロードマップが挙げるセマンティック系のアイデア（semantic triple graph / AC 単位のトレーサビリティ、name-equivalence / ユビキタス言語レジストリ、rationale 必須化）は、素朴に LLM 推論へ寄せると、次のいずれかのリスクを負う。
+
+- AI 非依存という価値提案そのものを壊す（検証に AI 判断が混入する）
+- あるいは著者に過大な記述負担を課す
+
+新しい先例として **artifact-conformance test**（例: `scripts/harness/__tests__/unit/skill-quality/quick-implementor-skill-conformance.test.ts`、story H10-04）がある。これは markdown 成果物が特定の必須ディレクティブを含むかを **LLM を一切使わず機械的に** アサートするものであり、機械的（＝ AI 非依存）検証が raw AST よりさらに遠くまで届くことの証左である。
+
+## Decision
+
+「AI 非依存」を、全機能の性質ではなく **trust 境界（バリデータ / ゲート / 今後導入する attestation）の性質** として厳密に再定義する。この命名を明示することで、監査が指摘した曖昧さを解消する。
+
+1. **trust を付与する検査 — attestable な「green」を生み得るすべて — は、厳密に機械的かつ再現可能であり続ける。** 対象は path / 内容 / AST / content-conformance アサーション、およびユーザーが記述したレジストリ・アノテーションに対する整合性検査である。**LLM / AI 判断が検証（validation）の一部になることは決してない。**
+
+2. **AI は生成側で許容され、かつ期待される。** phasegate 固有スキルが成果物を生成する用途、および著者の補助として AI を使ってよい。ただし AI が生成したすべての成果物は、その後に機械的ゲートで検証される。**AI が trust を付与することはない。**
+
+3. **セマンティックな要件（name-equivalence、intent / rationale）は、ユーザーが記述したデータ** — ユビキタス言語レジストリ、AC 単位のアノテーション、ADR / WI リンクの必須化 — として表現し、それを **機械的に** 検査することで機械化する。**LLM 推論では機械化しない。**
+
+4. 本決定は **ADR-006 を維持・先鋭化するもの**であり、そのスコープを精緻化する（supersede しない）。
+
+5. 明示的に、**AI 補助のバリデータ tier は導入しない。** 将来あるセマンティック検査がそれを正当化する場合でも、それ自身の tightly-scoped な ADR を必要とし、non-blocking（advisory）でなければならず、attestation から除外されなければならない。
+
+位置づけの要約:
+
+| 側 | AI の可否 | trust の源泉 |
+|----|----------|-------------|
+| 生成（成果物の作成・著者補助） | 許容・期待 | trust は付与しない |
+| 検証（ゲート / attestation） | 不可 | 機械的・再現可能な検査のみ |
+
+## Consequences
+
+- attestation が絶対的かつ再現可能になる。誰でも AI なしで「green」を再検証できる。
+- セマンティックカバレッジは、レジストリ / アノテーションが表現できる範囲に有界となる（著者の記述負担を受け入れる）。
+- 「チェッカーは常に機械である」というアイデンティティが保たれる。
+- モデル / バージョンのドリフトでゲートが flaky になることがない。
+- 計画中の署名付き attestation（signed-attestation）ワークを可能にする土台となる。
+
+## Alternatives
+
+1. **現状維持** — 曖昧なまま「AI 非依存」を全機能の性質として語る。監査が指摘した矛盾を放置するため不採用。
+
+2. **機械的ゲート + non-blocking な AI-advisory バリデータ tier** — 現時点では不採用。理由は (a) gate-creep のリスク（advisory が事実上のゲート化する）、(b) AI の findings は再現不能で attestation を毀損する。将来の tightly-scoped なオプションとしてのみ残す。
+
+3. **原則を「機械的に検証可能なら AI も許容（AI の出力が決定的に検査できる限り）」へ再定義** — 中核的な価値提案に対する変更が大きすぎるため不採用。
+
+関連: ADR-006（エージェント非依存設計原則）、ADR-020（単方向規律と逆流学習）、`docs/inception/_shared/security_audit_2026-07-04.md` §1。

package/docs/ADR/020-reverse-learning-forward-proposal.md

@@ -0,0 +1,52 @@
+---
+adr_id: "020"
+title: "単方向規律と逆流学習 — 逆流は前方草案を提案し、人が承認する"
+status: Accepted
+date: 2026-07-05
+---
+
+# 単方向規律と逆流学習 — 逆流は前方草案を提案し、人が承認する
+
+## Context
+
+`docs/folder_management_rules.md` §2 は、inception → product → src（実装）という **単方向のデータフロー** を定め、「逆流はフェーズゲートでブロックされます」と明記している。フェーズ依存レベル L1 → L2 → L3 は Quick Mode でも緩和不可である。
+
+現時点で存在する唯一の「逆流的」機構は L4-001 `drift-detect` のみである。これは advisory・default-off・観測的（warning-only）であり、強制も自動更新も行わない（ADR-017 / ADR-018 / `docs/guide/layer-model.md` §L4 参照）。
+
+汎用化ロードマップのアイデア (g) は「逆流学習（reverse learning）」— コードからの学習（design-smell 検出、pattern learning）— を求めている。ここには **逆流が「まずコードを書き、後から設計を埋める（code-first, backfill design later）」への裏口になる** リスクがある。それはフェーズゲートの中核規律を溶かす。
+
+## Decision
+
+単方向の **強制（enforcement）は維持され、交渉の余地はない。** 逆流が単一源（product / inception 文書）を直接書き換えることは決してなく、前方ゲート（forward gate）を緩和することも決してない。
+
+逆流学習は、次の形でのみ許容する。
+
+```
+検出（detect）           : drift / smell を機械的に、または advisory な L4 層で表面化
+   ↓
+前方草案の生成（propose）  : inception の WI または ADR の草案（draft）を生成
+   ↓
+人が承認（approve）        : 承認された草案が通常の前方フローに再投入される
+   ↓
+機械的な前方ゲートで検証     : 他のいかなる設計変更とも同じゲートを通過する
+```
+
+- 逆流が生み出すのは **提案（proposal）のみ** である。ゲートを迂回するものは何もない。これにより単方向性を壊すことなく学習ループを閉じる。
+- **ADR-019 との整合**: 草案生成のステップは AI スキル（生成側）を用いてよい。しかし trust は **人の承認 + 機械的な前方ゲート** が付与するのであって、AI が付与するのではない。
+- **L4 との関係**: 検出は L4-001 `drift-detect` を拡張しうるが、L4-001 は **advisory / default-off のまま** である。本決定は L4 を blocking へ昇格させない。新しい要素は「前方草案の提案 + 人の承認」経路のみである。
+
+## Consequences
+
+- 「コードから学ぶ」という価値を取り込みつつ、背骨（単方向規律）を無傷に保つ。
+- 提案 / 承認の機構が加わる（machinery のコスト）。rubber-stamp（形式承認）のリスクは、承認された草案が **他の設計変更と同じ前方ゲートを通過することを必須とする** ことで緩和する。
+- 単一源の自動書き換え（auto-mutation）は行わない。逆流学習の恩恵は「人の承認を経た草案」に限られる。
+
+## Alternatives
+
+1. **逆流を advisory のみに留め、提案は行わない（検出 + 報告のみ）** — 能力が低く学習ループを閉じられないため不採用。
+
+2. **前方草案の提案フロー（本決定で採用）** — 検出 → 前方草案の提案 → 人の承認 → 前方ゲートでの検証。
+
+3. **双方向フローを全面的に排除する** — 「コードから学ぶ」価値を放棄することになるため不採用。
+
+関連: ADR-019（「AI 非依存」の境界）、ADR-017（warning severity の集計）、ADR-018（drift-detect の design pointers）、`docs/folder_management_rules.md` §2、`docs/guide/layer-model.md` §L4。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.162.0",
+  "version": "0.165.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",

package/scripts/harness/attestation/application/dto/attestation-document.ts

@@ -0,0 +1,54 @@
+// @unit attestation
+// @layer application
+
+/**
+ * record format `phasegate-attestation/v1` の plain object 表現（logical_design §1.4.3）。
+ * ファイル入出力・stdout エコー・mapper の境界で用いる契約型。VO はプリミティブ展開する。
+ */
+export interface AttestationDocumentValidatorOutcome {
+  readonly validatorId: string;
+  readonly passed: boolean;
+  readonly skipped: boolean;
+}
+
+export interface AttestationDocumentSource {
+  readonly path: string;
+  readonly digest: string;
+}
+
+export interface AttestationDocumentGranularityClaim {
+  readonly validator: string;
+  readonly level: "file" | "ac";
+  readonly claim: string;
+  readonly knownLimitations: string[];
+}
+
+export interface AttestationDocument {
+  readonly schemaVersion: "phasegate-attestation/v1";
+  readonly predicateType: string;
+  readonly subject: {
+    readonly command: string;
+    readonly gateResult: "pass" | "fail";
+    readonly validatorSet: AttestationDocumentValidatorOutcome[];
+  };
+  readonly inputs: {
+    readonly digestAlgorithm: "sha256";
+    readonly sources: AttestationDocumentSource[];
+    readonly inputDigest: string;
+  };
+  readonly granularity: {
+    readonly traceability: AttestationDocumentGranularityClaim;
+  };
+  readonly metadata: {
+    readonly producedAt: string;
+    readonly producer: string;
+    readonly gitCommit: string | null;
+  };
+  readonly signature: {
+    readonly mode: "unsigned-poc" | "signed";
+    readonly attestationDigest: string;
+    readonly algorithm: string | null;
+    readonly keyId: string | null;
+    readonly value: string | null;
+  };
+}

package/scripts/harness/attestation/application/dto/produce-attestation-input.ts

@@ -0,0 +1,18 @@
+// @unit attestation
+// @layer application
+
+import type { SignatureMode } from "../../domain/value-objects/signature-block.js";
+
+/**
+ * attest usecase 入力 DTO（logical_design §4.1）。
+ */
+export interface ProduceAttestationInput {
+  /** record 出力先パス（既定は presentation で `.harness/attestation.json`）。 */
+  readonly out: string;
+  /** gateResult != "pass" なら record を一切出力せず exit 1。 */
+  readonly requirePass: boolean;
+  /** 生成 document を stdout へエコーするか。 */
+  readonly emitJson: boolean;
+  /** 署名モード。`signed` は not-yet-implemented。 */
+  readonly mode: SignatureMode;
+}

package/scripts/harness/attestation/application/dto/verify-attestation-input.ts

@@ -0,0 +1,12 @@
+// @unit attestation
+// @layer application
+
+/**
+ * verify usecase 入力 DTO（logical_design §4.1）。
+ */
+export interface VerifyAttestationInput {
+  /** 検証対象の attestation ファイルパス。 */
+  readonly filePath: string;
+  /** 各チェック結果を機械可読に出力するか。 */
+  readonly emitJson: boolean;
+}

package/scripts/harness/attestation/application/dto/verify-attestation-output.ts

@@ -0,0 +1,30 @@
+// @unit attestation
+// @layer application
+
+/**
+ * 機械的 5 チェックの個別結果（logical_design §1.4.4 / §4.1）。
+ */
+export interface VerifyAttestationChecks {
+  /** schema/shape 妥当 */
+  readonly schema: boolean;
+  /** mode サポート対象（signed は非対応） */
+  readonly mode: boolean;
+  /** canonical payload 上で attestationDigest 再計算 == 格納値 */
+  readonly attestationDigest: boolean;
+  /** inputs.sources[].digest を現在ファイルから再計算 == 格納値 */
+  readonly inputHashes: boolean;
+  /** granularity を validatorSet から再導出 == 格納値（anti-laundering） */
+  readonly granularity: boolean;
+}
+
+/**
+ * verify usecase 出力 DTO（logical_design §4.1）。
+ */
+export interface VerifyAttestationOutput {
+  /** 全チェック合格か。 */
+  readonly ok: boolean;
+  /** 各機械的チェックの合否。 */
+  readonly checks: VerifyAttestationChecks;
+  /** mismatch / エラーの説明群。 */
+  readonly mismatches: string[];
+}

package/scripts/harness/attestation/application/mappers/attestation-record-mapper.ts

@@ -0,0 +1,240 @@
+// @unit attestation
+// @layer application
+
+import {
+  AttestationRecord,
+  type AttestationRecordProps,
+  type GateResult,
+} from "../../domain/entities/attestation-record.js";
+import { Digest } from "../../domain/value-objects/digest.js";
+import { GranularityClaim } from "../../domain/value-objects/granularity-claim.js";
+import { SignatureBlock } from "../../domain/value-objects/signature-block.js";
+import { ValidatorOutcome } from "../../domain/value-objects/validator-outcome.js";
+import type { AttestationDocument, AttestationDocumentGranularityClaim } from "../dto/attestation-document.js";
+
+/**
+ * verify 時に外部 JSON の shape/型が不正なとき送出する例外。
+ * errorCode: L1-053（logical_design §2.4）
+ */
+export class MalformedAttestationError extends Error {
+  readonly errorCode = "L1-053";
+
+  constructor(message: string) {
+    super(`Malformed attestation: ${message} [L1-053]`);
+    this.name = "MalformedAttestationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function requireString(v: unknown, field: string): string {
+  if (typeof v !== "string") {
+    throw new MalformedAttestationError(`${field} must be a string`);
+  }
+  return v;
+}
+
+function requireBoolean(v: unknown, field: string): boolean {
+  if (typeof v !== "boolean") {
+    throw new MalformedAttestationError(`${field} must be a boolean`);
+  }
+  return v;
+}
+
+/**
+ * AttestationRecord（domain）↔ AttestationDocument（application DTO）の双方向変換。
+ */
+export class AttestationRecordMapper {
+  /** 集約を plain object へ射影（VO をプリミティブ展開）。 */
+  toDocument(record: AttestationRecord): AttestationDocument {
+    return {
+      schemaVersion: record.schemaVersion as "phasegate-attestation/v1",
+      predicateType: record.predicateType,
+      subject: {
+        command: record.subject.command,
+        gateResult: record.subject.gateResult,
+        validatorSet: record.subject.validatorSet.map((o) => ({
+          validatorId: o.validatorId,
+          passed: o.passed,
+          skipped: o.skipped,
+        })),
+      },
+      inputs: {
+        digestAlgorithm: "sha256",
+        sources: record.inputs.sources.map((s) => ({ path: s.path, digest: s.digest.value })),
+        inputDigest: record.inputs.inputDigest.value,
+      },
+      granularity: {
+        traceability: {
+          validator: record.granularity.traceability.validator,
+          level: record.granularity.traceability.level,
+          claim: record.granularity.traceability.claim,
+          knownLimitations: [...record.granularity.traceability.knownLimitations],
+        },
+      },
+      metadata: {
+        producedAt: record.metadata.producedAt,
+        producer: record.metadata.producer,
+        gitCommit: record.metadata.gitCommit,
+      },
+      signature: {
+        mode: record.signature.mode,
+        attestationDigest: record.signature.attestationDigest.value,
+        algorithm: record.signature.algorithm,
+        keyId: record.signature.keyId,
+        value: record.signature.value,
+      },
+    };
+  }
+
+  /**
+   * verify 時に外部 JSON を検証しつつ集約へ再構築。shape/型不正は MalformedAttestationError。
+   * INV 違反（INV-1/3/6）は AttestationRecord.create が AttestationInvariantError を送出する。
+   */
+  fromDocument(doc: unknown): AttestationRecord {
+    if (!isObject(doc)) {
+      throw new MalformedAttestationError("root must be an object");
+    }
+
+    const schemaVersion = requireString(doc.schemaVersion, "schemaVersion");
+    const predicateType = requireString(doc.predicateType, "predicateType");
+
+    const subject = doc.subject;
+    if (!isObject(subject)) {
+      throw new MalformedAttestationError("subject must be an object");
+    }
+    const command = requireString(subject.command, "subject.command");
+    const gateResultRaw = requireString(subject.gateResult, "subject.gateResult");
+    if (gateResultRaw !== "pass" && gateResultRaw !== "fail") {
+      throw new MalformedAttestationError('subject.gateResult must be "pass" or "fail"');
+    }
+    const gateResult = gateResultRaw as GateResult;
+    if (!Array.isArray(subject.validatorSet)) {
+      throw new MalformedAttestationError("subject.validatorSet must be an array");
+    }
+    const validatorSet = subject.validatorSet.map((raw, i) => {
+      if (!isObject(raw)) {
+        throw new MalformedAttestationError(`subject.validatorSet[${i}] must be an object`);
+      }
+      return ValidatorOutcome.create({
+        validatorId: requireString(raw.validatorId, `subject.validatorSet[${i}].validatorId`),
+        passed: requireBoolean(raw.passed, `subject.validatorSet[${i}].passed`),
+        skipped: requireBoolean(raw.skipped, `subject.validatorSet[${i}].skipped`),
+      });
+    });
+
+    const inputs = doc.inputs;
+    if (!isObject(inputs)) {
+      throw new MalformedAttestationError("inputs must be an object");
+    }
+    if (inputs.digestAlgorithm !== "sha256") {
+      throw new MalformedAttestationError('inputs.digestAlgorithm must be "sha256"');
+    }
+    if (!Array.isArray(inputs.sources)) {
+      throw new MalformedAttestationError("inputs.sources must be an array");
+    }
+    const sources = inputs.sources.map((raw, i) => {
+      if (!isObject(raw)) {
+        throw new MalformedAttestationError(`inputs.sources[${i}] must be an object`);
+      }
+      return {
+        path: requireString(raw.path, `inputs.sources[${i}].path`),
+        digest: this.toDigest(raw.digest, `inputs.sources[${i}].digest`),
+      };
+    });
+    const inputDigest = this.toDigest(inputs.inputDigest, "inputs.inputDigest");
+
+    const granularity = doc.granularity;
+    if (!isObject(granularity) || !isObject(granularity.traceability)) {
+      throw new MalformedAttestationError("granularity.traceability must be an object");
+    }
+    const traceability = this.toGranularityClaim(granularity.traceability);
+
+    const metadata = doc.metadata;
+    if (!isObject(metadata)) {
+      throw new MalformedAttestationError("metadata must be an object");
+    }
+    const gitCommit = metadata.gitCommit === null ? null : requireString(metadata.gitCommit, "metadata.gitCommit");
+
+    const signature = doc.signature;
+    if (!isObject(signature)) {
+      throw new MalformedAttestationError("signature must be an object");
+    }
+    const mode = requireString(signature.mode, "signature.mode");
+    const attestationDigest = this.toDigest(signature.attestationDigest, "signature.attestationDigest");
+    // mode の非対応（signed）は verify usecase の mode check で判定するため、ここでは
+    // SignatureBlock を直接構築せず、mode をそのまま検証用に保持する必要がある。
+    // unsigned-poc のみ SignatureBlock を構築できるので、非対応 mode は shape 検証を通し
+    // usecase 側へ委譲するため、props を組み立てる際に signature block を後段で扱う。
+    const props: AttestationRecordProps = {
+      schemaVersion,
+      predicateType,
+      subject: { command, gateResult, validatorSet },
+      inputs: { digestAlgorithm: "sha256", sources, inputDigest },
+      granularity: { traceability },
+      metadata: {
+        producedAt: requireString(metadata.producedAt, "metadata.producedAt"),
+        producer: requireString(metadata.producer, "metadata.producer"),
+        gitCommit,
+      },
+      signature: this.toSignatureBlock(mode, attestationDigest, signature),
+    };
+
+    // verify 用の再構築: INV-1/INV-3 は verify usecase が機械的チェックとして検出するため
+    // ここでは強制しない（reconstruct）。shape/型不正のみ MalformedAttestationError として弾く。
+    return AttestationRecord.reconstruct(props);
+  }
+
+  private toDigest(v: unknown, field: string): Digest {
+    const raw = requireString(v, field);
+    try {
+      return Digest.create(raw);
+    } catch {
+      throw new MalformedAttestationError(`${field} is not a valid sha256 digest`);
+    }
+  }
+
+  private toGranularityClaim(raw: Record<string, unknown>): GranularityClaim {
+    const level = raw.level;
+    if (level !== "file" && level !== "ac") {
+      throw new MalformedAttestationError('granularity.traceability.level must be "file" or "ac"');
+    }
+    if (!Array.isArray(raw.knownLimitations)) {
+      throw new MalformedAttestationError("granularity.traceability.knownLimitations must be an array");
+    }
+    const knownLimitations = raw.knownLimitations.map((k, i) =>
+      requireString(k, `granularity.traceability.knownLimitations[${i}]`),
+    );
+    const claim: AttestationDocumentGranularityClaim = {
+      validator: requireString(raw.validator, "granularity.traceability.validator"),
+      level,
+      claim: requireString(raw.claim, "granularity.traceability.claim"),
+      knownLimitations,
+    };
+    return GranularityClaim.create(claim);
+  }
+
+  private toSignatureBlock(mode: string, attestationDigest: Digest, raw: Record<string, unknown>): SignatureBlock {
+    // unsigned-poc は SignatureBlock で INV-6 を強制。
+    // signed（非対応 mode）は SignatureBlock.create が UnsupportedSignatureModeError を送出するが、
+    // verify usecase は mode check（exitCode 2）で先に非対応を扱うため、ここでは
+    // unsigned-poc のみ通常構築し、それ以外は shape として null 三点組を検証して仮ブロックを組む。
+    if (mode === "unsigned-poc") {
+      if (raw.algorithm !== null || raw.keyId !== null || raw.value !== null) {
+        throw new MalformedAttestationError("unsigned-poc signature must have null algorithm/keyId/value");
+      }
+      return SignatureBlock.unsignedPoc(attestationDigest);
+    }
+    // 非対応 mode: shape のみ検証し unsupported として扱えるよう SignatureBlock.create に委譲。
+    return SignatureBlock.create({
+      mode: mode as "unsigned-poc" | "signed",
+      attestationDigest,
+      algorithm: (raw.algorithm ?? null) as string | null,
+      keyId: (raw.keyId ?? null) as string | null,
+      value: (raw.value ?? null) as string | null,
+    });
+  }
+}

package/scripts/harness/attestation/application/ports/attestation-repository-port.ts

@@ -0,0 +1,14 @@
+// @unit attestation
+// @layer application
+
+import type { AttestationDocument } from "../dto/attestation-document.js";
+
+/**
+ * attestation ファイルの read/write を抽象化する永続化調停ポート（application 所有）。
+ * 集約不変条件に関与しないため domain ではなく application に配置する。
+ */
+export interface AttestationRepositoryPort {
+  write(path: string, doc: AttestationDocument): Promise<void>;
+  /** parse 済み plain object を返す。不在/parse 失敗は throw し usecase が exitCode 2 へ変換する。 */
+  read(path: string): Promise<unknown>;
+}

package/scripts/harness/attestation/application/ports/gate-result-source-port.ts

@@ -0,0 +1,23 @@
+// @unit attestation
+// @layer application
+
+/**
+ * ci-check の1バリデータ結果を写す plain DTO（Shared Kernel の型 import は避ける）。
+ */
+export interface GateValidatorResult {
+  readonly validatorId: string;
+  readonly passed: boolean;
+  readonly skipped: boolean;
+}
+
+/**
+ * gate 実行結果を取得する調停ポート（application 所有）。
+ * black-box observation: 実体は subprocess `phasegate:ci-check --json`（infrastructure）。
+ * 集約不変条件に関与しないため domain ではなく application に配置する。
+ */
+export interface GateResultSourcePort {
+  fetchGateResult(): Promise<{
+    readonly allPassed: boolean;
+    readonly validatorResults: readonly GateValidatorResult[];
+  }>;
+}

package/scripts/harness/attestation/application/ports/source-digester-port.ts

@@ -0,0 +1,15 @@
+// @unit attestation
+// @layer application
+
+import type { Digest } from "../../domain/value-objects/digest.js";
+
+/**
+ * source パスの「現在の」内容から sha256 Digest を供給する調停ポート（application 所有）。
+ * 生成時は inputs.sources の digest 構築に、検証時は現在ファイルとの再照合に用いる。
+ * git commit SHA 等の非ファイル source は本ポート実装または usecase 側で source エントリ化する。
+ * 集約不変条件に関与しないファイル I/O 調停のため application に配置する。
+ */
+export interface SourceDigesterPort {
+  /** 相対/絶対パスを解決して現在の内容を読み、sha256 Digest を返す。 */
+  digestFile(path: string): Promise<Digest>;
+}