@starci/skills 1.1.0

package/operators/business-decide/validate.mjs

@@ -0,0 +1,277 @@
+// business.decide's own law over one branch, on top of the shared step check: the mode decides which
+// half ran, and a reconcile branch binds the delivered source it reconciles against; the head is
+// exactly one feature directory below the businesses root; the model, the response and the frozen
+// matrix are the same decision read three ways; the lineage transition is legal and agrees with both
+// states; an implemented head reconciles against delivered source with no discrepancy; the matrix
+// carries exactly one row per declared dimension and no other; a mandatory dimension and a discovered
+// lifecycle branch are never not-applicable; each disposition carries the substance it owes and no
+// more; every enforcing row rests on a fact claim from claims.json; every discovered consumer is
+// disposed once, under the dimension it was discovered in; and a blocked branch publishes no head.
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { validateStep } from '../../scripts/validate-step.mjs';
+import { tableUnder } from '../../scripts/validate-response.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+// A promise always has an actor, an entry, a purchase effect, a settlement, an idempotency answer, an
+// entitlement consumer, and a denial path. Marking one of these not-applicable, once it is declared,
+// is how "full access" was published while its downstream consumers were never proved.
+const MANDATORY_DIMENSIONS = new Set([
+  'actor-eligibility', 'offer-entry', 'read-entry', 'purchase-side-effect', 'settlement',
+  'idempotency', 'entitlement-consumer', 'denial',
+]);
+const LEGAL_TRANSITIONS = {
+  'absent->pending': { from: null, to: 'pending' },
+  'pending->in-progress': { from: 'pending', to: 'in-progress' },
+  'pending->rejected': { from: 'pending', to: 'rejected' },
+  'in-progress->implemented': { from: 'in-progress', to: 'implemented' },
+  'in-progress->rejected': { from: 'in-progress', to: 'rejected' },
+  'implemented->in-progress': { from: 'implemented', to: 'in-progress' },
+  'implemented->rejected': { from: 'implemented', to: 'rejected' },
+  'rejected->pending': { from: 'rejected', to: 'pending' },
+};
+const BUSINESSES_ROOT = /\.worktrees\/businesses$/;
+const empty = (v) => v === undefined || v === null || v === '' || v === '—';
+const fields = (rows) => Object.fromEntries((rows ?? []).map(([k, v]) => [k, v]));
+
+export async function validateBusinessStep(branchDir, root = ROOT) {
+  const base = await validateStep(root, branchDir);
+  const errors = [...base.errors];
+  const { request, response, requirements = {}, present = new Set() } = base;
+  if (!response || response.operatorId !== 'business.decide') return { errors };
+  const has = (f) => existsSync(path.join(branchDir, f));
+  const read = (f) => readFile(path.join(branchDir, f), 'utf8');
+  const mode = requirements.mode ?? 'model';
+  const inputs = request?.inputs ?? {};
+
+  // The Inputs table cannot say "required under one mode", so the mode says it here.
+  if (mode === 'reconcile' && empty(inputs['backend-source-application'])) {
+    errors.push('request.json: mode reconcile reconciles against delivered source, so input backend-source-application is required');
+  }
+  if (mode === 'model' && !empty(inputs['backend-source-application'])) {
+    errors.push('request.json: mode model models the promise and reads no delivered source, so input backend-source-application is refused');
+  }
+
+  // A blocked branch publishes no head and freezes no coverage fingerprint.
+  if (response.status === 'blocked') {
+    if (present.has('coverage-matrix')) errors.push('response/response.json: a blocked branch cannot freeze a coverage matrix');
+    if (present.has('model')) errors.push('response/response.json: a blocked branch cannot publish a head');
+  }
+  if (response.status === 'done' && mode === 'model' && !present.has('coverage-matrix')) {
+    errors.push('response/response.json: mode model freezes the coverage matrix, so coverage-matrix must be in fields');
+  }
+  if (mode === 'reconcile' && present.has('coverage-matrix')) {
+    errors.push('response/response.json: mode reconcile models nothing, so it may not freeze a new coverage matrix');
+  }
+
+  const declaredDimensions = Array.isArray(requirements.dimensions) ? requirements.dimensions : [];
+
+  let claims = new Map();
+  if (present.has('claims') && has('response/data/claims.json')) {
+    let doc = null;
+    try { doc = JSON.parse(await read('response/data/claims.json')); } catch { doc = null; }
+    if (doc) {
+      if (!empty(requirements.featureId) && doc.featureId !== requirements.featureId) errors.push(`response/data/claims.json: featureId ${doc.featureId} differs from the request's ${requirements.featureId}`);
+      for (const claim of doc.claims ?? []) {
+        if (claims.has(claim.claimId)) errors.push(`response/data/claims.json: claim ${claim.claimId} is declared more than once`);
+        claims.set(claim.claimId, claim);
+        if (claim.lineEnd < claim.lineStart) errors.push(`response/data/claims.json: claim ${claim.claimId} has an inverted line range`);
+        if (claim.kind === 'fact' && claim.sourceHead === null) errors.push(`response/data/claims.json: fact claim ${claim.claimId} must bind the observed source head`);
+        if (claim.kind === 'contradiction') errors.push(`response/data/claims.json: claim ${claim.claimId} is a contradiction, which stops the branch with CONTRADICTION_UNRESOLVED rather than being published`);
+      }
+    }
+  }
+
+  let matrix = null;
+  if (present.has('coverage-matrix') && has('response/data/coverage-matrix.json')) {
+    try { matrix = JSON.parse(await read('response/data/coverage-matrix.json')); } catch { matrix = null; }
+  }
+
+  if (matrix) {
+    if (!empty(requirements.featureId) && matrix.featureId !== requirements.featureId) {
+      errors.push(`response/data/coverage-matrix.json: featureId ${matrix.featureId} differs from the request's ${requirements.featureId}`);
+    }
+    if (declaredDimensions.length) {
+      for (const dimension of declaredDimensions) if (!matrix.dimensions.includes(dimension)) errors.push(`response/data/coverage-matrix.json: the request declared dimension ${dimension}, which the matrix does not carry`);
+      for (const dimension of matrix.dimensions) if (!declaredDimensions.includes(dimension)) errors.push(`response/data/coverage-matrix.json: dimension ${dimension} was never declared by the request`);
+    }
+    const rowByDimension = new Map();
+    for (const row of matrix.rows) {
+      if (rowByDimension.has(row.dimension)) errors.push(`response/data/coverage-matrix.json: coverage dimension ${row.dimension} appears in more than one row`);
+      rowByDimension.set(row.dimension, row);
+      if (!matrix.dimensions.includes(row.dimension)) errors.push(`response/data/coverage-matrix.json: row ${row.dimension} is not one of the declared dimensions`);
+    }
+    for (const dimension of matrix.dimensions) {
+      if (!rowByDimension.has(dimension)) errors.push(`response/data/coverage-matrix.json: coverage dimension ${dimension} has no disposition`);
+    }
+
+    const consumerIds = new Set();
+    for (const consumer of matrix.discoveredConsumers) {
+      if (consumerIds.has(consumer.consumerId)) errors.push(`response/data/coverage-matrix.json: discovered consumer ${consumer.consumerId} is declared more than once`);
+      consumerIds.add(consumer.consumerId);
+    }
+
+    const claimedConsumers = new Map();
+    for (const row of matrix.rows) {
+      const { dimension, disposition } = row;
+      if (disposition === 'not-applicable' && MANDATORY_DIMENSIONS.has(dimension)) {
+        errors.push(`response/data/coverage-matrix.json: ${dimension} is mandatory for a published promise and cannot be marked not-applicable`);
+      }
+      if (disposition === 'preserve' || disposition === 'replace') {
+        if (row.enforcementOwner === null) errors.push(`response/data/coverage-matrix.json: ${dimension} names no enforcement owner`);
+        if (row.sourceRef === null) errors.push(`response/data/coverage-matrix.json: ${dimension} names no enforcing source`);
+        if (row.positiveProofRef === null) errors.push(`response/data/coverage-matrix.json: ${dimension} has no positive proof`);
+        if (row.negativeProofRef === null) errors.push(`response/data/coverage-matrix.json: ${dimension} has no negative proof, so nothing shows the promise is denied when it should be`);
+      }
+      if (disposition === 'retire') {
+        if (row.enforcementOwner === null) errors.push(`response/data/coverage-matrix.json: retired ${dimension} names no owner of the retirement`);
+        if (row.sourceRef === null) errors.push(`response/data/coverage-matrix.json: retired ${dimension} names no source where the path was closed`);
+        if (row.positiveProofRef === null) errors.push(`response/data/coverage-matrix.json: retired ${dimension} has no proof the path is closed`);
+      }
+      if (disposition === 'defer') {
+        if (row.deferralRef === null) errors.push(`response/data/coverage-matrix.json: deferred ${dimension} names no deferral owner reference`);
+        if (row.positiveProofRef !== null || row.negativeProofRef !== null) errors.push(`response/data/coverage-matrix.json: deferred ${dimension} cannot claim proof for work that has not happened`);
+      }
+      if (disposition === 'not-applicable' && (row.enforcementOwner !== null || row.sourceRef !== null || row.positiveProofRef !== null || row.negativeProofRef !== null || row.deferralRef !== null || row.consumerIds.length > 0 || row.claimIds.length > 0)) {
+        errors.push(`response/data/coverage-matrix.json: ${dimension} is marked not-applicable but still carries owners, proof, consumers, or claims`);
+      }
+      for (const consumerId of row.consumerIds) {
+        if (claimedConsumers.has(consumerId)) errors.push(`response/data/coverage-matrix.json: consumer ${consumerId} is disposed in more than one row`);
+        claimedConsumers.set(consumerId, dimension);
+      }
+      // An example or a screenshot illustrates a promise; it never creates one.
+      if (claims.size) {
+        for (const claimId of row.claimIds) if (!claims.has(claimId)) errors.push(`response/data/coverage-matrix.json: ${dimension} cites claim ${claimId}, which claims.json does not carry`);
+        if (disposition === 'preserve' || disposition === 'replace' || disposition === 'retire') {
+          if (!row.claimIds.some((claimId) => claims.get(claimId)?.kind === 'fact')) errors.push(`response/data/coverage-matrix.json: ${dimension} asserts enforcement without one fact claim; examples and intent never create product truth`);
+        }
+      }
+    }
+
+    // The rule the "full access" release lacked: nothing discovered may pass without a disposition.
+    for (const consumer of matrix.discoveredConsumers) {
+      const disposedAt = claimedConsumers.get(consumer.consumerId);
+      if (disposedAt === undefined) errors.push(`response/data/coverage-matrix.json: discovered consumer ${consumer.consumerId} has no disposition in the coverage matrix`);
+      else if (disposedAt !== consumer.dimension) errors.push(`response/data/coverage-matrix.json: discovered consumer ${consumer.consumerId} was discovered under ${consumer.dimension} but disposed under ${disposedAt}`);
+    }
+    for (const consumerId of claimedConsumers.keys()) {
+      if (!matrix.discoveredConsumers.some((item) => item.consumerId === consumerId)) errors.push(`response/data/coverage-matrix.json: row consumer ${consumerId} was never discovered, so no evidence supports it`);
+    }
+    for (const branch of matrix.discoveredLifecycleBranches) {
+      const row = rowByDimension.get(branch);
+      if (!row) errors.push(`response/data/coverage-matrix.json: lifecycle branch ${branch} was discovered in the source and has no disposition`);
+      else if (row.disposition === 'not-applicable') errors.push(`response/data/coverage-matrix.json: lifecycle branch ${branch} was discovered in the source and cannot be marked not-applicable`);
+    }
+  }
+
+  let model = null;
+  if (present.has('model') && has('response/data/model.json')) {
+    try { model = JSON.parse(await read('response/data/model.json')); } catch { model = null; }
+  }
+  if (model) {
+    if (!empty(requirements.featureId) && model.featureId !== requirements.featureId) errors.push(`response/data/model.json: featureId ${model.featureId} differs from the request's ${requirements.featureId}`);
+    if (model.mode !== mode) errors.push(`response/data/model.json: mode ${model.mode} differs from the request's ${mode}`);
+    if (!empty(requirements.targetState) && model.state !== requirements.targetState) errors.push(`response/data/model.json: state ${model.state} differs from the request's target ${requirements.targetState}`);
+
+    // The head is one flat segment below the businesses root, and the root is the businesses worktree.
+    const headRef = String(model.headRef ?? '');
+    const cut = headRef.lastIndexOf('/features/');
+    if (cut === -1) errors.push(`response/data/model.json: head ${headRef} must be exactly <businesses root>/features/${model.featureId}: the feature directory, with no project segment below the businesses root`);
+    else {
+      if (!BUSINESSES_ROOT.test(headRef.slice(0, cut))) errors.push(`response/data/model.json: head ${headRef} is not under a .worktrees/businesses root`);
+      if (headRef.slice(cut + '/features/'.length) !== model.featureId) errors.push(`response/data/model.json: head ${headRef} must name the feature ${model.featureId}, with no project segment below the businesses root`);
+    }
+
+    // Lifecycle. A state that arrives through an unlisted transition has no lineage behind it.
+    const transition = LEGAL_TRANSITIONS[model.lineage.transition];
+    if (!transition) errors.push(`response/data/model.json: transition ${model.lineage.transition} is not a legal lifecycle transition`);
+    else {
+      if (transition.from !== model.lineage.previousState) errors.push(`response/data/model.json: transition ${model.lineage.transition} contradicts previous state ${String(model.lineage.previousState)}`);
+      if (transition.to !== model.state) errors.push(`response/data/model.json: transition ${model.lineage.transition} contradicts published state ${model.state}`);
+    }
+    if (model.lineage.previousState === null && model.lineage.previousHeadRef !== null) errors.push('response/data/model.json: a first publication cannot name a previous head');
+    if (model.lineage.previousState !== null && model.lineage.previousHeadRef === null) errors.push('response/data/model.json: a transition from an existing state must name the previous head, because rejection preserves lineage');
+
+    if (matrix && model.coverageFingerprint !== matrix.fingerprint) errors.push('response/data/model.json: coverageFingerprint must equal the frozen matrix fingerprint, or backend and UAT cannot correlate the same matrix');
+    if (mode === 'model' && model.reconciliation !== null) errors.push('response/data/model.json: mode model reconciles nothing, so reconciliation must be null');
+    if (mode === 'reconcile') {
+      if (model.reconciliation === null) errors.push('response/data/model.json: mode reconcile must carry the reconciliation it performed');
+      else if (response.status === 'done' && model.reconciliation.discrepancies.length) errors.push(`response/data/model.json: ${model.reconciliation.discrepancies.length} reconciliation discrepancy or discrepancies remain, so the branch is RECONCILIATION_DISCREPANCY rather than done`);
+    }
+    // implemented is never published on the strength of a plan.
+    if (model.state === 'implemented' && model.reconciliation === null) errors.push('response/data/model.json: an implemented head requires reconciliation against delivered source');
+  }
+
+  if (present.has('business-promise-authority') && has('response/response.md')) {
+    const text = await read('response/response.md');
+    const binding = fields(tableUnder(text, '## Binding'));
+    const lineage = fields(tableUnder(text, '## Lineage'));
+    const featureId = binding.Feature;
+
+    if (!empty(requirements.featureId) && featureId !== requirements.featureId) errors.push(`response/response.md: Feature ${featureId} differs from the request's ${requirements.featureId}`);
+    if (binding.Mode !== mode) errors.push(`response/response.md: Mode ${binding.Mode} differs from the request's ${mode}`);
+    if (!empty(requirements.targetState) && binding['Target state'] !== requirements.targetState) errors.push(`response/response.md: Target state ${binding['Target state']} differs from the request's ${requirements.targetState}`);
+    if (model) {
+      if (binding.Head !== model.headRef) errors.push(`response/response.md: Head ${binding.Head} differs from the published head ${model.headRef}`);
+      if (lineage.Transition !== model.lineage.transition) errors.push(`response/response.md: Transition ${lineage.Transition} differs from the model's ${model.lineage.transition}`);
+      if (binding['Claims fingerprint'] !== model.claimsFingerprint) errors.push('response/response.md: Claims fingerprint must equal the model claimsFingerprint');
+    }
+    if (matrix) {
+      if (binding['Coverage fingerprint'] !== matrix.fingerprint) errors.push('response/response.md: Coverage fingerprint must equal the coverage matrix fingerprint, or backend and UAT cannot correlate the same matrix');
+      if (featureId !== matrix.featureId) errors.push(`response/response.md: Feature ${featureId} differs from the matrix feature ${matrix.featureId}`);
+    }
+
+    // Cited claims: the response says exactly what claims.json holds, read by a person.
+    const cited = new Set();
+    for (const [claim, kind] of tableUnder(text, '## Cited claims') ?? []) {
+      if (cited.has(claim)) errors.push(`response/response.md: cited claim ${claim} is listed more than once`);
+      cited.add(claim);
+      if (claims.size) {
+        const record = claims.get(claim);
+        if (!record) errors.push(`response/response.md: cited claim ${claim} is absent from claims.json`);
+        else if (record.kind !== kind) errors.push(`response/response.md: claim ${claim} is ${kind} here and ${record.kind} in claims.json`);
+      }
+    }
+    for (const claimId of claims.keys()) if (!cited.has(claimId)) errors.push(`response/response.md: claims.json carries ${claimId}, which Cited claims omits`);
+
+    // The response table and the frozen matrix are the same decision, read two ways.
+    const mdRows = tableUnder(text, '## Coverage') ?? [];
+    if (matrix) {
+      if (mdRows.length !== matrix.rows.length) errors.push(`response/response.md: Coverage has ${mdRows.length} rows, the matrix has ${matrix.rows.length}`);
+      const byDimension = new Map(matrix.rows.map((r) => [r.dimension, r]));
+      for (const [dimension, disposition] of mdRows) {
+        const row = byDimension.get(dimension);
+        if (!row) { errors.push(`response/response.md: Coverage names dimension ${dimension}, which the matrix does not carry`); continue; }
+        if (row.disposition !== disposition) errors.push(`response/response.md: ${dimension} is ${disposition} here and ${row.disposition} in the matrix`);
+      }
+    } else if (mdRows.length) errors.push('response/response.md: Coverage carries rows, but no coverage matrix was frozen in this mode');
+
+    const reconciliation = tableUnder(text, '## Reconciliation') ?? [];
+    if (mode === 'reconcile') {
+      if (reconciliation.length === 0) errors.push('response/response.md: a reconcile branch requires reconciliation against delivered source');
+      for (const [dimension, delivered, discrepancy] of reconciliation) {
+        if (empty(delivered)) errors.push(`response/response.md: reconciliation of ${dimension} names no delivered evidence`);
+        if (!empty(discrepancy) && response.status === 'done') errors.push(`response/response.md: a published head cannot carry the unresolved reconciliation discrepancy on ${dimension}`);
+      }
+    } else if (reconciliation.length) errors.push('response/response.md: mode model reconciles nothing, so Reconciliation carries no rows');
+
+    // A published receipt cannot retain an error finding.
+    if (response.status === 'done') {
+      for (const [code, severity] of tableUnder(text, '## Findings') ?? []) {
+        if (severity === 'error') errors.push(`response/response.md: finding ${code} is still an open error, so the promise cannot be published`);
+      }
+    }
+  }
+  return { errors };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const target = process.argv[2];
+  if (!target) { process.stderr.write('usage: node validate.mjs <session>/step-N/parallel-M\n'); process.exit(2); }
+  const { errors } = await validateBusinessStep(path.resolve(target));
+  if (errors.length) { process.stderr.write(`${errors.join('\n')}\n`); process.exitCode = 1; } else process.stdout.write('valid business.decide branch\n');
+}

package/operators/content-generate/errors.json

@@ -0,0 +1,106 @@
+{
+  "schemaVersion": 9,
+  "note": "Stop codes only content.generate emits. Same entry shape as operators/errors.json, scope implicit. Shared codes (INVALID_INPUT, SOURCE_DRIFT, NO_PROGRESS) come from operators/errors.json. Every domain below is the one the old package's owningDomain enum published for this operator: content, curriculum, engineering, workspace, caller. routing.json answers content with a resume of this operator, and curriculum and engineering each with a person, which is not the same person as caller: the curriculum owner and the engineer who owns the generator are named separately on purpose.",
+  "codes": {
+    "BRIEF_UNBOUND": {
+      "domain": "curriculum",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The teacher brief cannot be frozen from the bound curriculum and source evidence.",
+        "vi": "Không đóng băng được brief người dạy từ chương trình học và bằng chứng nguồn đã ràng."
+      },
+      "resume": {
+        "en": "Supply the missing curriculum or source evidence.",
+        "vi": "Bổ sung chương trình học hoặc bằng chứng nguồn còn thiếu."
+      }
+    },
+    "OUTCOME_UNCOVERED": {
+      "domain": "content",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A declared language edition leaves a published learning outcome uncovered.",
+        "vi": "Một bản viết đã khai bỏ trống một kết quả học tập đã công bố."
+      },
+      "resume": {
+        "en": "Rewrite the edition, or narrow the brief.",
+        "vi": "Viết lại bản đó, hoặc thu hẹp brief."
+      }
+    },
+    "IMAGE_UNAVAILABLE": {
+      "domain": "engineering",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A required image cannot be generated to the brief's claims.",
+        "vi": "Không sinh được hình ảnh bắt buộc theo các tuyên bố của brief."
+      },
+      "resume": {
+        "en": "Provide a working generator, or turn the image stage off.",
+        "vi": "Cấp một bộ sinh chạy được, hoặc tắt giai đoạn hình ảnh."
+      }
+    },
+    "CODE_BUILD_FAILED": {
+      "domain": "content",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A declared implementation track does not build.",
+        "vi": "Một track cài đặt đã khai không build được."
+      },
+      "resume": {
+        "en": "Repair the track, then build it again.",
+        "vi": "Sửa track đó, rồi build lại."
+      }
+    },
+    "E2E_FAILED": {
+      "domain": "content",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "A declared executable check still fails when maxE2eIterations is spent.",
+        "vi": "Một phép kiểm chạy được đã khai vẫn hỏng khi đã tiêu hết maxE2eIterations."
+      },
+      "resume": {
+        "en": "Repair the implementation, or approve more iterations.",
+        "vi": "Sửa phần cài đặt, hoặc duyệt thêm số vòng."
+      }
+    },
+    "CONTRACT_WEAKENED": {
+      "domain": "content",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "The executable contract moved during the repair loop, so the proof measures nothing.",
+        "vi": "Contract chạy được bị dời trong vòng lặp sửa, nên bằng chứng không đo được gì."
+      },
+      "resume": {
+        "en": "Restore the contract and rerun without touching it.",
+        "vi": "Khôi phục contract và chạy lại mà không đụng vào nó."
+      }
+    },
+    "REVIEW_REVISION_REQUIRED": {
+      "domain": "content",
+      "disposition": "fallback",
+      "meaning": {
+        "en": "The independent review returned a revision.",
+        "vi": "Phản biện độc lập trả về yêu cầu sửa."
+      },
+      "fallback": {
+        "en": "Repair exactly the artifacts the review's findings name, by owning stage, record the round under ## Fallbacks taken, and reopen the review exchange for the next round.",
+        "vi": "Sửa đúng những artifact mà các finding của phản biện nêu tên, theo giai đoạn chủ, ghi vòng đó dưới ## Fallbacks taken, rồi mở lại cuộc trao đổi phản biện cho vòng kế."
+      },
+      "resume": {
+        "en": "Nothing is asked of anyone; the branch revises and reviews again until maxReviewRounds is spent.",
+        "vi": "Không hỏi ai cả; nhánh tự sửa và phản biện lại cho tới khi hết maxReviewRounds."
+      }
+    },
+    "REVIEW_ROUNDS_EXHAUSTED": {
+      "domain": "caller",
+      "disposition": "terminate",
+      "meaning": {
+        "en": "maxReviewRounds is spent and the review still returns a revision.",
+        "vi": "Đã tiêu hết maxReviewRounds mà phản biện vẫn trả về yêu cầu sửa."
+      },
+      "resume": {
+        "en": "Approve more rounds, or narrow the unit.",
+        "vi": "Duyệt thêm vòng, hoặc thu hẹp đơn vị."
+      }
+    }
+  }
+}

package/operators/content-generate/operator.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 9,
+  "id": "content.generate",
+  "domain": "content",
+  "job": "Generate or refactor one educational content unit in one linear pass: a teacher brief that constrains everything after it, one written edition per declared language, images made to a stated claim, code and executable checks that actually run, and an independent critique that receives the artifact without the producer's rationale.",
+  "package": "operator.md",
+  "errors": "errors.json",
+  "validator": "validate.mjs",
+  "selfTest": "self-test.mjs",
+  "resources": {
+    "profile": "luna",
+    "grammarBound": false,
+    "tools": {
+      "@tools/fileread": "context-aliases",
+      "@tools/shell": "declared-commands",
+      "@tools/websearch": "bounded",
+      "@tools/imagegen": "required",
+      "@tools/objectstorage": "read"
+    }
+  }
+}

package/operators/content-generate/operator.md

@@ -0,0 +1,155 @@
+# content.generate
+
+## Job
+
+Generate or refactor one educational content unit in one linear pass: a teacher brief that constrains
+everything after it, one written edition per declared language, images made to a stated claim, code
+and executable checks that actually run, and an independent review that receives the artifacts
+without the producer's rationale.
+
+## The brief comes first and constrains what follows
+
+The teacher brief is written before anything else, from curriculum and source evidence, in one fresh
+execution that inherits no turns. It publishes the learner inputs, the observable outcomes, the claims
+a visual may encode, the examples, and the explicit add, change, and remove dispositions, and it is
+then fingerprinted so nothing downstream may extend it. Everything after it is measured against it: an
+edition may only claim coverage of an outcome the brief published, an image may only encode a claim
+the brief published, and every declared edition must cover the whole published outcome set before the
+unit can ship. An edition that covers part of the brief is a partial lesson in one language and a
+complete one in another, which is exactly the silent defect this check exists to catch. A change or
+remove disposition names what it acts on, because a disposition with no target is a wish.
+
+## Generated code must actually run
+
+Every implementation track is built with the exact command `commands` names for it, and the exit code
+is read and recorded in `response/data/e2e.json`. A non-zero exit code cannot ship, because the lesson
+would tell a learner that code works on nobody's evidence. Step 7 runs the declared command per track
+inside a bounded run, read and repair loop whose ceiling is `maxE2eIterations`; the loop lives inside
+the step, so `E2E_FAILED` is raised once, when the iterations are spent, rather than on the first red
+run. The loop may repair the implementation or the harness. It may never move the contract it is
+measured by, so the contract fingerprint is taken before the first run and compared after the last
+one: a test deleted, skipped, loosened, or special cased to make the run green is the failure that
+comparison exists to catch, and it is `CONTRACT_WEAKENED`. A track carries its build command and its
+exit code, a run carries its command, its exit code, and its named assertions, and neither carries a
+sentence claiming success.
+
+## The image is made to a stated intent
+
+The visual is derived from the brief's claims, the prompt that states that intent is persisted beside
+the result, and the result is inspected for legibility, hierarchy, and claim fidelity. Step 5 runs
+only when `stageModes` turns the image on; with the image off the step produces nothing at all, no
+image and no prompt, and the receipt records `STAGE_DISABLED`, because a decision that leaves no
+record reads later as an omission. A claim the brief never published cannot appear, and a visual that
+fails its own claim-fidelity inspection cannot ship. An image is not decoration added at the end; it
+is one of the claims, drawn.
+
+## The review is a nested exchange, and revision is a fallback with a ceiling
+
+After the executable check, the branch pauses: it emits `response/response.json` with status `waiting`
+and `awaiting { exchange: review, kind: content-review }`. The orchestrator writes
+`review/request/request.json` with the produced artifacts and the claims they make as inputs, never
+the producer's rationale, and runs a fresh agent on this operator's own profile with no inherited
+turns; that agent is never the execution that wrote the brief or an edition, and it writes only
+`review/response/`. It scores correctness, pedagogy, interview value and language, and, where those
+stages ran, visual fidelity, code quality and executable proof. Approval requires every applicable
+score at or above 85 and no open error finding. A returned revision is not a stop: it is the fallback
+`REVIEW_REVISION_REQUIRED`, and the branch repairs exactly the artifacts the review's findings name,
+by owning stage, then reopens the exchange for the next round. The ceiling is `maxReviewRounds`; when
+those rounds are spent and the review still returns a revision, `REVIEW_ROUNDS_EXHAUSTED` terminates,
+because a unit that has been rewritten to a reviewer's satisfaction after unbounded rounds was
+rewritten by the reviewer. A unit that passes its own author's review has not been reviewed, which is
+why shared executions, inherited turns, and producer rationale are three separate refusals.
+
+## Boundary
+
+Context is read-only. The operator writes only `response/` of its own branch: the brief, the receipt,
+the machine record of the build and the executable check, and the editions, image, prompt and tracks
+under `response/artifacts/`; the review agent writes only `review/response/`. It runs only the
+declared build and executable-check commands. It never writes an article before the brief is frozen or
+beyond what the brief published, claims a learning outcome, example, or visual claim the brief does not
+publish, reports a build or executable check that was not run or whose exit code was not read, changes
+the executable contract during a repair loop, lets the producer of an artifact perform, steer, or
+brief its own review, or approves a unit while any applicable score sits below the published minimum.
+It does not edit the curriculum, publish the unit to the served object, or claim any readiness beyond
+the checks it actually ran.
+
+## Context
+
+| Alias | Bind | Required |
+| --- | --- | --- |
+| `@remote/minio/<contentId>/<locale>` | the lesson as served, by the fingerprint of the fetched object; the unit being authored or revised | yes |
+| `@worktrees/sessions/central-runtime` | the AI runtime that runs, reads, and repairs generated code, by generation | yes |
+
+## Inputs
+
+| Kind | From | Required |
+| --- | --- | --- |
+| `content-generation-receipt` | a prior run of `content.generate` on the same unit; regression history, absent on the first pass | no |
+
+## Requirements
+
+| Field | Type | Default | Ask |
+| --- | --- | --- | --- |
+| `unit` | id | — | The content unit being authored or revised |
+| `naturalLanguages` | list | vi | The languages the unit is written in; every one of them covers the whole outcome set |
+| `implementationLanguages` | list | empty | The languages the implementation tracks are written in; empty means no code and no executable check |
+| `stageModes` | list of `{image}` | image off | Which optional stages run; `image on` turns step 5 on |
+| `commands` | list of `{language, buildCommand, checkCommand}` | the commands the unit declares | The exact command each track is built and checked with |
+| `maxE2eIterations` | number 1–20 | 2 | How many run, read and repair iterations step 7 may spend before `E2E_FAILED` |
+| `maxReviewRounds` | number 1–20 | 2 | How many review rounds the revision fallback may spend before `REVIEW_ROUNDS_EXHAUSTED` |
+| `resume` | token | null | The blocked branch's token when re-entering after a stop |
+
+## Steps
+
+| # | Step | Params | Reads | Writes | Stops with |
+| --- | --- | --- | --- | --- | --- |
+| 1 | Validate the gate and resume | `resume` | `request/request.json`, input `content-generation-receipt` when present, @remote/minio/<contentId>/<locale> at the frozen unit binding | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Bind the served unit and the runtime | `unit` | @remote/minio/<contentId>/<locale> for curriculum and style as served, @worktrees/sessions/central-runtime for the runtime configuration, @tools/objectstorage | — | — |
+| 3 | Write and freeze the brief | `naturalLanguages`, `implementationLanguages` | @remote/minio/<contentId>/<locale> for curriculum and source evidence, @tools/websearch | `response/brief.md` | `BRIEF_UNBOUND` |
+| 4 | Write every declared edition | `naturalLanguages` | `response/brief.md` as the frozen brief | `response/artifacts/article.<language>.md` | `OUTCOME_UNCOVERED` |
+| 5 | Generate the image to its claims, only when `stageModes` turns it on | `stageModes` | `response/brief.md` for the claims and the stated image intent | `response/artifacts/image.<name>`, `response/artifacts/prompt.<name>.txt`, @tools/imagegen | `IMAGE_UNAVAILABLE` |
+| 6 | Implement every declared track | `implementationLanguages`, `commands` | `response/brief.md`, @worktrees/sessions/central-runtime where each build command runs | `response/artifacts/track.<language>.<extension>`, @tools/shell | `CODE_BUILD_FAILED` |
+| 7 | Run the executable check, at most `maxE2eIterations` iterations | `maxE2eIterations` | @worktrees/sessions/central-runtime where each declared command runs | `response/data/e2e.json`, @tools/shell | `E2E_FAILED`, `CONTRACT_WEAKENED` |
+| 8 | Await the review: pause, a fresh agent reads the artifacts without the producer's rationale, revise and reopen while rounds remain | `maxReviewRounds` | `review/response/review.md` once the exchange is done | `response/response.json` (waiting, awaiting review) | `REVIEW_REVISION_REQUIRED`, `REVIEW_ROUNDS_EXHAUSTED` |
+| 9 | Write the receipt and emit | — | everything above | `response/response.md`, `response/response.json` | — |
+
+Under the defaults the unit is one Vietnamese edition with no image, no track and no executable check,
+and its quality rests entirely on step 8. A resume begins again at step 1, reuses only unchanged
+fingerprinted observations, and consumes the exact delta; a revised brief arrives as a new
+fingerprint, because the same fingerprint cannot yield a different answer. The receipt claims no
+publication, no learner outcome in production, and no acceptance beyond the checks actually run.
+
+## Outputs
+
+| Kind | File | Type | Required |
+| --- | --- | --- | --- |
+| `content-generation-receipt` | `response/response.md` | md | yes |
+| `content-brief` | `response/brief.md` | md | yes |
+| `e2e` | `response/data/e2e.json` | data | no |
+| `content-review` | `review/response/review.md` | md | yes |
+| `article` | `response/artifacts/article.<language>.md` | artifact | yes |
+| `image` | `response/artifacts/image.<name>` | artifact | no |
+| `image-prompt` | `response/artifacts/prompt.<name>.txt` | artifact | no |
+| `track` | `response/artifacts/track.<language>.<extension>` | artifact | no |
+
+## Stops
+
+| Code | Disposition |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `NO_PROGRESS` | terminate |
+| `BRIEF_UNBOUND` | terminate |
+| `OUTCOME_UNCOVERED` | terminate |
+| `IMAGE_UNAVAILABLE` | terminate |
+| `CODE_BUILD_FAILED` | terminate |
+| `E2E_FAILED` | terminate |
+| `CONTRACT_WEAKENED` | terminate |
+| `REVIEW_REVISION_REQUIRED` | fallback |
+| `REVIEW_ROUNDS_EXHAUSTED` | terminate |
+
+## Next
+
+| When | Operator |
+| --- | --- |
+| the routed content object or the shared runtime does not answer at the frozen binding | `workspace.bind` |