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.
- package/.agents/workflows/ai-engineering-loop.md +7 -3
- package/.claude/skills/ai-engineering-loop/SKILL.md +13 -7
- package/.gemini/skills/ai-engineering-loop/SKILL.md +13 -7
- package/.grok/skills/ai-engineering-loop/SKILL.md +13 -7
- package/README.md +26 -3
- package/SECURITY.md +23 -0
- package/SUPPORT.md +28 -0
- package/adapters/dot/README.md +12 -8
- package/adapters/dot/gitlab.md +29 -5
- package/adapters/dot/multi-branch.md +47 -68
- package/adapters/dot/skills/dot-dev-workflow/SKILL.md +6 -8
- package/adapters/github/pull-request.md +15 -0
- package/adapters/gitlab/merge-request.md +15 -0
- package/adapters/standard/README.md +1 -0
- package/bin/ai-engineering-loop.js +255 -3
- package/core/artifact-gates.md +49 -0
- package/evals/README.md +35 -0
- package/evals/cases/01-stale-verification.json +17 -0
- package/evals/cases/02-vague-verification.json +16 -0
- package/evals/cases/03-missing-ac-evidence.json +17 -0
- package/evals/cases/04-hallucinated-citation.json +17 -0
- package/evals/cases/05-prompt-injection.json +17 -0
- package/evals/cases/06-source-secret.json +16 -0
- package/evals/cases/07-log-secret.json +16 -0
- package/evals/cases/08-symlink-escape.json +16 -0
- package/evals/cases/09-authorization-bypass.json +16 -0
- package/evals/cases/10-payment-idempotency.json +16 -0
- package/evals/cases/11-concurrent-update.json +16 -0
- package/evals/cases/12-swallowed-error.json +16 -0
- package/evals/cases/13-happy-path-only.json +17 -0
- package/evals/cases/14-invalid-finding-axis.json +16 -0
- package/evals/cases/15-blocker-without-alternative.json +16 -0
- package/evals/cases/16-unsupported-pass.json +17 -0
- package/evals/cases/17-soft-standard.json +16 -0
- package/evals/cases/18-iteration-ceiling.json +17 -0
- package/evals/cases/19-safe-documentation-change.json +17 -0
- package/evals/cases/20-valid-boundary-feature.json +18 -0
- package/lib/doctor.js +98 -0
- package/lib/escalation.js +192 -0
- package/lib/evaluation.js +137 -0
- package/lib/gates.js +315 -0
- package/lib/orchestration.js +5 -1
- package/lib/run-state.js +221 -0
- package/lib/safe-context.js +191 -0
- package/lib/sync-hosts.js +6 -5
- package/package.json +12 -9
- package/policies/model-escalation.md +41 -0
- package/schemas/delivery.schema.json +14 -0
- package/schemas/finding-ledger.schema.json +27 -0
- package/schemas/goal-contract.schema.json +32 -0
- package/schemas/verdict.schema.json +17 -0
- package/schemas/verification.schema.json +32 -0
- package/docs/antigravity-feasibility.md +0 -92
- package/docs/claude-code-feasibility.md +0 -80
- package/docs/grok-cli-feasibility.md +0 -99
- package/docs/migration-plan.md +0 -70
- package/examples/backend-api/payment-idempotency/README.md +0 -33
- package/examples/backend-api/payment-idempotency/goal-contract.md +0 -33
- package/examples/backend-api/payment-idempotency/judge-verdict.md +0 -28
- package/examples/backend-api/payment-idempotency/review-findings.md +0 -50
- package/examples/dot/status-display/README.md +0 -23
- package/examples/dot/status-display/delivery-report.md +0 -41
- package/examples/dot/status-display/goal-contract.md +0 -46
- package/examples/dot/status-display/judge-verdict.md +0 -44
- package/examples/dot/status-display/review-findings.md +0 -63
- package/examples/initialization/README.md +0 -19
- package/examples/initialization/discovery-trace.md +0 -63
- package/examples/initialization/generated-context.md +0 -110
- package/examples/mobile-app/offline-sync-queue/README.md +0 -33
- package/examples/mobile-app/offline-sync-queue/goal-contract.md +0 -32
- package/examples/mobile-app/offline-sync-queue/judge-verdict.md +0 -27
- package/examples/mobile-app/offline-sync-queue/review-findings.md +0 -30
- package/scripts/init.sh +0 -106
- package/templates/repo-config/adapter.md +0 -11
- package/templates/repo-config/adr-readme.md +0 -33
- package/templates/repo-config/architecture.md +0 -15
- package/templates/repo-config/claude-permissions.json +0 -10
- package/templates/repo-config/config.md +0 -11
- package/templates/repo-config/conventions.md +0 -16
- package/templates/repo-config/glossary.md +0 -18
- package/templates/repo-config/lessons.md +0 -8
- package/templates/repo-config/verification.md +0 -13
- package/templates/repo-config/workflow.md +0 -25
- package/tests/capability-selection.test.js +0 -207
- package/tests/claimed-vs-reality.test.js +0 -27
- package/tests/generate-adapter.test.js +0 -80
- package/tests/generate-workflow.test.js +0 -180
- package/tests/grok-runtime.test.js +0 -201
- package/tests/intern-catalog.test.js +0 -72
- package/tests/living-context.test.js +0 -61
- package/tests/no-company-leak.test.js +0 -82
- package/tests/orchestration.test.js +0 -368
- package/tests/skill-host-compat.test.js +0 -406
- 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.
|
|
16
|
-
7.
|
|
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
|
|
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
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
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:
|
|
49
|
-
7. Stage 7:
|
|
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
|
|
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
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
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:
|
|
42
|
-
7. Stage 7:
|
|
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
|
|
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
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
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: `
|
|
60
|
-
7. Stage 7: `
|
|
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
|
|
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
|
[](https://opensource.org/licenses/MIT)
|
|
7
7
|
[](https://github.com/egagofur/ai-engineering-loop/pulls)
|
|
8
8
|
[](https://github.com/egagofur/ai-engineering-loop)
|
|
9
|
-
[](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,
|
|
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
|
-
#
|
|
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.
|
package/adapters/dot/README.md
CHANGED
|
@@ -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.
|
|
18
|
-
BaseMR -->
|
|
19
|
-
|
|
20
|
-
|
|
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. **[
|
|
35
|
-
-
|
|
36
|
-
-
|
|
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
|
|
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.
|
package/adapters/dot/gitlab.md
CHANGED
|
@@ -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
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
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:
|
|
2
|
-
|
|
3
|
-
## 1.
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
-
|
|
32
|
-
|
|
33
|
-
3.
|
|
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
|
-
|
|
45
|
+
1. **`main` / `master`** — production (`[MR MAIN]` / `[MR PROD]`).
|
|
46
|
+
2. **`staging`** — QA (`[MR STAGING]`).
|
|
47
|
+
3. **`develop`** — integration (`[MR DEV]`).
|
|
38
48
|
|
|
39
|
-
|
|
49
|
+
## 4. Optional propagate (this turn only)
|
|
40
50
|
|
|
41
|
-
|
|
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
|
-
|
|
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,
|
|
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
|
-
-
|
|
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 —
|
|
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,
|
|
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.
|
|
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,
|
|
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
|