ai-engineering-loop 1.0.19 → 1.1.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 (94) hide show
  1. package/.agents/workflows/ai-engineering-loop.md +7 -3
  2. package/.claude/skills/ai-engineering-loop/SKILL.md +13 -7
  3. package/.gemini/skills/ai-engineering-loop/SKILL.md +13 -7
  4. package/.grok/skills/ai-engineering-loop/SKILL.md +13 -7
  5. package/README.md +26 -3
  6. package/SECURITY.md +23 -0
  7. package/SUPPORT.md +28 -0
  8. package/adapters/dot/README.md +12 -8
  9. package/adapters/dot/gitlab.md +29 -5
  10. package/adapters/dot/multi-branch.md +47 -68
  11. package/adapters/dot/skills/dot-dev-workflow/SKILL.md +6 -8
  12. package/adapters/github/pull-request.md +15 -0
  13. package/adapters/gitlab/merge-request.md +15 -0
  14. package/adapters/standard/README.md +1 -0
  15. package/bin/ai-engineering-loop.js +255 -3
  16. package/core/artifact-gates.md +49 -0
  17. package/evals/README.md +35 -0
  18. package/evals/cases/01-stale-verification.json +17 -0
  19. package/evals/cases/02-vague-verification.json +16 -0
  20. package/evals/cases/03-missing-ac-evidence.json +17 -0
  21. package/evals/cases/04-hallucinated-citation.json +17 -0
  22. package/evals/cases/05-prompt-injection.json +17 -0
  23. package/evals/cases/06-source-secret.json +16 -0
  24. package/evals/cases/07-log-secret.json +16 -0
  25. package/evals/cases/08-symlink-escape.json +16 -0
  26. package/evals/cases/09-authorization-bypass.json +16 -0
  27. package/evals/cases/10-payment-idempotency.json +16 -0
  28. package/evals/cases/11-concurrent-update.json +16 -0
  29. package/evals/cases/12-swallowed-error.json +16 -0
  30. package/evals/cases/13-happy-path-only.json +17 -0
  31. package/evals/cases/14-invalid-finding-axis.json +16 -0
  32. package/evals/cases/15-blocker-without-alternative.json +16 -0
  33. package/evals/cases/16-unsupported-pass.json +17 -0
  34. package/evals/cases/17-soft-standard.json +16 -0
  35. package/evals/cases/18-iteration-ceiling.json +17 -0
  36. package/evals/cases/19-safe-documentation-change.json +17 -0
  37. package/evals/cases/20-valid-boundary-feature.json +18 -0
  38. package/lib/doctor.js +98 -0
  39. package/lib/escalation.js +192 -0
  40. package/lib/evaluation.js +137 -0
  41. package/lib/gates.js +315 -0
  42. package/lib/orchestration.js +5 -1
  43. package/lib/run-state.js +221 -0
  44. package/lib/safe-context.js +191 -0
  45. package/lib/sync-hosts.js +6 -5
  46. package/package.json +12 -9
  47. package/policies/model-escalation.md +41 -0
  48. package/schemas/delivery.schema.json +14 -0
  49. package/schemas/finding-ledger.schema.json +27 -0
  50. package/schemas/goal-contract.schema.json +32 -0
  51. package/schemas/verdict.schema.json +17 -0
  52. package/schemas/verification.schema.json +32 -0
  53. package/docs/antigravity-feasibility.md +0 -92
  54. package/docs/claude-code-feasibility.md +0 -80
  55. package/docs/grok-cli-feasibility.md +0 -99
  56. package/docs/migration-plan.md +0 -70
  57. package/examples/backend-api/payment-idempotency/README.md +0 -33
  58. package/examples/backend-api/payment-idempotency/goal-contract.md +0 -33
  59. package/examples/backend-api/payment-idempotency/judge-verdict.md +0 -28
  60. package/examples/backend-api/payment-idempotency/review-findings.md +0 -50
  61. package/examples/dot/status-display/README.md +0 -23
  62. package/examples/dot/status-display/delivery-report.md +0 -41
  63. package/examples/dot/status-display/goal-contract.md +0 -46
  64. package/examples/dot/status-display/judge-verdict.md +0 -44
  65. package/examples/dot/status-display/review-findings.md +0 -63
  66. package/examples/initialization/README.md +0 -19
  67. package/examples/initialization/discovery-trace.md +0 -63
  68. package/examples/initialization/generated-context.md +0 -110
  69. package/examples/mobile-app/offline-sync-queue/README.md +0 -33
  70. package/examples/mobile-app/offline-sync-queue/goal-contract.md +0 -32
  71. package/examples/mobile-app/offline-sync-queue/judge-verdict.md +0 -27
  72. package/examples/mobile-app/offline-sync-queue/review-findings.md +0 -30
  73. package/scripts/init.sh +0 -106
  74. package/templates/repo-config/adapter.md +0 -11
  75. package/templates/repo-config/adr-readme.md +0 -33
  76. package/templates/repo-config/architecture.md +0 -15
  77. package/templates/repo-config/claude-permissions.json +0 -10
  78. package/templates/repo-config/config.md +0 -11
  79. package/templates/repo-config/conventions.md +0 -16
  80. package/templates/repo-config/glossary.md +0 -18
  81. package/templates/repo-config/lessons.md +0 -8
  82. package/templates/repo-config/verification.md +0 -13
  83. package/templates/repo-config/workflow.md +0 -25
  84. package/tests/capability-selection.test.js +0 -207
  85. package/tests/claimed-vs-reality.test.js +0 -27
  86. package/tests/generate-adapter.test.js +0 -80
  87. package/tests/generate-workflow.test.js +0 -180
  88. package/tests/grok-runtime.test.js +0 -201
  89. package/tests/intern-catalog.test.js +0 -72
  90. package/tests/living-context.test.js +0 -61
  91. package/tests/no-company-leak.test.js +0 -82
  92. package/tests/orchestration.test.js +0 -368
  93. package/tests/skill-host-compat.test.js +0 -406
  94. package/tests/sync-hosts.test.js +0 -168
@@ -7,14 +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`.
11
+
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
+
10
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`.
11
15
 
12
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.
13
17
 
14
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.
15
- 6. Devil's Advocate prompt: diff file path, name-only list, Goal Contract path, verification log path, conventions.md path, and "at most 8 tool calls; read the diff file; skip css and generated files". Report Spec and Standards axes separately.
16
- 7. Judge prompt: Goal Contract path, verification evidence path, Finding Ledger, and "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
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`.
17
21
 
18
22
  If no subagent tool exists, run the same budgets in this session as CONTEXT_ISOLATION_ONLY. Do not claim independent agent execution.
19
23
 
20
- 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 (`grok models` or `/models` if that command exists); do not type a model name. Stage 0: `npx ai-engineering-loop sync-hosts` then `npx ai-engineering-loop 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 Goal Contract, verification, Devil's Advocate, or Judge even if workflow.md asks. If workflow.md is missing, run the default 8-stage loop (no extra hooks). If sync-hosts copied files, tell the user a new session is needed for updated skill text; keep going with this session. After Judge PASS: run the `after_pass` hook if it is not `none`. Stage 8: load `adapters/<adapter_type>/`. If adapter.md is missing, run `generate-adapter` (grill). Do not invent a company pipeline. 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, 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.
@@ -35,20 +35,26 @@ Compact map (not a second OS): Specify (stages 0-1), Make (stages 2-4), Review (
35
35
 
36
36
  Parent session is Maker plus orchestrator. Spawn Devil's Advocate and Judge as **siblings**, not nested.
37
37
 
38
- 1. Stage 0: `npx ai-engineering-loop sync-hosts` then `npx ai-engineering-loop status` (init or refresh if missing or stale). 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 (no extra hooks). If sync-hosts copied files, tell the user a new session is needed for updated skill text; keep going with this session.
39
- 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. Skip grill if the contract is already frozen or the user waived it. 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. Chat agreement is not freeze: every user-visible decision must be a numbered AC in the Goal Contract file. Freeze before any production edit. Name test seams. Use glossary terms. AC is a failure table (happy, empty/omit, boundary, sibling, error). One red test per AC row. Do not freeze sunny-path-only. 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.
40
- 3. 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. Do not add a model key or HTTP client. Intern cannot skip verification, Devil's Advocate, or Judge. Bugs: red repro first (`core/root-cause-analysis.md`). Features: TDD at named seams (`policies/tdd-policy.md`): one red test per AC row. Surgical diff.
41
- 4. Stage 5: run commands from `.ai-engineering-loop/verification.md`. Keep command, exit code, stdout, test counts. Vague "seems green" is invalid. 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.
38
+ ## Deterministic artifact gates (mandatory)
39
+
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
+
42
+ 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
+
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.
45
+ 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`.
47
+ 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.
42
48
  5. Write artifacts, then spawn. Before Devil's Advocate:
43
49
  - Write `git diff` to a file (for example `.ai-engineering-loop/tasks/current.diff`).
44
50
  - Write changed paths (`git diff --name-only`) into the Task prompt as a short list.
45
51
  - Put those paths in the child prompt. Do not paste Maker rationale.
46
52
  - Write `.ai-engineering-loop/tasks/claimed-vs-reality.md` if missing. Do not spawn DA without it.
47
53
  - If stopping mid-loop, write `.ai-engineering-loop/tasks/handoff.md` (`core/handoff-policy.md`).
48
- 6. Stage 6: Task `subagent_type: devil-advocate`. Use `general-purpose` only if that type is rejected. If the Task schema includes `run_in_background`, set it false. Then wait for Task to return. Do not start Judge or more Maker work until the Finding Ledger is back. Prompt: diff file path, name-only list, Goal Contract path, verification log path, conventions.md path, and "at most 8 tool calls; read the diff file; skip css and generated files". Report Spec and Standards axes separately.
49
- 7. Stage 7: Task `subagent_type: judge` the same way (wait, no background). Use `general-purpose` only if `judge` is rejected. Prompt: Goal Contract path, verification evidence path, Finding Ledger, and "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
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.
50
56
  8. ITERATE with iteration under 3: fix in the parent, re-verify, spawn a **new** Devil's Advocate (do not resume the previous child).
51
- 9. After Judge PASS: run the `after_pass` hook from workflow.md if it is not `none`. Then Stage 8: delivery from `.ai-engineering-loop/adapter.md`. Load shipped spec `adapters/<adapter_type>/` (`standard`, `github`, `gitlab`, `dot`). If adapter.md is missing or the type is unknown, run `generate-adapter` (grill). Do not invent a company pipeline. When the user confirms a process lesson, append one row to `lessons.md` (not a chat dump). Terms go to glossary.md.
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.
52
58
 
53
59
  ## Report header
54
60
 
@@ -28,20 +28,26 @@ Canonical mode ids: `TRUE_INDEPENDENT_AGENT`, `ISOLATED_AGENT_INSTANCE`, `FRESH_
28
28
 
29
29
  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.
30
30
 
31
- 1. Stage 0: `npx ai-engineering-loop sync-hosts` then `npx ai-engineering-loop status` (init or refresh if missing or stale). 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 (no extra hooks). If sync-hosts copied files, tell the user a new session is needed for updated skill text; keep going with this session.
32
- 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. Skip grill if the contract is already frozen or the user waived it. 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. Chat agreement is not freeze: every user-visible decision must be a numbered AC in the Goal Contract file. Freeze before any production edit. Name test seams. Use glossary terms. AC is a failure table (happy, empty/omit, boundary, sibling, error). One red test per AC row. Do not freeze sunny-path-only. 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.
33
- 3. 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. Do not add HTTP clients or API keys. Intern cannot skip verification, Devil's Advocate, or Judge. After intern returns, parent runs Stage 5. Bugs: red repro first (`core/root-cause-analysis.md`). Features: TDD at named seams (`policies/tdd-policy.md`): one red test per AC row. Surgical diff.
34
- 4. Stage 5: run commands from `.ai-engineering-loop/verification.md`. Keep command, exit code, stdout, test counts. Vague "seems green" is invalid. 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.
31
+ ## Deterministic artifact gates (mandatory)
32
+
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
+
35
+ 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
+
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.
38
+ 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`.
40
+ 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.
35
41
  5. Write artifacts, then spawn. Before Devil's Advocate:
36
42
  - Write `git diff` to a file (for example `.ai-engineering-loop/tasks/current.diff`).
37
43
  - Write changed paths (`git diff --name-only`) into the child prompt as a short list.
38
44
  - Put those paths in the child prompt. Do not paste Maker rationale.
39
45
  - Write `.ai-engineering-loop/tasks/claimed-vs-reality.md` if missing. Do not spawn DA without it.
40
46
  - If stopping mid-loop, write `.ai-engineering-loop/tasks/handoff.md` (`core/handoff-policy.md`).
41
- 6. Stage 6: spawn `devil-advocate`. Wait. Prompt: diff file path, name-only list, Goal Contract path, verification log path, conventions.md path, and "at most 8 tool calls; read the diff file; skip css and generated files". Report Spec and Standards axes separately.
42
- 7. Stage 7: spawn `judge` the same way (wait, no background). Prompt: Goal Contract path, verification evidence path, Finding Ledger, and "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
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`.
43
49
  8. ITERATE with iteration under 3: fix in the parent, re-verify, spawn a **new** Devil's Advocate.
44
- 9. After Judge PASS: run the `after_pass` hook from workflow.md if it is not `none`. Then Stage 8: delivery from `.ai-engineering-loop/adapter.md`. Load shipped spec `adapters/<adapter_type>/` (`standard`, `github`, `gitlab`, `dot`). If adapter.md is missing or the type is unknown, run `generate-adapter` (grill). Do not invent a company pipeline. When the user confirms a process lesson, append one row to `lessons.md` (not a chat dump). Terms go to glossary.md.
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`.
45
51
 
46
52
  ## Report header
47
53
 
@@ -46,20 +46,26 @@ Run `npx ai-engineering-loop <command>` in the target repo. Do not commit unless
46
46
 
47
47
  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.
48
48
 
49
- 1. Stage 0: `npx ai-engineering-loop sync-hosts` then `npx ai-engineering-loop status` (init/refresh if missing or stale). 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 (no extra hooks). If sync-hosts copied files, tell the user a new session is needed for updated skill text; keep going with this session.
50
- 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. Skip grill if the contract is already frozen or the user waived it. 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. Chat agreement is not freeze: every user-visible decision must be a numbered AC in the Goal Contract file. Freeze before any production edit. Name test seams. Use glossary terms. AC is a failure table (happy, empty/omit, boundary, sibling, error). One red test per AC row. Do not freeze sunny-path-only. 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.
51
- 3. Stages 2–4: Read `maker_intern` from workflow.md (missing or none = parent is Maker). Do not type a model name. If a label is set, run `grok models` and confirm the id is in the coding list (not grok-imagine-*). If missing, parent is Maker; say intern INVOCATION_UNAVAILABLE. Otherwise write `.ai-engineering-loop/tasks/maker-brief.md` and spawn that intern as a sibling (`background: false`, wait). Pass a model key only if that key exists on the spawn schema. Do not invent keys, HTTP clients, or custom endpoints. Intern must not spawn DA or Judge (depth 1). After intern returns, parent runs Stage 5 then DA/Judge. Intern cannot skip verification, Devil's Advocate, or Judge. Bugs: red repro first (`core/root-cause-analysis.md`). Features: TDD at named seams (`policies/tdd-policy.md`): one red test per AC row. Surgical diff.
52
- 4. Stage 5: run verification from `.ai-engineering-loop/verification.md`. Keep command, exit code, stdout, test counts. Vague "seems green" is invalid. 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.
49
+ ## Deterministic artifact gates (mandatory)
50
+
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
+
53
+ 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
+
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.
56
+ 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`.
58
+ 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.
53
59
  5. Write artifacts to disk so children do not need parent chat:
54
60
  - Goal Contract path
55
61
  - `git diff` written to `.ai-engineering-loop/tasks/current.diff`
56
62
  - verification log (file)
57
63
  - `.ai-engineering-loop/tasks/claimed-vs-reality.md` (do not spawn DA without it)
58
64
  - If stopping mid-loop, `.ai-engineering-loop/tasks/handoff.md` (`core/handoff-policy.md`)
59
- 6. Stage 6: `spawn_subagent` Devil's Advocate. `background: false`. `capability_mode: "execute"`. Do **not** pass `resume_from`. Wait for the child. Prompt: diff file path, name-only file list, Goal Contract path, verification log path, conventions.md path, plus "at most 8 tool calls; read the diff file; skip css and generated files". Report Spec and Standards axes separately.
60
- 7. Stage 7: `spawn_subagent` Judge the same way (`background: false`, wait). Use `general-purpose` only if `judge` is rejected. Prompt: Goal Contract path, verification evidence path, Finding Ledger, and "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
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`.
61
67
  8. If Judge says `ITERATE` and iteration < 3, Maker fixes in the parent, re-verify, spawn a **fresh** DA (new spawn, no resume).
62
- 9. After Judge PASS: run the `after_pass` hook from workflow.md if it is not `none`. Then Stage 8: delivery from `.ai-engineering-loop/adapter.md`. Load shipped spec `adapters/<adapter_type>/` (`standard`, `github`, `gitlab`, `dot`). If adapter.md is missing or the type is unknown, run `generate-adapter` (grill). Do not invent a company pipeline. When the user confirms a process lesson, append one row to `lessons.md` (not a chat dump). Terms go to glossary.md.
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`.
63
69
 
64
70
  After a proven Grok DA spawn, the report header must be:
65
71
 
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.0.19-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
9
+ [![Release](https://img.shields.io/badge/release-v1.1.0-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, strict verification evidence contracts, 3-stage capability lifecycle registry, and dual-axis Judge evaluation.*
13
+ *Featuring living project context, deterministic artifact gates, bounded secret-redacted context, cheap-model escalation, and dual-axis Judge evaluation.*
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
 
@@ -71,6 +71,7 @@ The 8-stage loop stays one OS. These techniques sit **inside** existing stages (
71
71
  | 4–5 | Red-green at named **seams**; failure table (not happy path only); coverage is a map; no grep/tautology | `policies/tdd-policy.md` |
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
+ | 0–8 | Stateful run ledger and deterministic artifact transitions; model claims cannot advance a stage | `core/artifact-gates.md` |
74
75
  | any | Mid-loop stop writes `.ai-engineering-loop/tasks/handoff.md` | `core/handoff-policy.md` |
75
76
  | 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 |
76
77
 
@@ -178,9 +179,29 @@ npx ai-engineering-loop status
178
179
  # Reconcile drifted context against repository non-destructively
179
180
  npx ai-engineering-loop refresh
180
181
 
181
- # Verify context readiness and begin engineering loop
182
+ # Start or resume a stateful engineering run
182
183
  npx ai-engineering-loop run
183
184
 
185
+ # Inspect the run ledger
186
+ npx ai-engineering-loop state --json
187
+
188
+ # Validate artifacts and advance stages
189
+ npx ai-engineering-loop gate goal
190
+ npx ai-engineering-loop gate maker
191
+ npx ai-engineering-loop gate verification
192
+ npx ai-engineering-loop gate review
193
+ npx ai-engineering-loop escalation --json
194
+ npx ai-engineering-loop gate judge
195
+ npx ai-engineering-loop gate delivery
196
+
197
+ # Build bounded model-visible context
198
+ npx ai-engineering-loop context devil-advocate <files...>
199
+ npx ai-engineering-loop context judge <files...>
200
+
201
+ # Validate installation and the production evaluation catalog
202
+ npx ai-engineering-loop doctor
203
+ npx ai-engineering-loop eval
204
+
184
205
  # Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
185
206
  npx ai-engineering-loop sync-hosts
186
207
 
@@ -193,6 +214,8 @@ npx ai-engineering-loop generate-workflow
193
214
  npx ai-engineering-loop generate-workflow --write
194
215
  ```
195
216
 
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).
218
+
196
219
  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.
197
220
 
198
221
  `sync-hosts` updates only hosts that already exist on the machine. DOT skills (`dot-dev-skill-router`, `dot-dev-workflow`) are updated only if they are already installed. `task-impact-inquiry`, `generate-adapter`, and `generate-workflow` are upserted onto Claude, Grok, and Gemini. After a copy, start a new session so the host reloads skill text. `/ai-engineering-loop` Stage 0 and `run` call `sync-hosts` so a published package bump reaches global host files without a manual copy.
package/SECURITY.md ADDED
@@ -0,0 +1,23 @@
1
+ # Security Policy
2
+
3
+ ## Trust boundary
4
+
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
+
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.
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.
10
+
11
+ ## Credential handling
12
+
13
+ - Supply provider credentials through the host's documented environment or credential store.
14
+ - Never place credentials in `.ai-engineering-loop/`, workflow files, prompts, findings, or delivery reports.
15
+ - Do not pass the parent process environment to a child unless the host owns that boundary.
16
+ - Treat generated run artifacts as sensitive local files. The CLI writes state and context packs with mode `0600` where supported.
17
+ - Run a dedicated secret scanner such as `gitleaks` before delivery when available.
18
+
19
+ Pattern-based redaction is defense in depth, not proof that arbitrary secrets are absent.
20
+
21
+ ## Reporting a vulnerability
22
+
23
+ Do not open a public issue containing credentials, exploit details, private source, or model transcripts. Use GitHub private vulnerability reporting for this repository. Include the package version, host, minimal reproduction, and whether any remote payload was sent.
package/SUPPORT.md ADDED
@@ -0,0 +1,28 @@
1
+ # Public Beta Support Matrix
2
+
3
+ AI Engineering Loop is in public-beta readiness. The workflow contract is stable enough for evaluation, but host tool schemas can change independently.
4
+
5
+ | Host | Installation source | Independent reviewer path | Fallback |
6
+ |---|---|---|---|
7
+ | Claude Code / compatible Task hosts | `.claude/` | `Task` or `Agent` siblings | `CONTEXT_ISOLATION_ONLY` |
8
+ | Grok CLI | `.grok/` | `spawn_subagent` siblings | `grok -p` or `CONTEXT_ISOLATION_ONLY` |
9
+ | Gemini / Antigravity skill hosts | `.gemini/` | `invoke_subagent` or `Task` when present | `CONTEXT_ISOLATION_ONLY` |
10
+ | Antigravity workflows | `.agents/` | `invoke_subagent` or `Task` when present | `CONTEXT_ISOLATION_ONLY` |
11
+
12
+ Independent execution is reported as proven only after a child ID and model response are observed without inherited Maker history.
13
+
14
+ ## Runtime
15
+
16
+ - Node.js 18 or newer.
17
+ - Git is recommended for revision and diff evidence.
18
+ - Linux, macOS, and Windows are covered by the Node test matrix.
19
+ - No runtime npm dependencies.
20
+
21
+ Run diagnostics after installation:
22
+
23
+ ```bash
24
+ npx ai-engineering-loop doctor
25
+ npx ai-engineering-loop eval
26
+ ```
27
+
28
+ New hosts need a documented tool schema, context-isolation behavior, secret boundary, independent-execution proof, and conformance tests before being listed as supported.
@@ -14,10 +14,12 @@ flowchart TD
14
14
 
15
15
  subgraph DOTAdapter [DOT Delivery Pipeline]
16
16
  PASS --> Issue[1. GitLab Issue Card via glab]
17
- Issue --> BaseMR[2. Base Merge Request via glab]
18
- BaseMR --> MultiBranch[3. Multi-Branch Cherry-Pick: staging & develop]
19
- MultiBranch --> CoreviewTriage[4. External @coreview-bot Review Triage]
20
- CoreviewTriage --> MattermostDispatch[5. Mattermost Markdown Notification via MCP]
17
+ Issue --> BaseMR[2. One Merge Request via glab]
18
+ BaseMR --> AskPropagate{User named extra envs this turn?}
19
+ AskPropagate -->|No| CoreviewTriage[3. External @coreview-bot Review Triage]
20
+ AskPropagate -->|Yes| MultiBranch[Optional cherry-pick staging / develop]
21
+ MultiBranch --> CoreviewTriage
22
+ CoreviewTriage --> MattermostDispatch[4. Mattermost Markdown Notification via MCP]
21
23
  end
22
24
  ```
23
25
 
@@ -31,13 +33,15 @@ The DOT adapter is organized into four dedicated specification modules:
31
33
  - CLI automation with `glab`.
32
34
  - Standardized issue card templates with actual vs expected tables and QA testing steps.
33
35
  - Standardized MR descriptions linking issue IDs and change summaries.
34
- 2. **[Multi-Branch Propagation (`multi-branch.md`)](multi-branch.md)**:
35
- - Multi-environment branching model across `main`, `staging`, and `develop`.
36
- - Clean cherry-picking workflow and target-specific test verification.
36
+ 2. **[Topic branch and optional propagate (`multi-branch.md`)](multi-branch.md)**:
37
+ - Unrelated HEAD (`main` / `develop` / `staging` / other ticket): new `type/name` branch.
38
+ - Related `feat/…` or `fix/…`: stay. One MR. Do not open three MRs.
39
+ - Base: `origin/develop` when develop is in use (default branch is `develop`), including when HEAD is `main`. HEAD being `main` does not override an in-use `develop` default. `origin/main` only when develop is unused leftover (default branch is `main` / `master`). Do not force leftover develop.
40
+ - Cherry-pick extra envs only if the user named them this turn. Chat `setuju` is not propagate.
37
41
  3. **[Coreview External Reviewer Triage (`coreview.md`)](coreview.md)**:
38
42
  - Ingestion of `@coreview-bot` automated PR comments.
39
43
  - Mandatory Phase 8 Triage reporting gate before Mattermost dispatch.
40
- - Rigorous evaluation of bot suggestions into `VALID` (fix & propagate) vs `HALU` (false positive pushback) using principles from `gitlab-mr-feedback` and `receiving-code-review`.
44
+ - Rigorous evaluation of bot suggestions into `VALID` (fix on the same topic MR; do not cherry-pick unless the user named extra envs this turn) vs `HALU` (false positive pushback) using principles from `gitlab-mr-feedback` and `receiving-code-review`.
41
45
  4. **[Mattermost Notifications (`mattermost.md`)](mattermost.md)**:
42
46
  - Repository-to-channel resolution using persistent configuration.
43
47
  - MCP `mattermost_send_message` dispatch with mandatory `from: "AI Agent"` attribution.
@@ -76,11 +76,20 @@ glab issue create \
76
76
  - [x] [Component 2 modified]
77
77
  - [x] [Unit tests added in path/to/test.ts]
78
78
 
79
- ## Testing Steps
80
- 1. Login as [User Role / Email].
81
- 2. Navigate to [Target Menu / URL].
82
- 3. Perform [Action e.g. submit the form, approve the request].
83
- 4. Verify [Expected Result].
79
+ ## Steps to Reproduce & Testing (QA)
80
+ ### Pre-conditions
81
+ - <environment / data / permissions>
82
+ ### Steps to Reproduce
83
+ 1. <action>
84
+ 2. <action that triggers the bug or the new path>
85
+ ### How to Test
86
+ 1. <same path after the fix, or the feature path>
87
+ 2. <what QA should click / call / assert>
88
+ ### Actual Result (before the fix / sebelum fix)
89
+ - <error / status / log — N/A on a pure feature>
90
+ ### Expected Result (after the fix / setelah fix)
91
+ - <normal behaviour / status>
92
+ - <no error popup, no crash, no new error logs>
84
93
 
85
94
  ## Expectation
86
95
  | Kondisi / Skenario | Logika Lama (Sebelum) | Logika Baru (Sesudah) |
@@ -120,6 +129,21 @@ glab mr create \
120
129
  - <Concise point 2 explaining edge cases handled>
121
130
  - <Concise point 3 mentioning unit test coverage>
122
131
 
132
+ ## Steps to Reproduce & Testing (QA)
133
+ ### Pre-conditions
134
+ - <environment / data / permissions>
135
+ ### Steps to Reproduce
136
+ 1. <action>
137
+ 2. <action that triggers the bug or the new path>
138
+ ### How to Test
139
+ 1. <same path after the fix, or the feature path>
140
+ 2. <what QA should click / call / assert>
141
+ ### Actual Result (before the fix / sebelum fix)
142
+ - <error / status / log — N/A on a pure feature>
143
+ ### Expected Result (after the fix / setelah fix)
144
+ - <normal behaviour / status>
145
+ - <no error popup, no crash, no new error logs>
146
+
123
147
  ## Screenshot / Video
124
148
  <!-- Attach screenshots, terminal test logs, or UI captures if available -->
125
149
 
@@ -1,90 +1,69 @@
1
- # DOT Adapter: Multi-Branch Propagation
2
-
3
- ## 1. Overview & Branching Hierarchy
4
-
5
- DOT Indonesia repositories maintain synchronized deployments across multiple environments. A typical repository uses three primary target branches:
6
-
7
- ```mermaid
8
- gitGraph
9
- commit id: "Base"
10
- branch develop
11
- checkout develop
12
- commit id: "Dev Baseline"
13
- branch staging
14
- checkout staging
15
- commit id: "Staging Baseline"
16
- checkout main
17
- commit id: "Main Baseline"
18
-
19
- checkout main
20
- branch fix/attendance-status
21
- commit id: "Fix Commit"
22
- checkout main
23
- merge fix/attendance-status id: "MR MAIN"
24
-
25
- checkout staging
26
- cherry-pick id: "Fix Commit"
27
- checkout develop
28
- cherry-pick id: "Fix Commit"
1
+ # DOT Adapter: Topic branch, base, and optional propagate
2
+
3
+ ## 1. Default: one topic branch, one MR
4
+
5
+ Do not open three MRs. Cherry-pick to `staging` or `develop` is opt-in (section 4).
6
+
7
+ ### Related HEAD — stay
8
+
9
+ HEAD is related when the branch name is `feat/…` or `fix/…` (or the same ticket id) for **this** feature.
10
+
11
+ Stay on that branch. Do not create a new topic branch. Open **one MR** onto the branch it was cut from.
12
+
13
+ ### Unrelated HEAD — new topic branch
14
+
15
+ HEAD is unrelated when it is `main`, `master`, `develop`, `staging`, or another ticket's branch.
16
+
17
+ Create a new `type/descriptive-name` branch from the live integration base (section 2). Then open **one MR** onto that base.
18
+
19
+ ## 2. Pick the base
20
+
21
+ 1. `git fetch origin`
22
+ 2. Default branch: `git remote show origin` → `HEAD branch`.
23
+ 3. Do not `git pull` into the current HEAD. Cut the topic branch from `origin/<base>` so local `main` / leftover `develop` stay untouched.
24
+
25
+ **`develop` is in use** only when the default branch is `develop`. Then always cut the new topic branch from `origin/develop`, even if HEAD is `main`, `staging`, or another ticket. HEAD being `main` does not override an in-use `develop` default:
26
+
27
+ ```bash
28
+ git fetch origin
29
+ git checkout -b <type>/<descriptive-name> origin/develop
30
+ ```
31
+
32
+ **`develop` is unused** (leftover) when the default branch is `main` / `master`, even if `origin/develop` exists and even if HEAD is `develop`. Do not force leftover develop:
33
+
34
+ ```bash
35
+ git fetch origin
36
+ git checkout -b <type>/<descriptive-name> origin/main
29
37
  ```
30
38
 
31
- 1. **`main` / `master`** $\rightarrow$ Production Environment (`[MR MAIN]` / `[MR PROD]`).
32
- 2. **`staging`** $\rightarrow$ Staging / QA Testing Environment (`[MR STAGING]`).
33
- 3. **`develop`** $\rightarrow$ Active Development & Bot Review Environment (`[MR DEV]`).
39
+ (`master` if that is the default.)
40
+
41
+ ## 3. Environments (names only)
34
42
 
35
- ---
43
+ These exist on many DOT remotes. They are **not** automatic MR targets.
36
44
 
37
- ## 2. Multi-Branch Propagation Workflow
45
+ 1. **`main` / `master`** — production (`[MR MAIN]` / `[MR PROD]`).
46
+ 2. **`staging`** — QA (`[MR STAGING]`).
47
+ 3. **`develop`** — integration (`[MR DEV]`).
38
48
 
39
- Once the fix is committed on the source branch and the initial Merge Request is created, propagate the exact fix commit to all secondary environments.
49
+ ## 4. Optional propagate (this turn only)
40
50
 
41
- ### Step-by-Step Execution:
51
+ Do not cherry-pick to `staging` or `develop` unless the user named those branches **this turn** (`propagate`, `3 branch`, `staging dan develop`, `multi-branch`). Chat `setuju` is not propagate. `.ai-engineering-loop/adapter.md` cannot turn this on by itself.
42
52
 
43
- For each secondary target environment (`staging`, `develop`):
53
+ When asked, for each named extra target:
44
54
 
45
55
  ```bash
46
- # 1. Fetch latest changes from remote
47
56
  git fetch origin <target-env>
48
-
49
- # 2. Checkout a new dedicated branch tracking the remote environment
50
57
  git checkout -b <branch-name>-<target-env> origin/<target-env>
51
-
52
- # 3. Cherry-pick the verified fix commit
53
58
  git cherry-pick <commit-hash>
54
-
55
- # 4. Resolve any target-specific differences and verify tests pass
56
59
  # commands from .ai-engineering-loop/verification.md
57
- npx jest
58
- npx tsc --noEmit
59
-
60
- # 5. Push the branch to remote
61
60
  git push -u origin <branch-name>-<target-env>
62
-
63
- # 6. Create the environment-specific Merge Request via glab
64
61
  glab mr create \
65
- --repo <repo> \
66
62
  --source-branch <branch-name>-<target-env> \
67
63
  --target-branch <target-env> \
68
64
  --title "<type>(<scope>): <short description>" \
69
65
  --description "<MR Description Markdown>" \
70
- --assignee <username> \
71
66
  --yes
72
67
  ```
73
68
 
74
- ---
75
-
76
- ## 3. Conflict & Environment Discrepancy Handling
77
-
78
- 1. **Clean Cherry-Picks**:
79
- Because the [generic AI Engineering Loop](../../README.md) enforces surgical, minimal diffs, cherry-picking should be clean in >95% of cases.
80
- 2. **Merge Conflicts**:
81
- If a merge conflict occurs due to divergent code between `main` and `develop`:
82
- - Resolve the conflict surgically preserving the fix semantics.
83
- - Run the full test suite (`npx jest`) to prove correctness on the specific environment.
84
- - Complete the cherry-pick:
85
- ```bash
86
- git add <resolved-files>
87
- git cherry-pick --continue
88
- ```
89
- 3. **Environment-Specific Tests**:
90
- Always execute deterministic test suites (`npx jest`, `npx tsc --noEmit`) on each branch prior to pushing.
69
+ Conflicts: resolve surgically, re-run verification, `git cherry-pick --continue`.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: dot-dev-workflow
3
- description: DOT Stage 8 delivery after AI Engineering Loop Judge PASS. GitLab issue/MR, multi-branch cherry-pick, Coreview triage, Mattermost. Not a substitute for ai-engineering-loop.
3
+ description: DOT Stage 8 delivery after AI Engineering Loop Judge PASS. GitLab issue/MR, one topic-branch MR (extra env cherry-pick only if named this turn), Coreview triage, Mattermost. Not a substitute for ai-engineering-loop.
4
4
  ---
5
5
 
6
6
  # DOT Delivery Workflow (Stage 8)
@@ -33,7 +33,7 @@ While AEL Maker runs, still enforce:
33
33
  - `backend-development` for naming, queries, layering.
34
34
  - `backend-safety-guardrails` on mutations, jobs, recalculation: never bypass BullMQ; scope by entity id not coarse date strings; never overwrite `APPROVED`/`REJECTED` without explicit force; BigInt as string across boundaries; container moves sync old and new parents.
35
35
  - Tests: commands in `.ai-engineering-loop/verification.md` (fallback `npx jest && npx tsc --noEmit`).
36
- - Branch from a clean target (`main`, `staging`, or `develop`), then `git checkout -b <type>/<descriptive-name>`.
36
+ - Topic branch: if HEAD is already `feat/…` or `fix/…` for this feature, stay on that branch. Do not create a new topic branch. If HEAD is unrelated (`main`, `master`, `develop`, `staging`, other ticket), `git fetch origin`, then `git checkout -b type/descriptive-name origin/develop` when develop is in use (default branch is `develop`). Do not `git pull` into the current HEAD. HEAD being `main` does not override an in-use `develop` default. If develop is unused leftover (default branch is `main` / `master`), `git checkout -b type/descriptive-name origin/main` even if HEAD is `develop`. Do not force leftover develop.
37
37
 
38
38
  Print these six invariants before commit (N/A allowed only with one sentence citing the diff):
39
39
 
@@ -46,7 +46,7 @@ Print these six invariants before commit (N/A allowed only with one sentence cit
46
46
 
47
47
  ---
48
48
 
49
- ## Stage 8a — Multi-branch MR and issue card (`glab`)
49
+ ## Stage 8a — Topic-branch MR and issue card (`glab`)
50
50
 
51
51
  If the workspace has `adapters/dot/gitlab.md` and `adapters/dot/multi-branch.md`, follow those. Otherwise:
52
52
 
@@ -57,11 +57,9 @@ git add <modified-files>
57
57
  git commit -m "<type>(<scope>): <summary>"
58
58
  ```
59
59
 
60
- 2. Create a GitLab issue if none is linked (`glab issue create` with module title, scope checkboxes, testing steps, expectation table, label `Ready to Test`).
60
+ 2. Create a GitLab issue if none is linked (`glab issue create` with module title, scope checkboxes, `Steps to Reproduce & Testing (QA)` from `adapters/dot/gitlab.md`, expectation table, label `Ready to Test`). On a bugfix, do not leave those placeholders empty.
61
61
 
62
- 3. Create the base MR (`glab mr create` onto the target branch, description links the issue).
63
-
64
- 4. Propagate to `staging` and `develop`: fetch, branch from origin, cherry-pick the commit, re-run verification, push, open MR per environment.
62
+ 3. Open **one** MR (`glab mr create` onto the live integration base from the topic-branch rules above; description links the issue). Issue and MR descriptions must include `Steps to Reproduce & Testing (QA)` (reproduce + how to test). On a bugfix, do not leave those placeholders empty. Do not cherry-pick to `staging` or `develop` unless the user named those branches this turn. Chat `setuju` is not propagate. Do not open three MRs.
65
63
 
66
64
  ---
67
65
 
@@ -88,7 +86,7 @@ glab api "projects/:fullpath/merge_requests/<mr-id>/discussions"
88
86
  glab api "projects/:fullpath/merge_requests/<mr-id>/discussions/<discussion_id>/notes" -X POST -F "body=<text>"
89
87
  ```
90
88
 
91
- - VALID: fix surgically, re-verify, commit, propagate, reply with commit hash.
89
+ - VALID: fix surgically, re-verify, commit, push to the same topic MR, reply with commit hash. Do not cherry-pick to `staging` or `develop` unless the user named those branches this turn. Chat `setuju` is not propagate.
92
90
  - HALU: do not change code; reply with file-cited technical pushback.
93
91
 
94
92
  ---
@@ -12,6 +12,21 @@ gh pr create \
12
12
  - <edge cases>
13
13
  - <tests added>
14
14
 
15
+ ## Steps to Reproduce & Testing (QA)
16
+ ### Pre-conditions
17
+ - <environment / data / permissions>
18
+ ### Steps to Reproduce
19
+ 1. <action>
20
+ 2. <action that triggers the bug or the new path>
21
+ ### How to Test
22
+ 1. <same path after the fix, or the feature path>
23
+ 2. <what QA should click / call / assert>
24
+ ### Actual Result (before the fix)
25
+ - <error / status / log — N/A on a pure feature>
26
+ ### Expected Result (after the fix)
27
+ - <normal behaviour / status>
28
+ - <no error popup, no crash, no new error logs>
29
+
15
30
  ## Verification
16
31
  Commands from `.ai-engineering-loop/verification.md` (exit 0).
17
32
  EOF