ai-engineering-loop 1.5.0 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
6
6
  [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/egagofur/ai-engineering-loop/pulls)
7
7
  [![AI Engineering](https://img.shields.io/badge/AI-Engineering%20Loop-orange.svg)](https://github.com/egagofur/ai-engineering-loop)
8
- [![Release](https://img.shields.io/badge/release-v1.5.0-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
8
+ [![Release](https://img.shields.io/badge/release-v1.7.0-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
9
9
 
10
10
  **A Reusable, Framework-Agnostic AI Engineering Operating System for Autonomous Coding Agents**
11
11
 
@@ -19,41 +19,9 @@
19
19
 
20
20
  ## Overview & Philosophy
21
21
 
22
- The AI Engineering Loop enforces clean architectural separation across three core layers:
23
-
24
- ```mermaid
25
- flowchart TD
26
- Start([User Task in Workspace]) --> PreCheck{Pre-Task Drift Check: metadata.json}
27
-
28
- PreCheck -->|Context Missing| AutoInit[Stage 0: Bootstrap .ai-engineering-loop/]
29
- PreCheck -->|Drift Detected| Reconcile[Stage 0: Reconcile Drifted Context]
30
- PreCheck -->|Context Fresh| GC[Stage 1: Goal Contract: Explicit Acceptance Criteria]
31
-
32
- AutoInit --> GC
33
- Reconcile --> GC
34
-
35
- subgraph CoreEngine [AI ENGINEERING OPERATING SYSTEM]
36
- GC --> RCA[Stage 2: Root Cause Analysis]
37
- RCA --> Plan[Stage 3: Implementation Plan]
38
- Plan --> MA[Stage 4: Maker Agent: Surgical Diff & Tests]
39
- MA --> DV{Stage 5: Deterministic Verification<br>Evidence Contract: Exit Code 0 & Full Logs}
40
-
41
- DV -->|Fail| MA
42
- DV -->|Pass| DA[Stage 6: Devil's Advocate Review<br>Capability Registry & Artifact Barrier]
43
-
44
- DA --> JD[Stage 7: Judge Agent: Impartial Magistrate<br>Validity + Severity Decision Matrix]
45
- end
46
-
47
- JD -->|VALID BLOCKER / HIGH: ITERATE| MA
48
- JD -->|INVALID: Dismissed / VALID LOW: Tradeoff| CheckDoD{All ACs Verified?}
49
-
50
- CheckDoD -->|Yes: PASS| ImpactEval{Post-Task Context Impact Assessment}
51
- ImpactEval -->|NONE: Typo, UI tweak| Adapter[Stage 8: Delivery Adapter: GitLab / GitHub]
52
- ImpactEval -->|TARGETED: Dep/route changed| PartialRefresh[Surgical Context Update] --> Adapter
53
- ImpactEval -->|MAJOR: Framework migration| FullRefresh[Full Context Reconciliation] --> Adapter
54
-
55
- Adapter --> TargetRepo[(Target Repository)]
56
- ```
22
+ The AI Engineering Loop keeps one understandable path across four phases. Deterministic gates—not model confidence—decide when work can advance:
23
+
24
+ [![AI Engineering Loop: task and context preparation flow into Specify, Make, Review, and Deliver phases. Failed verification or an ITERATE verdict returns work to Maker; PASS reaches delivery.](docs/images/engineering-loop-overview.svg)](docs/images/engineering-loop-overview.svg)
57
25
 
58
26
  ---
59
27
 
@@ -237,9 +205,19 @@ npx ai-engineering-loop recipe install candidate-v2.json --replace
237
205
  # Operate a custom node in an immutable recipe-bound run
238
206
  npx ai-engineering-loop node status
239
207
  npx ai-engineering-loop node start root-cause
208
+ npx ai-engineering-loop node activity root-cause --message "Comparing failing evidence"
240
209
  npx ai-engineering-loop node complete root-cause --artifact .ai-engineering-loop/runs/<run-id>/root-cause.json
241
210
  npx ai-engineering-loop node approve delivery-approval --yes
242
211
 
212
+ # Open the local workflow canvas (localhost-only, authenticated session)
213
+ npx ai-engineering-loop studio
214
+ npx ai-engineering-loop studio --port 4400 --no-open
215
+
216
+ # Transfer redacted knowledge to another developer or agent
217
+ npx ai-engineering-loop handoff create --audience developer
218
+ npx ai-engineering-loop handoff inspect <run-id>.ael-handoff.json
219
+ npx ai-engineering-loop handoff brief <run-id>.ael-handoff.json
220
+
243
221
  # Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
244
222
  npx ai-engineering-loop sync-hosts
245
223
 
@@ -256,7 +234,7 @@ Every full run stores private local artifacts under `.ai-engineering-loop/runs/<
256
234
 
257
235
  Declarative recipes let an AI or future visual editor author a workflow graph without weakening the safety gates. Built-in presets and project recipes can be validated, explained, graphed, and simulated deterministically. `run --recipe` opts into an immutable, resumable DAG scheduler; legacy runs remain unchanged. See [`core/workflow-recipes.md`](core/workflow-recipes.md) and [`core/controlled-workflow-runtime.md`](core/controlled-workflow-runtime.md).
258
236
 
259
- The deterministic recipe builder scaffolds from safe presets, validates candidates before atomic installation, preserves replaced versions locally, and exposes catalog/inspect/diff JSON for AI agents and a future UI. The host-neutral agent protocol is in [`agents/recipe-builder.md`](agents/recipe-builder.md).
237
+ The deterministic recipe builder scaffolds from safe presets, validates candidates before atomic installation, and preserves replaced versions locally. Workflow Studio is a thin local interface over that compiler and controlled runtime: a pannable and zoomable DAG canvas, drag-and-drop nodes, guarded visual connections, undo/redo, private per-project layouts, Stage 8 adapter selection, live activity and budget telemetry, explicit approval/retry controls, decision memory, and integrity-bound handoff export—without model or shell execution in the browser. See [`core/local-workflow-studio.md`](core/local-workflow-studio.md). The host-neutral agent protocol remains available in [`agents/recipe-builder.md`](agents/recipe-builder.md).
260
238
 
261
239
  Shipped adapters (Stage 8 only, after Judge PASS): `standard`, `github`, `gitlab`, `dot`. Catalog: `adapters/README.md`. Each team generates its own; do not copy a neighbour's pipeline.
262
240
 
package/README.npm.md CHANGED
@@ -34,6 +34,12 @@ npx ai-engineering-loop run --mode report-only "audit this repository"
34
34
  npx ai-engineering-loop policy show
35
35
  npx ai-engineering-loop budget status
36
36
 
37
+ # Author and observe deterministic workflow recipes locally
38
+ npx ai-engineering-loop studio
39
+
40
+ # Export a redacted, integrity-bound knowledge handoff
41
+ npx ai-engineering-loop handoff create --audience developer
42
+
37
43
  # 5. Copy package host skills into ~/.claude ~/.grok ~/.gemini ~/.agents
38
44
  npx ai-engineering-loop sync-hosts
39
45
  ```
@@ -48,6 +54,7 @@ npx ai-engineering-loop sync-hosts
48
54
  4. **Context Impact Assessment**: Evaluates completed tasks (`NONE`, `TARGETED`, `MAJOR`) to keep project context fresh without expensive whole-repo re-analysis.
49
55
  5. **Grok CLI host**: Native `spawn_subagent` for Devil's Advocate and Judge (`TRUE_INDEPENDENT_AGENT`). Disabled by `GROK_SUBAGENTS=0`.
50
56
  6. **Production runtime controls**: `REPORT_ONLY`, human-approved `ASSISTED`, opt-in `UNATTENDED`, actual token ledgers, a persistent kill switch, and locked disposable Maker worktrees.
57
+ 7. **Local Workflow Studio**: A localhost-only authenticated DAG canvas with animated live stage state, token telemetry, explicit approvals, decision memory, atomic recipe installation, and redacted handoff export. It does not execute models or shell commands in the browser.
51
58
 
52
59
  ---
53
60
 
package/SECURITY.md CHANGED
@@ -8,6 +8,8 @@ AI Engineering Loop blocks `.env*`, private-key formats, common credential files
8
8
 
9
9
  No telemetry is collected. Token usage ledgers stay local and contain counts plus provider model identifiers, not prompts or responses. Stage 0–7 require no AI Engineering Loop network service. Delivery adapters may use authenticated forge tools only after Judge `PASS`; ASSISTED requires explicit human approval before delivery.
10
10
 
11
+ Workflow Studio binds to `127.0.0.1`, validates local `Host` headers, and requires a random process-local session token exchanged for an HttpOnly SameSite cookie. Its bundled browser client has no model, shell, telemetry, or remote-asset capability. Do not expose the Studio port through a reverse proxy or public tunnel. Handoff exports omit source content and redact recognized secrets and home paths; verify their integrity hash on import, and still review them before sharing because pattern-based redaction cannot recognize every private value.
12
+
11
13
  UNATTENDED is disabled by default and Maker uses a locked disposable Git worktree when enabled. This protects the parent checkout and prevents concurrent Maker sessions; it is not an OS sandbox. For untrusted code, use a container or VM with restricted credentials, filesystem, processes, and network. See `core/runtime-safety.md`.
12
14
 
13
15
  Package releases use npm trusted publishing from `.github/workflows/publish.yml`, with a pinned OIDC-capable npm CLI and provenance. The package owner must configure `egagofur/ai-engineering-loop`, workflow `publish.yml`, and environment `npm` as the trusted publisher on npmjs.com. Do not add `NPM_TOKEN` or another long-lived publish credential to the repository or GitHub environment.
@@ -18,7 +20,7 @@ Package releases use npm trusted publishing from `.github/workflows/publish.yml`
18
20
  - Never place credentials in `.ai-engineering-loop/`, workflow files, prompts, findings, or delivery reports.
19
21
  - Do not pass the parent process environment to a child unless the host owns that boundary.
20
22
  - Treat generated run artifacts as sensitive local files. The CLI writes state and context packs with mode `0600` where supported.
21
- - Keep `runs/`, `usage/`, `worktrees/`, `locks/`, and task logs under the generated `.ai-engineering-loop/.gitignore`.
23
+ - Keep `runs/`, `usage/`, `worktrees/`, `locks/`, temporary Studio `drafts/`, and task logs under the generated `.ai-engineering-loop/.gitignore`.
22
24
  - Use `budget pause` to stop new model boundaries if spend, behavior, or credentials are in doubt. Recording an already completed call remains possible while paused.
23
25
  - Run a dedicated secret scanner such as `gitleaks` before delivery when available.
24
26
 
@@ -13,7 +13,7 @@
13
13
  const fs = require('fs');
14
14
  const path = require('path');
15
15
  const crypto = require('crypto');
16
- const { execSync } = require('child_process');
16
+ const { execSync, spawn } = require('child_process');
17
17
  const {
18
18
  homeDir,
19
19
  applyHostSync,
@@ -98,6 +98,7 @@ const {
98
98
  completeWorkflowNode,
99
99
  createWorkflowBundle,
100
100
  failWorkflowNode,
101
+ recordWorkflowActivity,
101
102
  retryWorkflowNode,
102
103
  startWorkflowNode,
103
104
  workflowStatus
@@ -109,8 +110,15 @@ const {
109
110
  installRecipe,
110
111
  recipeCatalog
111
112
  } = require('../lib/recipe-builder.js');
112
-
113
- const VERSION = '1.5.0';
113
+ const {
114
+ createHandoff,
115
+ handoffBrief,
116
+ readHandoff,
117
+ verifyHandoff
118
+ } = require('../lib/handoff.js');
119
+ const { createStudioServer } = require('../lib/studio-server.js');
120
+
121
+ const VERSION = '1.7.0';
114
122
  const CWD = process.cwd();
115
123
  const CONTEXT_DIR = path.join(CWD, '.ai-engineering-loop');
116
124
 
@@ -364,7 +372,7 @@ function generateContextFiles(rootDir, discovery, trigger = 'init', impact = 'IN
364
372
 
365
373
  // 0. metadata.json (Baseline)
366
374
  const metadataJson = {
367
- contextVersion: '1.5.0',
375
+ contextVersion: '1.7.0',
368
376
  generatedAt: new Date().toISOString(),
369
377
  repositoryRevision: currentRevision,
370
378
  projectProfile: discovery.profile,
@@ -1175,6 +1183,11 @@ function handleNode() {
1175
1183
  runId,
1176
1184
  reason: argValue('--reason') || 'node execution failed'
1177
1185
  });
1186
+ } else if (action === 'activity') {
1187
+ workflow = recordWorkflowActivity(CWD, nodeId, {
1188
+ runId,
1189
+ message: argValue('--message')
1190
+ });
1178
1191
  } else if (action === 'retry') {
1179
1192
  workflow = retryWorkflowNode(CWD, nodeId, { runId });
1180
1193
  } else if (action === 'approve') {
@@ -1450,6 +1463,106 @@ function handleRecipe() {
1450
1463
  }
1451
1464
  }
1452
1465
 
1466
+ function safeHandoffOutput(file) {
1467
+ const absolute = path.resolve(CWD, file);
1468
+ const relative = path.relative(CWD, absolute);
1469
+ if (relative === '..' || relative.startsWith(`..${path.sep}`)) {
1470
+ throw Object.assign(new Error('Handoff output must stay inside the repository'), { code: 'UNSAFE_HANDOFF_PATH' });
1471
+ }
1472
+ const parent = path.dirname(absolute);
1473
+ fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
1474
+ const realRoot = fs.realpathSync(CWD);
1475
+ const realParent = fs.realpathSync(parent);
1476
+ if (realParent !== realRoot && !realParent.startsWith(`${realRoot}${path.sep}`)) {
1477
+ throw Object.assign(new Error('Handoff output escapes the repository through a symlink'), { code: 'UNSAFE_HANDOFF_PATH' });
1478
+ }
1479
+ return absolute;
1480
+ }
1481
+
1482
+ function handleHandoff() {
1483
+ const action = process.argv[3] || 'create';
1484
+ const json = process.argv.includes('--json');
1485
+ try {
1486
+ if (action === 'create') {
1487
+ const bundle = createHandoff(CWD, {
1488
+ runId: argValue('--run'),
1489
+ audience: argValue('--audience') || 'developer'
1490
+ });
1491
+ const requested = argValue('--output');
1492
+ if (requested === '-') {
1493
+ console.log(JSON.stringify(bundle, null, json ? 0 : 2));
1494
+ return;
1495
+ }
1496
+ const output = safeHandoffOutput(requested || `${bundle.runId}.ael-handoff.json`);
1497
+ const descriptor = fs.openSync(output, 'wx', 0o600);
1498
+ try {
1499
+ fs.writeFileSync(descriptor, `${JSON.stringify(bundle, null, 2)}\n`);
1500
+ fs.fsyncSync(descriptor);
1501
+ } finally {
1502
+ fs.closeSync(descriptor);
1503
+ }
1504
+ const result = {
1505
+ ok: true,
1506
+ path: path.relative(CWD, output).split(path.sep).join('/'),
1507
+ runId: bundle.runId,
1508
+ audience: bundle.audience,
1509
+ bundleHash: bundle.bundleHash
1510
+ };
1511
+ console.log(json ? JSON.stringify(result) : `Created ${result.path}\nBundle hash: ${result.bundleHash}`);
1512
+ return;
1513
+ }
1514
+ const file = process.argv[4];
1515
+ if (!file || file.startsWith('-')) throw new Error(`handoff ${action} requires a file`);
1516
+ const bundle = readHandoff(CWD, file);
1517
+ const verification = verifyHandoff(bundle);
1518
+ if (action === 'inspect') {
1519
+ console.log(JSON.stringify({ ok: true, ...verification }, null, json ? 0 : 2));
1520
+ } else if (action === 'brief') {
1521
+ console.log(handoffBrief(bundle));
1522
+ } else {
1523
+ throw new Error('Unknown handoff action. Use create|inspect|brief');
1524
+ }
1525
+ } catch (err) {
1526
+ if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'HANDOFF_FAILED', error: err.message }));
1527
+ else log.error(err.message);
1528
+ process.exitCode = 1;
1529
+ }
1530
+ }
1531
+
1532
+ function openStudio(url) {
1533
+ const command = process.platform === 'darwin'
1534
+ ? ['open', [url]]
1535
+ : process.platform === 'win32'
1536
+ ? ['cmd', ['/c', 'start', '', url]]
1537
+ : ['xdg-open', [url]];
1538
+ const child = spawn(command[0], command[1], { detached: true, stdio: 'ignore' });
1539
+ child.on('error', () => {});
1540
+ child.unref();
1541
+ }
1542
+
1543
+ function handleStudio() {
1544
+ const requestedPort = argValue('--port');
1545
+ const port = requestedPort == null ? 4317 : Number(requestedPort);
1546
+ if (!Number.isSafeInteger(port) || port < 0 || port > 65535) {
1547
+ log.error('--port must be an integer from 0 to 65535');
1548
+ process.exitCode = 1;
1549
+ return;
1550
+ }
1551
+ const { server, token } = createStudioServer(CWD);
1552
+ server.on('error', (error) => {
1553
+ log.error(`Unable to start Studio: ${error.message}`);
1554
+ process.exitCode = 1;
1555
+ });
1556
+ server.listen(port, '127.0.0.1', () => {
1557
+ const address = server.address();
1558
+ const url = `http://127.0.0.1:${address.port}/?token=${token}`;
1559
+ log.success('✓ Workflow Studio is running locally');
1560
+ console.log(url);
1561
+ console.log('Press Ctrl+C to stop. The session token is valid only for this process.');
1562
+ if (!process.argv.includes('--no-open')) openStudio(url);
1563
+ });
1564
+ }
1565
+
1453
1566
  // Help Menu
1454
1567
  function printHelp() {
1455
1568
  console.log(`
@@ -1479,6 +1592,7 @@ Commands:
1479
1592
  start <id> [--run <id>] [--json]
1480
1593
  complete <id> [--artifact <repository-relative-path>] [--json]
1481
1594
  fail <id> [--reason <text>] [--json]
1595
+ activity <id> --message <safe progress text> [--json]
1482
1596
  retry <id> [--json]
1483
1597
  approve <id> --yes [--by <name>] [--json]
1484
1598
  policy Inspect or update fail-closed runtime controls
@@ -1516,6 +1630,12 @@ Commands:
1516
1630
  show <id> [--json]
1517
1631
  validate <id> [--mode <mode>] [--json]
1518
1632
  explain | graph | simulate <id> [--mode <mode>] [--json]
1633
+ studio Open the localhost-only visual workflow editor
1634
+ [--port <0-65535>] [--no-open]
1635
+ handoff Export or verify a redacted, integrity-bound knowledge transfer
1636
+ create [--run <id>] [--audience developer|agent|auditor]
1637
+ [--output <repository-relative-file>|-] [--json]
1638
+ inspect | brief <repository-relative-file> [--json]
1519
1639
  sync-hosts Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
1520
1640
  (only hosts that already exist; DOT skills only if already installed)
1521
1641
  --dry-run print the plan without writing
@@ -1583,6 +1703,12 @@ switch (command) {
1583
1703
  case 'recipe':
1584
1704
  handleRecipe();
1585
1705
  break;
1706
+ case 'studio':
1707
+ handleStudio();
1708
+ break;
1709
+ case 'handoff':
1710
+ handleHandoff();
1711
+ break;
1586
1712
  case 'sync-hosts':
1587
1713
  handleSyncHosts();
1588
1714
  break;
@@ -0,0 +1,90 @@
1
+ # Local Workflow Studio
2
+
3
+ Workflow Studio is a localhost-only visual control plane for declarative recipes and recipe-bound runs. It does not execute models, shell commands, or arbitrary node code. The existing recipe compiler and controlled workflow runtime remain the source of truth.
4
+
5
+ ## Start
6
+
7
+ ```bash
8
+ ai-engineering-loop studio
9
+ ```
10
+
11
+ The CLI binds only to `127.0.0.1`, creates a random process-local session token, and opens a tokenized bootstrap URL. The server exchanges that URL for an `HttpOnly; SameSite=Strict` cookie and removes the token from the address bar. Use `--no-open` when you want to copy the printed URL manually, or `--port 0` to let the operating system choose an available port.
12
+
13
+ The server rejects non-local `Host` headers. Static assets are bundled in the npm package; there are no CDNs, analytics, remote fonts, or browser-side model calls. Responses use a restrictive Content Security Policy and are not cached.
14
+
15
+ ## Authoring model
16
+
17
+ The canvas loads built-in and project recipes through the same APIs as the CLI:
18
+
19
+ 1. Select a recipe.
20
+ 2. Fork a protected built-in by changing its ID.
21
+ 3. Drag allowlisted node types from the library or click to add them at the viewport center.
22
+ 4. Move nodes freely and drag an output port onto another node to create a dependency.
23
+ 5. Pan, zoom, fit, auto-layout, and use undo/redo without changing recipe semantics.
24
+ 6. Review graph validation and hashes for every compatible mode.
25
+ 7. Install only after explicit confirmation.
26
+
27
+ Installation writes a private temporary candidate, invokes the existing atomic installer, and removes the candidate. Built-ins cannot be overwritten. Replacing a project recipe still requires the version policy enforced by `recipe install --replace`.
28
+
29
+ Canvas positions and viewport state are not recipe fields and never contribute to the graph hash. Studio stores them under private `.ai-engineering-loop/studio-layouts/` files, validates IDs and coordinate bounds, rejects symlinks, and writes atomically. This keeps visual organization independent from execution semantics.
30
+
31
+ Visual connections are real `dependsOn` edges. Studio rejects a connection that would introduce a cycle, then the recipe compiler applies the complete safety-backbone and mode validation before installation. Selecting and deleting a node removes its incoming references; undo remains available until the recipe is changed or reloaded.
32
+
33
+ ## Stage 8 delivery adapter
34
+
35
+ The default canvas labels the lifecycle coverage from Stage 1 through Stage 8; Maker contains the Stage 2–4 diagnosis, planning, and implementation sequence. Delivery nodes expose the project-level Stage 8 adapter selected in `.ai-engineering-loop/adapter.md`. Studio can select the shipped `standard`, `github`, `gitlab`, or `dot` adapters and shows the adapter inferred from the repository remote.
36
+
37
+ An adapter belongs to the project, not to one delivery node. For a custom adapter, **Custom with AI** copies a bounded builder request that tells an agent to use the existing `generate-adapter` Q1–Q5 protocol, preserve Stages 0–7, require Judge `PASS`, and keep credentials out of configuration. Once that agent writes `.ai-engineering-loop/adapter.md`, Studio discovers the custom adapter on refresh. The browser never accepts arbitrary adapter code or executes delivery commands.
38
+
39
+ ## Live execution
40
+
41
+ For a recipe-bound current run, Studio polls a small live snapshot rather than reloading the recipe catalog. It displays:
42
+
43
+ - current node states and the append-only event stream;
44
+ - an animated connector leaving the running node;
45
+ - provider-recorded run token spend and configured limit;
46
+ - explicit approval and retry controls;
47
+ - a short redacted activity message reported by the host:
48
+
49
+ ```bash
50
+ ai-engineering-loop node activity <node-id> \
51
+ --message "Comparing the failing test with the implementation"
52
+ ```
53
+
54
+ Activity can only be attached to a `RUNNING` node. It is capped at 240 printable characters, secret-redacted before persistence, and added to the integrity-bound workflow event chain.
55
+
56
+ ## Decision memory
57
+
58
+ Studio can record a concise decision and rationale against the current run. Decision memory is private runtime data under the run directory, is bounded to 100 entries, and is redacted before persistence. It becomes part of exported handoffs so the next developer or agent receives the “why,” not only the final state.
59
+
60
+ Do not use decision memory as a credential store or as a replacement for a repository ADR when a durable architectural decision belongs in version control.
61
+
62
+ ## Knowledge handoff
63
+
64
+ The top bar provides two forms:
65
+
66
+ - **Copy Brief** creates a human-readable developer summary.
67
+ - **Export Handoff** downloads a machine-readable `.ael-handoff.json` bundle for another agent.
68
+
69
+ The bundle contains objective, workflow state, artifact descriptors, decisions, transitions, and ready next actions. It deliberately excludes source contents. Strings pass through secret and home-path redaction, and the complete canonical manifest is bound to `bundleHash`.
70
+
71
+ Verify a received bundle before trusting it:
72
+
73
+ ```bash
74
+ ai-engineering-loop handoff inspect run-id.ael-handoff.json
75
+ ai-engineering-loop handoff brief run-id.ael-handoff.json
76
+ ```
77
+
78
+ Inspection accepts only regular files smaller than 1 MiB inside the repository, rejects symlinks and path escapes, and fails if any field no longer matches the bundle hash.
79
+
80
+ ## Trust boundary
81
+
82
+ Studio improves authoring and observability; it does not weaken runtime gates:
83
+
84
+ - graph validation does not imply execution permission;
85
+ - command nodes remain disabled;
86
+ - approvals remain explicit state transitions;
87
+ - connector edits cannot bypass the required safety backbone;
88
+ - delivery adapters cannot run before Judge `PASS`;
89
+ - token data comes only from the provider-recorded usage ledger;
90
+ - handoff integrity proves the bundle has not changed after export, not that every original claim was true.
@@ -0,0 +1,114 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="1440" height="900" viewBox="0 0 1440 900" role="img" aria-labelledby="title description">
2
+ <title id="title">AI Engineering Loop overview</title>
3
+ <desc id="description">A user task passes through context preparation, Specify, Make, Review, and Deliver. Failed verification and Judge ITERATE decisions return to Maker. Only a Judge PASS reaches delivery.</desc>
4
+ <defs>
5
+ <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto">
6
+ <path d="M0 0L10 5L0 10Z" fill="#59616d"/>
7
+ </marker>
8
+ <marker id="arrow-orange" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto">
9
+ <path d="M0 0L10 5L0 10Z" fill="#e95d37"/>
10
+ </marker>
11
+ <style>
12
+ .title{font:700 38px system-ui,-apple-system,"Segoe UI",sans-serif;fill:#17191d}
13
+ .subtitle{font:400 18px system-ui,-apple-system,"Segoe UI",sans-serif;fill:#59616d}
14
+ .phase{font:700 14px system-ui,-apple-system,"Segoe UI",sans-serif;letter-spacing:2px;fill:#59616d}
15
+ .number{font:700 16px ui-monospace,SFMono-Regular,Consolas,monospace;fill:#ffffff}
16
+ .node-title{font:700 19px system-ui,-apple-system,"Segoe UI",sans-serif;fill:#17191d}
17
+ .node-copy{font:400 14px system-ui,-apple-system,"Segoe UI",sans-serif;fill:#59616d}
18
+ .gate{font:700 13px system-ui,-apple-system,"Segoe UI",sans-serif;letter-spacing:1px;fill:#17191d}
19
+ .label{font:700 13px system-ui,-apple-system,"Segoe UI",sans-serif;fill:#59616d}
20
+ .small{font:400 13px system-ui,-apple-system,"Segoe UI",sans-serif;fill:#6d7480}
21
+ .line{fill:none;stroke:#59616d;stroke-width:3;marker-end:url(#arrow)}
22
+ .feedback{fill:none;stroke:#e95d37;stroke-width:3;stroke-dasharray:8 7;marker-end:url(#arrow-orange)}
23
+ </style>
24
+ </defs>
25
+
26
+ <rect width="1440" height="900" rx="24" fill="#f5f2eb"/>
27
+ <text class="title" x="70" y="72">From task to trusted delivery</text>
28
+ <text class="subtitle" x="70" y="106">One workflow. Eight stages. Evidence advances the work—not AI confidence.</text>
29
+
30
+ <rect x="70" y="145" width="1300" height="98" rx="14" fill="#ffffff" stroke="#d8d3c9" stroke-width="2"/>
31
+ <rect x="94" y="170" width="154" height="48" rx="24" fill="#17191d"/>
32
+ <text x="171" y="200" text-anchor="middle" style="font:700 16px system-ui,-apple-system,'Segoe UI',sans-serif;fill:#fff">USER TASK</text>
33
+ <path class="line" d="M250 194H328"/>
34
+ <text class="node-title" x="355" y="188">Stage 0 · Prepare context</text>
35
+ <text class="node-copy" x="355" y="213">Initialize missing context or reconcile drift before reasoning begins.</text>
36
+ <path class="line" d="M920 194H1120"/>
37
+ <rect x="1132" y="166" width="204" height="56" rx="9" fill="#fff4e8" stroke="#e95d37" stroke-width="2"/>
38
+ <text class="gate" x="1234" y="190" text-anchor="middle">CONTEXT READY</text>
39
+ <text class="small" x="1234" y="210" text-anchor="middle">deterministic check</text>
40
+
41
+ <text class="phase" x="70" y="298">SPECIFY</text>
42
+ <text class="phase" x="380" y="298">MAKE</text>
43
+ <text class="phase" x="835" y="298">REVIEW</text>
44
+ <text class="phase" x="1190" y="298">DELIVER</text>
45
+
46
+ <rect x="70" y="320" width="270" height="322" rx="16" fill="#fff8ef" stroke="#e6b083" stroke-width="2"/>
47
+ <circle cx="104" cy="365" r="18" fill="#e95d37"/><text class="number" x="104" y="371" text-anchor="middle">1</text>
48
+ <text class="node-title" x="135" y="362">Goal Contract</text>
49
+ <text class="node-copy" x="104" y="398">Freeze explicit acceptance</text>
50
+ <text class="node-copy" x="104" y="419">criteria and failure cases.</text>
51
+ <line x1="104" y1="451" x2="306" y2="451" stroke="#e6b083"/>
52
+ <text class="gate" x="104" y="484">OUTPUT</text>
53
+ <text class="node-copy" x="104" y="513">A shared definition of done</text>
54
+ <text class="node-copy" x="104" y="534">that machines can verify.</text>
55
+ <rect x="104" y="570" width="202" height="44" rx="8" fill="#ffffff" stroke="#e6b083"/>
56
+ <text class="gate" x="205" y="597" text-anchor="middle">GOAL GATE</text>
57
+
58
+ <rect x="380" y="320" width="415" height="322" rx="16" fill="#f1f6fb" stroke="#94b5d2" stroke-width="2"/>
59
+ <circle cx="414" cy="365" r="18" fill="#467da8"/><text class="number" x="414" y="371" text-anchor="middle">2</text>
60
+ <text class="node-title" x="445" y="362">Root cause</text>
61
+ <text class="node-copy" x="414" y="394">Reproduce and explain the real problem.</text>
62
+ <path d="M414 422H760" stroke="#b8cad9" stroke-width="2"/>
63
+ <circle cx="414" cy="463" r="18" fill="#467da8"/><text class="number" x="414" y="469" text-anchor="middle">3</text>
64
+ <text class="node-title" x="445" y="460">Implementation plan</text>
65
+ <text class="node-copy" x="414" y="492">Choose seams, tests, and the smallest coherent change.</text>
66
+ <path d="M414 520H760" stroke="#b8cad9" stroke-width="2"/>
67
+ <circle cx="414" cy="561" r="18" fill="#467da8"/><text class="number" x="414" y="567" text-anchor="middle">4</text>
68
+ <text class="node-title" x="445" y="558">Maker</text>
69
+ <text class="node-copy" x="414" y="590">Implement surgical changes with red → green tests.</text>
70
+ <rect x="643" y="550" width="117" height="44" rx="8" fill="#ffffff" stroke="#94b5d2"/>
71
+ <text class="gate" x="701" y="577" text-anchor="middle">DIFF + TESTS</text>
72
+
73
+ <rect x="835" y="320" width="315" height="322" rx="16" fill="#f5f0fa" stroke="#b49bcb" stroke-width="2"/>
74
+ <circle cx="869" cy="365" r="18" fill="#765596"/><text class="number" x="869" y="371" text-anchor="middle">5</text>
75
+ <text class="node-title" x="900" y="362">Verify</text>
76
+ <text class="node-copy" x="869" y="394">Run commands; capture exact evidence.</text>
77
+ <path d="M869 422H1115" stroke="#c9bad7" stroke-width="2"/>
78
+ <circle cx="869" cy="463" r="18" fill="#765596"/><text class="number" x="869" y="469" text-anchor="middle">6</text>
79
+ <text class="node-title" x="900" y="460">Devil’s Advocate</text>
80
+ <text class="node-copy" x="869" y="492">Challenge claims against reality.</text>
81
+ <path d="M869 520H1115" stroke="#c9bad7" stroke-width="2"/>
82
+ <circle cx="869" cy="561" r="18" fill="#765596"/><text class="number" x="869" y="567" text-anchor="middle">7</text>
83
+ <text class="node-title" x="900" y="558">Judge</text>
84
+ <text class="node-copy" x="869" y="590">PASS, ITERATE, or ESCALATE.</text>
85
+
86
+ <rect x="1190" y="320" width="180" height="322" rx="16" fill="#eef8f1" stroke="#81b994" stroke-width="2"/>
87
+ <circle cx="1224" cy="365" r="18" fill="#39885a"/><text class="number" x="1224" y="371" text-anchor="middle">8</text>
88
+ <text class="node-title" x="1255" y="362">Deliver</text>
89
+ <text class="node-copy" x="1224" y="404">Refresh context.</text>
90
+ <text class="node-copy" x="1224" y="428">Require approval.</text>
91
+ <text class="node-copy" x="1224" y="452">Publish through</text>
92
+ <text class="node-copy" x="1224" y="476">the adapter.</text>
93
+ <rect x="1216" y="550" width="128" height="64" rx="9" fill="#39885a"/>
94
+ <text x="1280" y="576" text-anchor="middle" style="font:700 13px system-ui,-apple-system,'Segoe UI',sans-serif;fill:#fff">TARGET</text>
95
+ <text x="1280" y="596" text-anchor="middle" style="font:400 13px system-ui,-apple-system,'Segoe UI',sans-serif;fill:#fff">REPOSITORY</text>
96
+
97
+ <path class="line" d="M340 365H380"/>
98
+ <path class="line" d="M795 561H815V365H835"/>
99
+ <path class="line" d="M1150 561H1170V365H1190"/>
100
+ <rect x="1139" y="505" width="62" height="28" rx="14" fill="#39885a"/>
101
+ <text x="1170" y="524" text-anchor="middle" style="font:700 12px system-ui,-apple-system,'Segoe UI',sans-serif;fill:#fff">PASS</text>
102
+
103
+ <path class="feedback" d="M869 365C810 365 820 700 650 700H590C515 700 500 636 500 610"/>
104
+ <rect x="656" y="676" width="137" height="28" rx="14" fill="#f5f2eb"/>
105
+ <text class="label" x="724" y="695" text-anchor="middle">FAIL → FIX</text>
106
+ <path class="feedback" d="M869 561C815 561 835 770 665 770H575C470 770 455 650 455 610"/>
107
+ <rect x="665" y="746" width="175" height="28" rx="14" fill="#f5f2eb"/>
108
+ <text class="label" x="752" y="765" text-anchor="middle">ITERATE → MAKER</text>
109
+
110
+ <rect x="70" y="815" width="1300" height="48" rx="10" fill="#17191d"/>
111
+ <circle cx="101" cy="839" r="7" fill="#e95d37"/>
112
+ <text x="119" y="845" style="font:600 14px system-ui,-apple-system,'Segoe UI',sans-serif;fill:#fff">Safety invariant:</text>
113
+ <text x="245" y="845" style="font:400 14px system-ui,-apple-system,'Segoe UI',sans-serif;fill:#d5d8dd">a model can propose work, but only contracts, artifacts, verification evidence, and gates can advance the run.</text>
114
+ </svg>
package/lib/doctor.js CHANGED
@@ -30,7 +30,8 @@ const REQUIRED_SCHEMAS = [
30
30
  'node-definition.schema.json',
31
31
  'compiled-plan.schema.json',
32
32
  'workflow-state.schema.json',
33
- 'workflow-event.schema.json'
33
+ 'workflow-event.schema.json',
34
+ 'handoff.schema.json'
34
35
  ];
35
36
 
36
37
  function check(id, passed, detail) {
@@ -97,7 +98,7 @@ function runDoctor(rootDir = path.join(__dirname, '..')) {
97
98
  }
98
99
 
99
100
  const packageFiles = new Set(pkg.files || []);
100
- const requiredPackageEntries = ['bin/', 'lib/', 'core/', 'policies/', 'recipes/', 'schemas/', 'evals/'];
101
+ const requiredPackageEntries = ['bin/', 'lib/', 'core/', 'policies/', 'recipes/', 'schemas/', 'evals/', 'studio/'];
101
102
  const missingPackageEntries = requiredPackageEntries.filter((entry) => !packageFiles.has(entry));
102
103
  checks.push(check(
103
104
  'package-assets',