ai-engineering-loop 1.1.0 → 1.2.1

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.
Files changed (39) hide show
  1. package/.agents/workflows/ai-engineering-loop.md +5 -5
  2. package/.claude/skills/ai-engineering-loop/SKILL.md +7 -5
  3. package/.gemini/skills/ai-engineering-loop/SKILL.md +7 -5
  4. package/.grok/skills/ai-engineering-loop/SKILL.md +7 -5
  5. package/README.md +20 -3
  6. package/README.npm.md +9 -1
  7. package/SECURITY.md +8 -2
  8. package/agents/judge.md +5 -5
  9. package/agents/maker.md +6 -6
  10. package/bin/ai-engineering-loop.js +223 -13
  11. package/core/configuration-precedence.md +4 -4
  12. package/core/context-impact-assessment.md +1 -1
  13. package/core/definition-of-done.md +3 -3
  14. package/core/escalation-policy.md +2 -2
  15. package/core/goal-contract.md +2 -2
  16. package/core/iteration-policy.md +4 -4
  17. package/core/project-initialization.md +2 -2
  18. package/core/runtime-safety.md +75 -0
  19. package/core/verification-loop.md +1 -1
  20. package/lib/budget.js +220 -0
  21. package/lib/doctor.js +14 -1
  22. package/lib/gates.js +55 -1
  23. package/lib/package-audit.js +78 -0
  24. package/lib/run-state.js +47 -8
  25. package/lib/runtime-files.js +53 -0
  26. package/lib/runtime-policy.js +118 -0
  27. package/lib/safe-context.js +3 -0
  28. package/lib/sandbox.js +305 -0
  29. package/package.json +6 -3
  30. package/policies/finding-policy.md +2 -2
  31. package/policies/no-progress-policy.md +2 -2
  32. package/profiles/README.md +5 -5
  33. package/profiles/backend-api.md +1 -1
  34. package/profiles/library.md +1 -1
  35. package/profiles/mobile-app.md +1 -1
  36. package/profiles/monorepo.md +1 -1
  37. package/profiles/web-app.md +1 -1
  38. package/schemas/delivery.schema.json +2 -1
  39. package/schemas/report.schema.json +17 -0
@@ -7,18 +7,18 @@ Follow `policies/review-budget.md`. Parent is Maker plus orchestrator. Do not us
7
7
 
8
8
  Compact map (not a second OS): Specify (stages 0-1), Make (stages 2-4), Review (stages 5-7), Deliver (stage 8). Keep the 8-stage numbers. Do not skip Goal Contract, verification, Devil's Advocate, or Judge.
9
9
 
10
- Deterministic gates are mandatory. Stage 0 runs sync-hosts, status, then `npx ai-engineering-loop run`; `state --json` gives runId and `.ai-engineering-loop/runs/<runId>/` (`RUN_DIR`). Never edit state.json. Stage 1 keeps Goal Contract Markdown, writes goal-contract.json with failure cases, then runs `gate goal`. Maker writes RUN_DIR/diff.patch then `gate maker`. Stage 5 writes current verification.json then `gate verification`.
10
+ Deterministic gates are mandatory. Read `core/runtime-safety.md`. Stage 0 runs sync-hosts, status, then `npx ai-engineering-loop run [--mode report-only|assisted|unattended]`; `state --json` gives runId, immutable mode, and `.ai-engineering-loop/runs/<runId>/` (`RUN_DIR`). Never edit state.json. Run `budget status --run <runId>` before every model/subagent call and `budget record --input <actual> --output <actual> --model <id> --run <runId>` immediately after provider usage is returned. Never invent counts. Missing accounting stops UNATTENDED and requires human direction in ASSISTED. `budget pause` is the kill switch. Stage 1 keeps Goal Contract Markdown, writes goal-contract.json with failure cases, then runs `gate goal`.
11
11
 
12
12
  Inherited invariants: read `core/grill-policy.md`, `policies/tdd-policy.md`, and `.ai-engineering-loop/glossary.md`. On `adapter_type: dot`, grill includes blast radius: lifecycle sketch and load `task-impact-inquiry`. If the user prompt has no numbered AC, draft the contract, list a short menu and wait. Chat agreement is not freeze. AC is a failure table. One red test per AC row. Do not freeze sunny-path-only. Write claimed-vs-reality.md. Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality. Report Spec and Standards separately. DA prompt: "at most 8 tool calls; read the diff file; skip css and generated files". Judge prompt: "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff". Never use `browser_subagent` as reviewer. `generate-workflow` reads workflow.md and lessons.md; missing maker_intern means INVOCATION_UNAVAILABLE. Do not type a model name.
13
13
 
14
- Stage 1: if the user asks for ideas, list a short menu and wait; do not implement. Grill if the task is ambiguous (`core/grill-policy.md`), then freeze the Goal Contract file. Chat agreement is not freeze. If the user prompt has no numbered AC, draft `.ai-engineering-loop/tasks/goal-contract.md` with a failure table, show it, wait for freeze. Do not start Maker. On business-logic change, and always on `adapter_type: dot`, grill includes blast radius: lifecycle sketch, four pillars (state, sibling, approval, queues), ASCII picture. Load `task-impact-inquiry` if present. Do not run a second interview. Passing unit tests are not isolation proof. Use `.ai-engineering-loop/glossary.md`. Name test seams. AC is a failure table (happy, empty/omit, boundary, sibling, error). One red test per AC row. Do not freeze sunny-path-only. Stages 2-4: Read `maker_intern` from workflow.md (missing or none = parent is Maker). Do not type a model name. If intern is set, confirm it came from this host's list (`/models` if that command exists). If the list command is missing or the id is not on it, parent is Maker; say intern INVOCATION_UNAVAILABLE. Intern cannot skip verification, Devil's Advocate, or Judge. Maker: TDD at those seams (`policies/tdd-policy.md`): one red test per AC row. Bugs: red repro first (`core/root-cause-analysis.md`). Mid-loop stop: `core/handoff-policy.md`.
14
+ Stage 1: if the user asks for ideas, list a short menu and wait; do not implement. Grill if the task is ambiguous (`core/grill-policy.md`), then freeze the Goal Contract file. Chat agreement is not freeze. If the user prompt has no numbered AC, draft `.ai-engineering-loop/tasks/goal-contract.md` with a failure table, show it, wait for freeze. Do not start Maker. On business-logic change, and always on `adapter_type: dot`, grill includes blast radius: lifecycle sketch, four pillars (state, sibling, approval, queues), ASCII picture. Load `task-impact-inquiry` if present. Do not run a second interview. Passing unit tests are not isolation proof. Use `.ai-engineering-loop/glossary.md`. Name test seams. AC is a failure table (happy, empty/omit, boundary, sibling, error). One red test per AC row. Do not freeze sunny-path-only. Stages 2-4 branch on mode: REPORT_ONLY never edits repository files, writes RUN_DIR/report.json, runs `gate report`, and stops. ASSISTED uses normal Maker. UNATTENDED runs `sandbox create --run <runId>`, Maker only in the returned worktreePath, never edits the parent checkout, and runs `sandbox capture --run <runId>`. Read `maker_intern` from workflow.md (missing or none = parent is Maker). Do not type a model name. If intern is set, confirm it came from this host's list (`/models` if that command exists). If the list command is missing or the id is not on it, parent is Maker; say intern INVOCATION_UNAVAILABLE. Intern cannot skip verification, Devil's Advocate, or Judge. Maker: TDD at those seams (`policies/tdd-policy.md`): one red test per AC row. ASSISTED writes RUN_DIR/diff.patch; UNATTENDED capture writes it; then `gate maker`. Stage 5 writes current RUN_DIR/verification.json and runs `gate verification`. Bugs: red repro first (`core/root-cause-analysis.md`). Mid-loop stop: `core/handoff-policy.md`.
15
15
 
16
16
  If `invoke_subagent` (or Task) exists, spawn `devil-advocate` then `judge` as siblings. Wait for each child. Do not run them in the background. Use `general-purpose` only if the named type is rejected.
17
17
 
18
18
  5. Before Devil's Advocate: write `git diff` to `.ai-engineering-loop/tasks/current.diff` and put `git diff --name-only` in the child prompt. Do not paste Maker rationale. Write `.ai-engineering-loop/tasks/claimed-vs-reality.md` (AC, Claimed, Reality from command log). Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality.
19
- 6. Build `context devil-advocate`, spawn DA with the pack path, normalize RUN_DIR/findings.json with runId and diffHash, then `gate review`.
20
- 7. Run `escalation --json`, resolve the required tier from the host catalog, build Judge context from only goal-contract.json, verification.json, and findings.json, spawn Judge, write verdict.json with modelTier, then `gate judge`.
19
+ 6. Build `context devil-advocate`, check `budget status`, spawn DA with the pack path, wait, `budget record` actual usage, normalize RUN_DIR/findings.json with runId and diffHash, then `gate review`.
20
+ 7. Run `escalation --json`, resolve the required tier from the host catalog, build Judge context from only goal-contract.json, verification.json, and findings.json, check `budget status`, spawn Judge, wait, `budget record` actual usage, write verdict.json with modelTier, then `gate judge`.
21
21
 
22
22
  If no subagent tool exists, run the same budgets in this session as CONTEXT_ISOLATION_ONLY. Do not claim independent agent execution.
23
23
 
24
- Init/status/refresh/sync-hosts/generate-adapter/generate-workflow: `npx ai-engineering-loop <command>`. generate-workflow grills Q1-Q6. Q6 Maker intern: pick from the host catalog; do not type a model name. After Judge PASS, PR/MR body includes `Steps to Reproduce & Testing (QA)` and bugfix placeholders must not stay empty. Preview Stage 8 remote payloads and never include context packs, raw logs, or credentials. Write RUN_DIR/delivery.json and run `gate delivery`; only that gate completes the run. Confirmed process lessons go to lessons.md, not a chat dump.
24
+ Init/status/refresh/sync-hosts/generate-adapter/generate-workflow: `npx ai-engineering-loop <command>`. generate-workflow grills Q1-Q6. Q6 Maker intern: pick from the host catalog; do not type a model name. After Judge PASS, PR/MR body includes `Steps to Reproduce & Testing (QA)` and bugfix placeholders must not stay empty. Preview Stage 8 remote payloads and never include context packs, usage ledgers, raw logs, or credentials. In ASSISTED, wait for explicit human approval and write `humanApproved: true` in RUN_DIR/delivery.json; never infer it. Run `gate delivery`; only that gate completes the run. Confirmed process lessons go to lessons.md, not a chat dump.
@@ -39,11 +39,13 @@ Parent session is Maker plus orchestrator. Spawn Devil's Advocate and Judge as *
39
39
 
40
40
  Run `npx ai-engineering-loop state --json` to get the current `runId` and use `.ai-engineering-loop/runs/<runId>/` as `RUN_DIR`. Never edit `state.json` or `current.json`.
41
41
 
42
+ Read `core/runtime-safety.md`. The ledger mode is immutable. Before every model or Task call, run `npx ai-engineering-loop budget status --run <runId>`; after it returns, record actual provider-reported usage with `budget record --input <n> --output <n> --model <id> --run <runId>`. Never invent actual token counts. If usage metadata is unavailable, UNATTENDED stops and escalates; ASSISTED discloses the gap and asks the human whether to continue. `budget pause` is an emergency kill switch.
43
+
42
44
  Inherited invariants remain mandatory: read `core/grill-policy.md`, `policies/tdd-policy.md`, and `.ai-engineering-loop/glossary.md`. On `adapter_type: dot`, grill includes blast radius: lifecycle sketch and load `task-impact-inquiry`. If the user prompt has no numbered AC, draft the contract, list a short menu and wait. Chat agreement is not freeze. AC is a failure table. One red test per AC row. Do not freeze sunny-path-only. Write claimed-vs-reality.md. Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality. Report Spec and Standards separately. DA prompt includes "at most 8 tool calls; read the diff file; skip css and generated files". Judge prompt includes "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
43
45
 
44
- 1. Stage 0: `npx ai-engineering-loop sync-hosts`, `status`, then `run` to create or resume the ledger. Read `.ai-engineering-loop/glossary.md`. Read `.ai-engineering-loop/lessons.md` and `.ai-engineering-loop/workflow.md` if they exist. Follow workflow.md hooks (`before_grill`, `after_freeze`, `after_pass`). Do not skip Goal Contract, verification, Devil's Advocate, or Judge even if workflow.md asks. If workflow.md is missing, run the default 8-stage loop. If sync-hosts copied files, tell the user a new session is needed; keep going with this session.
46
+ 1. Stage 0: `npx ai-engineering-loop sync-hosts`, `status`, then `run [--mode report-only|assisted|unattended]` to create or resume the ledger. Run `state --json` and `budget status`. Read `.ai-engineering-loop/glossary.md`. Read `.ai-engineering-loop/lessons.md` and `.ai-engineering-loop/workflow.md` if they exist. Follow workflow.md hooks (`before_grill`, `after_freeze`, `after_pass`). Do not skip required gates even if workflow.md asks. If workflow.md is missing, run the default 8-stage loop. If sync-hosts copied files, tell the user a new session is needed; keep going with this session.
45
47
  2. Stage 1: Goal Contract (`core/goal-contract.md`). If the user asks for ideas, list a short menu and wait; do not implement. If the task is ambiguous and the user can answer, grill first (`core/grill-policy.md`): design tree, recommended answers, do not ask look-up facts. On business-logic change, and always on `adapter_type: dot`, include blast radius. Chat agreement is not freeze. Keep the human Markdown contract and write `RUN_DIR/goal-contract.json` with `schemaVersion`, `runId`, objective, numbered AC, evidenceRequired, and non-empty failureCases. Run `npx ai-engineering-loop gate goal`; do not edit production code unless it passes.
46
- 3. Stages 2-4: Read `maker_intern` from workflow.md (missing or none = parent is Maker). Do not type a model name. Confirm a configured intern through `/models` when available; otherwise parent is Maker and report INVOCATION_UNAVAILABLE. Intern cannot skip later gates. Bugs: red repro first. Features: one red test per AC row. Write the exact review diff to `RUN_DIR/diff.patch`, then run `npx ai-engineering-loop gate maker`.
48
+ 3. After Goal freeze, branch on mode. REPORT_ONLY: do not edit repository files; write `RUN_DIR/report.json` with summary and recommendations, then run `gate report` and stop. ASSISTED: run the normal Maker and later require human approval. UNATTENDED: run `sandbox create --run <runId>`, set Maker's working directory to the returned worktreePath, never edit the parent checkout, then run `sandbox capture --run <runId>`. For Maker, read `maker_intern` from workflow.md (missing or none = parent is Maker). Do not type a model name. Confirm it through `/models` when available; otherwise parent is Maker and report INVOCATION_UNAVAILABLE. Intern cannot skip later gates. Bugs: red repro first. Features: one red test per AC row. In ASSISTED write the exact review diff to `RUN_DIR/diff.patch`; UNATTENDED capture writes it. Then run `npx ai-engineering-loop gate maker`.
47
49
  4. Stage 5: run commands from `.ai-engineering-loop/verification.md`. Write `RUN_DIR/verification.json` with current git revision, gated diff hash, command, execution identity, times, exit code, stdout, timeout status, and test counts. Vague "seems green" is invalid. Keep `.ai-engineering-loop/tasks/claimed-vs-reality.md`. Run `npx ai-engineering-loop gate verification`; do not spawn Devil's Advocate unless it passes.
48
50
  5. Write artifacts, then spawn. Before Devil's Advocate:
49
51
  - Write `git diff` to a file (for example `.ai-engineering-loop/tasks/current.diff`).
@@ -51,10 +53,10 @@ Inherited invariants remain mandatory: read `core/grill-policy.md`, `policies/td
51
53
  - Put those paths in the child prompt. Do not paste Maker rationale.
52
54
  - Write `.ai-engineering-loop/tasks/claimed-vs-reality.md` if missing. Do not spawn DA without it.
53
55
  - If stopping mid-loop, write `.ai-engineering-loop/tasks/handoff.md` (`core/handoff-policy.md`).
54
- 6. Stage 6: Build `npx ai-engineering-loop context devil-advocate <files...>` from contract, diff, verification, conventions, and changed source paths. Task `subagent_type: devil-advocate`. Use `general-purpose` only if rejected. Wait. Normalize its ledger into `RUN_DIR/findings.json` with runId and diffHash, then run `npx ai-engineering-loop gate review`.
55
- 7. Stage 7: Run `npx ai-engineering-loop escalation --json` before selecting Judge. Resolve the required tier through `/models`; if unavailable, escalate to the user. Build Judge context from only goal-contract.json, verification.json, and findings.json. Spawn Judge as a sibling and wait. Normalize its output into `RUN_DIR/verdict.json`, include `modelTier`, then run `npx ai-engineering-loop gate judge`. A gate failure overrides optimistic prose.
56
+ 6. Stage 6: Build `npx ai-engineering-loop context devil-advocate <files...>` from contract, diff, verification, conventions, and changed source paths. Recheck `budget status`, then Task `subagent_type: devil-advocate`. Use `general-purpose` only if rejected. Wait and immediately `budget record` its actual usage. Normalize its ledger into `RUN_DIR/findings.json` with runId and diffHash, then run `npx ai-engineering-loop gate review`.
57
+ 7. Stage 7: Run `npx ai-engineering-loop escalation --json` before selecting Judge. Resolve the required tier through `/models`; if unavailable, escalate to the user. Build Judge context from only goal-contract.json, verification.json, and findings.json. Recheck `budget status`, spawn Judge as a sibling and wait, then immediately `budget record` actual usage. Normalize its output into `RUN_DIR/verdict.json`, include `modelTier`, then run `npx ai-engineering-loop gate judge`. A gate failure overrides optimistic prose.
56
58
  8. ITERATE with iteration under 3: fix in the parent, re-verify, spawn a **new** Devil's Advocate (do not resume the previous child).
57
- 9. After Judge PASS: run the `after_pass` hook, then Stage 8 from `.ai-engineering-loop/adapter.md`. PR/MR body includes `Steps to Reproduce & Testing (QA)`; bugfix placeholders must not stay empty. Preview remote payloads; do not expose context packs, raw logs, or credentials. Write `RUN_DIR/delivery.json` with destination and summary, then run `npx ai-engineering-loop gate delivery`. Only this gate completes the run.
59
+ 9. After Judge PASS: run the `after_pass` hook, then Stage 8 from `.ai-engineering-loop/adapter.md`. PR/MR body includes `Steps to Reproduce & Testing (QA)`; bugfix placeholders must not stay empty. Preview remote payloads; do not expose context packs, usage ledgers, raw logs, or credentials. In ASSISTED, wait for explicit human approval and write `humanApproved: true`; never infer approval. Write `RUN_DIR/delivery.json` with destination and summary, then run `npx ai-engineering-loop gate delivery`. Only this gate completes the run.
58
60
 
59
61
  ## Report header
60
62
 
@@ -32,11 +32,13 @@ Compact map (not a second OS): Specify (stages 0-1), Make (stages 2-4), Review (
32
32
 
33
33
  Run `npx ai-engineering-loop state --json` to get the current runId and use `.ai-engineering-loop/runs/<runId>/` as `RUN_DIR`. Never edit state.json or current.json.
34
34
 
35
+ Read `core/runtime-safety.md`. Before every model or subagent call, run `budget status --run <runId>` and afterward run `budget record --input <actual> --output <actual> --model <id> --run <runId>` using provider-reported usage. Never invent usage. Missing usage stops UNATTENDED and requires human direction in ASSISTED. `budget pause` is the kill switch.
36
+
35
37
  Inherited invariants remain mandatory: read `core/grill-policy.md`, `policies/tdd-policy.md`, and `.ai-engineering-loop/glossary.md`. On `adapter_type: dot`, grill includes blast radius: lifecycle sketch and load `task-impact-inquiry`. If the user prompt has no numbered AC, draft the contract, list a short menu and wait. Chat agreement is not freeze. AC is a failure table. One red test per AC row. Do not freeze sunny-path-only. Write claimed-vs-reality.md. Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality. Report Spec and Standards separately. DA prompt includes "at most 8 tool calls; read the diff file; skip css and generated files". Judge prompt includes "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff". `generate-workflow` still reads workflow.md and lessons.md; missing maker_intern means INVOCATION_UNAVAILABLE. Do not type a model name.
36
38
 
37
- 1. Stage 0: sync hosts, check status, then run `npx ai-engineering-loop run` to create or resume the ledger. Read glossary, lessons, and workflow overlays. Required stages cannot be skipped.
39
+ 1. Stage 0: sync hosts, check status, then run `npx ai-engineering-loop run [--mode report-only|assisted|unattended]` to create or resume the ledger. Run `state --json` and `budget status`. Read glossary, lessons, and workflow overlays. Required gates cannot be skipped.
38
40
  2. Stage 1: keep the human Goal Contract Markdown and write `RUN_DIR/goal-contract.json` with schemaVersion, runId, objective, numbered AC, evidenceRequired, and non-empty failureCases. Grill ambiguous decisions and business blast radius first. Run `npx ai-engineering-loop gate goal`; do not edit production code unless it passes.
39
- 3. Stages 2–4: Resolve maker_intern only through the host catalog; otherwise parent is Maker. Intern cannot skip gates. Use red repro or TDD, write `RUN_DIR/diff.patch`, then run `npx ai-engineering-loop gate maker`.
41
+ 3. After Goal freeze, branch on mode. REPORT_ONLY: never edit repository files; write `RUN_DIR/report.json`, run `gate report`, and stop. ASSISTED: use the normal Maker. UNATTENDED: run `sandbox create --run <runId>`, run Maker only in the returned worktreePath, never edit the parent checkout, then run `sandbox capture --run <runId>`. Resolve maker_intern only through the host catalog; otherwise parent is Maker. Intern cannot skip gates. Use red repro or TDD. ASSISTED writes `RUN_DIR/diff.patch`; UNATTENDED capture writes it. Then run `npx ai-engineering-loop gate maker`.
40
42
  4. Stage 5: write `RUN_DIR/verification.json` with current git revision, gated diff hash, command, execution identity, times, exit code, stdout, timeout status, and test counts. Keep claimed-vs-reality.md. Run `npx ai-engineering-loop gate verification`; do not spawn DA unless it passes.
41
43
  5. Write artifacts, then spawn. Before Devil's Advocate:
42
44
  - Write `git diff` to a file (for example `.ai-engineering-loop/tasks/current.diff`).
@@ -44,10 +46,10 @@ Inherited invariants remain mandatory: read `core/grill-policy.md`, `policies/td
44
46
  - Put those paths in the child prompt. Do not paste Maker rationale.
45
47
  - Write `.ai-engineering-loop/tasks/claimed-vs-reality.md` if missing. Do not spawn DA without it.
46
48
  - If stopping mid-loop, write `.ai-engineering-loop/tasks/handoff.md` (`core/handoff-policy.md`).
47
- 6. Stage 6: Build `npx ai-engineering-loop context devil-advocate <files...>`, spawn DA with the pack path, and wait. Normalize its output into `RUN_DIR/findings.json` with runId and diffHash, then run `npx ai-engineering-loop gate review`.
48
- 7. Stage 7: Run `npx ai-engineering-loop escalation --json`, resolve the required tier through the host catalog, or escalate to the user. Build Judge context from goal-contract.json, verification.json, and findings.json only. Spawn Judge and wait. Write `RUN_DIR/verdict.json` with modelTier, then run `npx ai-engineering-loop gate judge`.
49
+ 6. Stage 6: Build `npx ai-engineering-loop context devil-advocate <files...>`, check `budget status`, spawn DA with the pack path, wait, and `budget record` actual usage. Normalize its output into `RUN_DIR/findings.json` with runId and diffHash, then run `npx ai-engineering-loop gate review`.
50
+ 7. Stage 7: Run `npx ai-engineering-loop escalation --json`, resolve the required tier through the host catalog, or escalate to the user. Build Judge context from goal-contract.json, verification.json, and findings.json only. Check `budget status`, spawn Judge, wait, and `budget record` actual usage. Write `RUN_DIR/verdict.json` with modelTier, then run `npx ai-engineering-loop gate judge`.
49
51
  8. ITERATE with iteration under 3: fix in the parent, re-verify, spawn a **new** Devil's Advocate.
50
- 9. After Judge PASS: run after_pass, then the configured Stage 8 adapter. PR/MR body includes `Steps to Reproduce & Testing (QA)`; bugfix placeholders must not stay empty. Preview remote payloads and never include context packs, raw logs, or credentials. Write `RUN_DIR/delivery.json`, then run `npx ai-engineering-loop gate delivery`.
52
+ 9. After Judge PASS: run after_pass, then the configured Stage 8 adapter. PR/MR body includes `Steps to Reproduce & Testing (QA)`; bugfix placeholders must not stay empty. Preview remote payloads and never include context packs, usage ledgers, raw logs, or credentials. In ASSISTED, wait for explicit human approval and put `humanApproved: true` in `RUN_DIR/delivery.json`; never infer it. Then run `npx ai-engineering-loop gate delivery`.
51
53
 
52
54
  ## Report header
53
55
 
@@ -50,11 +50,13 @@ Compact map (not a second OS): Specify (stages 0-1), Make (stages 2-4), Review (
50
50
 
51
51
  Run `npx ai-engineering-loop state --json` to get the current `runId` and use `.ai-engineering-loop/runs/<runId>/` as `RUN_DIR`. Never edit `state.json` or `current.json`.
52
52
 
53
+ Read `core/runtime-safety.md`. Before every model or subagent call, run `budget status --run <runId>`; immediately afterward run `budget record --input <actual> --output <actual> --model <id> --run <runId>` from provider-reported metadata. Never invent usage. Missing usage stops UNATTENDED and requires human direction in ASSISTED. `budget pause` is the kill switch.
54
+
53
55
  Inherited invariants remain mandatory: read `core/grill-policy.md`, `policies/tdd-policy.md`, and `.ai-engineering-loop/glossary.md`. On `adapter_type: dot`, grill includes blast radius: lifecycle sketch and load `task-impact-inquiry`. If the user prompt has no numbered AC, draft the contract, list a short menu and wait. Chat agreement is not freeze. AC is a failure table. One red test per AC row. Do not freeze sunny-path-only. Write claimed-vs-reality.md. Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality. Report Spec and Standards separately. DA prompt includes "at most 8 tool calls; read the diff file; skip css and generated files". Judge prompt includes "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff". `generate-workflow` still reads workflow.md and lessons.md; missing maker_intern means INVOCATION_UNAVAILABLE. Do not type a model name.
54
56
 
55
- 1. Stage 0: `npx ai-engineering-loop sync-hosts`, `status`, then `run` to create or resume the ledger. Read glossary, lessons, and workflow overlays. Required stages cannot be skipped.
57
+ 1. Stage 0: `npx ai-engineering-loop sync-hosts`, `status`, then `run [--mode report-only|assisted|unattended]` to create or resume the ledger. Run `state --json` and `budget status`. Read glossary, lessons, and workflow overlays. Required gates cannot be skipped.
56
58
  2. Stage 1: keep the human Goal Contract Markdown and write `RUN_DIR/goal-contract.json` with schemaVersion, runId, objective, numbered AC, evidenceRequired, and non-empty failureCases. Grill ambiguous decisions and business blast radius first. Run `npx ai-engineering-loop gate goal`; do not edit production code unless it passes.
57
- 3. Stages 2–4: Resolve `maker_intern` only through `grok models`; unknown means parent Maker. Intern cannot skip gates or spawn DA/Judge. Use red repro or TDD, write the exact review diff to `RUN_DIR/diff.patch`, then run `npx ai-engineering-loop gate maker`.
59
+ 3. After Goal freeze, branch on mode. REPORT_ONLY: never edit repository files; write `RUN_DIR/report.json`, run `gate report`, and stop. ASSISTED: use the normal Maker. UNATTENDED: run `sandbox create --run <runId>`, run Maker only in the returned worktreePath, never edit the parent checkout, then run `sandbox capture --run <runId>`. Resolve `maker_intern` only through `grok models`; unknown means parent Maker. Intern cannot skip gates or spawn DA/Judge. Use red repro or TDD. ASSISTED writes `RUN_DIR/diff.patch`; UNATTENDED capture writes it. Then run `npx ai-engineering-loop gate maker`.
58
60
  4. Stage 5: run verification and write `RUN_DIR/verification.json` with current git revision, gated diff hash, command, execution identity, times, exit code, stdout, timeout status, and test counts. Keep claimed-vs-reality.md. Run `npx ai-engineering-loop gate verification`; do not spawn DA unless it passes.
59
61
  5. Write artifacts to disk so children do not need parent chat:
60
62
  - Goal Contract path
@@ -62,10 +64,10 @@ Inherited invariants remain mandatory: read `core/grill-policy.md`, `policies/td
62
64
  - verification log (file)
63
65
  - `.ai-engineering-loop/tasks/claimed-vs-reality.md` (do not spawn DA without it)
64
66
  - If stopping mid-loop, `.ai-engineering-loop/tasks/handoff.md` (`core/handoff-policy.md`)
65
- 6. Stage 6: Build `npx ai-engineering-loop context devil-advocate <files...>`. Spawn Devil's Advocate with the pack path, `background: false`, `capability_mode: "execute"`, and no `resume_from`. Normalize its output into `RUN_DIR/findings.json` with runId and diffHash, then run `npx ai-engineering-loop gate review`.
66
- 7. Stage 7: Run `npx ai-engineering-loop escalation --json`; resolve `STRONG_MODEL` through `grok models`, or escalate to the user if unavailable. Build Judge context from only goal-contract.json, verification.json, and findings.json. Spawn a fresh sibling Judge and wait. Normalize `RUN_DIR/verdict.json` with modelTier, then run `npx ai-engineering-loop gate judge`.
67
+ 6. Stage 6: Build `npx ai-engineering-loop context devil-advocate <files...>`. Check `budget status`, spawn Devil's Advocate with the pack path, `background: false`, `capability_mode: "execute"`, and no `resume_from`; wait and `budget record` actual usage. Normalize its output into `RUN_DIR/findings.json` with runId and diffHash, then run `npx ai-engineering-loop gate review`.
68
+ 7. Stage 7: Run `npx ai-engineering-loop escalation --json`; resolve `STRONG_MODEL` through `grok models`, or escalate to the user if unavailable. Build Judge context from only goal-contract.json, verification.json, and findings.json. Check `budget status`, spawn a fresh sibling Judge and wait, then `budget record` actual usage. Normalize `RUN_DIR/verdict.json` with modelTier, then run `npx ai-engineering-loop gate judge`.
67
69
  8. If Judge says `ITERATE` and iteration < 3, Maker fixes in the parent, re-verify, spawn a **fresh** DA (new spawn, no resume).
68
- 9. After Judge PASS: run `after_pass`, then the configured Stage 8 adapter. PR/MR body includes `Steps to Reproduce & Testing (QA)`; bugfix placeholders must not stay empty. Preview remote payloads and never include context packs, raw logs, or credentials. Write `RUN_DIR/delivery.json`, then run `npx ai-engineering-loop gate delivery`.
70
+ 9. After Judge PASS: run `after_pass`, then the configured Stage 8 adapter. PR/MR body includes `Steps to Reproduce & Testing (QA)`; bugfix placeholders must not stay empty. Preview remote payloads and never include context packs, usage ledgers, raw logs, or credentials. In ASSISTED, wait for explicit human approval and put `humanApproved: true` in `RUN_DIR/delivery.json`; never infer it. Then run `npx ai-engineering-loop gate delivery`.
69
71
 
70
72
  After a proven Grok DA spawn, the report header must be:
71
73
 
package/README.md CHANGED
@@ -6,11 +6,11 @@
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
7
7
  [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/egagofur/ai-engineering-loop/pulls)
8
8
  [![AI Engineering](https://img.shields.io/badge/AI-Engineering%20Loop-orange.svg)](https://github.com/egagofur/ai-engineering-loop)
9
- [![Release](https://img.shields.io/badge/release-v1.1.0-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
9
+ [![Release](https://img.shields.io/badge/release-v1.2.1-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
10
10
 
11
11
  **A Reusable, Framework-Agnostic AI Engineering Operating System for Autonomous Coding Agents**
12
12
 
13
- *Featuring living project context, deterministic artifact gates, bounded secret-redacted context, cheap-model escalation, and dual-axis Judge evaluation.*
13
+ *Featuring graduated safety modes, token budgets, isolated Maker worktrees, deterministic artifact gates, bounded secret-redacted context, and cheap-model escalation.*
14
14
 
15
15
  [Overview](#overview--philosophy) • [Stage techniques](#stage-techniques) • [Runtime Capability Registry](#runtime-capability-registry--execution-modes) • [Verification Evidence](#verification-evidence-contract) • [CLI Commands](#cli-interface--commands) • [Grok CLI](#grok-cli-integration) • [Claude Code](#claude-code-integration) • [Antigravity](#antigravity-agent-integration) • [Lifecycle](#lifecycle-stages) • [Architecture](#architecture--5-layer-configuration) • [Project Profiles](#project-profiles) • [Repository Structure](#repository-structure) • [Reference Examples](#reference-examples) • [Contributing](#contributing)
16
16
 
@@ -72,6 +72,7 @@ The 8-stage loop stays one OS. These techniques sit **inside** existing stages (
72
72
  | 5 | **Claimed vs Reality** table before DA. Missing file or empty Reality blocks Devil's Advocate. "Seems green" is not Reality. | `core/verification-loop.md` |
73
73
  | 6–7 | Spec vs Standards reported separately. Standards BLOCKER/HIGH iterate only when `hardConvention` is true | `policies/finding-policy.md` |
74
74
  | 0–8 | Stateful run ledger and deterministic artifact transitions; model claims cannot advance a stage | `core/artifact-gates.md` |
75
+ | 0–8 | `REPORT_ONLY`, human-approved `ASSISTED`, opt-in `UNATTENDED`; actual token budgets, kill switch, and locked Maker worktrees | `core/runtime-safety.md` |
75
76
  | any | Mid-loop stop writes `.ai-engineering-loop/tasks/handoff.md` | `core/handoff-policy.md` |
76
77
  | any | **Compact map** (host guidance, not a second OS): Specify (stages 0-1), Make (stages 2-4), Review (stages 5-7), Deliver (stage 8). Keep the 8-stage numbers. Do not skip Goal Contract, verification, Devil's Advocate, or Judge. | host skills |
77
78
 
@@ -181,12 +182,28 @@ npx ai-engineering-loop refresh
181
182
 
182
183
  # Start or resume a stateful engineering run
183
184
  npx ai-engineering-loop run
185
+ npx ai-engineering-loop run --mode report-only "audit this repository"
184
186
 
185
187
  # Inspect the run ledger
186
188
  npx ai-engineering-loop state --json
187
189
 
190
+ # Inspect policy, opt into unattended, and operate the token kill switch
191
+ npx ai-engineering-loop policy show
192
+ npx ai-engineering-loop policy set --allow-unattended true
193
+ npx ai-engineering-loop budget status
194
+ npx ai-engineering-loop budget pause
195
+ npx ai-engineering-loop budget resume
196
+
197
+ # Record actual provider-reported usage after each model response
198
+ npx ai-engineering-loop budget record --input 1200 --output 300 --model provider/model-id
199
+
200
+ # Isolate unattended Maker, then capture only its diff
201
+ npx ai-engineering-loop sandbox create
202
+ npx ai-engineering-loop sandbox capture
203
+
188
204
  # Validate artifacts and advance stages
189
205
  npx ai-engineering-loop gate goal
206
+ npx ai-engineering-loop gate report
190
207
  npx ai-engineering-loop gate maker
191
208
  npx ai-engineering-loop gate verification
192
209
  npx ai-engineering-loop gate review
@@ -214,7 +231,7 @@ npx ai-engineering-loop generate-workflow
214
231
  npx ai-engineering-loop generate-workflow --write
215
232
  ```
216
233
 
217
- Every full run stores private local artifacts under `.ai-engineering-loop/runs/<run-id>/`. Markdown remains the human contract; JSON sidecars follow the shipped `schemas/` and make stage claims deterministic. See [`core/artifact-gates.md`](core/artifact-gates.md), [`SECURITY.md`](SECURITY.md), and [`SUPPORT.md`](SUPPORT.md).
234
+ Every full run stores private local artifacts under `.ai-engineering-loop/runs/<run-id>/`. Usage, worktrees, locks, context packs, and logs are Git-ignored. Markdown remains the human contract; JSON sidecars follow the shipped `schemas/` and make stage claims deterministic. `ASSISTED` is the default and requires explicit human delivery approval. `UNATTENDED` is disabled until a human enables it. See [`core/runtime-safety.md`](core/runtime-safety.md), [`core/artifact-gates.md`](core/artifact-gates.md), [`SECURITY.md`](SECURITY.md), and [`SUPPORT.md`](SUPPORT.md).
218
235
 
219
236
  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.
220
237
 
package/README.npm.md CHANGED
@@ -4,7 +4,7 @@
4
4
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
5
5
  [![GitHub](https://img.shields.io/badge/GitHub-Repository-black.svg)](https://github.com/egagofur/ai-engineering-loop)
6
6
 
7
- **A Reusable, Framework-Agnostic AI Engineering Operating System for Autonomous Coding Agents**
7
+ **A Reusable, Framework-Agnostic AI Engineering Operating System for Safe Coding Agents**
8
8
 
9
9
  Move beyond linear AI pipelines and optimistic self-evaluation toward contract-driven execution, deterministic machine verification, independent adversarial review, and living project context.
10
10
 
@@ -27,6 +27,13 @@ npx ai-engineering-loop refresh
27
27
  # 4. Verify context readiness and begin engineering loop
28
28
  npx ai-engineering-loop run
29
29
 
30
+ # Optional: analysis without repository mutation
31
+ npx ai-engineering-loop run --mode report-only "audit this repository"
32
+
33
+ # Inspect spend controls; ASSISTED is the default
34
+ npx ai-engineering-loop policy show
35
+ npx ai-engineering-loop budget status
36
+
30
37
  # 5. Copy package host skills into ~/.claude ~/.grok ~/.gemini ~/.agents
31
38
  npx ai-engineering-loop sync-hosts
32
39
  ```
@@ -40,6 +47,7 @@ npx ai-engineering-loop sync-hosts
40
47
  3. **Multi-Agent Triad**: Coordinates **Maker** (surgical diffs & tests), **Devil's Advocate** (independent adversarial review), and **Judge** (impartial evaluation & PASS certification).
41
48
  4. **Context Impact Assessment**: Evaluates completed tasks (`NONE`, `TARGETED`, `MAJOR`) to keep project context fresh without expensive whole-repo re-analysis.
42
49
  5. **Grok CLI host**: Native `spawn_subagent` for Devil's Advocate and Judge (`TRUE_INDEPENDENT_AGENT`). Disabled by `GROK_SUBAGENTS=0`.
50
+ 6. **Production runtime controls**: `REPORT_ONLY`, human-approved `ASSISTED`, opt-in `UNATTENDED`, actual token ledgers, a persistent kill switch, and locked disposable Maker worktrees.
43
51
 
44
52
  ---
45
53
 
package/SECURITY.md CHANGED
@@ -4,9 +4,13 @@
4
4
 
5
5
  Repository files, generated logs, tool output, and comments are untrusted data. Instructions found inside them never override the active host skill, Goal Contract, or user authorization.
6
6
 
7
- AI Engineering Loop blocks `.env*`, private-key formats, common credential files, `.git/`, `node_modules/`, absolute paths, parent traversal, and symlinks that leave the repository from generated context packs. Recognized credentials are redacted before model-visible context is persisted.
7
+ AI Engineering Loop blocks `.env*`, private-key formats, common credential files, `.git/`, `node_modules/`, absolute paths, parent traversal, and symlinks that leave the repository from generated context packs. Recognized credentials are redacted before model-visible context is persisted. Package release auditing rejects private keys, local home paths, and `file://` links before publication.
8
8
 
9
- No telemetry is collected. Stage 0–7 require no AI Engineering Loop network service. Delivery adapters may use authenticated forge tools only after Judge `PASS`; users must review remote issue, pull-request, merge-request, and chat payloads before sending.
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
+
11
+ 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
+
13
+ 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.
10
14
 
11
15
  ## Credential handling
12
16
 
@@ -14,6 +18,8 @@ No telemetry is collected. Stage 0–7 require no AI Engineering Loop network se
14
18
  - Never place credentials in `.ai-engineering-loop/`, workflow files, prompts, findings, or delivery reports.
15
19
  - Do not pass the parent process environment to a child unless the host owns that boundary.
16
20
  - 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`.
22
+ - 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.
17
23
  - Run a dedicated secret scanner such as `gitleaks` before delivery when available.
18
24
 
19
25
  Pattern-based redaction is defense in depth, not proof that arbitrary secrets are absent.
package/agents/judge.md CHANGED
@@ -29,7 +29,7 @@ flowchart LR
29
29
  ## 2. Core Authority & Rules of Engagement
30
30
 
31
31
  1. **Sole Authority on Completion**:
32
- - Only the Judge Agent can issue a `PASS` verdict certifying that the [Definition of Done](file:///Users/egagofur/Development/work/ai-engineering-loop/core/definition-of-done.md) has been met.
32
+ - Only the Judge Agent can issue a `PASS` verdict certifying that the [Definition of Done](../core/definition-of-done.md) has been met.
33
33
  2. **Neutral Evaluation**:
34
34
  - The Judge holds neither author bias (optimism) nor reviewer bias (pedantry).
35
35
  - The Judge independently verifies reviewer claims against actual repository facts before treating a finding as blocking.
@@ -48,13 +48,13 @@ flowchart LR
48
48
  - *If any deterministic check failed $\rightarrow$ immediately issue `ITERATE` with instructions to fix failing tests/types.*
49
49
 
50
50
  ### Step 2: Goal Contract Compliance Audit
51
- - Cross-reference every Acceptance Criterion (AC-1 through AC-N) from the [Goal Contract](file:///Users/egagofur/Development/work/ai-engineering-loop/core/goal-contract.md).
51
+ - Cross-reference every Acceptance Criterion (AC-1 through AC-N) from the [Goal Contract](../core/goal-contract.md).
52
52
  - Verify that automated tests exist that explicitly exercise and prove each criterion, including non-happy-path rows in the failure table.
53
53
  - A happy-path-only suite while the contract lists empty, boundary, sibling, or error rows is `ITERATE`.
54
54
  - Verify that no out-of-scope files were touched and technical constraints were respected.
55
55
 
56
56
  ### Step 3: Finding Triage & Evidence Verification
57
- - Review all findings produced by the [Devil's Advocate](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md).
57
+ - Review all findings produced by the [Devil's Advocate](./devil-advocate.md).
58
58
  - Validate the Author's triage:
59
59
  - If a finding is `VALID` and unresolved $\rightarrow$ cannot issue `PASS`.
60
60
  - If a finding is triaged as `INVALID`, confirm whether the Maker's defense is factually supported by codebase evidence.
@@ -62,13 +62,13 @@ flowchart LR
62
62
 
63
63
  ### Step 4: Iteration & Stagnation Check
64
64
  - Check current iteration count ($K$). If $K \ge \text{MAX\_ITERATIONS}$ and blocking issues remain $\rightarrow$ issue `ESCALATE`.
65
- - Check finding signatures across iterations using the [No-Progress Policy](file:///Users/egagofur/Development/work/ai-engineering-loop/policies/no-progress-policy.md). If progress is stalled $\rightarrow$ issue `ESCALATE`.
65
+ - Check finding signatures across iterations using the [No-Progress Policy](../policies/no-progress-policy.md). If progress is stalled $\rightarrow$ issue `ESCALATE`.
66
66
 
67
67
  ---
68
68
 
69
69
  ## 4. Output Contract
70
70
 
71
- The Judge Agent generates the official **Judge Evaluation Report** conforming to [Judge Policy](file:///Users/egagofur/Development/work/ai-engineering-loop/core/judge-policy.md).
71
+ The Judge Agent generates the official **Judge Evaluation Report** conforming to [Judge Policy](../core/judge-policy.md).
72
72
 
73
73
  The verdict must be one of:
74
74
  - **`PASS`**: All acceptance criteria proven, deterministic checks 100% green, 0 blocking findings, DoD fully satisfied. Safe to hand off to delivery adapters.
package/agents/maker.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## 1. Role & Identity
4
4
 
5
- The **Maker Agent** is the builder and execution engine of the AI Engineering Loop. It is responsible for translating the [Goal Contract](file:///Users/egagofur/Development/work/ai-engineering-loop/core/goal-contract.md) into clean, minimal, robust, and verifiable software implementations.
5
+ The **Maker Agent** is the builder and execution engine of the AI Engineering Loop. It is responsible for translating the [Goal Contract](../core/goal-contract.md) into clean, minimal, robust, and verifiable software implementations.
6
6
 
7
7
  ```mermaid
8
8
  flowchart LR
@@ -25,12 +25,12 @@ flowchart LR
25
25
  - Maintain strict adherence to existing codebase architecture, design system tokens, naming conventions, and file organization.
26
26
  - Avoid speculative abstractions, unsolicited refactoring, or touching out-of-scope files.
27
27
  - Leave zero dead code, zero stubs, zero empty catch blocks, and zero speculative TODOs.
28
- 3. **Test-Driven Engineering** ([TDD Policy](file:///Users/egagofur/Development/work/ai-engineering-loop/policies/tdd-policy.md)):
28
+ 3. **Test-Driven Engineering** ([TDD Policy](../policies/tdd-policy.md)):
29
29
  - Red before green at the Goal Contract's named seams only.
30
30
  - Tests observe public behavior, use glossary terms, and never assert implementation details.
31
31
  - Cover the AC slice in play: happy path, empty/omit, boundary, sibling/isolation, error/denied. One red test per AC row. Vertical slices, not all-tests-then-all-code.
32
32
  4. **Addressing Reviewer Findings**:
33
- - In subsequent iterations, ingest findings from the [Devil's Advocate](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md) and directives from the [Judge](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/judge.md).
33
+ - In subsequent iterations, ingest findings from the [Devil's Advocate](./devil-advocate.md) and directives from the [Judge](./judge.md).
34
34
  - Fix validated issues surgically.
35
35
  - Provide concrete evidence when pushing back against invalid reviewer findings.
36
36
 
@@ -38,7 +38,7 @@ flowchart LR
38
38
 
39
39
  ## 3. Strict Boundary Rules (What the Maker MUST NOT Do)
40
40
 
41
- 1. **CANNOT Declare Completion**: The Maker Agent must NEVER declare the overall task finished or ready to merge. Completion can only be certified by the [Judge Agent](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/judge.md).
41
+ 1. **CANNOT Declare Completion**: The Maker Agent must NEVER declare the overall task finished or ready to merge. Completion can only be certified by the [Judge Agent](./judge.md).
42
42
  2. **CANNOT Alter Acceptance Criteria**: The Maker Agent must never modify the Goal Contract's acceptance criteria to bypass failing tests.
43
43
  3. **CANNOT Suppress Verification Failures**: The Maker Agent is strictly prohibited from adding `@ts-ignore`, `eslint-disable`, mock overrides that mask bugs, or skipping broken tests to achieve green results.
44
44
  4. **CANNOT Make Unsolicited Renovations**: Even if surrounding legacy code is poorly written, the Maker must not refactor untouched modules unless explicitly included in the Goal Contract.
@@ -49,7 +49,7 @@ flowchart LR
49
49
  ## 4. Execution Workflow
50
50
 
51
51
  ### Step 1: Pre-Code Analysis
52
- - Follow [Root Cause Analysis](file:///Users/egagofur/Development/work/ai-engineering-loop/core/root-cause-analysis.md). For bugs: red repro before a production edit.
52
+ - Follow [Root Cause Analysis](../core/root-cause-analysis.md). For bugs: red repro before a production edit.
53
53
  - Map the data flow across layers.
54
54
  - Confirm seams from the Goal Contract. Use `.ai-engineering-loop/glossary.md` for names.
55
55
  - Check git history for recent changes to the affected files.
@@ -66,4 +66,4 @@ flowchart LR
66
66
  - Run build if applicable.
67
67
 
68
68
  ### Step 4: Submit to Adversarial Gate
69
- - Once all deterministic checks pass 100%, freeze the diff and hand off to the [Devil's Advocate Agent](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md).
69
+ - Once all deterministic checks pass 100%, freeze the diff and hand off to the [Devil's Advocate Agent](./devil-advocate.md).