@thebackstoryis/engineering-with-ai 0.2.9 → 0.3.0-beta.2

package/skills-src/ewai-autonomy/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: ewai-autonomy
+description: Operate governed, bounded autonomous delivery for an exact pool of existing EWAI intents. Use for autonomy status, previews, named grants, local runs and services, human questions, recovery or revocation; keep phase delivery and approvals separate.
+---
+
+# EWAI autonomy
+
+Autonomy is **off by default** in a consumer project. Resolve the project and configured SPECS root from `.ewai-pipeline/project.json`; the npm engine repository is not the consumer's authority source. Read the project's current intents, dependencies, standards, delivery state, policy and `ewai autonomy status --project . --json` before proposing work. Do not choose new intent IDs on the owner's behalf or infer a grant from a request to continue.
+
+Use the dashboard's Autonomy view or `ewai autonomy preview` to explain an **exact intent pool**, permitted actions and providers, expiry, runtime, per-operation time, attempt limit, executable candidates, human decisions and blockers. A preview is **not permission**. Recording it only makes that displayed revision approvable. A named owner must explicitly approve its current digest using the guarded dashboard or `ewai autonomy approve --expected-digest DIGEST --approved-by NAME --yes`. A changed pool, provider, limit or evidence requires a new preview and decision. Never issue a live grant merely because the host AI recommends one.
+
+`ewai autonomy run` makes one bounded pass; `ewai autonomy service` starts a local continuing supervisor. Both require the exact approved grant digest and selected provider. Verify provider availability/version and the project's external-review policy; the orchestrator cannot independently review itself. Treat unknown execution, a stale digest, lost ownership, expired scope or an unavailable provider as a stop, not a retry invitation. Usage is provider-reported, not a hard money cap. Set bounded limits and direct the owner to provider-side spend controls.
+
+Monitor status and questions. A worker stages source-bound drafts and host-produced checks, never gate authority. Use `$ewai-deliver` for the complete fourteen-stage phase workflow, canonical gate ledger, standards sweep, validation cycles and leased Build tasks. Existing human Build approval and Manual QA approval remain separate explicit decisions. Do not turn a run question, private answer, worker draft or passing test into either approval. Answer through the dashboard or a private project-relative input file, not chat text containing credentials or private evidence.
+
+Pause, cancel, revoke and recover through guarded revision-bound controls. A cancel request does not confirm termination; inspect `executionStopped`, owner/process state and durable operation receipts. Recover only after inspecting whether the canonical effect already happened; never blindly replay it. Revocation removes future delegation, not historical evidence or an in-flight termination guarantee. Report blocked states honestly. Do not update premium personas, publish, release, deploy or accept on the owner's behalf.
+
+The dashboard and CLI share the same project-local control plane. The npm package also includes `Docs/autonomous-intent-delivery.md` for a longer user guide; do not assume a relative path from this copied skill to that guide. The instructions above remain usable when only the skill subtree is installed.

package/skills-src/ewai-autonomy/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EWAI Autonomy"
+  short_description: "Govern exact-pool autonomous intent delivery"
+  default_prompt: "Use $ewai-autonomy to review this project's autonomous delivery status and bounded next action."

package/skills-src/ewai-deliver/SKILL.md

@@ -7,6 +7,8 @@ description: Deliver or resume an EWAI intent through the complete fourteen-stag
 
 This skill is the only supported route from an EWAI intent into planning, Build, delivery, and learning. A host AI's generic planning mode is not an EWAI Plan and cannot replace a pipeline phase.
 
+When an owner asks for bounded delegation across an exact pool of existing intents, use `$ewai-autonomy` for the off-by-default preview, named grant, run controls and human questions. Keep `$ewai-deliver` as the phase-work route. An autonomy grant cannot replace existing human Build approval, the canonical gate ledger, standards sweep, or separate Manual QA approval.
+
 Resolve the workspace and SPECS root from `.ewai-pipeline/project.json`; all logical `SPECS/...` paths in this contract are relative to that configured root. Never assume the workspace itself or the repository being changed owns SPECS.
 
 ## Delivery contract

package/skills-src/ewai-test-scenarios/references/scenario-contract.md

@@ -83,6 +83,12 @@ Status means:
 
 JSON is authoritative. Never parse or manually edit Markdown to repair scenario state.
 
+New briefs and records carry `sourceDigestVersion: intent-content-v2`. Intent fingerprints cover the complete body and all parsed metadata except the five workflow fields `status`, `delivery_status`, `current_phase`, `delivery_state_path` and `updated_at`. Do not treat excerpts as the fingerprint boundary. Other evidence retains whole-file fingerprints, so genuine source changes still require review. Unsupported digest versions fail closed.
+
+Require at least one recognised intent source (captured Problem, Desired outcome or Constraints, or a listed Journey or Acceptance criterion), even when planning documents exist. Without it, preparation and recording fail closed and historical packs cannot claim current intent coverage. Content fingerprints accept only plain mappings, arrays and JSON scalar metadata; reject typed YAML dates, sets, ordered maps, binary values, non-finite numbers and cyclic aliases instead of silently erasing their meaning. Ordinary quoted date strings and repeated non-cyclic aliases remain supported. Do not convert unsupported sources or rewrite accepted evidence without the appropriate owner review.
+
+Legacy unversioned pairs remain readable with their original whole-file checks. An exact replay through `record`, while those sources are still current, may add the immutable `test-scenarios.source-baseline.json` compatibility receipt. It is bound to the original record digest and reviewed sources; both accepted evidence files remain byte-identical. Preparation and status remain read-only. Never bypass an already-stale legacy record, replace its pair, or edit the receipt manually. Keep the receipt alongside its pair; malformed, unsafe or mismatched receipt evidence is invalid. This is a fingerprint compatibility operation, not a revised-scenario approval or a way to accept changed requirements.
+
 ## Human evidence boundary
 
 Manual QA remains an explicit named human gate. Specialist assurance requires an accountable practitioner. Representative-user validation requires real representative participants. Persona simulation may improve the question set but may not complete any of those routes.

package/src/autonomy-phase-contracts.mjs

@@ -0,0 +1,88 @@
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+
+// This registry describes draft content, not gate evidence. A worker never
+// chooses a checker, command, canonical approval path or destination root.
+const definitions = {
+  intent: { paths: ['intent-summary.md'], checks: ['intent-dependency-map-check'],
+    humanQuestions: ['intent-evidence-review'] },
+  reconcile: { paths: ['reconcile.md'], checks: ['intent-dependency-map-check'],
+    humanQuestions: ['repository-truth-review', 'reconcile-disagreements'] },
+  plan: { paths: ['build-plan.md', 'destination.md', 'gates/plan/discovery-notes.md'],
+    checks: ['intent-dependency-map-check', 'task-graph-check'], humanQuestions: ['plan-contract-review'] },
+  'pattern-validation': { paths: ['pattern-validation.md'],
+    checks: ['intent-dependency-map-check', 'task-graph-check'], humanQuestions: ['repository-pattern-review'] },
+  'test-plan': { paths: ['test-plan.md', 'gates/test-plan/task-to-test-traceability.md', 'gates/test-plan/red-green-refactor-traceability.md'],
+    checks: ['task-graph-check'], humanQuestions: ['test-oracle-review'] },
+};
+const maxBytes = 128 * 1024;
+const maxArtifactBytes = 32 * 1024;
+const digestPattern = /^sha256:[a-f0-9]{64}$/;
+const ownKeys = (value, keys) => value && typeof value === 'object' && !Array.isArray(value)
+  && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+const safeFailure = code => ({ schema: 'ewai.autonomy-proposal-validation/v1', status: 'rejected', code, requiresHuman: true });
+const immutable = value => {
+  if (value && typeof value === 'object') { Object.values(value).forEach(immutable); Object.freeze(value); }
+  return value;
+};
+export const autonomyWorkerSchema = immutable(JSON.parse(readFileSync(new URL('../config/autonomy-worker.schema.json', import.meta.url), 'utf8')));
+
+export function getAutonomyPhaseContract(phase) {
+  if (typeof phase !== 'string' || !Object.hasOwn(definitions, phase)) {
+    return { status: 'unavailable', code: 'phase-contract-unavailable', requiresHuman: true };
+  }
+  return { schema: 'ewai.autonomy-phase-definition/v1', status: 'available', phase,
+    ...structuredClone(definitions[phase]), maxBytes, maxArtifactBytes, maxArtifacts: 8,
+    authority: 'draft-only' };
+}
+
+// Validate the wire bytes, not a provider-declared status or success summary.
+// Parsing errors deliberately do not quote input. Validated content remains
+// private to the host; the returned safe result contains references only.
+export function validatePhaseProposal(contract, result) {
+  const definition = getAutonomyPhaseContract(contract?.phase);
+  if (definition.status !== 'available' || !digestPattern.test(contract?.digest ?? '')
+    || !Array.isArray(contract?.sources) || !contract.sources.length
+    || contract.sources.some(source => !/^[a-z][a-z0-9_.-]{0,79}$/.test(source?.id ?? '')
+      || !digestPattern.test(source?.digest ?? ''))
+    || new Set(contract.sources.map(source => source.id)).size !== contract.sources.length) return safeFailure('proposal-contract-invalid');
+  if (!result || result.status !== 'complete' || result.exitCode !== 0 || result.executionStopped !== true) {
+    return safeFailure(['truncated', 'timed-out', 'unavailable', 'cancelled', 'failed'].includes(result?.status)
+      ? `proposal-${result.status}` : 'proposal-incomplete');
+  }
+  if (typeof result.output !== 'string') return safeFailure('proposal-malformed');
+  if (Buffer.byteLength(result.output, 'utf8') > maxBytes) return safeFailure('proposal-too-large');
+  let proposal;
+  try { proposal = JSON.parse(result.output); } catch { return safeFailure('proposal-malformed'); }
+  if (!ownKeys(proposal, ['schema', 'contractDigest', 'phase', 'artifacts'])
+    || proposal.schema !== 'ewai.autonomy-phase-proposal/v1'
+    || proposal.contractDigest !== contract.digest || proposal.phase !== contract.phase
+    || !Array.isArray(proposal.artifacts) || proposal.artifacts.length < 1 || proposal.artifacts.length > 8) return safeFailure('proposal-schema-invalid');
+  const sources = new Set(contract.sources.map(source => source.id)), seen = new Set(), artifacts = [];
+  for (const artifact of proposal.artifacts) {
+    if (!ownKeys(artifact, ['path', 'content', 'sourceRefs'])) return safeFailure('proposal-schema-invalid');
+    if (!definition.paths.includes(artifact.path) || seen.has(artifact.path)) return safeFailure('proposal-destination-invalid');
+    seen.add(artifact.path);
+    if (typeof artifact.content !== 'string' || !artifact.content.trim()
+      || Buffer.byteLength(artifact.content, 'utf8') > maxArtifactBytes
+      || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(artifact.content)) return safeFailure('proposal-content-invalid');
+    if (!Array.isArray(artifact.sourceRefs) || artifact.sourceRefs.length < 1 || artifact.sourceRefs.length > 32
+      || new Set(artifact.sourceRefs).size !== artifact.sourceRefs.length
+      || artifact.sourceRefs.some(ref => typeof ref !== 'string' || !sources.has(ref))) return safeFailure('proposal-source-invalid');
+    // This is defence in depth for obvious forged verdicts, not a semantic
+    // truth detector. Nothing in a draft is ever consumed as gate authority.
+    if (artifact.content.split('\n').some(line => {
+      const words = line.trim().toLowerCase().split(/[\s:=|*#-]+/).filter(Boolean);
+      if (words[0] === 'manual' && words[1] === 'qa') words.splice(0, 2, 'manual-qa');
+      if (!['gate', 'checker', 'verdict', 'approval', 'manual-qa'].includes(words[0])) return false;
+      return ['pass', 'passed', 'approved', 'complete', 'completed'].includes(words.slice(1).find(word => !['is', 'status'].includes(word)));
+    })
+      || /\b(?:approve-build|approve-manual-qa|record-phase-gate|recordPhaseGate|recordBuildApproval)\b/.test(artifact.content)) return safeFailure('proposal-authority-forbidden');
+    if (/```\s*(?:bash|sh|zsh|shell|powershell|cmd)\b|\$\(/.test(artifact.content)) return safeFailure('proposal-command-forbidden');
+    artifacts.push({ path: artifact.path, bytes: Buffer.byteLength(artifact.content, 'utf8'),
+      digest: `sha256:${createHash('sha256').update(artifact.content).digest('hex')}`, sourceRefs: [...artifact.sourceRefs] });
+  }
+  return { schema: 'ewai.autonomy-proposal-validation/v1', status: 'valid-draft', code: 'proposal-valid-draft',
+    phase: contract.phase, contractDigest: contract.digest, artifacts,
+    requiresHuman: true, authority: 'none', humanQuestions: definition.humanQuestions };
+}

package/src/autonomy-worker.mjs

@@ -0,0 +1,15 @@
+import { executeAutonomyRun, controlAutonomyRun, readAutonomyRun } from './runtime/autonomy-supervisor.mjs';
+
+// Only explicit service creation starts this entry point, via an IPC handshake.
+const args = process.argv.slice(2);
+if (args.length !== 4 || args[0] !== '--project' || args[2] !== '--run' || !process.send) throw new Error('Explicit local service launch required.');
+const root = args[1], id = args[3];
+const stop = () => {
+  try { const run = readAutonomyRun(root, id); controlAutonomyRun(root, { runId: id, action: 'cancel', expectedRevision: run.revision }); } catch {}
+};
+process.on('SIGTERM', stop); process.on('SIGINT', stop);
+process.once('message', async message => {
+  if (message?.start !== true || Object.keys(message).length !== 1) { process.exitCode = 1; return; }
+  try { await executeAutonomyRun(root, id); } catch { process.exitCode = 1; }
+  finally { process.removeListener('SIGTERM', stop); process.removeListener('SIGINT', stop); }
+});

package/src/autonomy.mjs

@@ -0,0 +1,199 @@
+import { resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { getAutonomyPhaseContract } from './autonomy-phase-contracts.mjs';
+import { autonomyError, autonomyGuard, autonomyDigest, autonomyPaths, autonomyFiles, readAutonomyFile,
+  writeAutonomyRecord, withAutonomyLock, readAutonomySnapshot } from './runtime/autonomy-workspace.mjs';
+
+export const AUTONOMY_ACTIONS = Object.freeze(['begin-harness', 'prepare-phase', 'afk-build']);
+export const AUTONOMY_PROVIDERS = Object.freeze(['codex', 'claude', 'antigravity']);
+export const AUTONOMY_HUMAN_EXCLUSIONS = Object.freeze(['approve-build', 'select-prototype', 'manual-qa', 'accept-risk', 'policy-exception', 'destructive-action', 'deploy', 'release']);
+const intentPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*\/[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const digestPattern = /^sha256:[a-f0-9]{64}$/;
+function keys(value, allowed) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype
+    || Object.keys(value).some(key => !allowed.includes(key))) autonomyError('autonomy-invalid-input', 400);
+}
+function boundedList(value, valid, maximum = 100) {
+  if (!Array.isArray(value) || !value.length || value.length > maximum || new Set(value).size !== value.length
+    || value.some(item => typeof item !== 'string' || item.length > 160 || !valid(item))) autonomyError('autonomy-invalid-scope', 400);
+  return [...value].sort();
+}
+export function validateAutonomyScope(input) {
+  keys(input, ['intentIds', 'actions', 'providers', 'expiresAt', 'limits']);
+  keys(input.limits, ['maxConcurrentIntents', 'maxRuntimeMs', 'maxOperationMs', 'maxAttempts']);
+  const limits = input.limits;
+  if (limits.maxConcurrentIntents !== 1 || !Number.isSafeInteger(limits.maxRuntimeMs) || limits.maxRuntimeMs < 1 || limits.maxRuntimeMs > 86400000
+    || !Number.isSafeInteger(limits.maxOperationMs) || limits.maxOperationMs < 1 || limits.maxOperationMs > limits.maxRuntimeMs
+    || !Number.isSafeInteger(limits.maxAttempts) || limits.maxAttempts < 1 || limits.maxAttempts > 100) autonomyError('autonomy-invalid-limits', 400);
+  if (typeof input.expiresAt !== 'string' || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(input.expiresAt)
+    || !Number.isFinite(Date.parse(input.expiresAt)) || new Date(input.expiresAt).toISOString() !== input.expiresAt) autonomyError('autonomy-invalid-expiry', 400);
+  return { intentIds: boundedList(input.intentIds, id => intentPattern.test(id)),
+    actions: boundedList(input.actions, action => AUTONOMY_ACTIONS.includes(action), AUTONOMY_ACTIONS.length),
+    providers: boundedList(input.providers, provider => AUTONOMY_PROVIDERS.includes(provider), AUTONOMY_PROVIDERS.length),
+    expiresAt: input.expiresAt, limits: { ...limits } };
+}
+function readPolicy(root) {
+  const paths = autonomyPaths(root);
+  const files = autonomyFiles(paths.projectRoot, resolve(paths.authorityRoot, 'grants'));
+  const records = files.filter(path => path.includes('/revisions/')).map(path => {
+    const record = JSON.parse(readAutonomyFile(paths.projectRoot, path));
+    keys(record, ['schema', 'id', 'revision', 'previousDigest', 'digest', 'proposalDigest', 'approvedBy', 'approvedAt', 'scope', 'humanExclusions', 'configDigest', 'projectIdentity']);
+    const { digest, ...body } = record;
+    validateAutonomyScope(record.scope);
+    if (record.schema !== 'ewai.autonomy-grant/v1' || !Number.isSafeInteger(record.revision) || record.revision < 1
+      || !/^[a-f0-9-]{36}$/.test(record.id) || !digestPattern.test(record.proposalDigest) || !digestPattern.test(record.configDigest)
+      || digest !== autonomyDigest(body) || !path.endsWith(`/grants/${record.id}/revisions/${record.revision}-${digest.slice(7)}.json`)
+      || record.projectIdentity !== autonomyDigest(paths.projectRoot) || !validApprover(record.approvedBy)
+      || !Number.isFinite(Date.parse(record.approvedAt)) || JSON.stringify(record.humanExclusions) !== JSON.stringify(AUTONOMY_HUMAN_EXCLUSIONS)) autonomyError('autonomy-grant-invalid', 422);
+    return record;
+  }).sort((a, b) => a.revision - b.revision);
+  records.forEach((record, index) => {
+    if (record.revision !== index + 1 || record.previousDigest !== (records[index - 1]?.digest ?? null)
+      || index > 0 && record.id !== records[0].id) autonomyError('autonomy-grant-history-invalid', 422);
+  });
+  const grant = records.at(-1) ?? null;
+  const revokedRevisions = new Set();
+  const revocations = files.filter(path => path.includes('/revocations/')).map(path => {
+    const record = JSON.parse(readAutonomyFile(paths.projectRoot, path));
+    keys(record, ['schema', 'id', 'grantRevision', 'grantDigest', 'revokedBy', 'revokedAt', 'projectIdentity', 'digest']);
+    const { digest, ...body } = record;
+    const source = records.find(candidate => candidate.revision === record.grantRevision);
+    if (record.schema !== 'ewai.autonomy-revocation/v1' || !source || record.id !== source.id
+      || record.grantDigest !== source.digest || record.projectIdentity !== source.projectIdentity
+      || !validApprover(record.revokedBy) || !Number.isFinite(Date.parse(record.revokedAt))
+      || Date.parse(record.revokedAt) < Date.parse(source.approvedAt)
+      || digest !== autonomyDigest(body) || revokedRevisions.has(record.grantRevision)
+      || !path.endsWith(`/grants/${record.id}/revocations/${record.grantRevision}-${digest.slice(7)}.json`)) autonomyError('autonomy-revocation-invalid', 422);
+    revokedRevisions.add(record.grantRevision); return record;
+  });
+  const revocation = revocations.find(record => record.grantDigest === grant?.digest) ?? null;
+  const status = !grant ? 'absent' : revocation ? 'revoked' : Date.parse(grant.scope.expiresAt) <= Date.now() ? 'expired' : 'current';
+  return { schema: 'ewai.autonomy-policy/v1', mode: status === 'current' ? 'delegated' : 'off', status, grant,
+    revocation, digest: revocation ? autonomyDigest({ grant: grant.digest, revocation: revocation.digest })
+      : grant?.digest ?? autonomyDigest({ mode: 'off', project: paths.projectRoot }),
+    humanExclusions: [...AUTONOMY_HUMAN_EXCLUSIONS], serviceStarted: false };
+}
+export function readAutonomyPolicy(root) { return autonomyGuard(() => readPolicy(root)); }
+
+function classify(item, scope, policy, snapshot, isProposal) {
+  const reasons = [], add = code => reasons.push({ code });
+  const state = item.execution, actions = state.actions;
+  let phase = state.lifecycle.nextPhase, action = null, human = false;
+  if (!scope?.intentIds.includes(item.intentId)) add('outside-approved-pool');
+  if (!item.accepted) add('intent-not-accepted');
+  if (!state.valid) state.blockers.forEach(blocker => add(/^[a-z0-9-]{1,100}$/.test(blocker.code) ? blocker.code : 'canonical-evidence-invalid'));
+  if (!scope) add('autonomy-off');
+  else if (Date.parse(scope.expiresAt) <= Date.now()) add('grant-expired');
+  if (!isProposal && policy.status === 'revoked') add('grant-revoked');
+  if (!isProposal && policy.grant && policy.grant.configDigest !== snapshot.configDigest) add('grant-policy-changed');
+  if (phase === 'manual-qa') { add('manual-qa-required'); human = true; }
+  else if (phase === 'ui-design') { add('prototype-selection-required'); human = true; }
+  else if (actions.approveBuild.permitted) { add('build-approval-required'); human = true; }
+  else if (actions.beginHarness.permitted && state.valid) { action = 'begin-harness'; phase = 'intent'; }
+  else if (phase === 'build') {
+    action = 'afk-build';
+    for (const blocker of actions.enterBuild.blockers ?? []) if (/^intent-dependency-/.test(blocker.code)) add(blocker.code);
+    if (!actions.acquireTask.permitted) add('afk-preflight-required');
+    if (!actions.enterBuild.permitted) add('build-approval-required');
+  } else if (actions.continueHarness.permitted && ['intent', 'reconcile', 'plan', 'pattern-validation', 'test-plan'].includes(phase)) {
+    action = 'prepare-phase';
+    if (getAutonomyPhaseContract(phase).status !== 'available') add('restricted-phase-contract-unavailable');
+  } else add('autonomy-phase-unavailable');
+  if (action && !scope?.actions.includes(action)) add('action-not-approved');
+  if (item.repositoryBusy) add('repository-ownership-conflict');
+  return { intentId: item.intentId, phase, action, sortKey: [item.priority, item.intentId],
+    reasons: [...new Map(reasons.map(reason => [reason.code, reason])).values()],
+    bucket: human ? 'humanDecisions' : reasons.length ? 'blocked' : 'executable' };
+}
+function latestProposalPreview(root) {
+  const paths = autonomyPaths(root);
+  const records = autonomyFiles(paths.projectRoot, resolve(paths.controlRoot, 'previews'))
+    .filter(path => /\/\d+-[a-f0-9]{64}\.json$/.test(path))
+    .map(path => {
+      const value = JSON.parse(readAutonomyFile(paths.projectRoot, path));
+      if (!Number.isSafeInteger(value.previewRevision) || value.previewRevision < 1 || !digestPattern.test(value.digest)
+        || !path.endsWith(`/${value.previewRevision}-${value.digest.slice(7)}.json`)) autonomyError('autonomy-preview-invalid');
+      return value;
+    }).sort((a, b) => a.previewRevision - b.previewRevision);
+  if (records.some((record, index) => record.previewRevision !== index + 1)) autonomyError('autonomy-preview-history-invalid');
+  return records.at(-1) ?? null;
+}
+function createPreview(root, input, recordedRevision = null) {
+  keys(input, ['proposal', 'record']);
+  if (input.record !== undefined && typeof input.record !== 'boolean') autonomyError('autonomy-invalid-input', 400);
+  const snapshot = readAutonomySnapshot(root), policy = readPolicy(root);
+  const proposal = input.proposal === undefined ? null : validateAutonomyScope(input.proposal);
+  if (proposal && Date.parse(proposal.expiresAt) <= Date.now()) autonomyError('autonomy-expired-proposal', 400);
+  if (proposal && proposal.intentIds.some(id => !snapshot.items.some(item => item.intentId === id))) autonomyError('autonomy-intent-unknown', 400);
+  const scope = proposal ?? policy.grant?.scope ?? null;
+  const basis = { schema: 'ewai.autonomy-preview/v1', evidenceRevision: snapshot.revision, policyDigest: policy.digest,
+    configDigest: snapshot.configDigest, projectIdentity: snapshot.projectIdentity, proposal,
+    previewRevision: proposal ? recordedRevision ?? (latestProposalPreview(root)?.previewRevision ?? 0) + 1 : null };
+  const result = { ...basis, digest: autonomyDigest(basis), authority: 'none', mode: 'shadow',
+    executable: [], humanDecisions: [], blocked: [], humanExclusions: [...AUTONOMY_HUMAN_EXCLUSIONS],
+    ordering: 'Ascending explicit numeric priority; missing or non-numeric priority is neutral zero; then intent ID.' };
+  for (const item of snapshot.items) {
+    const { bucket, ...candidate } = classify(item, scope, policy, snapshot, Boolean(proposal)); result[bucket].push(candidate);
+  }
+  for (const bucket of ['executable', 'humanDecisions', 'blocked']) result[bucket].sort((a, b) => a.sortKey[0] - b.sortKey[0] || (a.intentId < b.intentId ? -1 : a.intentId > b.intentId ? 1 : 0));
+  return result;
+}
+export function previewAutonomy(root, input = {}) {
+  return autonomyGuard(() => {
+    if (!input.record) return createPreview(root, input);
+    const paths = autonomyPaths(root);
+    return withAutonomyLock(paths, () => {
+      const result = createPreview(root, input);
+      writeAutonomyRecord(paths.projectRoot, resolve(paths.controlRoot, 'previews', `${result.proposal ? result.previewRevision + '-' : ''}${result.digest.slice(7)}.json`), result);
+      return result;
+    });
+  });
+}
+function validApprover(value) { return typeof value === 'string' && value === value.trim() && value.length > 0 && value.length <= 120 && !/[\x00-\x1f\x7f]/.test(value); }
+export function approveAutonomyGrant(root, input) {
+  return autonomyGuard(() => {
+    keys(input, ['expectedDigest', 'approvedBy', 'confirmed']);
+    if (input.confirmed !== true || !validApprover(input.approvedBy) || !digestPattern.test(input.expectedDigest)) autonomyError('autonomy-approval-required', 400);
+    const paths = autonomyPaths(root);
+    return withAutonomyLock(paths, () => {
+      const displayed = latestProposalPreview(root);
+      if (!displayed) autonomyError('autonomy-preview-required');
+      if (displayed.digest !== input.expectedDigest) autonomyError('autonomy-preview-stale');
+      const current = createPreview(root, { proposal: displayed.proposal }, displayed.previewRevision);
+      if (current.digest !== input.expectedDigest || autonomyDigest(current) !== autonomyDigest(displayed)) autonomyError('autonomy-preview-stale');
+      if ([...current.blocked, ...current.humanDecisions].some(item => current.proposal.intentIds.includes(item.intentId)
+        && item.reasons.some(reason => ['intent-not-accepted', 'intent-state-drift'].includes(reason.code)))) autonomyError('autonomy-intent-not-accepted');
+      const previous = readPolicy(root).grant;
+      const body = { schema: 'ewai.autonomy-grant/v1', id: previous?.id ?? randomUUID(), revision: (previous?.revision ?? 0) + 1,
+        previousDigest: previous?.digest ?? null, proposalDigest: current.digest, approvedBy: input.approvedBy, approvedAt: new Date().toISOString(),
+        scope: current.proposal, humanExclusions: [...AUTONOMY_HUMAN_EXCLUSIONS], configDigest: current.configDigest, projectIdentity: current.projectIdentity };
+      const grant = { ...body, digest: autonomyDigest(body) };
+      if (createPreview(root, { proposal: displayed.proposal }, displayed.previewRevision).digest !== current.digest) autonomyError('autonomy-preview-stale');
+      writeAutonomyRecord(paths.projectRoot, resolve(paths.authorityRoot, 'grants', grant.id, 'revisions', `${grant.revision}-${grant.digest.slice(7)}.json`), grant);
+      return grant;
+    });
+  });
+}
+
+// Revocation is canonical evidence bound to one exact grant revision. Runtime
+// rebuilds cannot restore it, and a successor needs a fresh named approval.
+export function revokeAutonomyGrant(root, input) {
+  return autonomyGuard(() => {
+    keys(input, ['expectedDigest', 'revokedBy', 'confirmed']);
+    if (input.confirmed !== true || !validApprover(input.revokedBy) || !digestPattern.test(input.expectedDigest)) autonomyError('autonomy-revocation-required', 400);
+    const paths = autonomyPaths(root);
+    return withAutonomyLock(paths, () => {
+      const policy = readPolicy(root), grant = policy.grant;
+      if (policy.digest !== input.expectedDigest) autonomyError('autonomy-policy-stale');
+      if (!grant) autonomyError('autonomy-grant-required');
+      if (policy.revocation) return policy.revocation;
+      const body = { schema: 'ewai.autonomy-revocation/v1', id: grant.id, grantRevision: grant.revision,
+        grantDigest: grant.digest, revokedBy: input.revokedBy, revokedAt: new Date().toISOString(), projectIdentity: grant.projectIdentity };
+      if (Date.parse(body.revokedAt) < Date.parse(grant.approvedAt)) autonomyError('autonomy-clock-rollback');
+      const record = { ...body, digest: autonomyDigest(body) };
+      writeAutonomyRecord(paths.projectRoot, resolve(paths.authorityRoot, 'grants', grant.id,
+        'revocations', `${grant.revision}-${record.digest.slice(7)}.json`), record);
+      return record;
+    });
+  });
+}

package/src/checkin.mjs

@@ -45,6 +45,24 @@ export {
 
 const execFileAsync = promisify(execFile);
 const moduleDir = dirname(fileURLToPath(import.meta.url));
+const betaVersionPattern = /^(\d+)\.(\d+)\.(\d+)-beta\.(\d+)$/;
+
+function betaVersionParts(version) {
+  const match = betaVersionPattern.exec(String(version ?? ''));
+  if (!match) return null;
+  const parts = match.slice(1).map(Number);
+  return parts.every(Number.isSafeInteger) ? parts : null;
+}
+
+function newerBetaVersion(current, candidate) {
+  const currentParts = betaVersionParts(current);
+  const candidateParts = betaVersionParts(candidate);
+  if (!currentParts || !candidateParts) return null;
+  for (let index = 0; index < currentParts.length; index++) {
+    if (candidateParts[index] !== currentParts[index]) return candidateParts[index] > currentParts[index];
+  }
+  return false;
+}
 
 export async function frameworkStatus(installRoot, options = {}) {
   if (!installRoot || !existsSync(resolve(installRoot, 'package.json'))) {
@@ -55,16 +73,17 @@ export async function frameworkStatus(installRoot, options = {}) {
   if (!metadata.name) {
     return { status: 'unknown', source: 'npm', current: currentVersion, reason: 'The npm registry cannot be checked from this runtime.' };
   }
+  const channel = betaVersionParts(currentVersion) ? 'beta' : 'latest';
   let latest = null;
   try {
     if (options.fetchImpl) {
-      const response = await options.fetchImpl(`https://registry.npmjs.org/${encodeURIComponent(metadata.name)}/latest`);
+      const response = await options.fetchImpl(`https://registry.npmjs.org/${encodeURIComponent(metadata.name)}/${channel}`);
       if (!response.ok) {
         return { status: 'unknown', source: 'npm', current: currentVersion, reason: `The npm registry returned HTTP ${response.status}.` };
       }
       latest = (await response.json()).version ?? null;
     } else {
-      const npm = await execFileAsync('npm', ['view', `${metadata.name}@latest`, 'version', '--json'], {
+      const npm = await execFileAsync('npm', ['view', `${metadata.name}@${channel}`, 'version', '--json'], {
         timeout: 8000,
         maxBuffer: 1024 * 1024,
         env: process.env
@@ -73,16 +92,21 @@ export async function frameworkStatus(installRoot, options = {}) {
       latest = Array.isArray(parsed) ? parsed.at(-1) : parsed;
     }
     if (!latest) return { status: 'unknown', source: 'npm', current: currentVersion, reason: 'The npm registry did not return a latest version.' };
+    const betaAvailable = channel === 'beta' ? newerBetaVersion(currentVersion, latest) : null;
+    if (channel === 'beta' && betaAvailable === null) {
+      return { status: 'unknown', source: 'npm', current: currentVersion, reason: 'The npm beta tag did not resolve to a beta version.' };
+    }
+    const updateAvailable = channel === 'beta' ? betaAvailable : currentVersion !== latest;
     return {
-      status: currentVersion === latest ? 'current' : 'update-available',
+      status: updateAvailable ? 'update-available' : 'current',
       source: 'npm',
       current: currentVersion,
       latest,
-      action: currentVersion === latest ? null : {
+      action: updateAvailable ? {
         kind: 'offer-npm-update',
         prompt: `EWAI ${latest} is available from npm. Would you like me to update the global package?`,
-        command: `npm install --global ${metadata.name}@latest`
-      }
+        command: `npm install --global ${metadata.name}@${channel}`
+      } : null
     };
   } catch {
     return { status: 'unknown', source: 'npm', current: currentVersion, reason: 'The npm update check did not finish. Check your connection and try again.' };

package/src/cli.mjs

@@ -3,6 +3,8 @@ import { fileURLToPath } from 'node:url';
 import { readFileSync, realpathSync } from 'node:fs';
 import YAML from 'yaml';
 import {DASHBOARD_VIEWS,readDashboardPreferences,saveDashboardPreferences} from './dashboard-preferences.mjs';
+import { autonomyInterfaceAction, safeAutonomyInterfaceError } from './runtime/dashboard-actions.mjs';
+import { readAutonomyFile } from './runtime/autonomy-workspace.mjs';
 import { createInterface } from 'node:readline/promises';
 import { Writable } from 'node:stream';
 import { configureAndInstallPremiumPersonas } from './checkin.mjs';
@@ -496,6 +498,14 @@ Commands:
   ewai checkin [--project PATH]
   ewai dashboard [--project PATH]
   ewai dashboard preferences [--project PATH] [--json]
+  ewai autonomy status [--run ID] [--project PATH] [--json]
+  ewai autonomy preview [--intent DOMAIN/SLUG --action ACTION --provider PROVIDER --expires-at ISO --max-runtime-ms N --max-operation-ms N --max-attempts N --record] [--project PATH] [--json]
+  ewai autonomy approve --expected-digest DIGEST --approved-by NAME --yes [--project PATH] [--json]
+  ewai autonomy revoke --expected-digest DIGEST --revoked-by NAME --yes [--project PATH] [--json]
+  ewai autonomy run|service --expected-digest DIGEST --provider PROVIDER --yes [--project PATH] [--json]
+  ewai autonomy pause|resume|cancel|recover --run ID --expected-revision N --yes [--project PATH] [--json]
+  ewai autonomy control --action pause|resume|cancel|revoke|recover --run ID --expected-revision N --yes [--revoked-by NAME] [--project PATH] [--json]
+  ewai autonomy answer --input PROJECT_RELATIVE_JSON --yes [--project PATH] [--json]
   ewai dashboard configure --enable VIEW | --disable VIEW [--collapse | --expand] --expected-digest DIGEST --yes [--project PATH] [--json]
   ewai server start|status|stop [--project PATH]
   ewai mcp [--project PATH]
@@ -839,6 +849,59 @@ export async function run(args) {
       return;
     }
 
+    if (command === 'autonomy') {
+      const controlAlias = ['pause', 'resume', 'cancel', 'recover'].includes(subcommand);
+      const action = controlAlias ? 'control' : subcommand;
+      const flags = {
+        status: { values: ['--project', '--run'], booleans: ['--json'] },
+        preview: { values: ['--project', '--intent', '--action', '--provider', '--expires-at', '--max-runtime-ms', '--max-operation-ms', '--max-attempts'], booleans: ['--json', '--record', '--yes'] },
+        approve: { values: ['--project', '--expected-digest', '--approved-by'], booleans: ['--json', '--yes'] },
+        revoke: { values: ['--project', '--expected-digest', '--revoked-by'], booleans: ['--json', '--yes'] },
+        run: { values: ['--project', '--expected-digest', '--provider'], booleans: ['--json', '--yes'] },
+        service: { values: ['--project', '--expected-digest', '--provider'], booleans: ['--json', '--yes'] },
+        control: { values: ['--project', '--run', '--expected-revision', '--revoked-by', ...(controlAlias ? [] : ['--action'])], booleans: ['--json', '--yes'] },
+        answer: { values: ['--project', '--input'], booleans: ['--json', '--yes'] },
+      }[action];
+      if (!flags) throw new Error('Unsupported autonomy operation.');
+      const seen = new Set();
+      for (let index = 2; index < args.length; index += 1) {
+        const flag = args[index];
+        if (seen.has(flag) && !(action === 'preview' && ['--intent', '--action', '--provider'].includes(flag))) throw new Error('Duplicate autonomy option.');
+        seen.add(flag);
+        if (flags.values.includes(flag)) {
+          if (!args[index + 1] || args[index + 1].startsWith('--')) throw new Error('An autonomy option is missing its value.');
+          index += 1;
+        } else if (!flags.booleans.includes(flag)) throw new Error('Unsupported autonomy option.');
+      }
+      const root = selectedProject(args);
+      let input = {};
+      if (action === 'preview') {
+        const scopeFlags = flags.values.filter(flag => flag !== '--project');
+        const proposal = scopeFlags.some(flag => has(args, flag)) ? {
+          intentIds: options(args, '--intent'), actions: options(args, '--action'), providers: options(args, '--provider'),
+          expiresAt: option(args, '--expires-at'), limits: { maxConcurrentIntents: 1,
+            maxRuntimeMs: Number(option(args, '--max-runtime-ms')), maxOperationMs: Number(option(args, '--max-operation-ms')),
+            maxAttempts: Number(option(args, '--max-attempts')) },
+        } : undefined;
+        // --record is existing explicit consent to persist a preview, never a grant.
+        input = { ...(proposal ? { proposal } : {}), record: has(args, '--record'), confirmed: has(args, '--record') || has(args, '--yes') };
+      } else if (action === 'answer') {
+        const path = option(args, '--input'); if (!path) throw new Error('Answer input is required.');
+        const parsed = JSON.parse(readAutonomyFile(root, resolve(root, path)));
+        if (!parsed || Object.getPrototypeOf(parsed) !== Object.prototype) throw new Error('Answer input must be an object.');
+        input = { ...parsed, confirmed: has(args, '--yes') };
+      } else {
+        for (const [flag, key] of [['--expected-digest', 'expectedDigest'], ['--approved-by', 'approvedBy'], ['--revoked-by', 'revokedBy'],
+          ['--provider', 'provider'], ['--run', 'runId'], ['--expected-revision', 'expectedRevision'], ['--action', 'action']]) {
+          if (has(args, flag)) input[key] = key === 'expectedRevision' ? Number(option(args, flag)) : option(args, flag);
+        }
+        if (action !== 'status') input.confirmed = has(args, '--yes');
+        if (controlAlias) input.action = subcommand;
+      }
+      const result = await autonomyInterfaceAction(root, action, input);
+      print(json ? result : JSON.stringify(result, null, 2), json); return;
+    }
+
     if (command === 'dashboard' && ['preferences','configure'].includes(subcommand)) {
       const valueFlags=['--project','--enable','--disable','--expected-digest'];
       const booleanFlags=['--json','--yes','--collapse','--expand'];
@@ -2416,6 +2479,10 @@ export async function run(args) {
         // Reporting must never replace or mask the original command failure.
       }
     }
+    if (command === 'autonomy') {
+      const safe = safeAutonomyInterfaceError(error);
+      console.error(json ? JSON.stringify(safe) : safe.error); process.exitCode = 1; return;
+    }
     const suppliedRolloutProject = option(args, '--project');
     const rolloutError = command === 'rollout'
       ? { error: suppliedRolloutProject ? String(error.message).replaceAll(suppliedRolloutProject, '<project>') : String(error.message), notices: { advisory: ROLLOUT_ADVISORY_NOTICE, security: ROLLOUT_ASSURANCE_NOTICE } }

package/src/delivery-gates.mjs

@@ -3,6 +3,7 @@ import { dirname, isAbsolute, relative, resolve } from 'node:path';
 import { atomicJson, isWithin, now, sha256 } from './delivery-documents.mjs';
 import { writeTaskGraphCheck } from './task-graph.mjs';
 import { policyGateRequirementsForPhase, readPolicyEvidenceFreshness } from './policy-gate-integration.mjs';
+import { withIntentMutation, assertIntentMutation } from './runtime/intent-ownership.mjs';
 
 const taskGraphPhases = new Set([
   'plan', 'pattern-validation', 'test-plan', 'build', 'delivery',
@@ -236,6 +237,10 @@ export function assertCompletedEvidenceFresh(paths, state) {
 }
 
 export function recordPhaseGateAtPaths(paths, slug, phaseId, input = {}, options = {}) {
+  return withIntentMutation(paths.projectRoot, slug, { action: 'record-gate', phase: phaseId, input: { input, options }, ownership: input.ownership }, () => recordOwnedPhaseGateAtPaths(paths, slug, phaseId, input, options));
+}
+
+function recordOwnedPhaseGateAtPaths(paths, slug, phaseId, input, options) {
   let taskGraphCheck = null;
   if (taskGraphPhases.has(phaseId)) {
     taskGraphCheck = writeTaskGraphCheck(paths.deliveryRoot, phaseId, { slug });
@@ -288,8 +293,10 @@ export function recordPhaseGateAtPaths(paths, slug, phaseId, input = {}, options
     deterministic_gate_failures_found_by_external_review: input.deterministicGateFailures ?? [],
     generated_at: now(),
   };
-  atomicJson(gatePathFor(paths, phaseId), gate);
+  assertIntentMutation(paths.projectRoot, slug);
   if (gate.status === 'pass') validateGate(paths, phaseId, gate, options.providers ?? []);
+  assertIntentMutation(paths.projectRoot, slug);
+  atomicJson(gatePathFor(paths, phaseId), gate);
   return gate;
 }