ai-engineering-loop 2.9.0 → 2.10.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/references/loop-commands.md +1 -0
- package/.agents/skills/ael/references/loop-goal.md +1 -0
- package/CHANGELOG.md +7 -0
- package/bin/ai-engineering-loop.js +109 -4
- package/core/goal-contract.md +38 -0
- package/core/recap.md +29 -0
- package/lib/cli-args.js +1 -0
- package/lib/flow-diagram.js +339 -0
- package/lib/flow.js +104 -19
- package/lib/gates.js +7 -1
- package/lib/generate-workflow.js +17 -0
- package/lib/recap-html.js +216 -0
- package/lib/recap.js +168 -0
- package/package.json +1 -1
- package/schemas/goal-contract.schema.json +42 -2
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
|
|
12
12
|
Run these when the user asks how the loop is doing, before planning work, or when a gate points at them. All read local Run files; none starts a Run.
|
|
13
13
|
- `stats [--last <n>] [--json]`: failure causes by harness layer (`task_spec`, `context`, `environment`, `verification`, `state`, `model`), false-victory rate per tier, iterations to PASS, revert rate of delivered Runs (from git) and the verification share of tokens. Fix the bottleneck layer first.
|
|
14
|
+
- `recap [--days N] [--for me|lead|client] [--projects <p,...>|all]`: one HTML page of what shipped, with evidence (`docs recap`). Client recaps take one project.
|
|
14
15
|
- `outcome record --run <id> --source mr-comment|revert|bug|incident --location <file[:line]> --summary <text> --by <name>`: a problem people found after delivery. Only record what the human reported; never invent one. Then `calibrate` lists DA misses and wrong dismissals per reviewer prompt version.
|
|
15
16
|
- `debt [--file <path>]` lists trade-offs the Judge accepted and L3 waivers; `debt close <id> --by <name>` only on the human's word.
|
|
16
17
|
- `next`: the next unblocked feature in `.ai-engineering-loop/features.json` and VCR (verified/activated). Finish the active feature before starting another.
|
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
- Boundary-crossing AC (UI-API, service-DB, queue, IPC): `crossComponent: true`; needs L3.
|
|
8
8
|
- 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`).
|
|
9
9
|
- Write the contract JSON to a repository-local file, 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 the draft and its `impactPreview` in one message.
|
|
10
|
+
- 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.
|
|
10
11
|
- 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`.
|
|
11
12
|
- 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`).
|
|
12
13
|
- Do not edit production code until the Goal gate passes.
|
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,13 @@ All notable changes to this project are documented here. Versions follow [Semant
|
|
|
6
6
|
|
|
7
7
|
_No changes yet._
|
|
8
8
|
|
|
9
|
+
## 2.10.0 - 2026-11-17
|
|
10
|
+
|
|
11
|
+
Cards C-27 and C-28 in `docs/cards/slop-to-gold-2026-11-16.md`.
|
|
12
|
+
|
|
13
|
+
- **Added:** look before you freeze (C-27). Goal `flow` steps may carry `actor`, `guard`, `effects` (with or without an AC) and `hotspot`, plus Goal-level `flowSubject`, `forbiddenTransitions` and `plainSummary`. `goal draft` returns `diagramOptions` and counts of undecided transitions, hotspots and side effects, and its impact preview no longer cuts tests to 10. `goal diagram --view state|storyboard|lanes` renders only the chosen view as an offline HTML page; the state view includes a full state × event transition table. Set a project default with `freeze_diagram` in `workflow.md`.
|
|
14
|
+
- **Added:** `ael recap` (C-28): an evidence-backed HTML recap of the last N days for me, the lead or a client, built only from Run artifacts (`docs recap`).
|
|
15
|
+
|
|
9
16
|
## 2.9.0 - 2026-11-16
|
|
10
17
|
|
|
11
18
|
From "All Code Is Slop (Except Mine)" 08:06-08:46 (card C-26 in `docs/cards/slop-to-gold-2026-11-16.md`).
|
|
@@ -1930,7 +1930,7 @@ function closeFreezeQuestions(runId, actor) {
|
|
|
1930
1930
|
function impactPreview(runId, goal) {
|
|
1931
1931
|
try {
|
|
1932
1932
|
const map = impactMap.buildImpactMap(CWD, { run: loadRun(CWD, runId), goal });
|
|
1933
|
-
return { files: (map.files || []).map((file) => file.path), tests: (map.tests || []).map((t) => t.path || t)
|
|
1933
|
+
return { files: (map.files || []).map((file) => file.path), tests: (map.tests || []).map((t) => t.path || t) };
|
|
1934
1934
|
} catch (err) {
|
|
1935
1935
|
return { error: err.message };
|
|
1936
1936
|
}
|
|
@@ -3163,10 +3163,13 @@ function handleGoal() {
|
|
|
3163
3163
|
expectedRevision: requiredIntegerArg('--revision')
|
|
3164
3164
|
});
|
|
3165
3165
|
extra.impactPreview = impactPreview(runId, draftGoal);
|
|
3166
|
-
// C-21: show the intended user flow as a transition table before freeze.
|
|
3167
3166
|
if (draftGoal && draftGoal.flow != null) {
|
|
3168
3167
|
const flowLib = require('../lib/flow.js');
|
|
3169
|
-
extra.flow = { table: flowLib.renderFlow(draftGoal.flow), mermaid: flowLib.renderMermaid(draftGoal.flow), problems: flowLib.flowProblems(draftGoal.flow), warnings: flowLib.flowWarnings(draftGoal.flow) };
|
|
3168
|
+
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) };
|
|
3169
|
+
const preference = require('../lib/generate-workflow.js').readFreezeDiagram(CWD);
|
|
3170
|
+
extra.diagramOptions = flowLib.diagramOptions(draftGoal, { preference });
|
|
3171
|
+
if (preference === 'off') extra.diagramsOff = true;
|
|
3172
|
+
else extra.diagramHint = `Offer the recommended view or freeze; render one with \`goal diagram --run ${runId} --view <state|storyboard|lanes>\`.`;
|
|
3170
3173
|
}
|
|
3171
3174
|
appendRunLifecycle(CWD, runId, {
|
|
3172
3175
|
type: 'GOAL_DRAFT_UPDATED',
|
|
@@ -3239,8 +3242,10 @@ function handleGoal() {
|
|
|
3239
3242
|
const confirmed = impactMap.confirmImpactMap(CWD, { runId, by: argValue('--by') || 'human' });
|
|
3240
3243
|
extra.impact = { status: confirmed.map ? confirmed.map.status : 'CONFIRMED' };
|
|
3241
3244
|
}
|
|
3245
|
+
} else if (action === 'diagram') {
|
|
3246
|
+
Object.assign(extra, renderGoalDiagram(runId));
|
|
3242
3247
|
} else {
|
|
3243
|
-
const error = new Error('goal must be show, draft, or
|
|
3248
|
+
const error = new Error('goal must be show, draft, freeze, or diagram');
|
|
3244
3249
|
error.code = 'INVALID_USAGE';
|
|
3245
3250
|
throw error;
|
|
3246
3251
|
}
|
|
@@ -3251,6 +3256,61 @@ function handleGoal() {
|
|
|
3251
3256
|
}
|
|
3252
3257
|
}
|
|
3253
3258
|
|
|
3259
|
+
function contentLangArg() {
|
|
3260
|
+
const lang = argValue('--lang');
|
|
3261
|
+
if (lang == null) return null;
|
|
3262
|
+
if (!/^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/.test(lang)) {
|
|
3263
|
+
throw Object.assign(new Error('--lang must be a language tag such as id, en or pt-BR'), { code: 'INVALID_USAGE' });
|
|
3264
|
+
}
|
|
3265
|
+
return lang;
|
|
3266
|
+
}
|
|
3267
|
+
|
|
3268
|
+
function renderGoalDiagram(runId) {
|
|
3269
|
+
const view = argValue('--view');
|
|
3270
|
+
const { VIEWS } = require('../lib/flow.js');
|
|
3271
|
+
if (!VIEWS.includes(view)) {
|
|
3272
|
+
throw Object.assign(new Error('goal diagram needs --view state|storyboard|lanes'), { code: 'INVALID_USAGE' });
|
|
3273
|
+
}
|
|
3274
|
+
const run = loadRun(CWD, runId);
|
|
3275
|
+
let goal;
|
|
3276
|
+
let revision;
|
|
3277
|
+
let suffix;
|
|
3278
|
+
if (run.goal?.frozen) {
|
|
3279
|
+
goal = JSON.parse(fs.readFileSync(path.join(CWD, '.ai-engineering-loop', 'runs', runId, 'goal-contract.json'), 'utf8'));
|
|
3280
|
+
revision = null;
|
|
3281
|
+
suffix = 'frozen';
|
|
3282
|
+
} else {
|
|
3283
|
+
const draft = loadGoalDraft(CWD, runId);
|
|
3284
|
+
if (!draft) throw Object.assign(new Error('No Goal draft yet: run `goal draft` first'), { code: 'GOAL_DRAFT_MISSING' });
|
|
3285
|
+
revision = draft.metadata.revision;
|
|
3286
|
+
const requested = argValue('--revision');
|
|
3287
|
+
if (requested != null && Number(requested) !== revision) {
|
|
3288
|
+
throw Object.assign(new Error(`Only the latest draft is kept: it is revision ${revision}. Rerun with --revision ${revision} or without --revision.`), { code: 'GOAL_REVISION_MISMATCH' });
|
|
3289
|
+
}
|
|
3290
|
+
goal = draft.contract;
|
|
3291
|
+
suffix = `r${revision}`;
|
|
3292
|
+
}
|
|
3293
|
+
if (!Array.isArray(goal.flow) || !goal.flow.length) {
|
|
3294
|
+
throw Object.assign(new Error('The Goal has no flow to draw. Add flow steps ({from, event, to}) to the draft, then rerun `goal draft`.'), { code: 'GOAL_FLOW_MISSING' });
|
|
3295
|
+
}
|
|
3296
|
+
const html = require('../lib/flow-diagram.js').renderDiagram(goal, { view, revision, lang: contentLangArg() });
|
|
3297
|
+
const dir = path.join(CWD, '.ai-engineering-loop', 'runs', runId, 'diagrams');
|
|
3298
|
+
fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
|
|
3299
|
+
const file = path.join(dir, `${view}-${suffix}.html`);
|
|
3300
|
+
fs.writeFileSync(file, html, { mode: 0o600 });
|
|
3301
|
+
fs.chmodSync(file, 0o600);
|
|
3302
|
+
if (process.argv.includes('--open')) openStudio(file);
|
|
3303
|
+
const counts = require('../lib/flow.js').flowCounts(goal);
|
|
3304
|
+
return {
|
|
3305
|
+
view,
|
|
3306
|
+
path: file,
|
|
3307
|
+
counts,
|
|
3308
|
+
next: counts.undecided || counts.hotspots || counts.sideEffects
|
|
3309
|
+
? 'Ask the human: freeze, another view, or turn the ? cells, hotspots and side effects into AC, non-goals or forbiddenTransitions (new draft revision).'
|
|
3310
|
+
: 'Ask the human: freeze or another view.'
|
|
3311
|
+
};
|
|
3312
|
+
}
|
|
3313
|
+
|
|
3254
3314
|
function handleActivity() {
|
|
3255
3315
|
const aliases = {
|
|
3256
3316
|
'goal-drafting': 'GOAL_DRAFTING',
|
|
@@ -3706,6 +3766,46 @@ function handleRules() {
|
|
|
3706
3766
|
}
|
|
3707
3767
|
}
|
|
3708
3768
|
|
|
3769
|
+
function handleRecap() {
|
|
3770
|
+
try {
|
|
3771
|
+
const days = argValue('--days') == null ? 7 : Number(argValue('--days'));
|
|
3772
|
+
if (!Number.isInteger(days) || days < 1 || days > 366) {
|
|
3773
|
+
throw Object.assign(new Error('--days must be a whole number from 1 to 366'), { code: 'INVALID_USAGE' });
|
|
3774
|
+
}
|
|
3775
|
+
const { AUDIENCES, renderRecap } = require('../lib/recap-html.js');
|
|
3776
|
+
const audience = argValue('--for') || 'me';
|
|
3777
|
+
if (!AUDIENCES.includes(audience)) throw Object.assign(new Error('--for must be me, lead or client'), { code: 'INVALID_USAGE' });
|
|
3778
|
+
const projectsArg = argValue('--projects');
|
|
3779
|
+
const projects = !projectsArg
|
|
3780
|
+
? [CWD]
|
|
3781
|
+
: projectsArg === 'all'
|
|
3782
|
+
? projectRegistry.listProjects().projects.map((project) => project.path)
|
|
3783
|
+
: projectsArg.split(',').map((item) => path.resolve(CWD, item.trim())).filter(Boolean);
|
|
3784
|
+
if (!projects.length) throw Object.assign(new Error('No projects to recap: register one with `ael projects` or pass --projects <path>'), { code: 'INVALID_USAGE' });
|
|
3785
|
+
if (audience === 'client' && projects.length > 1) {
|
|
3786
|
+
throw Object.assign(new Error('A client recap covers one project only: pass --projects <path> with a single path'), { code: 'INVALID_USAGE' });
|
|
3787
|
+
}
|
|
3788
|
+
const now = argValue('--now') ? new Date(argValue('--now')) : new Date();
|
|
3789
|
+
if (Number.isNaN(now.getTime())) throw Object.assign(new Error('--now must be an ISO date'), { code: 'INVALID_USAGE' });
|
|
3790
|
+
const data = require('../lib/recap.js').collectRecap({ projects, days, now });
|
|
3791
|
+
const html = renderRecap(data, { audience, now, lang: contentLangArg() });
|
|
3792
|
+
const day = (d) => d.toISOString().slice(0, 10);
|
|
3793
|
+
const out = argValue('--out')
|
|
3794
|
+
? path.resolve(CWD, argValue('--out'))
|
|
3795
|
+
: path.join(CWD, '.ai-engineering-loop', 'recaps', `recap-${day(data.window.from)}-${day(now)}-${audience}.html`);
|
|
3796
|
+
fs.mkdirSync(path.dirname(out), { recursive: true });
|
|
3797
|
+
fs.writeFileSync(out, html, { mode: 0o600 });
|
|
3798
|
+
fs.chmodSync(out, 0o600);
|
|
3799
|
+
if (process.argv.includes('--open')) openStudio(out);
|
|
3800
|
+
const summary = { ok: true, path: out, audience, days, projects: data.projects, runs: data.metrics.runs, delivered: data.metrics.delivered };
|
|
3801
|
+
if (process.argv.includes('--json')) console.log(JSON.stringify(summary, null, 2));
|
|
3802
|
+
else log.success(`✓ Recap (${audience}, ${days} days, ${summary.runs} runs, ${summary.delivered} delivered): ${out}`);
|
|
3803
|
+
} catch (error) {
|
|
3804
|
+
log.error(`${error.code || 'RECAP_FAILED'}: ${error.message}`);
|
|
3805
|
+
process.exitCode = 1;
|
|
3806
|
+
}
|
|
3807
|
+
}
|
|
3808
|
+
|
|
3709
3809
|
function handleStats() {
|
|
3710
3810
|
const json = process.argv.includes('--json');
|
|
3711
3811
|
try {
|
|
@@ -4285,6 +4385,7 @@ Commands:
|
|
|
4285
4385
|
draft --from-design <doc.md> [--file <json>] --revision <n> prefill from a design doc, record designRef
|
|
4286
4386
|
freeze --revision <n> --hash <sha256> [--run <id>] [--by <name>]
|
|
4287
4387
|
freeze --latest [--run <id>] --by <name> freeze the newest draft (CLI resolves revision/hash)
|
|
4388
|
+
diagram --view state|storyboard|lanes [--run <id>] [--revision <n>] [--lang <tag>] [--open] draw the Goal flow as HTML
|
|
4288
4389
|
verification Summarize verification.json for compact Judge context
|
|
4289
4390
|
summarize [--run <id>] [--json]
|
|
4290
4391
|
record [--run <id>] [--timeout-ms <n>] [--shell] [--json] -- <executable> [args...]
|
|
@@ -4362,6 +4463,7 @@ Commands:
|
|
|
4362
4463
|
calibrate Compare recorded outcomes with each Run's Finding Ledger: DA misses, wrong dismissals, per reviewer prompt
|
|
4363
4464
|
debt Accepted trade-offs and L3 waivers recorded at delivery: list [--file <path>] | close <id> --by <name> [--note <text>]
|
|
4364
4465
|
next Next unblocked feature from .ai-engineering-loop/features.json, VCR (verified/activated), evidence audit [--json]
|
|
4466
|
+
recap Evidence-backed recap of the last N days as one HTML page [--days 7] [--for me|lead|client] [--projects <p,...>|all] [--out <file>] [--lang <tag>] [--open] [--json]
|
|
4365
4467
|
stats Failure causes by harness layer, false-victory rate, iterations to PASS [--last <n>] [--json]
|
|
4366
4468
|
escalation Compute the minimum Judge model tier from deterministic risk signals
|
|
4367
4469
|
--run <id> target a non-current run
|
|
@@ -4582,6 +4684,9 @@ switch (command) {
|
|
|
4582
4684
|
case 'escalation':
|
|
4583
4685
|
handleEscalation();
|
|
4584
4686
|
break;
|
|
4687
|
+
case 'recap':
|
|
4688
|
+
handleRecap();
|
|
4689
|
+
break;
|
|
4585
4690
|
case 'stats':
|
|
4586
4691
|
handleStats();
|
|
4587
4692
|
break;
|
package/core/goal-contract.md
CHANGED
|
@@ -162,6 +162,44 @@ For UI or multi-step work, add the flow the user should experience as transition
|
|
|
162
162
|
|
|
163
163
|
`goal draft` returns it as a `From | Event | To` table and a Mermaid `stateDiagram-v2` (`flow.mermaid`), with warnings (a state nothing reaches, a state with no way out that is not Done/Error), so the human checks the intent before freeze. A malformed `flow` fails the Goal gate. The PR receipt shows the same diagram (GitHub renders it) and table under "Intended flow", after "Verification artifacts" and before the acceptance criteria.
|
|
164
164
|
|
|
165
|
+
## Look before you freeze: diagrams (C-27)
|
|
166
|
+
|
|
167
|
+
Steps may carry more than `from`, `event`, `to`, so the human can see what else a change touches before freezing:
|
|
168
|
+
|
|
169
|
+
```json
|
|
170
|
+
"flowSubject": "order",
|
|
171
|
+
"flow": [
|
|
172
|
+
{ "from": "Processing", "event": "cancel", "to": "Cancelled", "actor": "user", "guard": "not shipped",
|
|
173
|
+
"effects": [ { "text": "refund to wallet", "ac": "AC-2" }, { "text": "loyalty points revoked?" } ] },
|
|
174
|
+
{ "from": "Shipped", "event": "cancel", "to": "Cancelled", "hotspot": "allowed after shipping?" }
|
|
175
|
+
],
|
|
176
|
+
"forbiddenTransitions": [ { "from": "Delivered", "event": "cancel" } ]
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
- `actor`: who performs the step (user, app, service, db, cron); missing means `user`.
|
|
180
|
+
- `effects[]`: what else changes. An effect with `ac` is covered by that AC; one without `ac` is a **side effect** no AC covers.
|
|
181
|
+
- `hotspot`: an open question (string) or `true`.
|
|
182
|
+
- `flowSubject`: the entity whose status the flow describes.
|
|
183
|
+
- `forbiddenTransitions`: state/event pairs the human decided are invalid.
|
|
184
|
+
- `plainSummary`: one sentence for non-technical readers (used by `recap --for client`, at most 240 characters).
|
|
185
|
+
|
|
186
|
+
The Goal gate rejects an `ac` that is not an AC id, more than 40 steps or 12 effects per step, and forbidden pairs naming an unknown state or event.
|
|
187
|
+
|
|
188
|
+
`goal draft` returns `diagramOptions` (recommended first) and counts in `flow`: `undecided` (state × event pairs nobody decided), `hotspots` (plus conflicting transitions) and `sideEffects`. No file is written. Recommendations: `state` when `flowSubject` is set, `lanes` when steps run across a non-user actor, `storyboard` when every step is a user action. A project sets its default with `- **freeze_diagram**: auto | state | storyboard | lanes | off` in `.ai-engineering-loop/workflow.md` (`off` stops the offer; the command still works).
|
|
189
|
+
|
|
190
|
+
Render only the view the human picks:
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
npx ai-engineering-loop goal diagram --view state|storyboard|lanes [--run <id>] [--lang <tag>] [--open]
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
It writes `runs/<id>/diagrams/<view>-r<revision>.html` (`<view>-frozen.html` after freeze): one offline page, light and dark.
|
|
197
|
+
- **state**: a top-to-bottom state machine (`event [guard]`, effect counts, dashed red hotspots) and a transition table over every state × event. A cell is the target, several guarded targets, `conflict`, `invalid` (forbidden) or `?` (undecided).
|
|
198
|
+
- **storyboard**: one card per state in flow order, effects under the action that causes them.
|
|
199
|
+
- **lanes**: one column per actor, steps from top to bottom, so jobs and cron that run later stand out, followed by the same steps as a full-text list.
|
|
200
|
+
|
|
201
|
+
Then ask the human: freeze, another view, or turn `?` cells, hotspots and side effects into AC, non-goals or `forbiddenTransitions` (a new draft revision). A diagram never freezes or changes the Run.
|
|
202
|
+
|
|
165
203
|
## Verification artifacts in the receipt (C-21)
|
|
166
204
|
|
|
167
205
|
The receipt lists `--evidence AC-N=<https-url>` links first, typed as video, screenshot or diagram from the URL. An AC with `crossComponent: true` or a `rubric` is `MISSING` (❌) until it has at least one such link, because a reviewer should be able to look at the behaviour rather than read the diff.
|
package/core/recap.md
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Recap: what shipped in the last N days
|
|
2
|
+
|
|
3
|
+
`ael recap` turns local Run artifacts into one offline HTML page for a period (C-28). It never changes a Run and never calls a model: every number comes from a Run file.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npx ai-engineering-loop recap [--days 7] [--for me|lead|client] [--projects <path,...>|all] [--out <file>] [--lang <tag>] [--open] [--json]
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
- `--days`: window length, 1 to 366 (default 7). Runs are grouped by the time in their id.
|
|
10
|
+
- `--for`: which tab opens first. All three are in the file.
|
|
11
|
+
- `--projects`: default is the current project; `all` reads every registered project (`ael projects`). A client recap covers one project only.
|
|
12
|
+
- `--lang`: the language of the Goal text (for example `id`), so screen readers pronounce it right. The page chrome stays English.
|
|
13
|
+
- Output: `.ai-engineering-loop/recaps/recap-<from>-<to>-<for>.html` (mode 0600). It stays local; share it on purpose.
|
|
14
|
+
|
|
15
|
+
There is no built-in schedule. To get one every few days, run it from cron or a scheduled agent.
|
|
16
|
+
|
|
17
|
+
## The three views
|
|
18
|
+
|
|
19
|
+
| View | Shows | Never shows |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| For me | runs, first-try PASS rate, median cycle time, delivered; activity per day × project; cycle time per run split into goal, maker, verify, review+judge, deliver (from `state.json` history); ITERATE causes | |
|
|
22
|
+
| For the lead | delivered, first-try PASS rate, median cycle time, T2 runs; one card per run with verdict, tier, iterations, green checks, files outside the impact map; an evidence drawer with ACs and their evidence, verification commands with exit code and duration, the Judge reason and links to the artifact files | stdout or stderr |
|
|
23
|
+
| For the client | a "what's new" timeline of delivered runs and what is in progress | file paths, commands, findings, tiers, iterations, branch names |
|
|
24
|
+
|
|
25
|
+
Comparisons ("up 2 vs previous period") appear only when the previous window of the same length has runs.
|
|
26
|
+
|
|
27
|
+
## Text for clients
|
|
28
|
+
|
|
29
|
+
The client sentence is the Goal's `plainSummary`, else `businessOutcome`, else `objective`. When a delivered run falls back to the objective, the lead tab lists it under "Before you share the client tab"; the client tab itself never shows that note. The recap never rewrites it, so write `plainSummary` in the Goal when the work will be shown to a client.
|
package/lib/cli-args.js
CHANGED
|
@@ -24,6 +24,7 @@ const WRITER_COMMANDS = Object.freeze({
|
|
|
24
24
|
valued: ['--host', '--model', '--scenario', '--repeat', '--bin', '--mode', '--timeout', '--host-arg', '--without'],
|
|
25
25
|
positionals: []
|
|
26
26
|
},
|
|
27
|
+
recap: { flags: ['--json', '--open'], valued: ['--days', '--for', '--projects', '--out', '--now', '--lang'], positionals: [] },
|
|
27
28
|
migrate: { flags: ['--json', '--dry-run'], valued: ['--from'], positionals: [] },
|
|
28
29
|
debt: { flags: ['--json'], valued: ['--by', '--note', '--file'], positionals: null },
|
|
29
30
|
outcome: { flags: ['--json'], valued: ['--run', '--source', '--location', '--summary', '--evidence', '--by'], positionals: ['record'] },
|
|
@@ -0,0 +1,339 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const { VIEWS, flowActors, flowCounts, flowWarnings, transitionTable } = require('./flow.js');
|
|
4
|
+
|
|
5
|
+
const TILE_W = 200;
|
|
6
|
+
const TILE_H = 56;
|
|
7
|
+
const TILE_GAP = 56;
|
|
8
|
+
const GUTTER = 280;
|
|
9
|
+
const LINE = 20;
|
|
10
|
+
const PAD = 24;
|
|
11
|
+
|
|
12
|
+
function escapeHtml(value) {
|
|
13
|
+
return String(value ?? '').replace(/[&<>"']/g, (ch) => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' }[ch]));
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
const label = (step) => `${step.event}${step.guard ? ` [${step.guard}]` : ''}`;
|
|
17
|
+
const clip = (value, max) => {
|
|
18
|
+
const textValue = String(value ?? '');
|
|
19
|
+
return textValue.length > max ? `${textValue.slice(0, max - 1)}…` : textValue;
|
|
20
|
+
};
|
|
21
|
+
const hotspotText = (step) => (step.hotspot === true ? 'undecided' : step.hotspot);
|
|
22
|
+
const sideCount = (step) => (step.effects || []).filter((effect) => !effect.ac).length;
|
|
23
|
+
|
|
24
|
+
const STYLE = `
|
|
25
|
+
:root{--bg:#f5f7fa;--grid:#e9edf3;--paper:#fff;--ink:#141821;--muted:#4f5867;--line:#cfd6e1;--edge:#475467;--accent:#4338ca;--side:#92400e;--sidebg:#fff3dc;--hot:#b42318;--hotbg:#fee4e2;--ok:#05603a;--okbg:#dcfae6;--mono:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;--sans:system-ui,-apple-system,"Segoe UI",Roboto,sans-serif}
|
|
26
|
+
@media (prefers-color-scheme:dark){:root{--bg:#0d1016;--grid:#171c26;--paper:#161b24;--ink:#eef1f6;--muted:#a8b1c0;--line:#2e3646;--edge:#aab4c4;--accent:#a5b4fc;--side:#fcd27b;--sidebg:#3b2908;--hot:#fda29b;--hotbg:#47150f;--ok:#75e0a7;--okbg:#0b3324}}
|
|
27
|
+
*{box-sizing:border-box}
|
|
28
|
+
html{-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}
|
|
29
|
+
body{margin:0;background-color:var(--bg);background-image:linear-gradient(var(--grid) 1px,transparent 1px),linear-gradient(90deg,var(--grid) 1px,transparent 1px);background-size:24px 24px;color:var(--ink);font:400 1rem/1.55 var(--sans)}
|
|
30
|
+
.wrap{max-width:72rem;margin:0 auto;padding:2.25rem 1rem 4.5rem}
|
|
31
|
+
header{display:flex;justify-content:space-between;gap:1.5rem;align-items:flex-end;flex-wrap:wrap;margin-bottom:1.25rem}
|
|
32
|
+
h1{font-size:1.75rem;line-height:1.2;letter-spacing:-0.015em;margin:.25rem 0 0;font-weight:650;max-width:40ch;text-wrap:balance}
|
|
33
|
+
h2{font-size:1.125rem;line-height:1.3;margin:0 0 .25rem;font-weight:650}
|
|
34
|
+
.sub{margin:0 0 1rem;color:var(--muted);font-size:.9375rem;max-width:70ch}
|
|
35
|
+
.kicker{margin:0;color:var(--muted);font-family:var(--mono);font-size:.8125rem}
|
|
36
|
+
.counts{display:flex;gap:.625rem;flex-wrap:wrap}
|
|
37
|
+
.count{background:var(--paper);border:1px solid var(--line);border-radius:12px;padding:.5rem .875rem;min-width:7rem}
|
|
38
|
+
.count b{display:block;font-size:1.5rem;line-height:1.2;font-variant-numeric:tabular-nums}.count span{font-size:.8125rem;color:var(--muted)}
|
|
39
|
+
.count.alert b{color:var(--side)}
|
|
40
|
+
.panel{background:var(--paper);border:1px solid var(--line);border-radius:16px;padding:1.5rem;margin-bottom:1.125rem}
|
|
41
|
+
.scroll{overflow-x:auto;margin:0 -0.25rem;padding:0 .25rem}
|
|
42
|
+
.hint{display:none;font-size:.8125rem;color:var(--muted);margin:0 0 .5rem}
|
|
43
|
+
@media (max-width:48rem){.hint{display:block}}
|
|
44
|
+
.scroll:focus-visible{outline:2px solid var(--accent);outline-offset:4px;border-radius:8px}
|
|
45
|
+
.legend{display:flex;gap:.5rem 1.25rem;flex-wrap:wrap;font-size:.875rem;color:var(--muted);margin-top:1rem;padding-top:.875rem;border-top:1px solid var(--line)}
|
|
46
|
+
.legend span{white-space:nowrap}
|
|
47
|
+
.swatch{display:inline-block;width:1.75rem;height:0;margin-right:.5rem;vertical-align:middle;border-top:2px solid var(--edge)}
|
|
48
|
+
.swatch.hot{border-top:2px dashed var(--hot)}
|
|
49
|
+
svg{display:block;max-width:none}
|
|
50
|
+
svg text{font-family:var(--mono);font-size:13px;fill:var(--ink)}
|
|
51
|
+
svg .title{font-family:var(--sans);font-size:15px;font-weight:600}
|
|
52
|
+
svg .meta{fill:var(--muted)}
|
|
53
|
+
svg .tile{fill:var(--paper);stroke:var(--line);stroke-width:1.5}
|
|
54
|
+
svg .tile.initial{stroke:var(--accent);stroke-width:2.5}
|
|
55
|
+
svg .tile.end{stroke-dasharray:2 0;fill:var(--bg)}
|
|
56
|
+
svg .tile.warn{stroke:var(--side);stroke-dasharray:6 4}
|
|
57
|
+
svg .edge{fill:none;stroke:var(--edge);stroke-width:1.5}
|
|
58
|
+
svg .edge.hotspot{stroke:var(--hot);stroke-dasharray:7 5}
|
|
59
|
+
svg .lbl{paint-order:stroke;stroke:var(--paper);stroke-width:6px;stroke-linejoin:round}
|
|
60
|
+
svg .effect{fill:var(--ok)}
|
|
61
|
+
svg .effect.side{fill:var(--side);font-weight:600}
|
|
62
|
+
svg .hotspot-text{fill:var(--hot);font-weight:600}
|
|
63
|
+
svg .lane{fill:var(--bg);stroke:var(--line)}
|
|
64
|
+
svg .lane-name{font-family:var(--sans);font-size:14px;font-weight:600;fill:var(--muted)}
|
|
65
|
+
table.transitions{border-collapse:separate;border-spacing:0;width:100%;font-size:.9375rem}
|
|
66
|
+
table.transitions th,table.transitions td{border-bottom:1px solid var(--line);padding:.625rem .75rem;text-align:start;vertical-align:top}
|
|
67
|
+
table.transitions thead th{color:var(--muted);font-weight:600;font-family:var(--mono);font-size:.8125rem;white-space:nowrap}
|
|
68
|
+
table.transitions tbody th{font-weight:600;white-space:nowrap}
|
|
69
|
+
td.cell.undecided{background:var(--sidebg);color:var(--side);font-weight:650}
|
|
70
|
+
td.cell.invalid{color:var(--muted)}
|
|
71
|
+
td.cell.conflict{background:var(--hotbg);color:var(--hot);font-weight:600}
|
|
72
|
+
.ends{color:var(--muted);font-size:.9375rem;margin:.75rem 0 0}
|
|
73
|
+
.board{display:grid;grid-template-columns:repeat(auto-fill,minmax(15rem,1fr));gap:1rem;counter-reset:frame}
|
|
74
|
+
.frame{background:var(--paper);border:1.5px solid var(--line);border-radius:31.5px;padding:1rem;display:flex;flex-direction:column;gap:.625rem;counter-increment:frame}
|
|
75
|
+
.frame.initial{border-color:var(--accent);border-width:2.5px}
|
|
76
|
+
.screen{border:1px solid var(--line);border-radius:14px;padding:.875rem;min-height:5.5rem;background:var(--bg)}
|
|
77
|
+
.screen small{display:block;font-family:var(--mono);font-size:.75rem;color:var(--muted)}
|
|
78
|
+
.screen small::before{content:"Step " counter(frame)}
|
|
79
|
+
.screen b{font-size:1.0625rem;line-height:1.3;overflow-wrap:break-word}
|
|
80
|
+
.step{font-family:var(--mono);font-size:.875rem;line-height:1.5;border-top:1px dashed var(--line);padding-top:.5rem;overflow-wrap:break-word}
|
|
81
|
+
.step.hotspot{color:var(--hot)}
|
|
82
|
+
.chips{display:flex;flex-wrap:wrap;gap:.375rem;margin-top:.375rem}
|
|
83
|
+
.pill{display:inline-block;font-size:.8125rem;line-height:1.4;padding:.1875rem .625rem;border-radius:999px;background:var(--okbg);color:var(--ok);font-family:var(--mono);overflow-wrap:anywhere}
|
|
84
|
+
.pill.side{background:var(--sidebg);color:var(--side);border:1px dashed var(--side)}
|
|
85
|
+
.pill.side::before{content:"not in AC · "}
|
|
86
|
+
.pill.hotspot{background:var(--hotbg);color:var(--hot)}
|
|
87
|
+
.pill.hotspot::before{content:"decide · "}
|
|
88
|
+
ol.steps{margin:1.25rem 0 0;padding:0;list-style:none;display:grid;gap:.5rem}
|
|
89
|
+
ol.steps li{border-top:1px dashed var(--line);padding-top:.5rem;font-size:.9375rem;max-width:80ch}
|
|
90
|
+
ol.steps b{font-family:var(--mono);font-size:.8125rem;color:var(--muted);margin-right:.5rem}
|
|
91
|
+
ul.notes{margin:0;padding-left:1.125rem;color:var(--muted);max-width:70ch}
|
|
92
|
+
@media (max-width:40rem){h1{font-size:1.375rem}.panel{padding:1rem}}
|
|
93
|
+
`;
|
|
94
|
+
|
|
95
|
+
function legendHtml(view) {
|
|
96
|
+
const items = [
|
|
97
|
+
'<span><i class="swatch"></i>transition</span>',
|
|
98
|
+
'<span><i class="swatch hot"></i>hotspot: decide before freeze</span>',
|
|
99
|
+
'<span><span class="pill">effect · AC-n</span> covered by an AC</span>',
|
|
100
|
+
'<span><span class="pill side">effect</span> side effect</span>'
|
|
101
|
+
];
|
|
102
|
+
if (view === 'state') items.push('<span><b>?</b> = nobody decided this transition</span>');
|
|
103
|
+
return `<div class="legend">${items.join('')}</div>`;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function scrollBox(inner, title, what = 'diagram') {
|
|
107
|
+
return `<p class="hint">Scroll sideways to see the whole ${what} →</p><div class="scroll" tabindex="0" role="region" aria-label="${escapeHtml(title)}">${inner}</div>`;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
function svg(width, height, body, title) {
|
|
111
|
+
return scrollBox(`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img" aria-label="${escapeHtml(title)}"><defs><marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/></marker></defs>${body}</svg>`, title);
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
function edgeLabel(step, x, y, anchor = 'start') {
|
|
115
|
+
const total = (step.effects || []).length;
|
|
116
|
+
const side = sideCount(step);
|
|
117
|
+
const effects = total ? `<tspan class="effect${side ? ' side' : ''}"> · ${total} effect${total > 1 ? 's' : ''}${side ? `, ${side} not in AC` : ''}</tspan>` : '';
|
|
118
|
+
const hot = step.hotspot ? `<tspan class="hotspot-text hotspot"> · decide</tspan>` : '';
|
|
119
|
+
return `<text class="lbl" x="${x}" y="${y}" text-anchor="${anchor}"><title>${escapeHtml(label(step))}</title>${escapeHtml(clip(label(step), 28))}${effects}${hot}</text>`;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
function layering(flow) {
|
|
123
|
+
const states = [...new Set(flow.flatMap((step) => [step.from, step.to]))];
|
|
124
|
+
const outgoing = new Map(states.map((state) => [state, flow.filter((step) => step.from === state && step.to !== state)]));
|
|
125
|
+
const back = new Set();
|
|
126
|
+
const visiting = new Set();
|
|
127
|
+
const done = new Set();
|
|
128
|
+
const visit = (state) => {
|
|
129
|
+
visiting.add(state);
|
|
130
|
+
for (const step of outgoing.get(state)) {
|
|
131
|
+
if (visiting.has(step.to)) back.add(step);
|
|
132
|
+
else if (!done.has(step.to)) visit(step.to);
|
|
133
|
+
}
|
|
134
|
+
visiting.delete(state);
|
|
135
|
+
done.add(state);
|
|
136
|
+
};
|
|
137
|
+
for (const state of states) if (!done.has(state)) visit(state);
|
|
138
|
+
const rank = new Map(states.map((state) => [state, 0]));
|
|
139
|
+
for (let pass = 0; pass < states.length; pass += 1) {
|
|
140
|
+
for (const step of flow) {
|
|
141
|
+
if (step.from === step.to || back.has(step)) continue;
|
|
142
|
+
if (rank.get(step.to) < rank.get(step.from) + 1) rank.set(step.to, rank.get(step.from) + 1);
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
return { states, rank, back };
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
function stateSvg(goal) {
|
|
149
|
+
const flow = goal.flow;
|
|
150
|
+
const warned = flowWarnings(flow).join(' ');
|
|
151
|
+
const { states, rank, back } = layering(flow);
|
|
152
|
+
const sources = new Set(flow.map((step) => step.from));
|
|
153
|
+
const forward = flow.filter((step) => step.from !== step.to && !back.has(step));
|
|
154
|
+
const adjacent = forward.filter((step) => rank.get(step.to) - rank.get(step.from) === 1);
|
|
155
|
+
const long = forward.filter((step) => rank.get(step.to) - rank.get(step.from) > 1);
|
|
156
|
+
const rows = new Map();
|
|
157
|
+
for (const state of states) {
|
|
158
|
+
const r = rank.get(state);
|
|
159
|
+
if (!rows.has(r)) rows.set(r, []);
|
|
160
|
+
rows.get(r).push(state);
|
|
161
|
+
}
|
|
162
|
+
const rowCount = Math.max(...rows.keys()) + 1;
|
|
163
|
+
const widest = Math.max(...[...rows.values()].map((list) => list.length));
|
|
164
|
+
const left = PAD + (back.size ? GUTTER : 0);
|
|
165
|
+
const gapAfter = new Map();
|
|
166
|
+
for (let r = 0; r < rowCount; r += 1) {
|
|
167
|
+
const leaving = adjacent.filter((step) => rank.get(step.from) === r).length;
|
|
168
|
+
const arriving = long.filter((step) => rank.get(step.to) === r + 1).length;
|
|
169
|
+
gapAfter.set(r, 36 + (leaving + arriving) * LINE);
|
|
170
|
+
}
|
|
171
|
+
const rowY = new Map();
|
|
172
|
+
let y = PAD + 20;
|
|
173
|
+
for (let r = 0; r < rowCount; r += 1) {
|
|
174
|
+
rowY.set(r, y);
|
|
175
|
+
y += TILE_H + gapAfter.get(r);
|
|
176
|
+
}
|
|
177
|
+
const bodyRight = left + widest * TILE_W + (widest - 1) * TILE_GAP;
|
|
178
|
+
const width = bodyRight + (long.length || flow.some((step) => step.from === step.to) ? GUTTER : 0) + PAD;
|
|
179
|
+
const height = y - gapAfter.get(rowCount - 1) + PAD + 20;
|
|
180
|
+
const pos = new Map();
|
|
181
|
+
for (const [r, list] of rows) {
|
|
182
|
+
const offset = ((widest - list.length) * (TILE_W + TILE_GAP)) / 2;
|
|
183
|
+
list.forEach((state, i) => pos.set(state, { x: left + offset + i * (TILE_W + TILE_GAP), y: rowY.get(r) }));
|
|
184
|
+
}
|
|
185
|
+
const outs = new Map(states.map((state) => [state, adjacent.filter((step) => step.from === state)]));
|
|
186
|
+
const ins = new Map(states.map((state) => [state, forward.filter((step) => step.to === state)]));
|
|
187
|
+
const portX = (list, step, p) => p.x + ((list.indexOf(step) + 1) * TILE_W) / (list.length + 1);
|
|
188
|
+
const edges = [];
|
|
189
|
+
const labels = [];
|
|
190
|
+
const rowSlot = new Map();
|
|
191
|
+
for (const step of adjacent) {
|
|
192
|
+
const a = pos.get(step.from);
|
|
193
|
+
const b = pos.get(step.to);
|
|
194
|
+
const r = rank.get(step.from);
|
|
195
|
+
const slot = rowSlot.get(r) || 0;
|
|
196
|
+
rowSlot.set(r, slot + 1);
|
|
197
|
+
const x1 = portX(outs.get(step.from), step, a);
|
|
198
|
+
const x2 = portX(ins.get(step.to), step, b);
|
|
199
|
+
const mid = a.y + TILE_H + 26 + slot * LINE;
|
|
200
|
+
edges.push(`<path class="edge${step.hotspot ? ' hotspot' : ''}" d="M${x1} ${a.y + TILE_H} V${mid} H${x2} V${b.y - 4}" marker-end="url(#arrow)"/>`);
|
|
201
|
+
labels.push(edgeLabel(step, Math.min(x1, x2) + 10, mid - 5));
|
|
202
|
+
}
|
|
203
|
+
long.forEach((step, i) => {
|
|
204
|
+
const a = pos.get(step.from);
|
|
205
|
+
const b = pos.get(step.to);
|
|
206
|
+
const gx = bodyRight + 24 + i * 14;
|
|
207
|
+
const r = rank.get(step.to) - 1;
|
|
208
|
+
const slot = rowSlot.get(r) || 0;
|
|
209
|
+
rowSlot.set(r, slot + 1);
|
|
210
|
+
const lane = rowY.get(r) + TILE_H + 26 + slot * LINE;
|
|
211
|
+
const x2 = portX(ins.get(step.to), step, b);
|
|
212
|
+
edges.push(`<path class="edge${step.hotspot ? ' hotspot' : ''}" d="M${a.x + TILE_W} ${a.y + TILE_H / 2} H${gx} V${lane} H${x2} V${b.y - 4}" marker-end="url(#arrow)"/>`);
|
|
213
|
+
labels.push(edgeLabel(step, x2 + 10, lane - 5));
|
|
214
|
+
});
|
|
215
|
+
[...back].forEach((step, i) => {
|
|
216
|
+
const a = pos.get(step.from);
|
|
217
|
+
const b = pos.get(step.to);
|
|
218
|
+
const gx = left - 24 - i * 14;
|
|
219
|
+
edges.push(`<path class="edge${step.hotspot ? ' hotspot' : ''}" d="M${a.x} ${a.y + TILE_H / 2} H${gx} V${b.y + TILE_H / 2} H${b.x - 4}" marker-end="url(#arrow)"/>`);
|
|
220
|
+
labels.push(edgeLabel(step, gx - 10, a.y + TILE_H / 2 - 6, 'end'));
|
|
221
|
+
});
|
|
222
|
+
for (const step of flow.filter((item) => item.from === item.to)) {
|
|
223
|
+
const a = pos.get(step.from);
|
|
224
|
+
const yy = a.y + TILE_H / 2;
|
|
225
|
+
edges.push(`<path class="edge${step.hotspot ? ' hotspot' : ''}" d="M${a.x + TILE_W} ${yy - 10} H${a.x + TILE_W + 22} V${yy + 10} H${a.x + TILE_W + 4}" marker-end="url(#arrow)"/>`);
|
|
226
|
+
labels.push(edgeLabel(step, a.x + TILE_W + 30, yy + 4));
|
|
227
|
+
}
|
|
228
|
+
const tiles = states.map((state) => {
|
|
229
|
+
const p = pos.get(state);
|
|
230
|
+
const cls = ['tile', state === flow[0].from ? 'initial' : '', sources.has(state) ? '' : 'end', warned.includes(`"${state}"`) ? 'warn' : ''].filter(Boolean).join(' ');
|
|
231
|
+
const tag = state === flow[0].from ? 'start' : sources.has(state) ? '' : 'end state';
|
|
232
|
+
return `<g><title>${escapeHtml(state)}</title><rect class="${cls}" x="${p.x}" y="${p.y}" width="${TILE_W}" height="${TILE_H}" rx="12"/><text class="title" x="${p.x + TILE_W / 2}" y="${p.y + (tag ? 25 : 33)}" text-anchor="middle">${escapeHtml(clip(state, 22))}</text>${tag ? `<text class="meta" x="${p.x + TILE_W / 2}" y="${p.y + 44}" text-anchor="middle">${tag}</text>` : ''}</g>`;
|
|
233
|
+
}).join('');
|
|
234
|
+
return svg(width, height, `${edges.join('')}${tiles}${labels.join('')}`, `State machine of ${goal.flowSubject || 'the Goal flow'}`);
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
function tableHtml(goal) {
|
|
238
|
+
const table = transitionTable(goal);
|
|
239
|
+
const head = `<thead><tr><th scope="col">state \\ event</th>${table.events.map((event) => `<th scope="col">${escapeHtml(event)}</th>`).join('')}</tr></thead>`;
|
|
240
|
+
const rows = table.rows.map((row) => `<tr><th scope="row">${escapeHtml(row.state)}</th>${table.events.map((event) => {
|
|
241
|
+
const c = row.cells[event];
|
|
242
|
+
if (c.kind === 'undecided') return '<td class="cell undecided">?</td>';
|
|
243
|
+
if (c.kind === 'invalid') return '<td class="cell invalid">invalid</td>';
|
|
244
|
+
const body = c.targets.map((t) => {
|
|
245
|
+
const step = goal.flow.find((item) => item.from === row.state && item.event === event && item.to === t.to);
|
|
246
|
+
const chips = [
|
|
247
|
+
...(step?.effects || []).map((effect) => `<span class="pill${effect.ac ? '' : ' side'}">${escapeHtml(effect.text)}${effect.ac ? ` · ${escapeHtml(effect.ac)}` : ''}</span>`),
|
|
248
|
+
step?.hotspot ? `<span class="pill hotspot">${escapeHtml(hotspotText(step))}</span>` : ''
|
|
249
|
+
].filter(Boolean).join('');
|
|
250
|
+
return `→ ${escapeHtml(t.to)}${t.guard ? ` [${escapeHtml(t.guard)}]` : ''}${chips ? `<div class="chips">${chips}</div>` : ''}`;
|
|
251
|
+
}).join('<br>');
|
|
252
|
+
return `<td class="cell ${c.kind}">${c.kind === 'conflict' ? 'conflict: ' : ''}${body}</td>`;
|
|
253
|
+
}).join('')}</tr>`).join('');
|
|
254
|
+
const ends = table.endStates.length ? `<p class="ends">End states: ${table.endStates.map(escapeHtml).join(', ')}</p>` : '';
|
|
255
|
+
return `<section class="panel"><h2>Transition table</h2><p class="sub">Every state × event. Each <b>?</b> is a decision the Goal has not made: add an AC, a non-goal, or list it in <code>forbiddenTransitions</code>.</p>${scrollBox(`<table class="transitions">${head}<tbody>${rows}</tbody></table>`, 'Transition table', 'table')}${ends}</section>`;
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
function storyboardHtml(goal) {
|
|
259
|
+
const flow = goal.flow;
|
|
260
|
+
const states = [...new Set(flow.flatMap((step) => [step.from, step.to]))];
|
|
261
|
+
const frames = states.map((state) => {
|
|
262
|
+
const steps = flow.filter((step) => step.from === state).map((step) => {
|
|
263
|
+
const chips = [
|
|
264
|
+
...(step.effects || []).map((effect) => `<span class="pill${effect.ac ? '' : ' side'}">${escapeHtml(effect.text)}${effect.ac ? ` · ${escapeHtml(effect.ac)}` : ''}</span>`),
|
|
265
|
+
step.hotspot ? `<span class="pill hotspot">${escapeHtml(hotspotText(step))}</span>` : ''
|
|
266
|
+
].filter(Boolean).join('');
|
|
267
|
+
return `<div class="step${step.hotspot ? ' hotspot' : ''}">${escapeHtml(`${label(step)} → ${step.to}`)}${chips ? `<div class="chips">${chips}</div>` : ''}</div>`;
|
|
268
|
+
}).join('');
|
|
269
|
+
return `<li class="frame${state === flow[0].from ? ' initial' : ''}"><div class="screen"><small></small><b>${escapeHtml(state)}</b></div>${steps || '<div class="step">End of flow</div>'}</li>`;
|
|
270
|
+
});
|
|
271
|
+
return `<section class="panel"><h2>Storyboard</h2><p class="sub">One card per screen or state, in the order the flow first reaches it. Effects sit under the action that causes them.</p><ol class="board" style="list-style:none;padding:0;margin:0">${frames.join('')}</ol>${legendHtml('storyboard')}</section>`;
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
function lanesSvg(goal) {
|
|
275
|
+
const flow = goal.flow;
|
|
276
|
+
const actors = flowActors(flow);
|
|
277
|
+
const colW = TILE_W + 72;
|
|
278
|
+
const head = 44;
|
|
279
|
+
const effectLines = (step) => (step.effects || []).length + (step.hotspot ? 1 : 0);
|
|
280
|
+
const rowY = [];
|
|
281
|
+
let y = PAD + head;
|
|
282
|
+
for (const step of flow) {
|
|
283
|
+
rowY.push(y);
|
|
284
|
+
y += TILE_H + 34 + effectLines(step) * LINE;
|
|
285
|
+
}
|
|
286
|
+
const width = PAD * 2 + actors.length * colW;
|
|
287
|
+
const height = y + PAD - 20;
|
|
288
|
+
const actorOf = (step) => (step.actor ? String(step.actor).trim() : 'user');
|
|
289
|
+
const colX = (actor) => PAD + actors.indexOf(actor) * colW + (colW - TILE_W) / 2;
|
|
290
|
+
const lanes = actors.map((actor, i) => `<rect class="lane" x="${PAD + i * colW + 6}" y="${PAD}" width="${colW - 12}" height="${height - PAD * 2}" rx="12"/><text class="lane-name" x="${PAD + i * colW + colW / 2}" y="${PAD + 26}" text-anchor="middle">${escapeHtml(clip(actor, 20))}</text>`).join('');
|
|
291
|
+
const parts = [];
|
|
292
|
+
flow.forEach((step, i) => {
|
|
293
|
+
const x = colX(actorOf(step));
|
|
294
|
+
const ty = rowY[i];
|
|
295
|
+
const effects = (step.effects || []).map((effect, k) => `<text class="effect${effect.ac ? '' : ' side'} lbl" x="${x + 4}" y="${ty + TILE_H + 20 + k * LINE}">${escapeHtml(`${effect.ac ? '' : 'not in AC: '}${clip(effect.text, 24)}${effect.ac ? ` · ${effect.ac}` : ''}`)}</text>`).join('');
|
|
296
|
+
const hot = step.hotspot ? `<text class="hotspot-text hotspot lbl" x="${x + 4}" y="${ty + TILE_H + 20 + (step.effects || []).length * LINE}">${escapeHtml(`decide: ${clip(hotspotText(step), 22)}`)}</text>` : '';
|
|
297
|
+
parts.push(`<g><title>${escapeHtml(`${label(step)}: ${step.from} → ${step.to}`)}</title><rect class="tile${step.hotspot ? ' warn' : ''}" x="${x}" y="${ty}" width="${TILE_W}" height="${TILE_H}" rx="10"/><text class="title" x="${x + 12}" y="${ty + 23}">${escapeHtml(clip(label(step), 22))}</text><text class="meta" x="${x + 12}" y="${ty + 43}">${escapeHtml(clip(`${step.from} → ${step.to}`, 24))}</text>${effects}${hot}</g>`);
|
|
298
|
+
if (i > 0) {
|
|
299
|
+
const prev = flow[i - 1];
|
|
300
|
+
const px = colX(actorOf(prev)) + TILE_W / 2;
|
|
301
|
+
const nx = x + TILE_W / 2;
|
|
302
|
+
const from = rowY[i - 1] + TILE_H;
|
|
303
|
+
const mid = ty - 14;
|
|
304
|
+
parts.unshift(`<path class="edge${step.hotspot ? ' hotspot' : ''}" d="M${px} ${from} V${mid} H${nx} V${ty - 4}" marker-end="url(#arrow)"/>`);
|
|
305
|
+
}
|
|
306
|
+
});
|
|
307
|
+
return svg(width, height, `${lanes}${parts.join('')}`, 'Actor lanes');
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
function stepsList(goal) {
|
|
311
|
+
const items = goal.flow.map((step, i) => {
|
|
312
|
+
const effects = (step.effects || []).map((effect) => `<span class="pill${effect.ac ? '' : ' side'}">${escapeHtml(effect.text)}${effect.ac ? ` · ${escapeHtml(effect.ac)}` : ''}</span>`);
|
|
313
|
+
if (step.hotspot) effects.push(`<span class="pill hotspot">${escapeHtml(hotspotText(step))}</span>`);
|
|
314
|
+
return `<li><b>${i + 1}. ${escapeHtml(step.actor ? String(step.actor).trim() : 'user')}</b>${escapeHtml(`${label(step)}: ${step.from} → ${step.to}`)}${effects.length ? `<div class="chips">${effects.join('')}</div>` : ''}</li>`;
|
|
315
|
+
}).join('');
|
|
316
|
+
return `<h3 class="sub" style="margin:1.25rem 0 0">Steps in order</h3><ol class="steps">${items}</ol>`;
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
function renderDiagram(goal, { view, revision, now = new Date(), lang = null } = {}) {
|
|
320
|
+
const contentLang = lang ? ` lang="${escapeHtml(lang)}"` : '';
|
|
321
|
+
if (!VIEWS.includes(view)) throw new Error(`Unknown view "${view}": use state, storyboard or lanes`);
|
|
322
|
+
if (!Array.isArray(goal?.flow) || !goal.flow.length) throw new Error('The Goal has no flow to draw; add flow steps ({from, event, to}) to the draft first');
|
|
323
|
+
const counts = flowCounts(goal);
|
|
324
|
+
const titles = { state: 'State machine', storyboard: 'Storyboard', lanes: 'Actor lanes' };
|
|
325
|
+
let body;
|
|
326
|
+
if (view === 'state') {
|
|
327
|
+
body = `<section class="panel"><h2>${escapeHtml(goal.flowSubject ? `Status of ${goal.flowSubject}` : 'States')}</h2><p class="sub">Read top to bottom. Labels read <code>event [guard]</code>; dashed red lines are transitions still to decide.</p>${stateSvg(goal)}${legendHtml('state')}</section>${tableHtml(goal)}`;
|
|
328
|
+
} else if (view === 'storyboard') {
|
|
329
|
+
body = storyboardHtml(goal);
|
|
330
|
+
} else {
|
|
331
|
+
body = `<section class="panel"><h2>Actor lanes</h2><p class="sub">One column per actor, steps in flow order from top to bottom. Work that runs later (jobs, cron) shows up in its own column.</p>${lanesSvg(goal)}${stepsList(goal)}${legendHtml('lanes')}</section>`;
|
|
332
|
+
}
|
|
333
|
+
const warnings = flowWarnings(goal.flow);
|
|
334
|
+
const notes = warnings.length ? `<section class="panel"><h2>Flow warnings</h2><ul class="notes">${warnings.map((w) => `<li>${escapeHtml(w)}</li>`).join('')}</ul></section>` : '';
|
|
335
|
+
const count = (n, text) => `<div class="count${n ? ' alert' : ''}"><b>${n}</b><span>${escapeHtml(text)}</span></div>`;
|
|
336
|
+
return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escapeHtml(`${titles[view]} · ${clip(goal.objective || 'Goal', 60)}`)}</title><style>${STYLE}</style></head><body><main class="wrap"><header><div><p class="kicker">${escapeHtml(`AEL Goal · ${titles[view]} · revision ${revision ?? 'frozen'} · ${now.toISOString().slice(0, 16).replace('T', ' ')} UTC`)}</p><h1${contentLang}>${escapeHtml(goal.objective || '')}</h1></div><div class="counts">${count(counts.undecided, 'undecided')}${count(counts.hotspots, 'hotspots')}${count(counts.sideEffects, 'side effects')}</div></header><div${contentLang}>${body}</div>${notes}</main></body></html>`;
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
module.exports = { escapeHtml, renderDiagram };
|