ai-engineering-loop 2.1.0 → 2.3.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.
Files changed (108) hide show
  1. package/.agents/skills/ai-engineering-loop/SKILL.md +4 -4
  2. package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +2 -2
  3. package/.agents/skills/ai-engineering-loop/references/loop-goal.md +3 -3
  4. package/.agents/skills/ai-engineering-loop/references/loop-maker.md +1 -0
  5. package/.agents/skills/ai-engineering-loop/references/loop-review.md +3 -4
  6. package/.agents/skills/ai-engineering-loop/references/loop-verify.md +3 -3
  7. package/.claude/agents/judge.md +5 -2
  8. package/.grok/agents/judge.md +5 -2
  9. package/CHANGELOG.md +46 -0
  10. package/agents/maker.md +1 -1
  11. package/agents/shared/judge.body.md +5 -2
  12. package/bin/ai-engineering-loop.js +303 -77
  13. package/core/definition-of-done.md +2 -2
  14. package/core/escalation-policy.md +1 -1
  15. package/core/goal-contract.md +1 -1
  16. package/core/iteration-policy.md +2 -1
  17. package/core/judge-policy.md +10 -4
  18. package/core/local-workflow-studio.md +12 -7
  19. package/core/orchestration-model.md +8 -7
  20. package/core/repo-config-schema.md +2 -2
  21. package/core/runtime-safety.md +3 -3
  22. package/lib/auto-update.js +8 -14
  23. package/lib/claimed-vs-reality.js +2 -2
  24. package/lib/cli-args.js +3 -1
  25. package/lib/docs.js +1 -1
  26. package/lib/doctor.js +0 -6
  27. package/lib/escalation.js +1 -1
  28. package/lib/fsutil.js +88 -0
  29. package/lib/gates.js +69 -27
  30. package/lib/generate-workflow.js +0 -29
  31. package/lib/goal-runtime.js +3 -2
  32. package/lib/guard-hooks.js +26 -7
  33. package/lib/guard.js +100 -10
  34. package/lib/hosts/doctor.js +1 -5
  35. package/lib/impact-map.js +4 -9
  36. package/lib/jsonl-ledger.js +104 -0
  37. package/lib/learn.js +4 -9
  38. package/lib/loop-groups.js +0 -25
  39. package/lib/migrations.js +1 -5
  40. package/lib/no-progress.js +119 -0
  41. package/lib/node-evidence.js +873 -0
  42. package/lib/orchestration.js +5 -361
  43. package/lib/personal-workflow.js +1 -1
  44. package/lib/quick.js +152 -0
  45. package/lib/receipt.js +1 -5
  46. package/lib/recipe-builder.js +3 -35
  47. package/lib/recipe-graph.js +2 -63
  48. package/lib/recipe.js +2 -4
  49. package/lib/review-ingest.js +116 -0
  50. package/lib/run-abandon.js +2 -1
  51. package/lib/run-checkout.js +8 -13
  52. package/lib/run-compaction.js +4 -12
  53. package/lib/run-interactions.js +16 -71
  54. package/lib/run-lifecycle.js +25 -77
  55. package/lib/run-state.js +68 -17
  56. package/lib/run-watcher.js +11 -14
  57. package/lib/runtime-files.js +45 -1
  58. package/lib/safe-context.js +17 -6
  59. package/lib/sandbox.js +2 -1
  60. package/lib/smart-context.js +3 -13
  61. package/lib/spawn-command.js +94 -0
  62. package/lib/studio-layout.js +2 -8
  63. package/lib/studio-runtime.js +2 -1
  64. package/lib/studio-server.js +25 -5
  65. package/lib/tier.js +36 -10
  66. package/lib/user-state.js +2 -17
  67. package/lib/verification-lanes.js +115 -0
  68. package/lib/verification-recorder.js +110 -22
  69. package/lib/workflow-runtime.js +7 -4
  70. package/package.json +1 -2
  71. package/policies/review-budget.md +1 -1
  72. package/studio/app.js +734 -132
  73. package/studio/index.html +13 -4
  74. package/studio/styles.css +75 -20
  75. package/.claude/skills/ai-engineering-loop/SKILL.md +0 -62
  76. package/.claude/skills/ai-engineering-loop/references/loop-commands.md +0 -24
  77. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +0 -10
  78. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +0 -11
  79. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +0 -48
  80. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +0 -14
  81. package/.claude/skills/ai-engineering-loop/references/loop-review.md +0 -20
  82. package/.claude/skills/ai-engineering-loop/references/loop-risky.md +0 -9
  83. package/.claude/skills/ai-engineering-loop/references/loop-verify.md +0 -20
  84. package/.claude/skills/animate/RECIPES.md +0 -324
  85. package/.claude/skills/animate/SKILL.md +0 -207
  86. package/.claude/skills/animate-expo/RECIPES.md +0 -385
  87. package/.claude/skills/animate-expo/SKILL.md +0 -263
  88. package/.claude/skills/animation-vocabulary/SKILL.md +0 -181
  89. package/.claude/skills/apple-design/SKILL.md +0 -290
  90. package/.claude/skills/ask-sonner/API.md +0 -64
  91. package/.claude/skills/ask-sonner/SKILL.md +0 -88
  92. package/.claude/skills/backend-development/SKILL.md +0 -272
  93. package/.claude/skills/backend-development/references/api-design-guidelines.md +0 -95
  94. package/.claude/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  95. package/.claude/skills/backend-development/references/security-checklist.md +0 -60
  96. package/.claude/skills/emil-design-eng/SKILL.md +0 -674
  97. package/.claude/skills/find-animation-opportunities/SKILL.md +0 -140
  98. package/.claude/skills/improve-animations/AUDIT.md +0 -115
  99. package/.claude/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  100. package/.claude/skills/improve-animations/SKILL.md +0 -109
  101. package/.claude/skills/mobile-native/SKILL.md +0 -311
  102. package/.claude/skills/pick-ui-library/SKILL.md +0 -85
  103. package/.claude/skills/prototype/PICKER.md +0 -197
  104. package/.claude/skills/prototype/SKILL.md +0 -98
  105. package/.claude/skills/review-animations/SKILL.md +0 -120
  106. package/.claude/skills/review-animations/STANDARDS.md +0 -187
  107. package/.claude/skills/write-swift/SKILL.md +0 -396
  108. package/lib/intern-catalog.js +0 -53
@@ -46,7 +46,7 @@ flowchart LR
46
46
 
47
47
  ### Pillar 4: Adversarial Consensus
48
48
  - Independent [Devil's Advocate Review](../agents/devil-advocate.md) has been executed across all 6 core review domains.
49
- - **Zero Unresolved Blocking Findings**: No open `SEV-1 (Critical)` or `SEV-2 (High)` findings.
49
+ - **Zero Unresolved Blocking Findings**: No open VALID `BLOCKER` or `HIGH` findings (older docs call these SEV-1 and SEV-2).
50
50
  - **Evidence-Based Triage**: Every raised finding has been formally triaged with reproducible evidence as `VALID` (and resolved in code) or `INVALID` (with technical proof of why it is a false positive).
51
51
 
52
52
  ### Pillar 5: Judge Certified PASS
@@ -78,4 +78,4 @@ An engineering run MUST be rejected and flagged as `FAIL` or `BLOCKED` if any of
78
78
  1. **Unverified Claims**: The agent states that a test passed or feature works without providing command outputs or test code.
79
79
  2. **Post-Hoc Goal Shifting**: Modifying Acceptance Criteria to match buggy behavior instead of fixing the bug.
80
80
  3. **Suppressed Errors**: Adding `@ts-ignore`, `eslint-disable`, empty catch blocks, or skipping tests to force a green build.
81
- 4. **Unresolved Critical Findings**: Attempting to declare completion while a `SEV-1` or `SEV-2` finding from the Devil's Advocate remains open.
81
+ 4. **Unresolved Critical Findings**: Attempting to declare completion while a VALID `BLOCKER` or `HIGH` finding from the Devil's Advocate remains open.
@@ -27,7 +27,7 @@ flowchart TD
27
27
  ```
28
28
 
29
29
  ### Trigger 1: Maximum Iterations Reached
30
- - **Condition**: The system has completed `MAX_ITERATIONS` (default: 3) and unresolved blocking findings (`SEV-1` or `SEV-2`) still persist.
30
+ - **Condition**: The system has completed `MAX_ITERATIONS` (default: 3) and unresolved blocking findings (VALID `BLOCKER` or `HIGH`) still persist, or the loop stopped making progress (`NO_PROGRESS`: the same Maker diff or the same blocking findings as the previous iteration).
31
31
  - **Rationale**: Prolonged retries indicate either an incorrect fundamental strategy or a hidden architectural obstacle.
32
32
 
33
33
  ### Trigger 2: No-Progress / Stagnation Detected
@@ -66,7 +66,7 @@ Each AC is one row that can **fail**. Happy path alone is not a contract (`polic
66
66
  ## 9. Definition of Done (DoD)
67
67
  - [ ] All Acceptance Criteria (AC-1 through AC-N) verified with automated tests.
68
68
  - [ ] 100% pass on all deterministic verification commands (0 errors, 0 warnings where enforced).
69
- - [ ] Independent Devil's Advocate review completed with 0 unresolved blocking findings (SEV-1 / SEV-2).
69
+ - [ ] Independent Devil's Advocate review completed with 0 unresolved blocking findings (VALID BLOCKER / HIGH).
70
70
  - [ ] All review findings triaged with evidence (VALID, INVALID, UNCERTAIN).
71
71
  - [ ] Judge Agent issues a formal PASS verdict.
72
72
  ```
@@ -17,7 +17,8 @@ MAX_ALLOWED_CEILING = 5
17
17
  ```
18
18
 
19
19
  - **Default Cap**: An engineering run is allotted a maximum of **3 iterations** by default.
20
- - **Configurability**: Projects or workflows may configure `MAX_ITERATIONS` between 1 and 5 in their runtime configuration or Goal Contract.
20
+ - **Configurability**: A recipe sets the cap with `maxIterations` on the loop group whose decision node is the Judge (`recipes/default.json`). Gates clamp it to 1..5; runs without a recipe use 3.
21
+ - **No progress**: an ITERATE that repeats the previous iteration's Maker diff or its blocking findings becomes ESCALATE (`NO_PROGRESS`), recorded in `RUN_DIR/iterations.jsonl`.
21
22
  - **Hard Ceiling**: Under no circumstances may an agent loop beyond 5 iterations without human re-authorization.
22
23
 
23
24
  ---
@@ -37,8 +37,8 @@ The Judge renders decisions based strictly on **Validity + Severity**, then **re
37
37
  | **`VALID`** | **`BLOCKER`** | Any | **UPHELD (Blocking)** if `axis` is `spec` (or omitted), or `standards` with `hardConvention: true` | **`ITERATE`** — Maker must apply alternative diff & tests. |
38
38
  | **`VALID`** | **`HIGH`** | Any | **UPHELD (Blocking)** under the same axis rule | **`ITERATE`** — Maker must apply alternative diff & tests. |
39
39
  | **`VALID`** | **`BLOCKER` / `HIGH`** | Any | **TRADEOFF** if `axis` is `standards` and `hardConvention` is not true | **`PASS`** (if ACs met) — smell/convention judgement, not an AC breach. |
40
- | **`VALID`** | **`MEDIUM`** | `ACCEPTABLE` | **UPHELD (Tradeoff)** | **`PASS`** (if ACs met) — Logged as known tradeoff in MR. |
41
- | **`VALID`** | **`LOW`** | `ACCEPTABLE` | **UPHELD (Tradeoff)** | **`PASS`** (if ACs met) — Logged as known tradeoff in MR. |
40
+ | **`VALID`** | **`MEDIUM`** | Any | **UPHELD (Tradeoff)** | **`PASS`** (if ACs met) — Logged as known tradeoff in MR. |
41
+ | **`VALID`** | **`LOW`** | Any | **UPHELD (Tradeoff)** | **`PASS`** (if ACs met) — Logged as known tradeoff in MR. |
42
42
  | **`INVALID`** | Any | `WEAK` | **DISMISSED (Hallucination)** | **`PASS`** (if ACs met) — Discarded with evidence proof. |
43
43
 
44
44
  ---
@@ -69,9 +69,15 @@ The Judge renders decisions based strictly on **Validity + Severity**, then **re
69
69
 
70
70
  ---
71
71
 
72
+ ### Judge-added findings
73
+
74
+ The gate recomputes the verdict from the Finding Ledger plus `judgeFindings` in `verdict.json`. A Judge that blocks for a reason the ledger lacks (rows 3-5 above) adds that reason as a `judgeFindings` entry in the Finding Ledger shape (VALID BLOCKER/HIGH with evidence and `concreteAlternativeDiff`). The Judge cannot PASS what the ledger blocks, and the gate rejects a blocking verdict with no supporting finding.
75
+
76
+ ---
77
+
72
78
  ### Verdict 3: `ESCALATE`
73
79
  - **Conditions**:
74
- 1. Active iteration count $\ge \text{MAX\_ITERATIONS}$ (3).
75
- 2. Stagnation detected (identical finding signatures repeated across 2 iterations).
80
+ 1. Active iteration count $\ge \text{MAX\_ITERATIONS}$ (recipe `maxIterations`, default 3, at most 5).
81
+ 2. Stagnation detected (`NO_PROGRESS`): the same blocking finding signatures or the same Maker diff as the previous iteration. The gate enforces this.
76
82
  3. Contradictory architectural invariants that cannot be resolved within task scope.
77
83
  - **Action**: Halt the loop immediately and generate an actionable Human Escalation Report.
@@ -28,13 +28,14 @@ The first SSE frame is `hello` with `mode` (`watch` or `poll`), `root`, `current
28
28
 
29
29
  ## Live run view
30
30
 
31
- The default route is the live run view:
31
+ The default route is the live run view. It follows the open run over `GET /api/events`.
32
32
 
33
- - stage rail goal → maker → verify → review → judge → deliver, with the current stage and heartbeat age;
34
- - tier, mode, iteration, and budget;
35
- - compliance chips for guard warns/blocks, impact drift, and receipt verification;
36
- - pending questions, decisions, and approvals as the top banner;
37
- - a merged timeline of lifecycle, activity, and execution events.
33
+ - A progress rail for goal, maker, verify, review, judge, and deliver. Each stage shows its status and duration, and the running stage is highlighted.
34
+ - A question banner when the run is waiting on a person, with Answer in Studio.
35
+ - A current-step card with the node, iteration, running time, latest activity, evidence chips recorded so far, Open node details, and Start with AI Agent.
36
+ - Compliance and budget chips for mode, tier, iteration, guard warns and blocks, drift, receipt, and tokens. Tokens read `unknown` when the host reports no usage. A delivered run with no receipt reads “no receipt: run predates receipts”.
37
+ - Latest events with clock times, and a timeline grouped by step.
38
+ - The header shows when the run started and the heartbeat age. Every time is a `<time datetime>` with the exact local timestamp in a tooltip.
38
39
 
39
40
  The Goal Contract stays a side sheet of this view (draft, review, freeze, unfreeze). Start with AI Agent still copies a run-bound handoff into the clipboard.
40
41
 
@@ -58,7 +59,9 @@ Each existing node is one tile: a type icon, the node name, and exactly one stat
58
59
 
59
60
  ### Side panel
60
61
 
61
- Click a tile to open the side panel. The tabs are Input, Output, Evidence, and Timeline. Evidence uses the same artifact inspection as the rest of Studio: path traversal and symlinks are rejected, size is bounded, and recognized secrets are redacted.
62
+ Click a tile to open the side panel. The tabs are Overview, Output, Evidence, and Timeline. The Overview tab shows the node's upstream input, status, and timing as labeled chips: status, duration, finished, loop iteration, attempts, and the reason when the node failed or blocked. Output is a one-paragraph summary plus the run files. Evidence for a built-in gate is read from the run directory: the goal contract, diff stats and files touched, verification output and test counts, review findings, the judge verdict, the approver, and the delivery receipt. `nodes[id].artifact` stays authoritative when a custom node has one. Each read is confined to that run directory and checked against the sha256 in `state.json`. A mismatch shows “artifact changed”. Path traversal and symlinks are rejected, size is bounded, and recognized secrets are redacted. The Timeline tab lists only this node's events, grouped by iteration or attempt, with human labels and no numbering.
63
+
64
+ Times read as “5 min ago”, “2 days ago · Oct 16, 15:41”, or an absolute date after 7 days. The exact timestamp is in the tooltip and in `<time datetime>`. Durations read as `2m 20s` and `1h 04m`. A gate duration comes from `GATE_PASSED` or from `NODE_COMPLETED` in the lifecycle log.
62
65
 
63
66
  ### Tooltip
64
67
 
@@ -72,6 +75,8 @@ The minimap draws one rectangle per node. Zoom controls are zoom in (+), zoom ou
72
75
 
73
76
  The `?` sheet lists the shortcuts: `F` fit, `L` auto-layout, `+` and `-` zoom, `0` reset zoom, arrow keys between nodes, Enter to open the side panel, Esc to close it, and undo/redo for wiring edits. `:focus-visible` outlines the canvas controls.
74
77
 
78
+ On a trackpad, two-finger scroll pans the canvas on both axes, and pinch zooms around the cursor. Ctrl+wheel zooms the same way. Dragging empty canvas with the left button pans, which is also how macOS three-finger drag pans. A click on empty canvas clears the selection. Shift+drag draws a marquee selection. Middle-button drag and Space+drag still pan. The page and the canvas set `overscroll-behavior: none`, and the canvas wheel listener is non-passive, so a horizontal swipe does not navigate browser history. Scrolling inside the side panel scrolls the panel.
79
+
75
80
  ### Save bar
76
81
 
77
82
  The dirty-only save bar stays hidden while the wiring is clean. The first edge change shows the change count, Valid or Invalid, Discard, and Save. Save opens the confirm dialog before `POST /api/install`. A backbone-breaking edge shows the compiler's named error and disables Save. Every edit is checked with `POST /api/validate`.
@@ -22,7 +22,7 @@ The architecture explicitly distinguishes three separate stages:
22
22
 
23
23
  > [!IMPORTANT]
24
24
  > **Semantic Invariant**:
25
- > If `CONFIGURATION_SUPPORTED = true`, `INVOCATION_AVAILABLE = false`, and `EXECUTION_PROVEN = false`, the engine **must select `CONTEXT_ISOLATION_ONLY`**.
25
+ > If `CONFIGURATION_SUPPORTED = true`, `INVOCATION_AVAILABLE = false`, and `EXECUTION_PROVEN = false`, the review **must report `CONTEXT_ISOLATION_ONLY`**.
26
26
  > Configuration discovery is **never** conflated with execution capability.
27
27
 
28
28
  ---
@@ -62,7 +62,7 @@ The system categorically rejects the following as proof of independent LLM execu
62
62
  | **External Agent CLI** | `/Users/.../.local/bin/claude -p` | `UNAVAILABLE` | Unauthenticated: `Not logged in · Please run /login`. |
63
63
  | **Antigravity `new-conversation`** | `agentapi new-conversation` | `UNAVAILABLE` | Blocked by Language Server `project_id` authorization. |
64
64
  | **Antigravity `send-message`** | `agentapi send-message` | `IPC_MESSAGE_DISPATCH` | Succeeded (IPC message dispatch works, but is not an agent). |
65
- | **Artifact Barrier** | `buildReviewContextBarrier()` | `CONTEXT_ISOLATION_ONLY` | **Available & Verified**: 0% prompt bleed on disk. |
65
+ | **Artifact Barrier** | Clean-slate review artifacts | `CONTEXT_ISOLATION_ONLY` | **Available**: review reads only on-disk artifacts. |
66
66
 
67
67
  ### Architectural Conclusion:
68
68
  > *"Antigravity custom subagent configuration is supported/discoverable, but native subagent invocation is not exposed or executable from the current standalone agent runtime."*
@@ -80,7 +80,7 @@ The system categorically rejects the following as proof of independent LLM execu
80
80
  | **Headless process** | `grok -p` | `FRESH_PROCESS_AGENT` | Only after the process prints a model response. |
81
81
  | **Cavecrew reviewer** | `caveman:cavecrew-reviewer` | `GROK_COMPRESSED_REVIEW_PRESET` | **Rejected** as Devil's Advocate / Judge (wrong output schema). |
82
82
  | **Maker resume** | `spawn_subagent(resume_from=maker)` | tainted history | **Rejected**. DA and Judge must spawn fresh. |
83
- | **Artifact barrier** | `buildReviewContextBarrier()` | `CONTEXT_ISOLATION_ONLY` | Fallback when spawn is disabled. |
83
+ | **Artifact barrier** | Clean-slate review artifacts | `CONTEXT_ISOLATION_ONLY` | Fallback when spawn is disabled. |
84
84
 
85
85
  ### Architectural Conclusion:
86
86
  > *"Grok CLI spawn_subagent is a true independent child session. Select TRUE_INDEPENDENT_AGENT only after a child id and model response are captured without resume_from. Binary presence and agent markdown are never sufficient."*
@@ -91,7 +91,7 @@ See [docs/grok-cli-feasibility.md](../docs/grok-cli-feasibility.md).
91
91
 
92
92
  ## 5. Truthful Reporting Output
93
93
 
94
- When `CONTEXT_ISOLATION_ONLY` is selected, the report generator strictly produces:
94
+ When `CONTEXT_ISOLATION_ONLY` applies, the review report header is:
95
95
 
96
96
  ```text
97
97
  Execution Mode: CONTEXT_ISOLATION_ONLY
@@ -111,8 +111,9 @@ Review Method: Clean-Slate Artifact Isolation Barrier
111
111
 
112
112
  REPORT_ONLY (recipe `audit`) policy: when the host can invoke a native subagent, one fresh `devil-advocate` sibling reviews `report.json` before `gate report` (no Judge, no iteration loop); otherwise the same check runs in-session with a reason. `report.json` may carry a `review` block, which `gate report` validates.
113
113
 
114
- ### Strictly Forbidden Phrases during `CONTEXT_ISOLATION_ONLY`:
114
+ ### Strictly Forbidden Claims during `CONTEXT_ISOLATION_ONLY`:
115
+ Outside the fixed header lines above (which name `Native Subagent Invocation` as a capability), never claim that a separate agent reviewed the work:
115
116
  - *"independent agent review"*
116
- - *"subagent"*
117
+ - *"reviewed by a subagent"* (or any wording that says a subagent ran)
117
118
  - *"multi-agent review"*
118
- - *"independent reviewer"*
119
+ - *"independent reviewer"
@@ -18,7 +18,7 @@ The `.ai-engineering-loop/` directory serves as the **Living Project Context** f
18
18
  ├── lessons.md # Optional confirmed process lessons (not a chat log)
19
19
  ├── adrs/ # Architecture Decision Records from Stage 1 grill
20
20
  │ └── README.md
21
- └── tasks/ # Ephemeral: current.diff, handoff.md, verification logs
21
+ └── tasks/ # Ephemeral: handoff.md, verification logs
22
22
  ```
23
23
 
24
24
  ---
@@ -79,7 +79,7 @@ Maintains lightweight state for instant drift detection:
79
79
  - Durable why for load-bearing choices settled in grill. `refresh` does not overwrite existing ADRs.
80
80
 
81
81
  ### 9. `tasks/` — Run artifacts (optional)
82
- - `current.diff`, verification logs, `handoff.md`, `claimed-vs-reality.md`, `maker-brief.md`. Not required for `init` validity.
82
+ - Verification logs, `handoff.md`, `claimed-vs-reality.md`, `maker-brief.md`. Not required for `init` validity.
83
83
 
84
84
  ### 10. `workflow.md` — Loop overlay (optional)
85
85
  - Hooks around the 8-stage OS: `before_grill`, `after_freeze`, `after_pass`.
@@ -32,12 +32,12 @@ npx ai-engineering-loop hooks status | uninstall
32
32
 
33
33
  | Check | Rule |
34
34
  |---|---|
35
- | Edit / Write / MultiEdit / NotebookEdit | Blocked or warned when the file is outside the Run scope or matches `scope.deniedPaths`. `.ai-engineering-loop/` (Run artifacts) is always writable. A `REPORT_ONLY` Run may not edit at all. |
36
- | Bash | `rm` with recursive + force flags, `DROP TABLE/DATABASE/SCHEMA`, `TRUNCATE`, `git push --force` / `-f` / `--force-with-lease` / `+refspec`, `git reset --hard`, `git clean` with `-f` and `-d`. |
35
+ | Edit / Write / MultiEdit / NotebookEdit | Blocked or warned when the file is outside the Run scope or matches `scope.deniedPaths`. `.ai-engineering-loop/` (Run artifacts) is writable, except CLI-owned Run evidence (`runs/current.json` and, per Run, `state.json`, `plan.json`, `workflow-state.json`, `events.jsonl`, `lifecycle.jsonl`, `interactions.jsonl`, `verification*`, `sandbox-evidence.json`, `impact-map.json`, `impact-drift.json`, `guard-events.json`, `receipt.*`, `CANCELLED`): rule `run-evidence`. A `REPORT_ONLY` Run may not edit at all. |
36
+ | Bash | `rm` with recursive + force flags (also `\rm` and `"rm"`), `find -delete` / `find -exec rm`, `DROP TABLE/DATABASE/SCHEMA`, `TRUNCATE`, `git push --force` / `-f` / `--force-with-lease` / `+refspec`, `git reset --hard`, `git clean` with `-f` and `-d`, `git checkout -- <paths>` / `git checkout .` / `-f`, `git restore` (except `--staged` only), `git branch -D`. |
37
37
 
38
38
  **Scope** = the frozen Goal's optional `scope.allowedPaths` plus the confirmed blast-radius map (`impact confirm`, see `docs blast-radius-map`). `scope.deniedPaths` always applies. A Goal without `scope` and without a confirmed map has no path enforcement (backward compatible). Globs: `**` crosses directories, `*` and `?` stay inside one segment, a trailing `/` is a directory prefix; paths are repository-relative.
39
39
 
40
- **Decision** by Run mode: `ASSISTED` → `warn` (the Claude hook answers `ask`, so the human decides); `UNATTENDED` and `REPORT_ONLY` → `block` (`deny`; CLI exit code 2). With no active Run the policy `defaultMode` applies and nothing is recorded.
40
+ **Decision** by Run mode: `ASSISTED` → `warn` (the Claude hook answers `ask`, so the human decides); `UNATTENDED` and `REPORT_ONLY` → `block` (`deny`; CLI exit code 2). If `guard check --hook` itself fails (bad input, unreadable Run), it exits 2 so the host blocks the call, except in `ASSISTED` where it exits 1 and the human still approves. `hooks install` pins the hook to the installed version (`npx --yes ai-engineering-loop@<version>`) and re-pins hooks from older installs. With no active Run the policy `defaultMode` applies and nothing is recorded.
41
41
 
42
42
  **Evidence:** every warn and block is appended to `RUN_DIR/guard-events.json` (tool, rule ids, reasons, mode, redacted repository-relative target). `gate <name>` prints the counts and `--json` returns `guard: { warn, block, rules }`.
43
43
 
@@ -14,7 +14,14 @@
14
14
 
15
15
  const fs = require('fs');
16
16
  const path = require('path');
17
- const { execFileSync, spawn } = require('child_process');
17
+ const { execFileSync: rawExecFileSync, spawn } = require('child_process');
18
+ const { resolveSpawn } = require('./spawn-command.js');
19
+
20
+ // npm and the global ai-engineering-loop bin are .cmd shims on Windows.
21
+ function execFileSync(cmd, args, options) {
22
+ const target = resolveSpawn(cmd, args);
23
+ return rawExecFileSync(target.command, target.args, { ...options, ...target.options });
24
+ }
18
25
  const { homeDir, userStatePath, readJsonFile, writeJsonFile, readUserConfig, writeUserConfig } = require('./user-state.js');
19
26
  const { compareVersions, parseVersion } = require('./update-manager.js');
20
27
 
@@ -161,18 +168,6 @@ function decideUpdate({ current, distTags, policy, channel = 'latest', pin = nul
161
168
  return { action: 'apply', reason: `POLICY_${policy.toUpperCase()}`, target, bump };
162
169
  }
163
170
 
164
- function noticeText(current, decision) {
165
- const why = {
166
- MAJOR_NOTICE_ONLY: 'major release: read the changelog/migration notes, then run `ai-engineering-loop update apply --yes`',
167
- PINNED: 'outside your pin (`update policy --pin`)',
168
- PRERELEASE: 'prerelease; policy `all` is needed to apply it',
169
- POLICY_NOTIFY: 'run `ai-engineering-loop update apply --yes`, or choose `update policy minor`',
170
- POLICY_PATCH_ONLY: 'policy `patch` applies patch releases only',
171
- PROJECT_SCOPE_NOTIFY_ONLY: 'project install: update package.json yourself (`npm install ai-engineering-loop@latest --save-dev`)'
172
- }[decision.reason] || decision.reason;
173
- return `ai-engineering-loop ${decision.target} is available (current ${current}, ${decision.bump}): ${why}.`;
174
- }
175
-
176
171
  // ---- lock ----------------------------------------------------------------
177
172
 
178
173
  function acquireLock(home = homeDir(), { now = Date.now() } = {}) {
@@ -476,7 +471,6 @@ module.exports = {
476
471
  bumpType,
477
472
  matchesPin,
478
473
  decideUpdate,
479
- noticeText,
480
474
  acquireLock,
481
475
  readState,
482
476
  applyUpdate,
@@ -1,8 +1,8 @@
1
1
  'use strict';
2
2
 
3
- const crypto = require('crypto');
4
3
  const fs = require('fs');
5
4
  const path = require('path');
5
+ const { sha256 } = require('./fsutil.js');
6
6
  const { getCurrentRun, loadRun } = require('./run-state.js');
7
7
 
8
8
  function claimedVsRealityError(message, code = 'CLAIMED_VS_REALITY_FAILED') {
@@ -35,7 +35,7 @@ function frozenGoal(rootDir, run) {
35
35
  throw claimedVsRealityError('Frozen Goal Contract must be a regular file.', 'UNSAFE_GOAL_PATH');
36
36
  }
37
37
  const content = fs.readFileSync(goalPath);
38
- const hash = crypto.createHash('sha256').update(content).digest('hex');
38
+ const hash = sha256(content);
39
39
  if (hash !== artifact.sha256) {
40
40
  throw claimedVsRealityError('Frozen Goal Contract changed after its gate.', 'STALE_GOAL');
41
41
  }
package/lib/cli-args.js CHANGED
@@ -25,7 +25,9 @@ const WRITER_COMMANDS = Object.freeze({
25
25
  positionals: []
26
26
  },
27
27
  migrate: { flags: ['--json', '--dry-run'], valued: ['--from'], positionals: [] },
28
- verify: { flags: ['--json', '--serial', '--shell'], valued: ['--run', '--cmd', '--timeout-ms'], positionals: [] },
28
+ verify: { flags: ['--json', '--serial', '--shell', '--related', '--final', '--fresh'], valued: ['--run', '--cmd', '--timeout-ms'], positionals: [] },
29
+ quick: { flags: ['--json', '--serial', '--shell'], valued: ['--run', '--cmd', '--timeout-ms', '--mode'], positionals: null },
30
+ review: { flags: ['--json'], valued: ['--run', '--child-id', '--file'], positionals: ['ingest'] },
29
31
  learn: { flags: ['--json', '--dry-run', '--prune'], valued: ['--max-age-runs'], positionals: [] },
30
32
  guard: { flags: ['--json'], valued: ['--run', '--tool', '--input', '--path', '--command', '--hook'], positionals: ['check'] },
31
33
  hooks: { flags: ['--json'], valued: ['--host'], positionals: ['install', 'uninstall', 'status'] },
package/lib/docs.js CHANGED
@@ -8,7 +8,7 @@ const fs = require('fs');
8
8
  const path = require('path');
9
9
 
10
10
  // Loop stage references are generated host-neutral copies (issue #35).
11
- const DOC_ROOTS = Object.freeze(['core', 'policies', 'profiles', 'agents', 'adapters', '.claude/skills/ai-engineering-loop/references']);
11
+ const DOC_ROOTS = Object.freeze(['core', 'policies', 'profiles', 'agents', 'adapters', '.agents/skills/ai-engineering-loop/references']);
12
12
 
13
13
  function packageRoot() {
14
14
  return path.join(__dirname, '..');
package/lib/doctor.js CHANGED
@@ -9,15 +9,9 @@ const { listRecipes, loadRecipe, validateRecipe } = require('./recipe.js');
9
9
  const { checkAdapter } = require('./adapter-check.js');
10
10
 
11
11
  const REQUIRED_HOST_ASSETS = [
12
- '.claude/skills/ai-engineering-loop/SKILL.md',
13
12
  'adapters/project-onboarding/SKILL.md',
14
13
  'adapters/quality/skills/ael-code-simplifier/SKILL.md',
15
14
  'adapters/quality/skills/ael-receiving-code-review/SKILL.md',
16
- '.claude/skills/ai-engineering-loop/references/loop-review.md',
17
- '.claude/skills/backend-development/SKILL.md',
18
- '.claude/skills/emil-design-eng/SKILL.md',
19
- '.claude/skills/animate/SKILL.md',
20
- '.claude/skills/review-animations/SKILL.md',
21
15
  '.claude/agents/devil-advocate.md',
22
16
  '.claude/agents/judge.md',
23
17
  '.grok/agents/devil-advocate.md',
package/lib/escalation.js CHANGED
@@ -145,7 +145,7 @@ function assessRunEscalation(rootDir, { runId } = {}) {
145
145
  const assessment = assessEscalation({
146
146
  changedPaths: extractChangedPaths(diff),
147
147
  iteration: run.iteration,
148
- maxIterations: signals.maxIterations || 3,
148
+ maxIterations: signals.maxIterations || require('./no-progress.js').runMaxIterations(rootDir, run),
149
149
  schemaFailures: signals.schemaFailures || 0,
150
150
  hallucinatedCitations: signals.hallucinatedCitations || 0,
151
151
  reviewerJudgeDisagreement: signals.reviewerJudgeDisagreement === true,
package/lib/fsutil.js ADDED
@@ -0,0 +1,88 @@
1
+ 'use strict';
2
+
3
+ // Small file helpers shared across lib/: one atomic write, one sha256, one
4
+ // optional JSON read, one actor-id rule.
5
+
6
+ const crypto = require('crypto');
7
+ const fs = require('fs');
8
+ const path = require('path');
9
+
10
+ // Who asked, answered, approved, or acted: a short handle or an email.
11
+ const ACTOR_ID = /^[A-Za-z0-9@._-]{1,64}$/;
12
+
13
+ function sha256(content) {
14
+ return crypto.createHash('sha256').update(content).digest('hex');
15
+ }
16
+
17
+ // Missing or unparsable file -> fallback.
18
+ function readJsonOptional(filePath, fallback = null) {
19
+ try {
20
+ return JSON.parse(fs.readFileSync(filePath, 'utf8'));
21
+ } catch {
22
+ return fallback;
23
+ }
24
+ }
25
+
26
+ const RENAME_RETRY_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
27
+ const RENAME_ATTEMPTS = 10;
28
+
29
+ function sleepSync(ms) {
30
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
31
+ }
32
+
33
+ // Windows reports EPERM/EBUSY while an antivirus scanner, indexer, or a
34
+ // concurrent reader briefly holds the destination open. Retry with backoff.
35
+ function renameWithRetry(from, to) {
36
+ for (let attempt = 1; ; attempt += 1) {
37
+ try {
38
+ fs.renameSync(from, to);
39
+ return;
40
+ } catch (error) {
41
+ if (!RENAME_RETRY_CODES.has(error.code) || attempt >= RENAME_ATTEMPTS) throw error;
42
+ sleepSync(Math.min(20 * attempt, 200));
43
+ }
44
+ }
45
+ }
46
+
47
+ function jsonText(value) {
48
+ return `${JSON.stringify(value, null, 2)}\n`;
49
+ }
50
+
51
+ // Write to a temporary sibling, then rename, so readers never see a partial
52
+ // file. `mode` (e.g. 0o600) is enforced on the result; without it the file
53
+ // gets the process default permissions.
54
+ function atomicWrite(filePath, content, { mode, dirMode } = {}) {
55
+ fs.mkdirSync(path.dirname(filePath), dirMode ? { recursive: true, mode: dirMode } : { recursive: true });
56
+ const temporary = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
57
+ try {
58
+ fs.writeFileSync(temporary, content, mode ? { mode } : undefined);
59
+ renameWithRetry(temporary, filePath);
60
+ if (mode) fs.chmodSync(filePath, mode);
61
+ } finally {
62
+ try {
63
+ fs.unlinkSync(temporary);
64
+ } catch {
65
+ // Rename succeeded or no temporary file was written.
66
+ }
67
+ }
68
+ }
69
+
70
+ function writePrivateFile(filePath, content, options = {}) {
71
+ atomicWrite(filePath, content, { ...options, mode: 0o600 });
72
+ }
73
+
74
+ function writePrivateJson(filePath, value, options = {}) {
75
+ writePrivateFile(filePath, jsonText(value), options);
76
+ }
77
+
78
+ module.exports = {
79
+ ACTOR_ID,
80
+ renameWithRetry,
81
+ sleepSync,
82
+ sha256,
83
+ readJsonOptional,
84
+ jsonText,
85
+ atomicWrite,
86
+ writePrivateFile,
87
+ writePrivateJson
88
+ };
package/lib/gates.js CHANGED
@@ -1,8 +1,8 @@
1
1
  'use strict';
2
2
 
3
- const crypto = require('crypto');
4
3
  const fs = require('fs');
5
4
  const path = require('path');
5
+ const { sha256: hashContent } = require('./fsutil.js');
6
6
  const {
7
7
  validateVerificationEvidence,
8
8
  validateFindingLedger,
@@ -52,6 +52,9 @@ const {
52
52
  } = require('./escalation.js');
53
53
  const { raiseTierFromDiff } = require('./tier.js');
54
54
  const { readyForDa } = require('./claimed-vs-reality.js');
55
+ const { runMaxIterations, detectNoProgress, recordIteration } = require('./no-progress.js');
56
+ const { finalVerificationStatus } = require('./verification-lanes.js');
57
+ const { checkLedgerBinding } = require('./review-ingest.js');
55
58
 
56
59
  const CLAIMED_VS_REALITY_PATH = '.ai-engineering-loop/tasks/claimed-vs-reality.md';
57
60
 
@@ -87,10 +90,6 @@ function readJsonArtifact(rootDir, runId, fileName) {
87
90
  return { filePath, value };
88
91
  }
89
92
 
90
- function hashContent(content) {
91
- return crypto.createHash('sha256').update(content).digest('hex');
92
- }
93
-
94
93
  function hashFile(filePath) {
95
94
  try {
96
95
  return hashContent(fs.readFileSync(filePath));
@@ -284,7 +283,7 @@ function judgeRequirement(rootDir, run) {
284
283
  }
285
284
  const serious = findings.filter((f) => f && (f.severity === 'BLOCKER' || f.severity === 'HIGH'));
286
285
  if (serious.length) reasons.push(`BLOCKER_OR_HIGH_FINDINGS: ${serious.map((f) => f.id).join(', ')}`);
287
- if (run.iteration >= 3) reasons.push('ITERATION_CEILING');
286
+ if (run.iteration >= runMaxIterations(rootDir, run)) reasons.push('ITERATION_CEILING');
288
287
  let escalation = null;
289
288
  try {
290
289
  escalation = assessRunEscalation(rootDir, { runId: run.runId });
@@ -298,6 +297,49 @@ function judgeRequirement(rootDir, run) {
298
297
  return { required: reasons.length > 0, tier, reasons };
299
298
  }
300
299
 
300
+ // The verdict the evidence supports. The Judge may add evidence-backed
301
+ // blocking findings (judgeFindings) that the Maker's ledger lacks; it can
302
+ // never PASS what the deterministic rules block. An ITERATE that repeats the
303
+ // previous iteration (same diff or same blocking findings) escalates.
304
+ function expectedJudgeVerdict(rootDir, run, { judgeFindings = [] } = {}) {
305
+ const verification = readJsonArtifact(rootDir, run.runId, GATE_FILES.verification).value;
306
+ const findings = readJsonArtifact(rootDir, run.runId, GATE_FILES.review).value;
307
+ const goalContract = readJsonArtifact(rootDir, run.runId, GATE_FILES.goal).value;
308
+ const ledger = judgeFindings.length
309
+ ? { ...findings, findings: [...(findings.findings || []), ...judgeFindings] }
310
+ : findings;
311
+ const expected = computeJudgeVerdict({
312
+ goalContract,
313
+ verificationEvidence: verificationForJudge(verification),
314
+ findingLedger: ledger,
315
+ activeIteration: run.iteration,
316
+ maxIterations: runMaxIterations(rootDir, run)
317
+ });
318
+ if (expected.verdict === 'ITERATE') {
319
+ const noProgress = detectNoProgress(rootDir, run, {
320
+ diffHash: run.artifacts?.diff?.sha256,
321
+ blockingFindings: expected.blockingFindings || []
322
+ });
323
+ if (noProgress) {
324
+ return {
325
+ ...expected,
326
+ verdict: 'ESCALATE',
327
+ reason: noProgress,
328
+ action: 'Human escalation: the loop stopped making progress.'
329
+ };
330
+ }
331
+ }
332
+ return expected;
333
+ }
334
+
335
+ function validateJudgeFindings(value) {
336
+ if (value == null) return [];
337
+ if (!Array.isArray(value)) throw gateError('Judge gate failed', ['judgeFindings must be an array']);
338
+ const check = validateFindingLedger({ findings: value });
339
+ if (!check.valid) throw gateError('Judge gate failed', [`judgeFindings: ${check.reason}`]);
340
+ return value.map((finding) => ({ ...finding, source: 'judge' }));
341
+ }
342
+
301
343
  function writeDeterministicVerdictIfEligible(rootDir, run) {
302
344
  const filePath = artifactPath(rootDir, run.runId, GATE_FILES.judge);
303
345
  if (fs.existsSync(filePath)) return false;
@@ -307,16 +349,7 @@ function writeDeterministicVerdictIfEligible(rootDir, run) {
307
349
  if (requirement.required) {
308
350
  throw gateError(`Judge subagent required for tier ${tier}; write ${GATE_FILES.judge} from its verdict`, requirement.reasons);
309
351
  }
310
- const verification = readJsonArtifact(rootDir, run.runId, GATE_FILES.verification).value;
311
- const findings = readJsonArtifact(rootDir, run.runId, GATE_FILES.review).value;
312
- const goalContract = readJsonArtifact(rootDir, run.runId, GATE_FILES.goal).value;
313
- const expected = computeJudgeVerdict({
314
- goalContract,
315
- verificationEvidence: verificationForJudge(verification),
316
- findingLedger: findings,
317
- activeIteration: run.iteration,
318
- maxIterations: 3
319
- });
352
+ const expected = expectedJudgeVerdict(rootDir, run);
320
353
  fs.writeFileSync(filePath, `${JSON.stringify({
321
354
  schemaVersion: 1,
322
355
  runId: run.runId,
@@ -458,6 +491,15 @@ function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
458
491
  }
459
492
  const check = validateFindingLedger(value);
460
493
  if (!check.valid) throw gateError('Review gate failed', [check.reason]);
494
+ const binding = checkLedgerBinding(rootDir, run, value);
495
+ if (binding.errors.length) {
496
+ throw gateError('Finding Ledger does not match the reviewer output (LEDGER_TAMPERED)', binding.errors);
497
+ }
498
+ if (binding.binding === 'UNBOUND' && mode === RUN_MODES.UNATTENDED) {
499
+ throw gateError('UNATTENDED review needs a ledger bound to the reviewer output', [
500
+ 'Run `review ingest --run <id> --child-id <id> --file <child-output>` instead of writing findings.json'
501
+ ]);
502
+ }
461
503
  return transitionRun(rootDir, run.runId, RUN_STATES.REVIEWED, {
462
504
  gate,
463
505
  artifacts: { findings: descriptor(rootDir, filePath) }
@@ -482,19 +524,16 @@ function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
482
524
  } catch (cause) {
483
525
  throw gateError(cause.message, [cause.code]);
484
526
  }
485
- const verification = readJsonArtifact(rootDir, run.runId, GATE_FILES.verification).value;
486
- const findings = readJsonArtifact(rootDir, run.runId, GATE_FILES.review).value;
487
- const goalContract = readJsonArtifact(rootDir, run.runId, GATE_FILES.goal).value;
488
- const expected = computeJudgeVerdict({
489
- goalContract,
490
- verificationEvidence: verificationForJudge(verification),
491
- findingLedger: findings,
492
- activeIteration: run.iteration,
493
- maxIterations: 3
494
- });
527
+ const judgeFindings = validateJudgeFindings(value.judgeFindings);
528
+ const expected = expectedJudgeVerdict(rootDir, run, { judgeFindings });
495
529
  if (value.verdict !== expected.verdict) {
496
- throw gateError(`Judge verdict is unsupported: expected ${expected.verdict}, received ${value.verdict}`);
530
+ throw gateError(`Judge verdict is unsupported: expected ${expected.verdict}, received ${value.verdict}`, [expected.reason]);
497
531
  }
532
+ recordIteration(rootDir, run, {
533
+ verdict: expected.verdict,
534
+ diffHash: run.artifacts?.diff?.sha256,
535
+ blockingFindings: expected.blockingFindings || []
536
+ });
498
537
  const artifacts = { verdict: descriptor(rootDir, filePath) };
499
538
  if (expected.verdict === 'PASS') {
500
539
  return transitionRun(rootDir, run.runId, RUN_STATES.JUDGED_PASS, { gate, artifacts });
@@ -527,6 +566,8 @@ function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
527
566
  if (mode === RUN_MODES.ASSISTED && value.humanApproved !== true) {
528
567
  deliveryErrors.push('humanApproved must be true for ASSISTED delivery');
529
568
  }
569
+ const finalCheck = finalVerificationStatus(rootDir, run);
570
+ if (!finalCheck.satisfied) deliveryErrors.push(`Full verification required before delivery: ${finalCheck.reason}`);
530
571
  if (deliveryErrors.length) throw gateError('Delivery gate failed', deliveryErrors);
531
572
  return transitionRun(rootDir, run.runId, RUN_STATES.DELIVERED, {
532
573
  gate,
@@ -545,5 +586,6 @@ module.exports = {
545
586
  validateVerificationBundle,
546
587
  validateVerdictDocument,
547
588
  judgeRequirement,
589
+ expectedJudgeVerdict,
548
590
  applyGate
549
591
  };
@@ -41,17 +41,6 @@ function assertNoRequiredSkip(skips) {
41
41
  }
42
42
  }
43
43
 
44
- function routeDurableNote(kind) {
45
- const map = {
46
- term: 'glossary.md',
47
- process: 'lessons.md',
48
- lesson: 'lessons.md',
49
- convention: 'conventions.md',
50
- adr: 'adrs/'
51
- };
52
- return map[kind] || 'lessons.md';
53
- }
54
-
55
44
  function normalizeMakerIntern(raw) {
56
45
  const s = String(raw || '').trim();
57
46
  if (!s || /^none$/i.test(s)) return DEFAULT_MAKER_INTERN;
@@ -143,22 +132,6 @@ function parseWorkflowMarkdown(text) {
143
132
  };
144
133
  }
145
134
 
146
- function parseWorkflowFile(rootDir) {
147
- const dest = path.join(rootDir, '.ai-engineering-loop', 'workflow.md');
148
- try {
149
- const text = fs.readFileSync(dest, 'utf8');
150
- return parseWorkflowMarkdown(text);
151
- } catch {
152
- return {
153
- missing: true,
154
- required: REQUIRED_STAGES.slice(),
155
- hooks: { ...DEFAULT_HOOKS },
156
- makerIntern: DEFAULT_MAKER_INTERN,
157
- optionalSkips: []
158
- };
159
- }
160
- }
161
-
162
135
  function lessonsAreFilled(text) {
163
136
  if (!text || !text.trim()) return false;
164
137
  return /\| 20\d{2}-/.test(text);
@@ -223,11 +196,9 @@ module.exports = {
223
196
  DEFAULT_MAKER_INTERN,
224
197
  assertNoRequiredSkip,
225
198
  normalizeMakerIntern,
226
- routeDurableNote,
227
199
  workflowMarkdown,
228
200
  lessonsMarkdown,
229
201
  parseWorkflowMarkdown,
230
- parseWorkflowFile,
231
202
  writeWorkflowOverlay,
232
203
  formatGenerateWorkflowReport,
233
204
  parseWriteArg