@graphrefly/stack 0.1.1 → 0.1.4

package/README.md

@@ -3,9 +3,9 @@
 **Semantic stacked diffs that know when their architectural assumptions expire.**
 
 GraphReFly Stack is an OpenAI Build Week developer tool built with Codex, GPT-5.6, Git, and
-GraphReFly. It adds a semantic validity layer above Git: every work-unit commit is bound to a
-GraphBlueprint witness, an allowed source scope, dependency claims, required checks, and a
-deterministic `GateResult`.
+GraphReFly. Its generic local review binds every stacked commit to the GraphBlueprint generated at
+that Git object and its exact parent diff. Repositories that adopt semantic change records can also
+bind allowed source scopes, dependency claims, required checks, and a deterministic `GateResult`.
 
 Git can report a clean rebase while an agent-generated change is no longer valid under the
 architecture it was planned against. GraphReFly Stack makes that mismatch visible, keeps unaffected
@@ -15,8 +15,8 @@ decides validity.
 ## Install and review a GraphReFly repository
 
 Requirements: macOS or Linux, Node.js 24, pnpm 11.7, and Git. The CLI and local web review shell use
-no hosted service, database, or credentials. Once the package is published, install it in the
-GraphReFly repository you want to review:
+no hosted service, database, or credentials. Install it in the GraphReFly repository you want to
+review:
 
 ```bash
 pnpm add -D @graphrefly/stack
@@ -34,8 +34,17 @@ automatically. Open the printed URL (normally <http://127.0.0.1:4173>), then:
    runtime.
 3. Verify that commit OID, Blueprint hash, upstream Mermaid diagram, delta events, and split code diff
    move together.
-4. Expand repository evidence or commit lineage only when needed. No session, delivery, fixture, or
-   fake semantic-gate state appears in the generic review.
+4. Use **Review changes** to record Approve or Request changes for the exact commit and Blueprint.
+5. Open **Help** for the Git → Blueprint delta → code diff relationship, and expand **Technical
+   details** only when troubleshooting runtime or immutable identities.
+
+Local review decisions and their summaries are strict immutable records under the repository's Git
+common directory at `.git/grfs/reviews`; they never appear in `git status`, change source files, or
+update Git refs. The Technical details disclosure offers an explicit portable review export after a
+decision exists. That content-hashed bundle is the explicit sharing boundary for another reviewer or
+CI. A future hosted GraphReFly Stack can wrap selected exported artifacts in its policy-redacted
+upload envelope; this release neither treats the local export as upload-ready nor uploads review
+state automatically.
 
 `--graph-module` means the repository's root Graph construction module, not the only Graph module
 allowed in the repository. That root module may import, compose, and mount any number of Graphs and
@@ -83,8 +92,10 @@ pnpm exec grfs review --repo . --base "$BASE" --head HEAD --json
 ```
 
 The generic payload is commit-centric. When a repository has not adopted semantic change records,
-the UI says `Semantic gate not configured`; it never turns missing semantic evidence into a passing
-`GateResult`.
+the payload records that internal absence but the primary UI does not advertise an unavailable
+gate, and it never turns missing semantic evidence into a passing `GateResult`. A local human
+decision remains separate from any future semantic gate and does not approve or merge a GitHub pull
+request.
 
 Before registry publication, the same install path is exercised from the packed tarball rather than
 from workspace imports:
@@ -197,8 +208,10 @@ and canonical milestones in `docs/evidence/milestones.jsonl` distinguish that wo
 - The portable bundle is not self-listed in its manifest because that would create a circular hash.
 - Raw provider responses, generated repositories, and sensitive submission drafts stay under
   ignored `.private/` paths.
-- The review server only binds to `127.0.0.1`, sends a restrictive CSP, accepts only GET/HEAD, and
-  exposes no write endpoint.
+- The review server only binds to `127.0.0.1` and sends a restrictive CSP. Its sole write surface is
+  a size-bounded, same-origin `application/json` endpoint that appends validated review decisions
+  below `.git/grfs`; source files, Git objects and refs, repository config, and `GateResult` remain
+  read-only.
 - Generic Blueprint entrypoints run with an empty environment, a five-second timeout, a one-MiB
   stdout bound, read-only filesystem allowlists, and no network or child-process permission.
 - Generic payloads omit Blueprint provenance and reject absolute paths in topology metadata before

package/dist/assets/contracts/ci/v1/artifacts.schema.json

@@ -0,0 +1,253 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "urn:graphrefly-stack:schema:ci-artifacts:v1",
+	"title": "GraphReFly Stack CI artifacts v1",
+	"definitions": {
+		"Hash": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["algorithm", "value"],
+			"properties": {
+				"algorithm": { "const": "sha256" },
+				"value": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+			}
+		},
+		"GitOid": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["algorithm", "value"],
+			"properties": {
+				"algorithm": { "enum": ["sha1", "sha256"] },
+				"value": { "type": "string", "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$" }
+			}
+		},
+		"DecimalId": {
+			"type": "string",
+			"pattern": "^[1-9][0-9]*$",
+			"maxLength": 32
+		},
+		"Identifier": {
+			"type": "string",
+			"minLength": 1,
+			"maxLength": 64,
+			"pattern": "^[A-Za-z][A-Za-z0-9._-]*$"
+		},
+		"RuntimeVersion": {
+			"type": "string",
+			"minLength": 1,
+			"maxLength": 64,
+			"pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$"
+		},
+		"GitHubEvent": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["name", "pullRequestNumber", "base", "head"],
+			"properties": {
+				"name": { "const": "pull_request" },
+				"pullRequestNumber": { "type": "integer", "minimum": 1 },
+				"base": { "$ref": "#/definitions/GitOid" },
+				"head": { "$ref": "#/definitions/GitOid" }
+			}
+		},
+		"CacheInputs": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"operatingSystem",
+				"architecture",
+				"nodeVersion",
+				"pnpmVersion",
+				"lockfilePath",
+				"lockfileDigest",
+				"packageManifestDigest",
+				"stackVersion",
+				"graphreflyVersion",
+				"cacheKey"
+			],
+			"properties": {
+				"operatingSystem": { "type": "string", "minLength": 1, "maxLength": 64 },
+				"architecture": { "type": "string", "minLength": 1, "maxLength": 32 },
+				"nodeVersion": { "$ref": "#/definitions/RuntimeVersion" },
+				"pnpmVersion": { "$ref": "#/definitions/RuntimeVersion" },
+				"lockfilePath": { "const": "pnpm-lock.yaml" },
+				"lockfileDigest": { "$ref": "#/definitions/Hash" },
+				"packageManifestDigest": { "$ref": "#/definitions/Hash" },
+				"stackVersion": { "$ref": "#/definitions/RuntimeVersion" },
+				"graphreflyVersion": { "$ref": "#/definitions/RuntimeVersion" },
+				"cacheKey": { "type": "string", "minLength": 1, "maxLength": 512 }
+			}
+		},
+		"CIInvocation": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"schema",
+				"adapter",
+				"repository",
+				"event",
+				"workflow",
+				"run",
+				"plan",
+				"cacheInputs",
+				"identity"
+			],
+			"properties": {
+				"schema": { "const": "graphrefly.stack.ci-invocation.v1" },
+				"adapter": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["provider", "version"],
+					"properties": {
+						"provider": { "const": "github-actions" },
+						"version": { "const": "v1" }
+					}
+				},
+				"repository": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["id", "ownerId", "headRepositoryId"],
+					"properties": {
+						"id": { "$ref": "#/definitions/DecimalId" },
+						"ownerId": { "$ref": "#/definitions/DecimalId" },
+						"headRepositoryId": { "$ref": "#/definitions/DecimalId" }
+					}
+				},
+				"event": { "$ref": "#/definitions/GitHubEvent" },
+				"workflow": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["ref", "sha"],
+					"properties": {
+						"ref": { "type": "string", "minLength": 1, "maxLength": 1024 },
+						"sha": { "$ref": "#/definitions/GitOid" }
+					}
+				},
+				"run": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["id", "attempt", "actorId", "jobName"],
+					"properties": {
+						"id": { "$ref": "#/definitions/DecimalId" },
+						"attempt": { "type": "integer", "minimum": 1 },
+						"actorId": { "$ref": "#/definitions/DecimalId" },
+						"jobName": { "const": "GraphReFly Stack / Semantic Gate" }
+					}
+				},
+				"plan": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["id", "policyDigest"],
+					"properties": {
+						"id": { "$ref": "#/definitions/Identifier" },
+						"policyDigest": { "$ref": "#/definitions/Hash" }
+					}
+				},
+				"cacheInputs": { "$ref": "#/definitions/CacheInputs" },
+				"identity": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["assurance"],
+					"properties": { "assurance": { "const": "platform-asserted" } }
+				}
+			}
+		},
+		"CIResult": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"schema",
+				"invocationDigest",
+				"outcome",
+				"gateInputDigest",
+				"gateResult",
+				"portableBundleDigest",
+				"provenance",
+				"redaction",
+				"summary",
+				"artifactName"
+			],
+			"properties": {
+				"schema": { "const": "graphrefly.stack.ci-result.v1" },
+				"invocationDigest": { "$ref": "#/definitions/Hash" },
+				"outcome": { "enum": ["pass", "blocked", "error"] },
+				"gateInputDigest": { "$ref": "#/definitions/Hash" },
+				"gateResult": {
+					"$ref": "urn:graphrefly-stack:schema:semantic-artifacts:v1#/definitions/GateResult"
+				},
+				"portableBundleDigest": { "$ref": "#/definitions/Hash" },
+				"provenance": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["provider", "repositoryId", "workflowSha", "runId", "attempt"],
+					"properties": {
+						"provider": { "const": "github-actions" },
+						"repositoryId": { "$ref": "#/definitions/DecimalId" },
+						"workflowSha": { "$ref": "#/definitions/GitOid" },
+						"runId": { "$ref": "#/definitions/DecimalId" },
+						"attempt": { "type": "integer", "minimum": 1 }
+					}
+				},
+				"redaction": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["excludes"],
+					"properties": {
+						"excludes": {
+							"type": "array",
+							"items": {
+								"enum": [
+									"source-content",
+									"raw-blueprint",
+									"check-output",
+									"credentials",
+									"environment",
+									"model-response"
+								]
+							},
+							"minItems": 6,
+							"maxItems": 6,
+							"uniqueItems": true
+						}
+					}
+				},
+				"summary": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["verdict", "affectedWorkUnitIds", "reasonCodes"],
+					"properties": {
+						"verdict": { "enum": ["pass", "blocked", "error"] },
+						"affectedWorkUnitIds": {
+							"type": "array",
+							"items": { "type": "string", "minLength": 1, "maxLength": 64 },
+							"uniqueItems": true
+						},
+						"reasonCodes": {
+							"type": "array",
+							"items": {
+								"$ref": "urn:graphrefly-stack:schema:semantic-artifacts:v1#/definitions/ReasonCode"
+							},
+							"uniqueItems": true
+						}
+					}
+				},
+				"artifactName": {
+					"type": "string",
+					"pattern": "^graphrefly-stack-ci-[0-9a-f]{64}$"
+				}
+			}
+		},
+		"CIBundle": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["schema", "invocation", "result", "portableBundle"],
+			"properties": {
+				"schema": { "const": "graphrefly.stack.ci-bundle.v1" },
+				"invocation": { "$ref": "#/definitions/CIInvocation" },
+				"result": { "$ref": "#/definitions/CIResult" },
+				"portableBundle": {
+					"$ref": "urn:graphrefly-stack:schema:semantic-artifacts:v1#/definitions/SemanticPortableBundle"
+				}
+			}
+		}
+	}
+}

package/dist/assets/contracts/ci/v1/golden-suite.schema.json

@@ -0,0 +1,17 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "urn:graphrefly-stack:schema:ci-golden-suite:v1",
+	"title": "GraphReFly Stack CI golden suite v1",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["schema", "invocation", "result"],
+	"properties": {
+		"schema": { "const": "graphrefly.stack.ci-golden-suite.v1" },
+		"invocation": {
+			"$ref": "urn:graphrefly-stack:schema:ci-artifacts:v1#/definitions/CIInvocation"
+		},
+		"result": {
+			"$ref": "urn:graphrefly-stack:schema:ci-artifacts:v1#/definitions/CIResult"
+		}
+	}
+}

package/dist/assets/contracts/repository/v1/review-bundle.schema.json

@@ -0,0 +1,49 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "urn:graphrefly-stack:schema:repository-review-bundle:v1",
+	"title": "GraphReFly Stack portable repository review bundle v1",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["schema", "repository", "artifacts"],
+	"properties": {
+		"schema": { "const": "graphrefly.stack.repository-review-bundle.v1" },
+		"repository": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["label", "baseOid", "headOid"],
+			"properties": {
+				"label": { "type": "string", "minLength": 1 },
+				"baseOid": {
+					"$ref": "urn:graphrefly-stack:schema:repository-review:v1#/definitions/GitOid"
+				},
+				"headOid": {
+					"$ref": "urn:graphrefly-stack:schema:repository-review:v1#/definitions/GitOid"
+				}
+			}
+		},
+		"artifacts": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["path", "hash", "record"],
+				"properties": {
+					"path": {
+						"type": "string",
+						"pattern": "^reviews/[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\.json$"
+					},
+					"hash": {
+						"type": "object",
+						"additionalProperties": false,
+						"required": ["algorithm", "value"],
+						"properties": {
+							"algorithm": { "const": "sha256" },
+							"value": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+						}
+					},
+					"record": { "$ref": "urn:graphrefly-stack:schema:repository-review-decision:v1" }
+				}
+			}
+		}
+	}
+}

package/dist/assets/contracts/repository/v1/review-decision-request.schema.json

@@ -0,0 +1,15 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "urn:graphrefly-stack:schema:repository-review-decision-request:v1",
+	"title": "GraphReFly Stack local repository review decision request v1",
+	"type": "object",
+	"additionalProperties": false,
+	"required": ["schema", "commitOid", "decision", "reviewerLabel", "summary"],
+	"properties": {
+		"schema": { "const": "graphrefly.stack.repository-review-decision-request.v1" },
+		"commitOid": { "$ref": "urn:graphrefly-stack:schema:repository-review:v1#/definitions/GitOid" },
+		"decision": { "enum": ["approve", "request-changes"] },
+		"reviewerLabel": { "type": "string", "minLength": 1, "maxLength": 120 },
+		"summary": { "type": "string", "maxLength": 10000 }
+	}
+}

package/dist/assets/contracts/repository/v1/review-decision.schema.json

@@ -0,0 +1,52 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "urn:graphrefly-stack:schema:repository-review-decision:v1",
+	"title": "GraphReFly Stack local repository review decision v1",
+	"type": "object",
+	"additionalProperties": false,
+	"required": [
+		"schema",
+		"id",
+		"target",
+		"decision",
+		"reviewerLabel",
+		"summary",
+		"recordedAt",
+		"identityVerified"
+	],
+	"properties": {
+		"schema": { "const": "graphrefly.stack.repository-review-decision.v1" },
+		"id": {
+			"type": "string",
+			"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+		},
+		"target": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["baseOid", "headOid", "parentOid", "commitOid", "blueprintHash"],
+			"properties": {
+				"baseOid": {
+					"$ref": "urn:graphrefly-stack:schema:repository-review:v1#/definitions/GitOid"
+				},
+				"headOid": {
+					"$ref": "urn:graphrefly-stack:schema:repository-review:v1#/definitions/GitOid"
+				},
+				"parentOid": {
+					"$ref": "urn:graphrefly-stack:schema:repository-review:v1#/definitions/GitOid"
+				},
+				"commitOid": {
+					"$ref": "urn:graphrefly-stack:schema:repository-review:v1#/definitions/GitOid"
+				},
+				"blueprintHash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+			}
+		},
+		"decision": { "enum": ["approve", "request-changes"] },
+		"reviewerLabel": { "type": "string", "minLength": 1, "maxLength": 120 },
+		"summary": { "type": "string", "maxLength": 10000 },
+		"recordedAt": {
+			"type": "string",
+			"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$"
+		},
+		"identityVerified": { "const": false }
+	}
+}

package/dist/assets/contracts/repository/v1/review.schema.json

@@ -11,9 +11,10 @@
 		"repository": {
 			"type": "object",
 			"additionalProperties": false,
-			"required": ["label", "graphreflyVersion", "entrypoint", "baseOid", "headOid"],
+			"required": ["label", "headLabel", "graphreflyVersion", "entrypoint", "baseOid", "headOid"],
 			"properties": {
 				"label": { "type": "string", "minLength": 1 },
+				"headLabel": { "type": "string", "minLength": 1 },
 				"graphreflyVersion": { "type": "string", "pattern": "^0\\.3\\.[0-9]+$" },
 				"entrypoint": {
 					"$ref": "urn:graphrefly-stack:schema:repository-config:v1#/properties/blueprint/properties/entrypoint"
@@ -28,8 +29,51 @@
 			"minItems": 1,
 			"items": { "$ref": "#/definitions/ReviewCommit" }
 		},
-		"semanticStatus": { "const": "not-configured" }
+		"semanticStatus": { "enum": ["not-configured", "evaluated"] },
+		"semantic": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["plan", "bindings", "records", "checks", "gateResult", "invalidWorkUnitIds"],
+			"properties": {
+				"plan": {
+					"$ref": "urn:graphrefly-stack:schema:semantic-artifacts:v1#/definitions/AcceptedChangePlan"
+				},
+				"bindings": {
+					"type": "array",
+					"items": {
+						"$ref": "urn:graphrefly-stack:schema:semantic-artifacts:v1#/definitions/CommitWorkUnitBinding"
+					}
+				},
+				"records": {
+					"type": "array",
+					"items": {
+						"$ref": "urn:graphrefly-stack:schema:semantic-artifacts:v1#/definitions/SemanticChangeRecord"
+					}
+				},
+				"checks": {
+					"type": "array",
+					"items": {
+						"$ref": "urn:graphrefly-stack:schema:semantic-artifacts:v1#/definitions/CheckResult"
+					}
+				},
+				"gateResult": {
+					"$ref": "urn:graphrefly-stack:schema:semantic-artifacts:v1#/definitions/GateResult"
+				},
+				"invalidWorkUnitIds": {
+					"type": "array",
+					"items": { "type": "string" },
+					"uniqueItems": true
+				}
+			}
+		}
 	},
+	"allOf": [
+		{
+			"if": { "properties": { "semanticStatus": { "const": "evaluated" } } },
+			"then": { "properties": { "semantic": {} }, "required": ["semantic"] },
+			"else": { "not": { "required": ["semantic"] } }
+		}
+	],
 	"definitions": {
 		"GitOid": { "type": "string", "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$" },
 		"Hash": {