yaaw-se 0.2.0 → 0.2.1

package/dist/payload/yaaw-core/system/schemas/handoff.schema.json

@@ -2,38 +2,223 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "yaaw.handoff/v2",
   "type": "object",
-  "required": ["schema", "role", "workflow", "desired_intent", "active_artifact", "references", "reads", "writes", "forbidden_writes", "revisions", "expertise", "host_expertise", "expected_output", "result_vocabulary", "repository_requirement", "repository", "transition_sequence"],
+  "required": [
+    "schema",
+    "framework",
+    "role",
+    "workflow",
+    "desired_intent",
+    "active_artifact",
+    "references",
+    "reads",
+    "writes",
+    "forbidden_writes",
+    "revisions",
+    "expertise",
+    "host_expertise",
+    "expected_output",
+    "result_vocabulary",
+    "repository_requirement",
+    "repository",
+    "transition_sequence"
+  ],
   "properties": {
-    "schema": {"const": "yaaw.handoff/v2"},
-    "role": {"enum": ["prd", "planner", "implementer", "reviewer", "orchestrator"]},
-    "workflow": {"type": "string", "minLength": 1},
-    "desired_intent": {"type": ["string", "null"]},
-    "active_artifact": {"type": ["string", "null"]},
-    "references": {"type": "array", "items": {"type": "string"}},
-    "reads": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
-    "writes": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
-    "forbidden_writes": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
-    "revisions": {"type": "object", "additionalProperties": {"type": "integer", "minimum": 0}},
-    "expertise": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
-    "host_expertise": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
-    "expected_output": {"type": "string", "minLength": 1},
-    "result_vocabulary": {"type": "array", "items": {"type": "string"}, "minItems": 1, "uniqueItems": true},
-    "repository_requirement": {"enum": ["NONE", "INSPECT", "IDENTITY"]},
+    "schema": {
+      "const": "yaaw.handoff/v2"
+    },
+    "role": {
+      "enum": [
+        "prd",
+        "planner",
+        "implementer",
+        "reviewer",
+        "orchestrator"
+      ]
+    },
+    "workflow": {
+      "type": "string",
+      "minLength": 1
+    },
+    "desired_intent": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "active_artifact": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "references": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "reads": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "writes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "forbidden_writes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "revisions": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "integer",
+        "minimum": 0
+      }
+    },
+    "expertise": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "host_expertise": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "expected_output": {
+      "type": "string",
+      "minLength": 1
+    },
+    "result_vocabulary": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "repository_requirement": {
+      "enum": [
+        "NONE",
+        "INSPECT",
+        "IDENTITY"
+      ]
+    },
     "repository": {
       "type": "object",
-      "required": ["status", "workspace_scope", "git_root_relation", "head_commit", "dirty", "worktree_digest", "error"],
+      "required": [
+        "status",
+        "workspace_scope",
+        "git_root_relation",
+        "head_commit",
+        "dirty",
+        "worktree_digest",
+        "error"
+      ],
       "properties": {
-        "status": {"enum": ["READY", "UNVERSIONED", "UNAVAILABLE", "ROOT_MISMATCH", "IDENTITY_FAILED"]},
-        "workspace_scope": {"type": "string", "minLength": 1},
-        "git_root_relation": {"enum": ["same", "ancestor", "none", "unknown"]},
-        "head_commit": {"type": ["string", "null"]},
-        "dirty": {"type": ["boolean", "null"]},
-        "worktree_digest": {"type": ["string", "null"]},
-        "error": {"type": ["string", "null"]}
+        "status": {
+          "enum": [
+            "READY",
+            "UNVERSIONED",
+            "UNAVAILABLE",
+            "ROOT_MISMATCH",
+            "IDENTITY_FAILED"
+          ]
+        },
+        "workspace_scope": {
+          "type": "string",
+          "minLength": 1
+        },
+        "git_root_relation": {
+          "enum": [
+            "same",
+            "ancestor",
+            "none",
+            "unknown"
+          ]
+        },
+        "head_commit": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "dirty": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "worktree_digest": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "error": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
       },
       "additionalProperties": false
     },
-    "transition_sequence": {"type": "integer", "minimum": 0}
+    "transition_sequence": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "framework": {
+      "type": "object",
+      "required": [
+        "yaaw_version",
+        "system_schema",
+        "installation_schema",
+        "project_schema",
+        "manifest_digest",
+        "integrity_status"
+      ],
+      "properties": {
+        "yaaw_version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "system_schema": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "installation_schema": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "project_schema": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "manifest_digest": {
+          "type": "string",
+          "minLength": 1
+        },
+        "integrity_status": {
+          "const": "HEALTHY"
+        }
+      },
+      "additionalProperties": false
+    }
   },
   "additionalProperties": false
 }

package/dist/payload/yaaw-core/system/schemas/observed-state.schema.json

@@ -2,28 +2,173 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "yaaw.observed-state/v2",
   "type": "object",
-  "required": ["schema", "repository", "transition_sequence", "claims", "artifacts", "inconsistencies", "candidate_actions"],
+  "required": [
+    "schema",
+    "framework",
+    "repository",
+    "transition_sequence",
+    "claims",
+    "artifacts",
+    "inconsistencies",
+    "candidate_actions"
+  ],
   "properties": {
-    "schema": {"const": "yaaw.observed-state/v2"},
+    "schema": {
+      "const": "yaaw.observed-state/v2"
+    },
     "repository": {
       "type": "object",
-      "required": ["status", "workspace_scope", "git_root_relation", "head_commit", "dirty", "worktree_digest", "error"],
+      "required": [
+        "status",
+        "workspace_scope",
+        "git_root_relation",
+        "head_commit",
+        "dirty",
+        "worktree_digest",
+        "error"
+      ],
       "properties": {
-        "status": {"enum": ["READY", "UNVERSIONED", "UNAVAILABLE", "ROOT_MISMATCH", "IDENTITY_FAILED"]},
-        "workspace_scope": {"type": "string", "minLength": 1},
-        "git_root_relation": {"enum": ["same", "ancestor", "none", "unknown"]},
-        "head_commit": {"type": ["string", "null"]},
-        "dirty": {"type": ["boolean", "null"]},
-        "worktree_digest": {"type": ["string", "null"]},
-        "error": {"type": ["string", "null"]}
+        "status": {
+          "enum": [
+            "READY",
+            "UNVERSIONED",
+            "UNAVAILABLE",
+            "ROOT_MISMATCH",
+            "IDENTITY_FAILED"
+          ]
+        },
+        "workspace_scope": {
+          "type": "string",
+          "minLength": 1
+        },
+        "git_root_relation": {
+          "enum": [
+            "same",
+            "ancestor",
+            "none",
+            "unknown"
+          ]
+        },
+        "head_commit": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "dirty": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "worktree_digest": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "error": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
       },
       "additionalProperties": false
     },
-    "transition_sequence": {"type": "integer", "minimum": 0},
-    "claims": {"type": "object"},
-    "artifacts": {"type": "object"},
-    "inconsistencies": {"type": "array", "items": {"type": "string"}},
-    "candidate_actions": {"type": "array", "items": {"type": "string"}}
+    "transition_sequence": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "claims": {
+      "type": "object"
+    },
+    "artifacts": {
+      "type": "object"
+    },
+    "inconsistencies": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "candidate_actions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "framework": {
+      "type": "object",
+      "required": [
+        "yaaw_version",
+        "system_schema",
+        "installation_schema",
+        "project_schema",
+        "manifest_digest",
+        "integrity_status",
+        "modified",
+        "missing",
+        "local_overrides",
+        "repair_required"
+      ],
+      "properties": {
+        "yaaw_version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "system_schema": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "installation_schema": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "project_schema": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "manifest_digest": {
+          "type": "string",
+          "minLength": 1
+        },
+        "integrity_status": {
+          "type": "string",
+          "enum": [
+            "HEALTHY",
+            "MODIFIED",
+            "MISSING",
+            "LOCAL_OVERRIDE",
+            "MANIFEST_INVALID",
+            "UNKNOWN",
+            "CONTRACT_INCONSISTENT"
+          ]
+        },
+        "modified": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "missing": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "local_overrides": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "repair_required": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    }
   },
   "additionalProperties": false
 }

package/dist/payload/yaaw-core/system/templates/handoff.json

@@ -1,5 +1,13 @@
 {
   "schema": "yaaw.handoff/v2",
+  "framework": {
+    "yaaw_version": "VERSION",
+    "system_schema": 2,
+    "installation_schema": 1,
+    "project_schema": 1,
+    "manifest_digest": "sha256:MANIFEST",
+    "integrity_status": "HEALTHY"
+  },
   "role": "implementer",
   "workflow": "implementation.implement-ticket",
   "desired_intent": "IMPLEMENT",
@@ -8,11 +16,22 @@
   "reads": [],
   "writes": [],
   "forbidden_writes": [],
-  "revisions": {"product": 1, "engineering": 1, "spec": 1, "ticket": 1},
+  "revisions": {
+    "product": 1,
+    "engineering": 1,
+    "spec": 1,
+    "ticket": 1
+  },
   "expertise": [],
   "host_expertise": [],
   "expected_output": "implementation_evidence",
-  "result_vocabulary": ["SUCCESS", "REVIEW_REQUIRED", "REPLAN_REQUIRED", "PRECONDITION_UNSATISFIED", "BLOCKED"],
+  "result_vocabulary": [
+    "SUCCESS",
+    "REVIEW_REQUIRED",
+    "REPLAN_REQUIRED",
+    "PRECONDITION_UNSATISFIED",
+    "BLOCKED"
+  ],
   "repository_requirement": "IDENTITY",
   "repository": {
     "status": "READY",

package/dist/payload/yaaw-core/system/templates/observed-state.json

@@ -1,5 +1,17 @@
 {
   "schema": "yaaw.observed-state/v2",
+  "framework": {
+    "yaaw_version": "VERSION",
+    "system_schema": 2,
+    "installation_schema": 1,
+    "project_schema": 1,
+    "manifest_digest": "sha256:MANIFEST",
+    "integrity_status": "HEALTHY",
+    "modified": [],
+    "missing": [],
+    "local_overrides": [],
+    "repair_required": false
+  },
   "repository": {
     "status": "UNVERSIONED",
     "workspace_scope": ".",

package/dist/payload/yaaw-core/system/tools/framework-integrity.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { lstat, readFile } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+function digest(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+async function exists(path) {
+  try { await lstat(path); return true; } catch { return false; }
+}
+
+function within(root, target) {
+  const rel = relative(root, target);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+function normalizeRel(value) {
+  return String(value).replaceAll("\\", "/");
+}
+
+function isFrameworkManaged(rel, record) {
+  const path = normalizeRel(rel);
+  return record?.owner === "package:system" || path.startsWith(".yaaw-core/system/");
+}
+
+async function safeFile(root, rel) {
+  const normalized = normalizeRel(rel);
+  if (!normalized || isAbsolute(normalized) || normalized.split("/").includes("..")) {
+    throw new Error(`unsafe manifest path: ${rel}`);
+  }
+  const target = resolve(root, normalized);
+  if (!within(root, target)) throw new Error(`manifest path escapes workspace: ${rel}`);
+  const info = await lstat(target);
+  if (info.isSymbolicLink()) throw new Error(`managed framework path is a symlink: ${rel}`);
+  if (!info.isFile()) throw new Error(`managed framework path is not a file: ${rel}`);
+  return target;
+}
+
+function workspaceArg(argv) {
+  const index = argv.indexOf("--workspace");
+  if (index >= 0 && argv[index + 1]) return argv[index + 1];
+  return process.cwd();
+}
+
+async function inspect(workspace) {
+  const root = resolve(workspace);
+  const manifestPath = join(root, ".yaaw-core", "install", "manifest.json");
+  let manifestBytes;
+  let manifest;
+  try {
+    manifestBytes = await readFile(manifestPath);
+    manifest = JSON.parse(manifestBytes.toString("utf8"));
+  } catch (error) {
+    return {
+      schema: "yaaw.framework-integrity/v1",
+      status: "MANIFEST_INVALID",
+      package_version: null,
+      manifest_digest: null,
+      modified: [],
+      missing: [],
+      local_overrides: [],
+      unsafe: [String(error?.message ?? error)],
+      repair_required: true
+    };
+  }
+
+  const supportedManifest = manifest?.schema === "yaaw.installation/v1" || manifest?.schema === "yaaw.installation/v2";
+  if (
+    !supportedManifest ||
+    manifest?.project?.root !== "." ||
+    !manifest?.managedFiles ||
+    typeof manifest.managedFiles !== "object"
+  ) {
+    return {
+      schema: "yaaw.framework-integrity/v1",
+      status: "MANIFEST_INVALID",
+      package_version: manifest?.yaawVersion ?? null,
+      manifest_digest: `sha256:${digest(manifestBytes)}`,
+      modified: [],
+      missing: [],
+      local_overrides: [],
+      unsafe: ["unsupported or incomplete installation manifest"],
+      repair_required: true
+    };
+  }
+
+  const modified = [];
+  const missing = [];
+  const localOverrides = [];
+  const unsafe = [];
+
+  for (const [rel, record] of Object.entries(manifest.managedFiles)) {
+    if (!isFrameworkManaged(rel, record)) continue;
+    const normalized = normalizeRel(rel);
+    if (record?.localOverride === true) localOverrides.push(normalized);
+    const target = resolve(root, normalized);
+    if (!(await exists(target))) {
+      missing.push(normalized);
+      continue;
+    }
+    try {
+      const safe = await safeFile(root, normalized);
+      const actual = digest(await readFile(safe));
+      if (actual !== record.sha256) modified.push(normalized);
+    } catch (error) {
+      unsafe.push(`${normalized}: ${String(error?.message ?? error)}`);
+    }
+  }
+
+  let status = "HEALTHY";
+  if (unsafe.length) status = "MANIFEST_INVALID";
+  else if (missing.length) status = "MISSING";
+  else if (modified.length) status = "MODIFIED";
+  else if (localOverrides.length) status = "LOCAL_OVERRIDE";
+
+  return {
+    schema: "yaaw.framework-integrity/v1",
+    status,
+    package_version: manifest.yaawVersion ?? null,
+    system_schema: manifest.systemSchema ?? 1,
+    installation_schema: manifest.installationSchema ?? 1,
+    project_schema: manifest.projectSchema ?? manifest.projectStateSchema ?? 1,
+    manifest_digest: `sha256:${digest(manifestBytes)}`,
+    modified,
+    missing,
+    local_overrides: localOverrides,
+    unsafe,
+    repair_required: status !== "HEALTHY"
+  };
+}
+
+try {
+  const result = await inspect(workspaceArg(process.argv.slice(2)));
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  process.exitCode = result.status === "HEALTHY" ? 0 : 2;
+} catch (error) {
+  process.stdout.write(JSON.stringify({
+    schema: "yaaw.framework-integrity/v1",
+    status: "UNKNOWN",
+    package_version: null,
+    manifest_digest: null,
+    modified: [],
+    missing: [],
+    local_overrides: [],
+    unsafe: [String(error?.message ?? error)],
+    repair_required: true
+  }, null, 2) + "\n");
+  process.exitCode = 2;
+}

package/dist/payload/yaaw-core/system/workflows/orchestration/determine-next-action.md

@@ -7,13 +7,18 @@ Turn reconciled observed reality into one explicit, fresh dispatch contract.
 Current observed-state snapshot, reconciled state, `.yaaw-core/system/core/routing.md`, workflow/execution/artifact/role-I/O/expertise registries, and optional current intent.
 
 ## Procedure
-1. Choose exactly one next canonical workflow or terminal state using explicit routing precedence. Do not load candidate workflow bodies while choosing.
-2. Resolve its repository requirement from `.yaaw-core/system/registries/execution-policy.json`.
-3. If requirement is `IDENTITY` and repository status is not `READY`, return `PRECONDITION_UNSATISFIED:REPOSITORY_IDENTITY_UNAVAILABLE` or `BLOCKED` as appropriate; do not dispatch.
-4. Resolve exact read/write/forbidden-write artifact classes from `.yaaw-core/system/registries/role-io.json` and exact current artifact references.
-5. Select only YAAW expertise relevant to the selected workflow/artifact. Host expertise is admitted only through `.yaaw-core/system/rules/research-admission.md`.
-6. Write `.yaaw-core/runtime/handoff.json` conforming to handoff v2 with desired intent, role, workflow ID, exact references/revisions, read/write sets, expertise, expected output/result vocabulary, repository requirement/basis, and transition sequence.
-7. If the result is human-input, BLOCKED, or COMPLETE, write no executable handoff and return the stop result.
+1. Require the current observed framework integrity status to be `HEALTHY`. Otherwise return the typed framework stop and write no executable handoff.
+2. Choose exactly one next canonical workflow or terminal state using explicit routing precedence. Do not load candidate workflow bodies while choosing.
+3. Resolve its repository requirement from `.yaaw-core/system/registries/execution-policy.json`.
+4. If requirement is `IDENTITY` and repository status is not `READY`, return `PRECONDITION_UNSATISFIED:REPOSITORY_IDENTITY_UNAVAILABLE` or `BLOCKED` as appropriate; do not dispatch.
+5. Resolve exact read/write/forbidden-write artifact classes from `.yaaw-core/system/registries/role-io.json` and exact current artifact references.
+6. Select only YAAW expertise relevant to the selected workflow/artifact. Host expertise is admitted only through `.yaaw-core/system/rules/research-admission.md`.
+7. Write `.yaaw-core/runtime/handoff.json` conforming to handoff v2 with desired intent, role, workflow ID, exact references/revisions, read/write sets, expertise, expected output/result vocabulary, repository requirement/basis, and transition sequence.
+8. If the result is human-input, BLOCKED, or COMPLETE, write no executable handoff and return the stop result.
 
 ## Boundary
 Do not perform target role semantic work here.
+
+## Framework write guard
+
+Before persisting a handoff, verify that its write set is a subset of the selected role's canonical artifact writes and contains no installer-managed artifact or `.yaaw-core/system/**` path. A framework defect is a stop condition, never a target workflow.