phasegate 0.229.0 → 0.264.0

package/docs/contracts/attestation-v2.schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://phasegate.dev/contracts/attestation-v2.schema.json",
+  "title": "PhaseGate attestation v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "predicateType",
+    "subject",
+    "inputs",
+    "granularity",
+    "acBoundScope",
+    "worldSnapshotRoot",
+    "metadata",
+    "signature"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "phasegate-attestation/v2" },
+    "predicateType": { "const": "https://phasegate.dev/attestation/gate-run/v2" },
+    "worldSnapshotRoot": { "$ref": "#/$defs/digest" },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "gateResult", "validatorSet"],
+      "properties": {
+        "command": { "type": "string", "minLength": 1 },
+        "gateResult": { "enum": ["pass", "fail"] },
+        "validatorSet": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["validatorId", "passed", "skipped"],
+            "properties": {
+              "validatorId": { "type": "string", "minLength": 1 },
+              "passed": { "type": "boolean" },
+              "skipped": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    },
+    "inputs": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["digestAlgorithm", "sources", "inputDigest"],
+      "properties": {
+        "digestAlgorithm": { "const": "sha256" },
+        "sources": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "digest"],
+            "properties": {
+              "path": { "type": "string", "minLength": 1 },
+              "digest": { "$ref": "#/$defs/digest" }
+            }
+          }
+        },
+        "inputDigest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "granularity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["traceability"],
+      "properties": {
+        "traceability": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["validator", "level", "claim", "knownLimitations"],
+          "properties": {
+            "validator": { "type": "string", "minLength": 1 },
+            "level": { "enum": ["file", "ac"] },
+            "claim": { "type": "string" },
+            "knownLimitations": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      }
+    },
+    "acBoundScope": { "type": "array", "items": { "type": "string" } },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["producedAt", "producer", "gitCommit"],
+      "properties": {
+        "producedAt": { "type": "string", "minLength": 1 },
+        "producer": { "type": "string", "minLength": 1 },
+        "gitCommit": { "type": ["string", "null"] }
+      }
+    },
+    "signature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "attestationDigest", "algorithm", "keyId", "value"],
+      "properties": {
+        "mode": { "enum": ["unsigned-poc", "signed"] },
+        "attestationDigest": { "$ref": "#/$defs/digest" },
+        "algorithm": { "type": ["string", "null"] },
+        "keyId": { "type": ["string", "null"] },
+        "value": { "type": ["string", "null"] }
+      }
+    }
+  },
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+  }
+}

package/docs/contracts/requirement-test-matrix.schema.json

@@ -20,6 +20,21 @@
             "type": "string",
             "pattern": "^H(?:F\\d+|\\d{2})-\\d{2}$"
           },
+          "coverageStatus": {
+            "type": "string",
+            "enum": ["planned", "required"],
+            "description": "WI-292 (schema 1.2): Story coverage gate lifecycle の現在値。省略時は required として扱う（1.0/1.1 後方互換）。"
+          },
+          "coverageLifecycle": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 2,
+            "items": {
+              "type": "string",
+              "enum": ["planned", "required"]
+            },
+            "description": "WI-292 (schema 1.2): Git 管理された順方向遷移履歴。有効系列と status 終端一致は L3-004 が fail-closed で検査する。"
+          },
           "storyMappings": {
             "type": "array",
             "items": {

package/docs/contracts/world-baseline.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://phasegate.dev/contracts/world-baseline.schema.json",
+  "title": "PhaseGate World adoption baseline",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "rulesetVersion", "sourceEvaluationId", "sourceCorpusRoot", "sourceConstraintRoot", "adoptedByWorkItemId", "adoptionReason", "entries"],
+  "properties": {
+    "schemaVersion": { "const": "phasegate-world-adoption-baseline/v1" },
+    "rulesetVersion": { "type": "string", "minLength": 1 },
+    "sourceEvaluationId": { "type": "string", "pattern": "^pgw:v1:evaluation:sha256:[0-9a-f]{64}$" },
+    "sourceCorpusRoot": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "sourceConstraintRoot": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "adoptedByWorkItemId": { "type": "string", "pattern": "^WI-[0-9]+$" },
+    "adoptionReason": { "type": "string", "minLength": 1 },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["violationFingerprint", "ruleId", "constraintId"],
+        "properties": {
+          "violationFingerprint": { "type": "string", "pattern": "^pgw:v1:violation-fingerprint:sha256:[0-9a-f]{64}$" },
+          "ruleId": { "enum": ["WCR-002", "WCR-003", "WCR-004", "WCR-005", "WCR-006", "WCR-007", "WCR-008"] },
+          "constraintId": {
+            "oneOf": [
+              { "type": "null" },
+              { "type": "string", "pattern": "^pgw:v1:constraint:[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$" }
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/docs/contracts/world-constraints.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://phasegate.dev/contracts/world-constraints.schema.json",
+  "title": "PhaseGate World constraint declarations",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "constraints", "aliases"],
+  "properties": {
+    "schemaVersion": { "const": "phasegate-world-constraints/v1" },
+    "constraints": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/constraintRecord" }
+    },
+    "aliases": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/aliasRecord" }
+    }
+  },
+  "$defs": {
+    "nodePin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["nodeId", "contentDigest"],
+      "properties": {
+        "nodeId": { "type": "string", "pattern": "^pgw:v1:.+" },
+        "contentDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+      }
+    },
+    "constraintRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["constraintId", "factType", "claimant", "premise", "applicableRuleIds"],
+      "properties": {
+        "constraintId": { "type": "string", "pattern": "^pgw:v1:constraint:[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$" },
+        "factType": { "enum": ["references", "depends-on", "refines", "content-equals"] },
+        "claimant": { "$ref": "#/$defs/nodePin" },
+        "premise": { "$ref": "#/$defs/nodePin" },
+        "applicableRuleIds": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "enum": ["WCR-002", "WCR-003", "WCR-004", "WCR-005", "WCR-006", "WCR-007", "WCR-008"] }
+        }
+      }
+    },
+    "aliasRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["from", "to"],
+      "properties": {
+        "from": { "type": "string", "pattern": "^pgw:v1:.+" },
+        "to": { "type": "string", "pattern": "^pgw:v1:.+" }
+      }
+    }
+  }
+}

package/docs/contracts/world-debts.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://phasegate.dev/contracts/world-debts.schema.json",
+  "title": "PhaseGate World semantic debt declarations",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "debts"],
+  "properties": {
+    "schemaVersion": { "const": "phasegate-world-debts/v1" },
+    "debts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["debtId", "kind", "title", "reason", "ownerUnit", "introducedByWorkItemId", "references"],
+        "properties": {
+          "debtId": { "type": "string", "pattern": "^pgw:v1:semantic-debt:[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$" },
+          "kind": { "const": "semantic" },
+          "title": { "type": "string", "minLength": 1 },
+          "reason": { "type": "string", "minLength": 1 },
+          "ownerUnit": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" },
+          "introducedByWorkItemId": { "type": "string", "pattern": "^WI-[0-9]+$" },
+          "references": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "type": "string", "pattern": "^pgw:v1:.+" }
+          }
+        }
+      }
+    }
+  }
+}

package/docs/contracts/world-obligation-report.schema.json

@@ -0,0 +1,259 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://phasegate.dev/contracts/world-obligation-report.schema.json",
+  "title": "PhaseGate World obligation report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "evaluationId",
+    "rulesetVersion",
+    "policyInputsDigest",
+    "structuralObligations",
+    "repaidBaselineEntries",
+    "declaredSemanticDebts",
+    "policyDiagnostics",
+    "summary"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "phasegate-world-obligation-report/v1" },
+    "evaluationId": {
+      "type": "string",
+      "pattern": "^pgw:v1:evaluation:sha256:[0-9a-f]{64}$"
+    },
+    "rulesetVersion": { "type": "string", "minLength": 1 },
+    "policyInputsDigest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "structuralObligations": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/structuralObligation" }
+    },
+    "repaidBaselineEntries": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/repaidBaselineEntry" }
+    },
+    "declaredSemanticDebts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/semanticDebt" }
+    },
+    "policyDiagnostics": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/policyDiagnostic" }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "structuralObligations",
+        "repaidBaselineEntries",
+        "declaredSemanticDebts",
+        "policyDiagnostics"
+      ],
+      "properties": {
+        "structuralObligations": { "type": "integer", "minimum": 0 },
+        "repaidBaselineEntries": { "type": "integer", "minimum": 0 },
+        "declaredSemanticDebts": { "type": "integer", "minimum": 0 },
+        "policyDiagnostics": { "type": "integer", "minimum": 0 }
+      }
+    }
+  },
+  "$defs": {
+    "jsonValue": {
+      "oneOf": [
+        { "type": "null" },
+        { "type": "boolean" },
+        { "type": "number" },
+        { "type": "string" },
+        {
+          "type": "array",
+          "items": { "$ref": "#/$defs/jsonValue" }
+        },
+        {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+        }
+      ]
+    },
+    "pin": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["nodeId", "contentDigest"],
+          "properties": {
+            "nodeId": { "type": "string", "pattern": "^pgw:v1:.+" },
+            "contentDigest": {
+              "type": "string",
+              "pattern": "^sha256:[0-9a-f]{64}$"
+            }
+          }
+        }
+      ]
+    },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["endpointRole", "nodeIds"],
+      "properties": {
+        "endpointRole": {
+          "enum": ["claimant", "premise", "both", "declaration", "global"]
+        },
+        "nodeIds": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^pgw:v1:.+" }
+        }
+      }
+    },
+    "waiver": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["waiverId", "reason", "expiresOn", "workItemId"],
+          "properties": {
+            "waiverId": { "type": "string", "pattern": "^pgw:v1:waiver:.+" },
+            "reason": { "type": "string", "minLength": 1 },
+            "expiresOn": {
+              "type": "string",
+              "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+            },
+            "workItemId": { "type": "string", "pattern": "^WI-[0-9]+$" }
+          }
+        }
+      ]
+    },
+    "structuralObligation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "violationFingerprint",
+        "ruleId",
+        "constraintId",
+        "factType",
+        "subject",
+        "claimantPin",
+        "premisePin",
+        "expected",
+        "observed",
+        "classification",
+        "waiver"
+      ],
+      "properties": {
+        "violationFingerprint": {
+          "type": "string",
+          "pattern": "^pgw:v1:violation-fingerprint:sha256:[0-9a-f]{64}$"
+        },
+        "ruleId": { "type": "string", "pattern": "^WCR-[0-9]{3}$" },
+        "constraintId": {
+          "oneOf": [
+            { "type": "null" },
+            { "type": "string", "pattern": "^pgw:v1:constraint:.+" }
+          ]
+        },
+        "factType": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "enum": ["references", "depends-on", "refines", "content-equals"]
+            }
+          ]
+        },
+        "subject": { "$ref": "#/$defs/subject" },
+        "claimantPin": { "$ref": "#/$defs/pin" },
+        "premisePin": { "$ref": "#/$defs/pin" },
+        "expected": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+        },
+        "observed": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+        },
+        "classification": {
+          "enum": [
+            "adopted-legacy",
+            "new-structural",
+            "invalid-declaration",
+            "waived"
+          ]
+        },
+        "waiver": { "$ref": "#/$defs/waiver" }
+      }
+    },
+    "repaidBaselineEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "violationFingerprint",
+        "ruleId",
+        "constraintId",
+        "classification",
+        "disposition"
+      ],
+      "properties": {
+        "violationFingerprint": {
+          "type": "string",
+          "pattern": "^pgw:v1:violation-fingerprint:sha256:[0-9a-f]{64}$"
+        },
+        "ruleId": { "type": "string", "pattern": "^WCR-[0-9]{3}$" },
+        "constraintId": {
+          "oneOf": [
+            { "type": "null" },
+            { "type": "string", "pattern": "^pgw:v1:constraint:.+" }
+          ]
+        },
+        "classification": { "const": "repaid" },
+        "disposition": { "const": "cleanup-required" }
+      }
+    },
+    "semanticDebt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "debtId",
+        "kind",
+        "title",
+        "reason",
+        "ownerUnit",
+        "introducedByWorkItemId",
+        "references"
+      ],
+      "properties": {
+        "schemaVersion": { "const": "phasegate-world-debts/v1" },
+        "debtId": { "type": "string", "pattern": "^pgw:v1:semantic-debt:.+" },
+        "kind": { "const": "semantic" },
+        "title": { "type": "string", "minLength": 1 },
+        "reason": { "type": "string", "minLength": 1 },
+        "ownerUnit": { "type": "string", "minLength": 1 },
+        "introducedByWorkItemId": {
+          "type": "string",
+          "pattern": "^WI-[0-9]+$"
+        },
+        "references": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^pgw:v1:.+" }
+        }
+      }
+    },
+    "policyDiagnostic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "subjectId", "details"],
+      "properties": {
+        "code": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+        "subjectId": {
+          "oneOf": [{ "type": "null" }, { "type": "string", "minLength": 1 }]
+        },
+        "details": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+        }
+      }
+    }
+  }
+}

package/docs/contracts/world-waivers.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://phasegate.dev/contracts/world-waivers.schema.json",
+  "title": "PhaseGate World waivers",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "waivers"],
+  "properties": {
+    "schemaVersion": { "const": "phasegate-world-waivers/v1" },
+    "waivers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["waiverId", "violationFingerprint", "reason", "expiresOn", "workItemId", "renewalOf"],
+        "properties": {
+          "waiverId": { "type": "string", "pattern": "^pgw:v1:waiver:[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$" },
+          "violationFingerprint": { "type": "string", "pattern": "^pgw:v1:violation-fingerprint:sha256:[0-9a-f]{64}$" },
+          "reason": { "type": "string", "minLength": 1 },
+          "expiresOn": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+          "workItemId": { "type": "string", "pattern": "^WI-[0-9]+$" },
+          "renewalOf": {
+            "oneOf": [
+              { "type": "null" },
+              { "type": "string", "pattern": "^pgw:v1:waiver:[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$" }
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/docs/guide/cli-reference.md

@@ -325,6 +325,51 @@ L4 warning findings fail the process only when warning strictness is enabled (`v
 
 ---
 
+## World Model
+
+<!-- @work-item-id WI-299 -->
+<!-- @work-item-id WI-307 -->
+
+World Model コマンド（ADR-037）。設計文書・ソース・テスト・matrix・attestation を型付き事実グラフとして抽出し、pin された制約を両端点対称に再評価して義務を導出する。明示実行は config に依存せず常に可能。`world.enabled` のproduct既定値は`false`で、trueの場合に登録済み`L2-017` / `L3-008`とSessionStart integrationを有効化する。phasegate self-repoはdogfoodのためtrueである。
+
+| Command | Options | Description |
+|---|---|---|
+| `world:inspect` | `--format human\|json` `--json` | Read-only World snapshot（node / edge / 抽出 diagnostics）を構築・表示。宣言も report も書かない |
+| `world:pin` | `--constraint <id>`（`pgw:v1:constraint` ID, 必須） `--endpoint <claimant\|premise>`（必須） `--apply` `--format human\|json` `--json` | 制約端点の現在 digest をプレビュー。`--apply` で `phasegate.world-constraints.json` を atomic に更新 |
+| `world:derive` | `--write` `--out <path>`（`--write` 必須） `--format human\|json` `--json` | immutable な obligation report を再導出。既定は pure・read-only。`--write` で raw report を `.harness/world-obligations.json`（untracked）へ永続化 |
+
+### Automatic integration
+
+| Surface | Contract |
+|---|---|
+| `L2-017 world-constraint-admission` | local fast-path。new / changed constraintのmalformed、新規pin / unpinned claimをfail-closed。adopted-legacyはwarningのみ。local resultは偽造可能でauthorityではない |
+| `L3-008 world-constraint-rederivation` | current corpusとversioned control inputからauthoritativeにpure再導出。保存`.harness/world-obligations.json`は読まず、改竄・削除で結果が変わらない |
+| SessionStart | blocking相当を優先して最大5件 / 2000 Unicode scalar。adopted-legacyは件数一行、全文やreasonをpromptへ注入しない。derive不能は固定warningへfail-open |
+| Attestation v2 | `phasegate-attestation/v2`がcanonical`worldSnapshotRoot`一件をpin。fragment digest collectionは保存しない。既存v1のproduce / verify互換を維持 |
+| Bundled `aidlc-gate` | `world.enabled:true`のprojectでmatrix生成後にpure deriveを二回実行してbyte一致を確認し、その後L3を実行。false / absentではWorld段階だけをskip |
+
+### Exit code
+
+| Exit | 意味 |
+|---|---|
+| 0 | クリーン（`world:derive` では adopted-legacy / waived / declared debt のみで blocking なし） |
+| 1 | blocking な finding あり（`world:inspect` は抽出 diagnostics あり、`world:derive` は新規違反・期限切れ waiver 等） |
+| 2 | 契約エラー（未知の control-file schema、不正な引数など） |
+
+### 制御ファイルと出力
+
+| File | Role |
+|---|---|
+| `phasegate.world-constraints.json` | pin された制約宣言（`world:pin --apply` が更新する唯一の mutation 経路） |
+| `phasegate.world-baseline.json` | 既存違反の adoption baseline（閉じた集合・縮小のみ。同一 ruleset での追加は拒否） |
+| `phasegate.world-waivers.json` | 単一 fingerprint 単位の waiver（理由 / 期限 / Work Item 必須） |
+| `phasegate.world-debts.json` | 宣言済み semantic debt（import として表示され、「再発見」はしない） |
+| `.harness/world-obligations.json` | `world:derive --write` の永続 report。**導出結果のキャッシュに過ぎず**、手編集・削除しても再導出の判定は変わらない |
+
+JSON 出力は envelope `phasegate-world-cli/v1` に包まれ、同一 checkout での 2 回実行は byte-identical（決定性契約）。schema は `docs/contracts/world-*.schema.json` を参照。
+
+---
+
 ## ADR Management
 
 | Command | Options | Description |