ai-engineering-loop 2.13.0 → 2.14.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/skills/ael/SKILL.md +1 -17
- package/.agents/skills/ael/references/loop-deliver.md +20 -0
- package/.agents/skills/ael/references/loop-goal.md +3 -2
- package/.agents/skills/ael/references/loop-judge.md +9 -0
- package/.agents/skills/ael/references/loop-maker.md +1 -2
- package/.agents/skills/ael/references/loop-modes.md +6 -0
- package/.agents/skills/ael/references/loop-review.md +2 -6
- package/CHANGELOG.md +8 -0
- package/agents/instruction-only/AGENTS.md +1 -1
- package/bin/ai-engineering-loop.js +18 -2
- package/core/goal-contract.md +18 -0
- package/lib/ste.js +69 -0
- package/lib/sync-hosts.js +2 -0
- package/package.json +1 -1
|
@@ -43,20 +43,4 @@ Invariants (every tier):
|
|
|
43
43
|
|
|
44
44
|
## Report header
|
|
45
45
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
```
|
|
49
|
-
Execution Mode: TRUE_INDEPENDENT_AGENT
|
|
50
|
-
Independent LLM Execution: PROVEN
|
|
51
|
-
Native Subagent Invocation: AVAILABLE
|
|
52
|
-
Review Method: True Independent Agent
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
When no subagent ran (tool AVAILABLE: mode adds `(reason: <why>)`):
|
|
56
|
-
|
|
57
|
-
```
|
|
58
|
-
Execution Mode: CONTEXT_ISOLATION_ONLY
|
|
59
|
-
Independent LLM Execution: NOT PROVEN
|
|
60
|
-
Native Subagent Invocation: UNAVAILABLE
|
|
61
|
-
Review Method: Clean-Slate Artifact Isolation Barrier
|
|
62
|
-
```
|
|
46
|
+
The final report starts with the execution-mode block in `loop-deliver` (TRUE_INDEPENDENT_AGENT or CONTEXT_ISOLATION_ONLY); never claim independent execution without a subagent result. Tool AVAILABLE but unused: add `(reason: <why>)`.
|
|
@@ -9,3 +9,23 @@
|
|
|
9
9
|
- Commit before `deliver` (its receipt binds `HEAD`; videos/screenshots: `--evidence AC-N=<https-url>`, required for `crossComponent` and rubric ACs). Paste `RUN_DIR/receipt.md` into the PR/MR Receipt section unchanged; ❌ stays ❌ (`docs pr-receipt`).
|
|
10
10
|
- Only the delivery gate completes the run. It also mines lessons for the next Run.
|
|
11
11
|
- Worktree Run: after `deliver`, continue in `cleanup.mainCheckout` (Stage 9).
|
|
12
|
+
|
|
13
|
+
## Report header (execution mode)
|
|
14
|
+
|
|
15
|
+
When a subagent returned its own result (Grok: its own `subagent_id`):
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
Execution Mode: TRUE_INDEPENDENT_AGENT
|
|
19
|
+
Independent LLM Execution: PROVEN
|
|
20
|
+
Native Subagent Invocation: AVAILABLE
|
|
21
|
+
Review Method: True Independent Agent
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
When no subagent ran (tool AVAILABLE: mode adds `(reason: <why>)`):
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
Execution Mode: CONTEXT_ISOLATION_ONLY
|
|
28
|
+
Independent LLM Execution: NOT PROVEN
|
|
29
|
+
Native Subagent Invocation: UNAVAILABLE
|
|
30
|
+
Review Method: Clean-Slate Artifact Isolation Barrier
|
|
31
|
+
```
|
|
@@ -7,9 +7,10 @@
|
|
|
7
7
|
- AC is a failure table: each row has a statement, required evidence, and failure cases. Do not freeze sunny-path-only. T0 may use 1-3 rows that still list failure cases.
|
|
8
8
|
- Boundary-crossing AC (UI-API, service-DB, queue, IPC): `crossComponent: true`; needs L3.
|
|
9
9
|
- Optional per AC: `verify.command` (Judge PASS needs it green), `rubric` for subjective ACs; Goal `featureId` links `features.json`; Goal `flow` (from/event/to) for UI work: show its table with the draft (`docs goal-contract`).
|
|
10
|
-
- Write the contract JSON to `.ai-engineering-loop/drafts/goal.json`, then `npx ai-engineering-loop goal draft --run <runId> --file <file> --revision <currentRevision>` (publishes the draft and the freeze question to Studio). Show the human
|
|
10
|
+
- Write the contract JSON to `.ai-engineering-loop/drafts/goal.json`, then `npx ai-engineering-loop goal draft --json --run <runId> --file <file> --revision <currentRevision>` (publishes the draft and the freeze question to Studio). Show the human `goal show --run <runId> --human` (plain Markdown) and the `impactPreview` in one message.
|
|
11
|
+
- Write `objective`, AC `statement` and `failureCases` in STE style (`docs goal-contract`, STE): one fact or action per sentence, active voice, at most 20-25 words, words a test can check. Fix `readability` warnings from `goal draft` before asking for the freeze.
|
|
11
12
|
- If `goal draft` returns `diagramOptions`, offer the recommended view or freeze; render only the pick (`goal diagram --view <v>`), then ask: freeze, another view, or add AC for `?`/side effects.
|
|
12
|
-
- Wait for the explicit human freeze, then `npx ai-engineering-loop goal freeze --latest --run <runId> --by <name>` (or `--revision <r> --hash <h>`). Add `--confirm-impact` when that answer also accepts the blast radius. T0: `quick start`.
|
|
13
|
+
- Wait for the explicit human freeze, then `npx ai-engineering-loop goal freeze --json --latest --run <runId> --by <name>` (or `--revision <r> --hash <h>`). Add `--confirm-impact` when that answer also accepts the blast radius. T0: `quick start`.
|
|
13
14
|
- Otherwise the freeze writes a DRAFT blast-radius map: `impact show --run <runId>`. ASSISTED: the human confirms or edits it (`impact confirm --by <name> [--allow <glob>] [--remove <path>]`); copy/CSS/comment-only goals: `impact skip --by <name> --reason <text>` (`docs blast-radius-map`).
|
|
14
15
|
- Do not edit production code until the Goal gate passes.
|
|
15
16
|
- After the freeze, work from the frozen contract (`goal show --run <runId>`), not the drafting chat; compact the conversation there if the host supports it.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Stage 7: Judge and ITERATE
|
|
2
|
+
|
|
3
|
+
Read when `gate review` says `judgeRequired`, on T2, or when acting on findings.
|
|
4
|
+
|
|
5
|
+
- Otherwise run `npx ai-engineering-loop escalation --json` and resolve the required tier through the host model catalog; if unavailable, escalate to the user. T2 needs STRONG_MODEL.
|
|
6
|
+
- Judge context: only run-summary.md, verification-summary.json (or verification.json), open-findings.json/findings.json, and the Goal hash; it reads the full diff only if those contradict each other. Judge prompt includes "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
|
|
7
|
+
- Spawn a fresh sibling Judge, wait, `budget record`, write `RUN_DIR/verdict.json` with `modelTier` and any `judgeFindings`, then `gate judge`. A gate failure overrides optimistic prose.
|
|
8
|
+
- Acting on findings (ITERATE or human MR comments): verify each one before changing code; fix valid ones test-first, decline invalid ones with evidence (skill `ael-receiving-code-review` if installed).
|
|
9
|
+
- ITERATE under the recipe cap: fix in the parent, re-verify, spawn a **new** DA (never resume the previous child). At the cap or NO_PROGRESS, ESCALATE to the human.
|
|
@@ -1,8 +1,7 @@
|
|
|
1
1
|
# Stages 2-4: Maker
|
|
2
2
|
|
|
3
3
|
- T1/T2: read `docs tdd-policy` before Maker. Use `npx ai-engineering-loop context query <term>` and `context related <file>` before opening broad source files.
|
|
4
|
-
-
|
|
5
|
-
- Maker intern: read `maker_intern` from workflow.md (missing or `none` = parent is Maker). Confirm it through the host model catalog; otherwise the parent is Maker and you report INVOCATION_UNAVAILABLE. The intern cannot skip later gates or spawn DA/Judge.
|
|
4
|
+
- ASSISTED (default): the parent (or intern) is Maker; delivery needs human approval. REPORT_ONLY, UNATTENDED, `maker_intern`: `loop-modes`.
|
|
6
5
|
- Guardrails: Claude Code enforces them after `hooks install`. Elsewhere, before an out-of-scope edit or a destructive command (`rm -rf`, `DROP TABLE`, `git push --force`, `git reset --hard`, `git clean -fd`) run `guard check --tool edit --path <file>` or `--tool bash --command "<cmd>"`: `warn` = ask the human, `block` = do not run it.
|
|
7
6
|
- No code comments in product code (C-26): put intent in names, types, tests; rationale in the commit.
|
|
8
7
|
- Bugs: red repro first. Features: one red test per AC row, then green.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# Run modes and the Maker intern
|
|
2
|
+
|
|
3
|
+
Read when the Run is REPORT_ONLY or UNATTENDED, or `workflow.md` names a `maker_intern`.
|
|
4
|
+
|
|
5
|
+
- Branch on mode. REPORT_ONLY: never edit repository files; write `RUN_DIR/report.json` with summary and recommendations, then the report review (`loop-report`), run `gate report`, and stop. ASSISTED: the parent (or intern) is Maker; delivery later needs human approval. UNATTENDED: `sandbox create --run <runId>`, Maker works only in the returned worktreePath, never the parent checkout, then `sandbox capture --run <runId>`.
|
|
6
|
+
- Maker intern: read `maker_intern` from workflow.md (missing or `none` = parent is Maker). Confirm it through the host model catalog; otherwise the parent is Maker and you report INVOCATION_UNAVAILABLE. The intern cannot skip later gates or spawn DA/Judge.
|
|
@@ -10,10 +10,6 @@ REPORT_ONLY runs skip these stages; their single report review is in `loop-maker
|
|
|
10
10
|
- Iteration 2+: give unresolved findings and new hunks, not the whole diff again.
|
|
11
11
|
- Wait, `budget record` its usage (or `--unavailable`), save its output to a file, then `review ingest --run <runId> --child-id <id> --file <output> --json` (binds the ledger, runs `gate review`, and `gate judge` when not required). Never drop a finding; dismiss or downgrade only with `dismissal: {by, evidence}`. Report Spec and Standards separately.
|
|
12
12
|
|
|
13
|
-
## Judge
|
|
13
|
+
## Judge and iterate
|
|
14
14
|
|
|
15
|
-
-
|
|
16
|
-
- Judge context: only run-summary.md, verification-summary.json (or verification.json), open-findings.json/findings.json, and the Goal hash; it reads the full diff only if those contradict each other. Judge prompt includes "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
|
|
17
|
-
- Spawn a fresh sibling Judge, wait, `budget record`, write `RUN_DIR/verdict.json` with `modelTier` and any `judgeFindings`, then `gate judge`. A gate failure overrides optimistic prose.
|
|
18
|
-
- Acting on findings (ITERATE or human MR comments): verify each one before changing code; fix valid ones test-first, decline invalid ones with evidence (skill `ael-receiving-code-review` if installed).
|
|
19
|
-
- ITERATE under the recipe cap: fix in the parent, re-verify, spawn a **new** DA (never resume the previous child). At the cap or NO_PROGRESS, ESCALATE to the human.
|
|
15
|
+
- Judge only when `gate review` says `judgeRequired` or T2, or on ITERATE: `loop-judge`.
|
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,14 @@ All notable changes to this project are documented here. Versions follow [Semant
|
|
|
6
6
|
|
|
7
7
|
_No changes yet._
|
|
8
8
|
|
|
9
|
+
## 2.14.0 - 2026-11-21
|
|
10
|
+
|
|
11
|
+
Readable Goals for people (ASD-STE100 style) and skill headroom.
|
|
12
|
+
|
|
13
|
+
- **Changed:** `goal draft` and `goal freeze` print the readable Goal (`goal.md`) and the next step by default, everywhere. Agents and scripts pass `--json` for the full JSON (the skill does). Scripts that parsed the old default output must add `--json`.
|
|
14
|
+
- **Added:** a Goal for people. Every `goal draft` writes `RUN_DIR/goal.md` (What changes, Done when with proof and "Fail if" lines, Not in this change, Not confirmed yet), and `goal show --human` prints it. `goal draft` returns `readability` warnings in the style of ASD-STE100 Simplified Technical English (long or passive sentences, vague words, several actions in one sentence); they never block. The JSON for agents is unchanged (`docs goal-contract`, "Writing for people").
|
|
15
|
+
- **Changed:** skill headroom. The Judge and ITERATE steps moved to `loop-judge` (read only when `judgeRequired`, on T2 or on ITERATE), REPORT_ONLY / UNATTENDED / Maker intern to `loop-modes`, and the report header block to `loop-deliver`. SKILL.md 4000 -> 3757 of 4000 chars; T1 context 17853 -> 16626 of 17859. No rule was dropped.
|
|
16
|
+
|
|
9
17
|
## 2.13.0 - 2026-11-21
|
|
10
18
|
|
|
11
19
|
Newcomer UX from a clean Docker sandbox (cards C-47..C-56 in `docs/cards/novice-ux-2026-11-21.md`; rerun with `scripts/sandbox-e2e.sh`) and "dig first" (C-45, C-46 in `docs/cards/dig-first-2026-11-21.md`).
|
|
@@ -6,7 +6,7 @@ For hosts with no subagent tool (certification `instruction-only`). Full skill:
|
|
|
6
6
|
Loop: Specify (0-1), Make (2-4), Review (5-7), Deliver (8). You are Maker. Devil's Advocate (DA) and Judge run in this session as `CONTEXT_ISOLATION_ONLY`, with the same budgets; never claim independent review.
|
|
7
7
|
|
|
8
8
|
1. `npx ai-engineering-loop run --json` gives runId, tier, budget. Read `.ai-engineering-loop/glossary.md`.
|
|
9
|
-
2. Goal Contract: AC is a failure table (happy, empty, boundary, error). Only after the human freezes: `goal freeze --latest --run <runId> --by human`. Chat agreement is not freeze.
|
|
9
|
+
2. Goal Contract: AC is a failure table (happy, empty, boundary, error). Only after the human freezes: `goal freeze --json --latest --run <runId> --by human`. Chat agreement is not freeze.
|
|
10
10
|
3. Maker: one red test per AC row before the fix, then `gate maker`.
|
|
11
11
|
4. `verify --cmd <test command>`, then write claimed-vs-reality.md.
|
|
12
12
|
5. DA: re-read only the diff, Goal, and evidence; log findings; `gate review`. Judge: write the verdict from the evidence, then `gate judge`. ITERATE at most 3 times.
|
|
@@ -3336,6 +3336,11 @@ function handleGoal() {
|
|
|
3336
3336
|
const extra = {};
|
|
3337
3337
|
if (action === 'show') {
|
|
3338
3338
|
result = loadGoalDraft(CWD, runId);
|
|
3339
|
+
if (process.argv.includes('--human')) {
|
|
3340
|
+
if (!result) throw Object.assign(new Error('No Goal draft yet'), { code: 'GOAL_DRAFT_MISSING', fix: '`scaffold goal`, fill it in, then `goal draft --file .ai-engineering-loop/drafts/goal.json --revision 0`.' });
|
|
3341
|
+
process.stdout.write(require('../lib/ste.js').renderHumanGoal(result.contract, { runId, revision: result.metadata?.revision }));
|
|
3342
|
+
return;
|
|
3343
|
+
}
|
|
3339
3344
|
if (result?.contract?.designRef) extra.design = require('../lib/design-ref.js').designStatus(CWD, result.contract.designRef);
|
|
3340
3345
|
} else if (action === 'draft') {
|
|
3341
3346
|
appendRunLifecycle(CWD, runId, {
|
|
@@ -3375,6 +3380,11 @@ function handleGoal() {
|
|
|
3375
3380
|
expectedRevision: requiredIntegerArg('--revision')
|
|
3376
3381
|
});
|
|
3377
3382
|
extra.impactPreview = impactPreview(runId, draftGoal);
|
|
3383
|
+
const ste = require('../lib/ste.js');
|
|
3384
|
+
const humanPath = path.join(runsDir(CWD), runId, 'goal.md');
|
|
3385
|
+
fs.writeFileSync(humanPath, ste.renderHumanGoal(draftGoal, { runId, revision: result.metadata?.revision }), { mode: 0o600 });
|
|
3386
|
+
extra.human = { path: path.relative(CWD, humanPath).split(path.sep).join('/'), show: `goal show --run ${runId} --human` };
|
|
3387
|
+
extra.readability = ste.goalReadability(draftGoal);
|
|
3378
3388
|
if (draftGoal && draftGoal.flow != null) {
|
|
3379
3389
|
const flowLib = require('../lib/flow.js');
|
|
3380
3390
|
extra.flow = { table: flowLib.renderFlow(draftGoal.flow), mermaid: flowLib.renderMermaid(draftGoal.flow), problems: flowLib.flowProblems(draftGoal.flow), warnings: flowLib.flowWarnings(draftGoal.flow), ...flowLib.flowCounts(draftGoal) };
|
|
@@ -3461,12 +3471,17 @@ function handleGoal() {
|
|
|
3461
3471
|
error.code = 'INVALID_USAGE';
|
|
3462
3472
|
throw error;
|
|
3463
3473
|
}
|
|
3464
|
-
if (
|
|
3474
|
+
if (!process.argv.includes('--json') && ['draft', 'freeze'].includes(action)) {
|
|
3465
3475
|
const meta = result?.metadata || {};
|
|
3466
3476
|
log.success(`✓ goal ${action}: Run ${runId}${meta.revision != null ? `, revision ${meta.revision}` : ''}${meta.contentHash ? ` (${String(meta.contentHash).slice(0, 12)})` : ''}`);
|
|
3477
|
+
if (action === 'draft' && extra.human) {
|
|
3478
|
+
console.log('');
|
|
3479
|
+
process.stdout.write(fs.readFileSync(path.join(CWD, extra.human.path), 'utf8'));
|
|
3480
|
+
console.log('');
|
|
3481
|
+
}
|
|
3467
3482
|
if (extra.impactPreview) console.log(`- Impact preview: ${JSON.stringify(extra.impactPreview).slice(0, 200)}`);
|
|
3468
3483
|
if (extra.warning) console.log(`! ${extra.warning}`);
|
|
3469
|
-
console.log(action === 'draft' ? `- Next:
|
|
3484
|
+
console.log(action === 'draft' ? `- Next: the human reads this and says freeze; then \`goal freeze --latest --run ${runId} --by <name>\`. Agents: add --json.` : '- Next: Maker (implement), then `gate maker --from-git`. Agents: add --json.');
|
|
3470
3485
|
return;
|
|
3471
3486
|
}
|
|
3472
3487
|
console.log(JSON.stringify({ ok: true, runId, [action === 'show' ? 'draft' : 'result']: result, ...extra }, null, 2));
|
|
@@ -4765,6 +4780,7 @@ Commands:
|
|
|
4765
4780
|
draft --file <json> --revision <n> [--run <id>] [--by <agent>]
|
|
4766
4781
|
draft --from-design <doc.md> [--file <json>] --revision <n> prefill from a design doc, record designRef
|
|
4767
4782
|
freeze --revision <n> --hash <sha256> [--run <id>] [--by <name>]
|
|
4783
|
+
show --human [--run <id>] the Goal as plain Markdown for people (STE style: short active sentences)
|
|
4768
4784
|
freeze --latest [--run <id>] --by <name> freeze the newest draft (CLI resolves revision/hash)
|
|
4769
4785
|
diagram --view state|storyboard|lanes [--run <id>] [--revision <n>] [--lang <tag>] [--open] draw the Goal flow as HTML
|
|
4770
4786
|
verification Summarize verification.json for compact Judge context
|
package/core/goal-contract.md
CHANGED
|
@@ -230,3 +230,21 @@ The receipt lists `--evidence AC-N=<https-url>` links first, typed as video, scr
|
|
|
230
230
|
```
|
|
231
231
|
|
|
232
232
|
Then: `goal draft --run <runId> --file .ai-engineering-loop/drafts/goal.json --revision 0`, show the draft to the human, and `goal freeze`.
|
|
233
|
+
|
|
234
|
+
## Writing for people: STE style (ASD-STE100)
|
|
235
|
+
|
|
236
|
+
The Goal JSON is for the tools; people read `RUN_DIR/goal.md` (`goal show --human`), written on every `goal draft`. Write the text fields in the style of ASD-STE100 Simplified Technical English (https://www.asd-ste100.org), so a reviewer, a client or a non-native reader understands each line on the first read:
|
|
237
|
+
|
|
238
|
+
| Rule | Do | Not |
|
|
239
|
+
|---|---|---|
|
|
240
|
+
| One fact or one action per sentence | "Export saves a CSV file." | "Export saves a CSV and then emails it and logs it." |
|
|
241
|
+
| Active voice: say who does what | "The API rejects an empty name." | "An empty name is rejected." |
|
|
242
|
+
| Short sentences | Instructions 20 words or fewer, descriptions 25 or fewer | Long sentences with many clauses |
|
|
243
|
+
| Words a test can check | "The page loads in 2 seconds or less." | "fast", "robust", "properly", "should", "etc." |
|
|
244
|
+
| Same word for the same thing | Use the glossary term every time | Switching between "invoice", "bill" and "receipt" |
|
|
245
|
+
| Start with the subject or the verb | "The filter keeps the last value." | "Keeping the last value, the filter..." |
|
|
246
|
+
|
|
247
|
+
`goal draft` prints `goal.md` and the next step by default; agents and scripts pass `--json` for the full JSON. With `--json` it returns `readability`: warnings for long sentences, passive voice, vague words, several actions in one sentence and sentences that start with an -ing word. They never block the gate; fix them before you ask for the freeze. AEL checks these general writing rules only; it does not ship the ASD-STE100 dictionary.
|
|
248
|
+
|
|
249
|
+
`goal.md` has these sections: What changes, Done when (each AC with its proof and "Fail if" lines), Not in this change, Not confirmed yet (assumptions from `statements`), and the writing checks.
|
|
250
|
+
|
package/lib/ste.js
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const MAX_WORDS = { instruction: 20, description: 25 };
|
|
4
|
+
const VAGUE = ['should', 'might', 'could', 'would', 'may', 'maybe', 'probably', 'possibly', 'some', 'various', 'etc', 'and/or', 'appropriate', 'properly', 'correctly', 'as needed', 'if necessary', 'user-friendly', 'robust', 'seamless', 'fast', 'easy'];
|
|
5
|
+
const PASSIVE = /\b(is|are|was|were|be|been|being|gets|got)\s+(\w+ly\s+)?(\w+ed|built|done|made|shown|sent|set|written|given|taken|seen|known|found|kept|held|read|run|left|put|shut|split|spent|chosen|broken)\b/i;
|
|
6
|
+
const IMPERATIVE_HINT = /^(add|remove|show|hide|send|save|open|close|keep|use|return|reject|accept|write|read|run|stop|start|set|make|create|delete|update|move|check|display|export|import|log|block|allow)\b/i;
|
|
7
|
+
|
|
8
|
+
const words = (sentence) => sentence.split(/\s+/).filter((word) => /[A-Za-z0-9]/.test(word));
|
|
9
|
+
|
|
10
|
+
function sentences(text) {
|
|
11
|
+
return String(text || '')
|
|
12
|
+
.replace(/`[^`]*`/g, 'CODE')
|
|
13
|
+
.split(/(?<=[.!?;])\s+|\n+/)
|
|
14
|
+
.map((part) => part.trim())
|
|
15
|
+
.filter(Boolean);
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
function steFindings(text, { kind = 'description' } = {}) {
|
|
19
|
+
const findings = [];
|
|
20
|
+
const limit = MAX_WORDS[kind] || MAX_WORDS.description;
|
|
21
|
+
for (const sentence of sentences(text)) {
|
|
22
|
+
const count = words(sentence).length;
|
|
23
|
+
if (count > limit) findings.push({ rule: 'length', detail: `${count} words; keep ${kind} sentences at ${limit} or fewer` });
|
|
24
|
+
if (PASSIVE.test(sentence)) findings.push({ rule: 'active-voice', detail: `passive "${sentence.match(PASSIVE)[0]}"; say who does what` });
|
|
25
|
+
const lower = ` ${sentence.toLowerCase().replace(/[^a-z/\s-]/g, ' ')} `;
|
|
26
|
+
const vague = VAGUE.filter((word) => lower.includes(` ${word} `));
|
|
27
|
+
if (vague.length) findings.push({ rule: 'precise-words', detail: `vague: ${vague.join(', ')}; use a word a test can check` });
|
|
28
|
+
if (kind === 'instruction' && (sentence.match(/\b(and then|then|and also)\b/gi) || []).length) findings.push({ rule: 'one-instruction', detail: 'more than one action; write one sentence per action' });
|
|
29
|
+
if (/^\w+ing\b/.test(sentence) && !IMPERATIVE_HINT.test(sentence)) findings.push({ rule: 'no-ing-start', detail: 'starts with an -ing word; start with the subject or the verb' });
|
|
30
|
+
}
|
|
31
|
+
return findings;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function goalReadability(goal) {
|
|
35
|
+
const out = [];
|
|
36
|
+
const add = (field, text, kind) => {
|
|
37
|
+
for (const finding of steFindings(text, { kind })) out.push({ field, ...finding });
|
|
38
|
+
};
|
|
39
|
+
add('objective', goal?.objective, 'description');
|
|
40
|
+
if (goal?.plainSummary) add('plainSummary', goal.plainSummary, 'description');
|
|
41
|
+
for (const criterion of goal?.acceptanceCriteria || []) {
|
|
42
|
+
add(`${criterion.id}.statement`, criterion.statement, 'description');
|
|
43
|
+
(criterion.failureCases || []).forEach((item, index) => add(`${criterion.id}.failureCases[${index}]`, item, 'description'));
|
|
44
|
+
}
|
|
45
|
+
return out;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
const line = (text) => String(text || '').replace(/\s+/g, ' ').trim();
|
|
49
|
+
|
|
50
|
+
function renderHumanGoal(goal, { runId = goal?.runId, revision = null } = {}) {
|
|
51
|
+
const parts = [`# Goal${runId ? ` for Run ${runId}` : ''}${revision != null ? ` (revision ${revision})` : ''}`, ''];
|
|
52
|
+
parts.push('## What changes', '', line(goal?.plainSummary || goal?.objective), '');
|
|
53
|
+
parts.push('## Done when', '');
|
|
54
|
+
for (const criterion of goal?.acceptanceCriteria || []) {
|
|
55
|
+
parts.push(`${criterion.id}. ${line(criterion.statement)}`);
|
|
56
|
+
parts.push(` - Proof: ${line(criterion.evidenceRequired)}.`.replace(/\.\.$/, '.'));
|
|
57
|
+
for (const failure of criterion.failureCases || []) parts.push(` - Fail if: ${line(failure)}`);
|
|
58
|
+
}
|
|
59
|
+
parts.push('');
|
|
60
|
+
if ((goal?.outOfScope || []).length) parts.push('## Not in this change', '', ...goal.outOfScope.map((item) => `- ${line(item)}`), '');
|
|
61
|
+
const statements = goal?.statements || [];
|
|
62
|
+
const unconfirmed = statements.filter((item) => item.kind === 'assumption');
|
|
63
|
+
if (unconfirmed.length) parts.push('## Not confirmed yet', '', ...unconfirmed.map((item) => `- ${line(item.text)}`), '');
|
|
64
|
+
const findings = goalReadability(goal);
|
|
65
|
+
if (findings.length) parts.push('## Writing checks (STE style, not blocking)', '', ...findings.map((item) => `- ${item.field}: ${item.detail}`), '');
|
|
66
|
+
return `${parts.join('\n').trimEnd()}\n`;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
module.exports = { MAX_WORDS, goalReadability, renderHumanGoal, steFindings };
|
package/lib/sync-hosts.js
CHANGED
package/package.json
CHANGED