@graphrefly/stack 0.1.0 → 0.1.2

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,38 +15,59 @@ 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
 pnpm exec grfs init --graph-module src/application-graph.ts
-git add .graphrefly-stack.json graphrefly-stack.blueprint.mjs
-git commit -m "configure GraphReFly Stack"
 
 BASE=<the commit immediately before your stack>
 pnpm exec grfs review --repo . --base "$BASE" --head HEAD
 ```
 
-Open <http://127.0.0.1:4173>, then:
+The review command stays running and prints its loopback URL; it does not launch a browser
+automatically. Open the printed URL (normally <http://127.0.0.1:4173>), then:
 
 1. Select each commit discovered from the real linear Git range.
 2. See the Blueprint and parent delta produced by the repository's installed GraphReFly 0.3.x
    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.
-
-`grfs init` does not guess how an arbitrary application assembles its graph. You point it at the
-module and export that already build the repository's root Graph. It generates the strict
-`.graphrefly-stack.json` config and a small deterministic `graphrefly-stack.blueprint.mjs` adapter;
-both are ordinary source files that should be committed. Use `--graph-export <name>` when the module
-does not export `createApplicationGraph`.
-
-The CLI executes that generated adapter at the base and every commit in permission-limited detached
-worktrees. Each invocation calls the real GraphReFly `graph.blueprint()` API; Stack then parses,
-verifies, renders, and diffs only with the installed runtime's public GraphReFly APIs.
+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
+subgraphs. The first version reviews one configured root Blueprint target at a time; selecting among
+multiple independent application roots in a monorepo is roadmap work.
+
+`grfs init` does not guess how an arbitrary application assembles that root Graph. You point it at
+the module and export that already construct it once during onboarding. The command generates the
+strict `.graphrefly-stack.json` config and a small deterministic
+`graphrefly-stack.blueprint.mjs` adapter; both are ordinary source files that should be committed.
+Use `--graph-export <name>` when the module does not export `createApplicationGraph`. JSON is the v1
+configuration format; optional YAML and TOML authoring formats are deferred roadmap work and must
+normalize to the same strict configuration contract before execution.
+
+Initialization may happen after the stack already exists. The review snapshots the configured
+adapter and supplies those same bounded bytes only inside isolated detached revisions where that
+entrypoint did not exist yet; it does not rewrite repository history. The referenced root Graph
+module must exist at every reviewed revision. Commit the config and adapter after onboarding so
+future reviews have a Git-owned configuration witness.
+
+The CLI executes the adapter at the base and every commit in permission-limited detached worktrees.
+Each invocation calls the real GraphReFly `graph.blueprint()` API; Stack then parses, verifies,
+renders, and diffs only with the installed runtime's public GraphReFly APIs.
 
 ## Generic repository contract
 
@@ -71,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:
@@ -185,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/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"