yay-layer 1.0.0-rc.1

package/src/assurance.js

@@ -0,0 +1,122 @@
+'use strict';
+// P4 — long-lived assurance helpers (pure logic; the CLI/dashboard wire them up):
+//   • reverifyDiff       — compare a stored attestation's verdicts to a fresh run (verifier upgrades
+//                          APPEND a new attestation, never rewrite — "Green is an event", D5).
+//   • integrityWitness   — cross-check the append-only ledgers against each other and the tree
+//                          (git vs ledger vs spec-archive): does the record still describe reality?
+//   • earnedAutonomy     — turn the rejection history (P3) into per-category trust metrics: where the
+//                          agent's delegated work is reliably ratified vs. repeatedly rejected.
+
+// ── reverify diff ────────────────────────────────────────────────────────────────
+// prevAtt.evidence and newVerObj.evidence are per-Cell { state, proven } maps. Returns the verdict
+// changes between them (a Cell moving YELLOW→GREEN is an *improvement* from a better verifier; a
+// GREEN→RED is a *regression* a capability bump surfaced). Never mutates either input.
+function reverifyDiff(prevAtt, newVerObj) {
+  const a = (prevAtt && prevAtt.evidence) || {};
+  const b = (newVerObj && newVerObj.evidence) || {};
+  const rank = { PINK: 0, RED: 1, UNSIGNED: 2, YELLOW: 3, GREEN: 4 };
+  const ids = Object.keys({ ...a, ...b }).sort();
+  const changes = [];
+  let improved = 0, regressed = 0;
+  for (const id of ids) {
+    const from = a[id] ? a[id].state : '(absent)';
+    const to = b[id] ? b[id].state : '(gone)';
+    const fromProven = !!(a[id] && a[id].proven), toProven = !!(b[id] && b[id].proven);
+    if (from === to && fromProven === toProven) continue;
+    const dir = ((rank[to] != null ? rank[to] : -1) - (rank[from] != null ? rank[from] : -1));
+    if (dir > 0 || (from === to && !fromProven && toProven)) improved++;
+    else if (dir < 0) regressed++;
+    changes.push({ cell: id, from, to, fromProven, toProven });
+  }
+  return {
+    capabilityChanged: !!(prevAtt && newVerObj && prevAtt.capability !== newVerObj.capability),
+    fromCapability: prevAtt ? prevAtt.capability : null,
+    toCapability: newVerObj ? newVerObj.capability : null,
+    changes, improved, regressed,
+  };
+}
+
+// ── integrity witness (git/tree vs ledger vs spec-archive) ─────────────────────────
+// A witness answers "does the record still describe reality, and is the record internally sound?"
+// It takes already-loaded state (so it's pure/testable) and returns { ok, problems, checks }.
+//   deps: {
+//     ledger,            // attestation ledger { entries:[...] }
+//     loadAttestation,   // (hash) => validated attestation | null   (tamper check baked in)
+//     currentCodeTreeHash,
+//     approvals,         // lock.approvals
+//     hasSpecObject,     // (specHash) => bool  (is the as-signed spec archived? P1)
+//   }
+function integrityWitness(deps) {
+  const problems = [];
+  const led = (deps.ledger && deps.ledger.entries) || [];
+  // 1) attestation chain: each entry references the previous hash, and each stored object validates.
+  let chainOk = true, prev = 'genesis', validated = 0;
+  for (const e of led) {
+    if (e.prev !== prev) { chainOk = false; problems.push(`attestation ${String(e.hash).slice(0, 12)}: broken chain (prev ${String(e.prev).slice(0, 8)} ≠ expected ${String(prev).slice(0, 8)})`); }
+    const att = deps.loadAttestation ? deps.loadAttestation(e.hash) : null;
+    if (!att) problems.push(`attestation ${String(e.hash).slice(0, 12)}: object missing or fails signature/tamper check`);
+    else validated++;
+    prev = e.hash;
+  }
+  // 2) git/tree vs ledger: does the newest attestation still describe the code on disk?
+  const last = led.length ? led[led.length - 1] : null;
+  const covered = !!(last && deps.currentCodeTreeHash && last.codeTreeHash === deps.currentCodeTreeHash);
+  if (last && !covered) problems.push(`the latest attestation (${String(last.hash).slice(0, 12)}) no longer matches the current code — re-run \`yay attest\` / \`yay reverify\``);
+  // 3) spec-archive completeness: every signed spec identity should be archived (P1), so "as signed"
+  //    reconstruction never depends on git surviving.
+  let missingSpecs = 0, checkedSpecs = 0;
+  if (deps.hasSpecObject) {
+    const seen = new Set();
+    for (const ap of deps.approvals || []) {
+      for (const id of Object.keys(ap.items || {})) {
+        const h = ap.items[id]; if (!h || seen.has(h)) continue; seen.add(h); checkedSpecs++;
+        if (!deps.hasSpecObject(h)) missingSpecs++;
+      }
+    }
+    if (missingSpecs) problems.push(`${missingSpecs} signed spec revision(s) are not in the archive (history could blank if git is lost) — re-sign or run a spec re-archive`);
+  }
+  return {
+    ok: problems.length === 0,
+    problems,
+    checks: { attestations: led.length, attestationsValidated: validated, chainOk, latestCovered: covered, specsChecked: checkedSpecs, specsMissing: missingSpecs },
+  };
+}
+
+// ── earned-autonomy metrics (from rejection + delegation history) ─────────────────
+// "refactor delegated changes — 97% ratified; dependency changes — 31% rejected → exclude by default."
+// Approximate but honest: delegated = autoApproved approvals; ratified ≈ a Cell that was delegated and
+// later carries a real human approval; rejected = recorded rejection events (P3), by category.
+function earnedAutonomy(rejections, approvals) {
+  const rej = (rejections && rejections.events ? rejections.events : rejections) || [];
+  const aps = approvals || [];
+  // per-Cell: was it ever delegated? ever human-signed after?
+  const delegatedCell = new Set(), humanCell = new Set();
+  for (const ap of aps) {
+    const ids = Object.keys(ap.items || {});
+    if (ap.autoApproved) ids.forEach((id) => delegatedCell.add(id));
+    else ids.forEach((id) => humanCell.add(id));
+  }
+  let ratified = 0; for (const id of delegatedCell) if (humanCell.has(id)) ratified++;
+  const byCategory = {};
+  let rejectedCells = 0;
+  for (const e of rej) {
+    if (e.type && e.type !== 'reject') continue;
+    const cat = String(e.category || 'other').toLowerCase();
+    const n = (e.cells || []).length || 1;
+    byCategory[cat] = (byCategory[cat] || 0) + n;
+    rejectedCells += n;
+  }
+  const delegated = delegatedCell.size;
+  const decided = ratified + rejectedCells;
+  const suggestions = [];
+  for (const cat of Object.keys(byCategory)) {
+    if (byCategory[cat] >= 3) suggestions.push(`"${cat}" changes have been rejected ${byCategory[cat]}× — consider excluding them from grants by default`);
+  }
+  return {
+    delegated, ratified, rejected: rejectedCells, byCategory,
+    ratifiedRate: decided ? +(ratified / decided).toFixed(3) : null,
+    suggestions,
+  };
+}
+
+module.exports = { reverifyDiff, integrityWitness, earnedAutonomy };

package/src/attest.js

@@ -0,0 +1,216 @@
+'use strict';
+// P2 — VERIFIER ATTESTATION. The third cryptographic identity (after artifact hashes and the
+// human phone signature): the machine verifier signs its OWN verdict with its OWN key, so "Green"
+// stops being a local, unfalsifiable claim and becomes a portable, verifiable object — "Green
+// under THIS verifier + environment at this time" (see docs 02, 03; decisions D3, D5, D13, D16).
+//
+// Separation of duties (D1): the verifier key is DISTINCT from any human/owner key and from the
+// machine grant key. It is project/CI-scoped and MACHINE-HELD (private half gitignored in
+// .yaylayer/keys/, never committed, NEVER shipped in the npm package — D11); only its PUBLIC key
+// is committed (config.verifier), so anyone can verify an attestation without being able to forge
+// one. A fresh clone / a CI runner without the secret can VERIFY attestations but cannot MINT them.
+//
+// "Green is an event" (D5): attestations are append-only. Each references the previous one's hash;
+// a better verifier appends new attestations (P4 `yay reverify`), never rewrites old ones. The
+// verifier carries a CAPABILITY VERSION (PATCH/MINOR/MAJOR) recorded in every attestation, so a
+// capability bump is a first-class, dated event.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const C = require('./crypto');
+const { canonical } = require('./util');
+const rosterMod = require('./roster');
+
+// The verifier's capability version + fingerprint live in src/capability.js, DERIVED from the live
+// provers/effect-nets/checks so a forgotten version bump can't silently claim more than the verifier
+// can do (assertCapability). Every attestation records both the declared version and the fingerprint.
+const { CAPABILITY, capabilityFingerprint } = require('./capability');
+
+function pkgVersion() {
+  try { return require('../package.json').version || '0.0.0'; } catch (_) { return '0.0.0'; }
+}
+
+function verifierKeyPath(p) { return path.join(p.keys, 'verifier.json'); }
+function attestPath(p) { return path.join(p.yay, 'attest.json'); }
+function attDir(p) { return path.join(p.yay, 'attestations'); }
+function attFile(p, hash) { return path.join(attDir(p), String(hash) + '.json'); }
+
+// Ensure a project verifier identity exists. The private half lives machine-side (gitignored keys/);
+// the public half is mirrored into config.verifier (committed) as the project's verifier of record.
+// `create` false → return null instead of generating (used by pure verification / read paths).
+function verifierIdentity(p, config, opts) {
+  const create = !opts || opts.create !== false;
+  const kp = verifierKeyPath(p);
+  let rec = null;
+  try { rec = JSON.parse(fs.readFileSync(kp, 'utf8')); } catch (_) { rec = null; }
+  if (!rec) {
+    if (!create) return null;
+    const gk = C.generateKeypair();
+    rec = { pub: gk.pubB64, priv: Buffer.from(gk.privDer).toString('base64'), createdAt: new Date().toISOString() };
+    fs.mkdirSync(p.keys, { recursive: true });
+    fs.writeFileSync(kp, JSON.stringify(rec, null, 2) + '\n', { mode: 0o600 });
+  }
+  return { pub: rec.pub, privDer: Buffer.from(rec.priv, 'base64'), fp: rosterMod.fingerprint(rec.pub) };
+}
+
+// The public verifier of record for this project: config.verifier.pub if pinned (committed),
+// else the local key's public half. Used to VERIFY attestations (needs no private key).
+function verifierPub(p, config) {
+  if (config && config.verifier && config.verifier.pub) return config.verifier.pub;
+  const id = verifierIdentity(p, config, { create: false });
+  return id ? id.pub : null;
+}
+
+// Pin the local verifier's PUBLIC key into config (committed) as the project verifier of record.
+// Returns true if config changed (caller writes it).
+function pinVerifier(config, id) {
+  config.verifier = config.verifier || {};
+  const changed = config.verifier.pub !== id.pub || config.verifier.capability !== CAPABILITY;
+  config.verifier.pub = id.pub;
+  config.verifier.fp = id.fp;
+  config.verifier.capability = CAPABILITY;
+  return changed;
+}
+
+// ── the canonical Verification object (what gets hashed + signed) ──────────────────────────────
+// A deterministic digest of exactly the inputs and outputs of a verification run:
+//   specSetHash  — the set of signed spec identities (per-Cell specHash)
+//   codeTreeHash — the exact code that was judged (per-Cell body hash)
+//   rulesetHash  — the signing/inertness policy in force (verdicts depend on it)
+//   evidenceHash — the per-Cell verdict + whether it was machine-proven
+//   result       — the gate summary (passed + colour counts)
+//   env          — recorded for determinism honesty (D16): same verifier can differ across
+//                  environments only on timing-sensitive cases; the attestation says so.
+// The leaf Cells (specs, not modules) in stable order — the unit of both spec-set and code-tree.
+function leafIds(manifest) {
+  const cells = manifest.cells || {};
+  return Object.keys(cells).filter((id) => !(cells[id].contains && cells[id].contains.length)).sort();
+}
+
+// Hash of the exact code that was (or would be) judged — per-leaf-Cell body. Cheap: needs only the
+// manifest, so callers (e.g. `yay sign`) can test "does an attestation cover this exact tree?"
+// without re-running the full verifier.
+function codeTreeHashOf(manifest) {
+  const cells = manifest.cells || {};
+  const codeTree = {};
+  for (const id of leafIds(manifest)) codeTree[id] = C.sha256(String(cells[id].unitBody || ''));
+  return C.sha256(canonical(codeTree));
+}
+
+function buildVerification(manifest, verified, opts) {
+  opts = opts || {};
+  const cells = manifest.cells || {};
+  const results = (verified && verified.results) || {};
+  const leaves = leafIds(manifest);
+
+  const specSet = {};
+  const codeTree = {};
+  const evidence = {};
+  for (const id of leaves) {
+    const c = cells[id];
+    specSet[id] = c.specHash || null;
+    codeTree[id] = C.sha256(String(c.unitBody || ''));
+    const r = results[id] || {};
+    evidence[id] = { state: r.state || 'UNSIGNED', proven: !!r.proven };
+    // Record the branch-coverage boundary of a proof, so the signed verdict is honest about
+    // how much of the code its inputs actually exercised (not just "proven").
+    if (r.coverage && r.coverage.total) evidence[id].branches = { exercised: r.coverage.exercised, total: r.coverage.total };
+  }
+  const counts = (verified && verified.counts) || {};
+  const result = {
+    passed: !!(verified && verified.passed),
+    counts: { GREEN: counts.GREEN || 0, YELLOW: counts.YELLOW || 0, RED: counts.RED || 0, UNSIGNED: counts.UNSIGNED || 0, PINK: counts.PINK || 0 },
+    proven: counts.proven || 0,
+  };
+  return {
+    v: 1,
+    kind: 'verification',
+    project: (opts.config && opts.config.project) || null,
+    capability: CAPABILITY,
+    capabilityFingerprint: capabilityFingerprint(), // binds the verdict to the EXACT detector set that produced it
+    verifierPkg: pkgVersion(),
+    specSetHash: C.sha256(canonical(specSet)),
+    codeTreeHash: C.sha256(canonical(codeTree)),
+    rulesetHash: C.sha256(canonical(opts.policy || { rules: [] })),
+    rootFp: (verified && verified.rootFp) || null,
+    evidenceHash: C.sha256(canonical(evidence)),
+    evidence, // per-Cell {state,proven} — small, self-describing, and lets `yay reverify` diff verdicts across capability versions
+    cells: leaves.length,
+    result,
+    env: { node: process.version, platform: os.platform() + '/' + os.arch() },
+    at: opts.at || new Date().toISOString(),
+  };
+}
+
+// Sign a verification object with the verifier key → a self-contained attestation. `hash` and the
+// signature both cover the SAME canonical bytes of the bare verification object, so a verifier
+// re-canonicalises {everything except hash/verifier/signature} and checks both.
+function signAttestation(verObj, id) {
+  const bytes = canonical(verObj);
+  const hash = C.sha256(bytes);
+  const signature = C.sign(bytes, id.privDer);
+  return Object.assign({}, verObj, { hash, verifier: { pub: id.pub, fp: id.fp }, signature });
+}
+
+// Recompute the canonical bytes of an attestation's verification core (strip the wrapper fields).
+function coreBytes(att) {
+  const core = Object.assign({}, att);
+  delete core.hash; delete core.verifier; delete core.signature; delete core.prev;
+  return canonical(core);
+}
+
+// Validate an attestation: its hash matches its core, the signature verifies under its embedded
+// verifier key, and (if a project verifier is pinned) that key IS the project's verifier of record.
+function verifyAttestation(att, expectedPub) {
+  if (!att || !att.verifier || !att.signature) return { ok: false, reason: 'not an attestation' };
+  const bytes = coreBytes(att);
+  if (C.sha256(bytes) !== att.hash) return { ok: false, reason: 'hash does not match content (tampered)' };
+  if (!C.verify(bytes, att.signature, att.verifier.pub)) return { ok: false, reason: 'bad verifier signature' };
+  if (expectedPub && att.verifier.pub !== expectedPub) return { ok: false, reason: 'signed by a different verifier than the project verifier of record' };
+  return { ok: true };
+}
+
+// Append-only attestation ledger (committed). Each entry references the previous hash → a chain
+// anchored by the project verifier. The full attestation object is stored content-addressed in
+// objects/ (keyed by its own hash); the ledger keeps the ordered index.
+function loadLedger(p, config) {
+  const led = (function () { try { return JSON.parse(fs.readFileSync(attestPath(p), 'utf8')); } catch (_) { return null; } })();
+  return led || { project: (config && config.project) || null, capability: CAPABILITY, entries: [] };
+}
+
+function appendAttestation(p, config, att) {
+  const led = loadLedger(p, config);
+  const prev = led.entries.length ? led.entries[led.entries.length - 1].hash : 'genesis';
+  att.prev = prev;
+  // Persist the full attestation (committed), keyed by its own attestation hash. The tamper check
+  // is verifyAttestation() — stronger than a raw sha256(content) check because it also re-validates
+  // the verifier signature. The ledger keeps the ordered, chained index.
+  fs.mkdirSync(attDir(p), { recursive: true });
+  fs.writeFileSync(attFile(p, att.hash), JSON.stringify(att, null, 2) + '\n');
+  led.entries.push({ hash: att.hash, at: att.at, passed: att.result.passed, capability: att.capability, codeTreeHash: att.codeTreeHash, prev });
+  led.capability = CAPABILITY;
+  fs.mkdirSync(path.dirname(attestPath(p)), { recursive: true });
+  fs.writeFileSync(attestPath(p), JSON.stringify(led, null, 2) + '\n');
+  return att;
+}
+
+// Load a stored attestation by its hash, re-validating signature + integrity before returning it
+// (null if missing or tampered — never hand back an unverified attestation).
+function loadAttestation(p, config, hash) {
+  let att = null;
+  try { att = JSON.parse(fs.readFileSync(attFile(p, hash), 'utf8')); } catch (_) { return null; }
+  const chk = verifyAttestation(att, verifierPub(p, config));
+  return chk.ok ? att : null;
+}
+
+function latestEntry(p, config) {
+  const led = loadLedger(p, config);
+  return led.entries.length ? led.entries[led.entries.length - 1] : null;
+}
+
+module.exports = {
+  CAPABILITY, verifierKeyPath, attestPath, attDir, attFile, verifierIdentity, verifierPub, pinVerifier,
+  buildVerification, codeTreeHashOf, leafIds, signAttestation, verifyAttestation, coreBytes,
+  loadLedger, appendAttestation, loadAttestation, latestEntry,
+};

package/src/capability.js

@@ -0,0 +1,59 @@
+'use strict';
+// VERIFIER CAPABILITY — the verifier's own versioned identity, DERIVED from what it can actually
+// detect and prove, so the declared version can't drift from reality.
+//
+// The problem this closes: `CAPABILITY` is a semver a human bumps by hand. If someone adds a prover,
+// an effect net, or a check but forgets to bump it, an attestation would claim capability 1.0.0 while
+// the verifier is really doing more (or, after a semantics change, something different) — a silent,
+// unversioned claim. So we compute a FINGERPRINT over a machine-derived descriptor of the live
+// capabilities and REGISTER the expected fingerprint per version. `assertCapability()` compares the
+// two; `yay attest` refuses on drift and tells you to bump + re-register. A shipped package never
+// drifts (its code and registry match); only a *modified* verifier does — exactly when we want the
+// guard to fire.
+
+const { sha256 } = require('./crypto');
+const { canonical } = require('./util');
+const { ADAPTERS } = require('./prove');
+const { effectNetDescriptor } = require('./verify');
+
+// Declared capability version (PATCH = bug fix, same verdicts · MINOR = new detectors/provers, a
+// verdict may improve · MAJOR = a semantics change that can flip existing verdicts). Bump this AND
+// re-register the fingerprint (below) whenever `describeCapability()` changes.
+const CAPABILITY = '1.2.0';
+
+// Checks the verifier runs on a passing Cell, and the policy rule kinds it understands. Listed
+// explicitly (and hashed) so adding/removing one is a visible, version-forcing change. Provers and
+// effect nets are pulled from the live code, so those shift the fingerprint on their own.
+const CHECKS = ['branch-coverage', 'ensures-prover', 'inertness', 'jsx-render-prover', 'literal-seeding', 'mutation-grading', 'predicate-provenance'];
+const POLICY_KINDS = ['coverage-full', 'ignore-source', 'inert-level', 'non-delegable', 'predicate-declared', 'required-signer', 'reverify-latest'];
+
+// A structured, machine-derived description of everything the verifier can currently do.
+function describeCapability() {
+  return {
+    v: 1,
+    provers: ADAPTERS.map((a) => a.name).sort(),   // ← live: adding an adapter changes this
+    effectNets: effectNetDescriptor(),             // ← live: adding a net / signal changes this
+    checks: CHECKS.slice().sort(),
+    policyKinds: POLICY_KINDS.slice().sort(),
+  };
+}
+
+// A stable hash over the descriptor — the verifier's capability fingerprint.
+function capabilityFingerprint() { return sha256(canonical(describeCapability())); }
+
+// The fingerprint expected for each declared version. The entry for the CURRENT CAPABILITY must
+// equal the live fingerprint; if it doesn't, the code changed without a version bump.
+const REGISTERED = {
+  '1.0.0': '1579c1ec83344596b4e3de93162ac7062d9846e0bd9793c7969b1fe3064e1aa1',
+  '1.1.0': '1d2a74604dcffc789bf7de6ee98f9368fee68241ea7aafcb87c57c858167388c',
+  '1.2.0': 'f29468bffd24b0f93529bd1daa6b1f98e96dce9df1b55993d44b4055c9599d75',
+};
+
+// Compare the live fingerprint to the one registered for the declared version.
+function assertCapability() {
+  const actual = capabilityFingerprint();
+  const expected = REGISTERED[CAPABILITY] || null;
+  return { ok: expected === actual, declared: CAPABILITY, expected, actual, drift: expected !== actual };
+}
+
+module.exports = { CAPABILITY, describeCapability, capabilityFingerprint, assertCapability, REGISTERED };

package/src/constitution.js

@@ -0,0 +1,162 @@
+'use strict';
+// Write the YayLayer Constitution into the instruction file that a given AI coding
+// harness auto-reads, so a fresh session in this repo follows YayLayer from the
+// very first file. The Constitution text is the single source (../CONSTITUTION.md);
+// we just place it where each tool looks.
+//
+// Writes are marker-wrapped and idempotent: the block between YAYLAYER:BEGIN/END is
+// managed by `yay` (re-running updates just that block); anything outside it is the
+// user's and is preserved.
+
+const fs = require('fs');
+const path = require('path');
+
+const BEGIN = '<!-- YAYLAYER:BEGIN (managed by `yay` — re-run `yay constitution` to update; edits inside are overwritten) -->';
+const END = '<!-- YAYLAYER:END -->';
+
+// File-based, auto-loaded instruction conventions per harness. `note` flags how
+// standard each is — conventions move fast, so verify against your tool's docs.
+const HARNESSES = [
+  { key: 'claude', label: 'Claude Code', path: 'CLAUDE.md', note: 'auto-loaded at repo root' },
+  { key: 'agents', label: 'AGENTS.md (Codex CLI + cross-tool standard)', path: 'AGENTS.md', note: 'read by OpenAI Codex CLI and a growing set of tools' },
+  { key: 'copilot', label: 'GitHub Copilot', path: '.github/copilot-instructions.md', note: 'repo custom instructions' },
+  { key: 'cursor', label: 'Cursor', path: '.cursorrules', note: 'legacy single-file (modern: .cursor/rules/*.mdc)' },
+  { key: 'windsurf', label: 'Windsurf', path: '.windsurfrules', note: 'root rules file' },
+  { key: 'cline', label: 'Cline', path: '.clinerules', note: 'root rules file' },
+  { key: 'gemini', label: 'Gemini CLI', path: 'GEMINI.md', note: 'auto-loaded at repo root' },
+  { key: 'generic', label: 'CONSTITUTION.md (wire into any tool yourself)', path: 'CONSTITUTION.md', note: 'plain copy; point your tool at it' },
+];
+
+// The approval command depends on how THIS project signs (chosen at `yay init`):
+// a phone-signed project must tell the AI to have the human approve on their phone.
+// `yay sign` auto-uses the project's established method, so the command is always
+// just `yay sign` — the note explains where the signature actually happens.
+function signGuidance(method) {
+  if (method === 'phone') {
+    return { cmd: '`yay sign`', note: 'This project signs on a **phone**: `yay sign` automatically opens the phone approval (prints a QR/URL) and the signing key never touches this machine. You cannot sign — only the human’s phone can.' };
+  }
+  if (method === 'local') {
+    return { cmd: '`yay sign`', note: 'This project signs with a **local key**: `yay sign` prompts for the human’s passphrase.' };
+  }
+  return { cmd: '`yay sign`', note: '`yay sign` uses whichever signing method this project is set up with.' };
+}
+
+function header(method) {
+  const g = signGuidance(method);
+  const waits = method === 'phone';
+  return [
+    '# This project is built under YayLayer',
+    '',
+    'Follow the YayLayer Constitution below **exactly, from the very first file**.',
+    '',
+    '**The loop for every observable change:**',
+    '1. Write/update the spec block(s) FIRST — no implementation code yet.',
+    '2. Draft a one-paragraph **Brief** — what the human asked you to build, in your own',
+    '   fine-tuned words (not their verbatim text) — and present the change-set headed by it,',
+    '   with the colour you expect each Cell to earn. Then request approval by running',
+    `   \`yay sign --brief "<that paragraph>"\` yourself. ${waits ? 'It BLOCKS until the human approves on their phone, where they can EDIT the brief before signing (allow a few minutes; use a long command timeout).' : 'The human enters their passphrase to sign.'}`,
+    `3. **The moment ${g.cmd} returns a completed signature, continue on your own** — implement the code`,
+    '   to match the signed spec, then run `yay verify` and report the result. Do NOT stop to ask',
+    '   "should I implement now?" — a returned signature IS the go-ahead.',
+    '4. When `yay verify` passes, COMMIT the code and `.yaylayer/` together in ONE commit',
+    '   (e.g. `git add -A && git commit -m "C-xxx: <intent> (signed)"`). This makes the seal durable',
+    '   (the CI gate reads committed state) and gives the next spec change a clean before/after diff.',
+    '   Do NOT `git push` unless the human asks.',
+    '5. If approval fails, is declined, or times out, STOP and ask — never implement unapproved specs.',
+    '',
+    '**When the human adds new requests before signing the pending brief:** decide by coherence, and keep one brief = one coherent intent.',
+    '- If the additions BELONG to the same brief (logically part of the same intent), SUGGEST folding them in: cancel the pending approval, add the new spec(s), and re-present ONE updated brief covering everything, then sign.',
+    '- If they are a DIFFERENT concern, ask the human to SIGN (or decline) the current brief FIRST, then start the new concern as its own separate brief.',
+    'Never mix unrelated concerns into one brief, and never leave a stale pending approval hanging.',
+    '',
+    '**Specs are never perfect — treat `yay verify` as a spec-STRENGTHENING loop, not just a pass/fail gate.**',
+    'When it flags a Cell as weak — `ensures` not machine-verified (prose), inputs (`in:`) under-declared, a',
+    'dangling reference, a unit-name mismatch, or a prover/adversary counterexample — do NOT leave it green.',
+    'Propose a STRONGER spec (a checkable `ensures` as a boolean JS expression over `out` and the inputs;',
+    'tighter `in:` domains; the corrected clause), present it, get it RE-SIGNED, then reconcile the code.',
+    'For SIDE-EFFECTING code (canvas/DOM/IO), declare its effect surface with `records: <param>` and write',
+    '`ensures` over the recorded trace — `calls(name)` (arg-arrays), `sets(name)` (assigned values),',
+    '`didCall(name)`, `didSet(name, value)` — so effects become machine-checkable instead of unprovable.',
+    'A signed-but-unproven Cell is a to-do, not a finish line. Run `yay adversary` to hunt weak spots.',
+    '',
+    `Never sign on the human's behalf${waits ? ' (only their phone holds the key — you cannot)' : ''}. ${g.note}`.trim(),
+    '',
+    '---',
+    '',
+    '',
+  ].join('\n');
+}
+
+function constitutionText() {
+  return fs.readFileSync(path.join(__dirname, '..', 'CONSTITUTION.md'), 'utf8').trim();
+}
+// The project's own tag pool, embedded so the AI sees the ACTUAL tags to use (Article 13).
+function tagPoolBlock(root) {
+  try {
+    const o = JSON.parse(fs.readFileSync(path.join(root, '.yaylayer', 'tags.json'), 'utf8'));
+    if (o && Array.isArray(o.tags) && o.tags.length) {
+      const d = o.descriptions || {};
+      const hasD = o.tags.some((t) => d[t]);
+      const body = hasD
+        ? o.tags.map((t) => '- `' + t + '`' + (d[t] ? ' — ' + d[t] : '')).join('\n')
+        : o.tags.map((t) => '`' + t + '`').join(' · ');
+      return '\n\n---\n\n**Project tag pool** (Article 13) — tag every Brief with 1–3 of these, via `yay sign --tags "…"`:\n\n' + body + '\n';
+    }
+  } catch (_) {}
+  return '';
+}
+// Cell-id shard directive (Article 2). The literal shard is NOT baked in here — the constitution is
+// committed and shared, but each working copy needs its OWN shard so ids never collide on merge. So
+// the shard lives in gitignored .yaylayer/local.json; this tells the AI to look it up per clone.
+function shardBlock() {
+  return '\n\n---\n\n**Cell-id shard** (Article 2) — mint every NEW Cell as `C-<shard>-<n>`, where ' +
+    '`<shard>` is THIS working copy\'s shard: run `yay id` to get it (unique to your clone, so ids from ' +
+    'different clones never collide when branches merge). Count up from the highest `C-<shard>-*` already ' +
+    'present; never reuse a number, even a deleted Cell\'s. (Legacy flat `C-NNN` ids keep working as-is.)\n';
+}
+function block(method, root) {
+  return `${BEGIN}\n${header(method)}${constitutionText()}${root ? tagPoolBlock(root) : ''}${shardBlock()}\n${END}\n`;
+}
+
+function mergeInto(existing, blk) {
+  const i = existing.indexOf(BEGIN);
+  const j = existing.indexOf(END);
+  if (i !== -1 && j !== -1 && j > i) {
+    return existing.slice(0, i) + blk.trimEnd() + existing.slice(j + END.length);
+  }
+  const sep = existing.endsWith('\n') ? '\n' : '\n\n';
+  return existing + sep + blk; // append, preserving the user's own content
+}
+
+function harnessByKey(key) { return HARNESSES.find((h) => h.key === key); }
+function resolveKeys(spec) {
+  if (!spec || spec === 'all') return HARNESSES.map((h) => h.key);
+  return String(spec).split(/[,\s]+/).map((s) => s.trim().toLowerCase()).filter(Boolean);
+}
+
+// Write/merge the constitution into the chosen harness files. Returns a report
+// [{ key, label, path, action:'created'|'updated'|'appended'|'unchanged' } | { key, error }].
+function writeConstitution(root, keys, method) {
+  const blk = block(method, root);
+  const report = [];
+  for (const key of keys) {
+    const h = harnessByKey(key);
+    if (!h) { report.push({ key, error: 'unknown harness' }); continue; }
+    const abs = path.join(root, h.path);
+    let action;
+    if (fs.existsSync(abs)) {
+      const before = fs.readFileSync(abs, 'utf8');
+      const after = mergeInto(before, blk);
+      if (after === before) action = 'unchanged';
+      else { fs.writeFileSync(abs, after); action = before.includes(BEGIN) ? 'updated' : 'appended'; }
+    } else {
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, blk);
+      action = 'created';
+    }
+    report.push({ key, label: h.label, path: h.path, action });
+  }
+  return report;
+}
+
+module.exports = { HARNESSES, writeConstitution, resolveKeys, harnessByKey };

package/src/coverage.js

@@ -0,0 +1,77 @@
+'use strict';
+// BRANCH-EXERCISE HONESTY. During proving we count which branches the spec-derived inputs actually
+// EXECUTED. A Cell can pass its `ensures` yet leave branches unexercised — and a dormant payload is,
+// by definition, an unexercised branch. So instead of hiding that inside an unqualified green, we
+// show the coverage boundary ("proven — 5/7 branches exercised") and feed the missed branches to
+// inertness + policy. HONESTY INVARIANT preserved: coverage is a BADGE, never a Green→X downgrade by
+// itself (a legitimate `throws:` guard is often unexercised on purpose); only an owner-signed policy
+// (`coverage: full`) makes missing exercise gate-blocking for sensitive Cells.
+//
+// Instrumentation is a Babel pass: probe each branch with `__ylcov[i]++`, keyed to the ORIGINAL
+// source line. Babel is an OPTIONAL dep (same as the JSX prover) — absent ⇒ we return null and there
+// is simply no badge, never an error.
+
+// Instrument the branches of `source` whose position falls within [startLine,endLine] (1-based, the
+// unit's body) so each records a hit in a global `__ylcov` array. TS/JSX are lowered in the same pass
+// (so the output runs), while probe line numbers stay in ORIGINAL-source coordinates. Returns
+// { code, probes:[{line,kind}] } or null (Babel missing / parse fail — graceful, no badge).
+function instrument(source, startLine, endLine, opts) {
+  opts = opts || {};
+  let babel, t;
+  try { babel = require('@babel/core'); t = require('@babel/types'); }
+  catch (_) { return null; }
+
+  const probes = [];
+  const inRange = (node) => !!node.loc && node.loc.start.line >= startLine && node.loc.start.line <= endLine;
+  const lineOf = (node, fallback) => ((node && node.loc) ? node.loc.start.line : fallback);
+  const member = (idx) => t.memberExpression(t.identifier('__ylcov'), t.numericLiteral(idx), true);
+  const stmtProbe = (idx) => t.expressionStatement(t.updateExpression('++', member(idx)));
+  const exprProbe = (idx, expr) => t.sequenceExpression([t.updateExpression('++', member(idx)), expr]);
+  const asBlock = (node) => t.isBlockStatement(node) ? node : t.blockStatement([t.isStatement(node) ? node : t.expressionStatement(node)]);
+  // add a probe as the first statement of a (possibly newly-wrapped) block; returns the block.
+  const probedBlock = (node, kind) => { const idx = probes.length; probes.push({ line: lineOf(node), kind }); const b = asBlock(node); b.body.unshift(stmtProbe(idx)); return b; };
+  const probedExpr = (node, kind) => { const idx = probes.length; probes.push({ line: lineOf(node), kind }); return exprProbe(idx, node); };
+
+  const plugin = () => ({ visitor: {
+    IfStatement(pth) {
+      const n = pth.node; if (!inRange(n)) return;
+      n.consequent = probedBlock(n.consequent, 'if');
+      if (n.alternate) n.alternate = probedBlock(n.alternate, 'else');
+    },
+    ConditionalExpression(pth) {
+      const n = pth.node; if (!inRange(n)) return;
+      n.consequent = probedExpr(n.consequent, 'ternary');
+      n.alternate = probedExpr(n.alternate, 'ternary');
+    },
+    LogicalExpression(pth) {
+      const n = pth.node; if (!inRange(n)) return;
+      n.right = probedExpr(n.right, 'logical'); // RHS only runs when the operator short-circuits into it
+    },
+    SwitchCase(pth) {
+      const n = pth.node; if (!inRange(n) || !n.consequent.length) return;
+      const idx = probes.length; probes.push({ line: lineOf(n), kind: 'case' });
+      n.consequent.unshift(stmtProbe(idx));
+    },
+    CatchClause(pth) {
+      const n = pth.node; if (!inRange(n)) return;
+      const idx = probes.length; probes.push({ line: lineOf(n), kind: 'catch' });
+      n.body.body.unshift(stmtProbe(idx));
+    },
+    'ForStatement|WhileStatement|DoWhileStatement|ForInStatement|ForOfStatement'(pth) {
+      const n = pth.node; if (!inRange(n)) return;
+      n.body = probedBlock(n.body, 'loop');
+    },
+  } });
+
+  // Coverage plugin FIRST (capture branches at original positions), then TS/JSX lowering.
+  const plugins = [plugin];
+  if (opts.ts) { try { let p = require('@babel/plugin-transform-typescript'); plugins.push([p.default || p, { isTSX: !!opts.tsx, allowDeclareFields: true }]); } catch (_) { return null; } }
+  if (opts.jsx) { try { let p = require('@babel/plugin-transform-react-jsx'); plugins.push([p.default || p, { runtime: 'classic', pragma: '__h', pragmaFrag: '__Fragment' }]); } catch (_) { return null; } }
+  try {
+    const out = babel.transformSync(source, { filename: opts.file || 'cell.js', babelrc: false, configFile: false, compact: false, plugins });
+    if (!out || out.code == null) return null;
+    return { code: out.code, probes };
+  } catch (_) { return null; }
+}
+
+module.exports = { instrument };