mandrel 2.77.0 → 2.79.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/README.md +6 -1
- package/.agents/agents/auditor.md +2 -3
- package/.agents/audit-checklists/architecture.md +1 -0
- package/.agents/audit-checklists/clean-code.md +1 -0
- package/.agents/audit-checklists/devops.md +4 -1
- package/.agents/audit-checklists/security.md +1 -1
- package/.agents/docs/configuration.md +1 -1
- package/.agents/schemas/agentrc.schema.json +1 -1
- package/.agents/scripts/bootstrap.js +87 -16
- package/.agents/scripts/lib/audit-to-stories/build-story-body.js +48 -14
- package/.agents/scripts/lib/audit-to-stories/finding-bullets.js +33 -0
- package/.agents/scripts/lib/audit-to-stories/parse-audit-md.js +6 -4
- package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js +34 -19
- package/.agents/scripts/lib/bootstrap/commit-push.js +3 -2
- package/.agents/scripts/lib/bootstrap/manifest.js +2 -2
- package/.agents/scripts/lib/bootstrap/project-bootstrap.js +51 -15
- package/.agents/scripts/lib/bootstrap/prompt.js +30 -1
- package/.agents/scripts/lib/close-validation/commands.js +33 -0
- package/.agents/scripts/lib/close-validation/gates.js +11 -4
- package/.agents/scripts/lib/config/explain.js +2 -1
- package/.agents/scripts/lib/config-settings-schema.js +2 -1
- package/.agents/scripts/lib/findings/severity.js +33 -6
- package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
- package/.agents/scripts/lib/orchestration/story-handoff.js +15 -3
- package/.agents/scripts/lib/orchestration/verify-credit.js +9 -4
- package/.agents/scripts/lib/test-run-credit.js +46 -17
- package/.agents/workflows/audit-architecture.md +20 -4
- package/.agents/workflows/audit-baselines.md +3 -3
- package/.agents/workflows/audit-clean-code.md +17 -1
- package/.agents/workflows/audit-devops.md +58 -14
- package/.agents/workflows/audit-exceptions.md +3 -2
- package/.agents/workflows/audit-performance.md +22 -0
- package/.agents/workflows/audit-quality.md +30 -0
- package/.agents/workflows/audit-security.md +23 -8
- package/.agents/workflows/audit-to-stories.md +9 -6
- package/.agents/workflows/helpers/audit-lens-core.md +53 -8
- package/README.md +13 -1
- package/docs/CHANGELOG.md +22 -0
- package/lib/cli/registry.js +85 -12
- package/lib/cli/uninstall.js +34 -18
- package/lib/cli/update.js +37 -6
- package/lib/migrations/index.js +2 -0
- package/lib/migrations/steps/2.79.0-container-safe-projections.js +91 -0
- package/package.json +1 -1
package/.agents/README.md
CHANGED
|
@@ -269,7 +269,12 @@ and the prompt falls through to manual free-text entry — so a missing or
|
|
|
269
269
|
stale `gh` never breaks the run.
|
|
270
270
|
|
|
271
271
|
For non-interactive (CI) installs, pass `--owner`, `--repo`, and
|
|
272
|
-
`--assume-yes`; pass `--skip-github` to defer the remote half.
|
|
272
|
+
`--assume-yes`; pass `--skip-github` to defer the remote half. A
|
|
273
|
+
non-interactive run creates no Projects V2 board unless one is stored in
|
|
274
|
+
`.agentrc.json` or named with `--project-number <name>`; `--no-project` (or an
|
|
275
|
+
empty / `none` `--project-number` or `GH_PROJECT_NUMBER`) skips it explicitly,
|
|
276
|
+
and labels are still provisioned. Interactively declining a new project also
|
|
277
|
+
continues without a board.
|
|
273
278
|
|
|
274
279
|
After bootstrap, every Mandrel command is generated into a flat
|
|
275
280
|
`.claude/commands/` tree by `npm run sync:commands` (kept current at install
|
|
@@ -83,7 +83,8 @@ declares a deviation follows its own Scope section instead.
|
|
|
83
83
|
## Findings schema — the finding-block skeleton (MUST stay parseable)
|
|
84
84
|
|
|
85
85
|
Write the report with an `## Executive Summary` and a `## Detailed Findings`
|
|
86
|
-
section.
|
|
86
|
+
section. List findings in descending severity order (Critical first, Info
|
|
87
|
+
last). Every finding under Detailed Findings uses this shared skeleton; the
|
|
87
88
|
lens may **add** fields and may relabel `Severity` ↔ `Impact` and
|
|
88
89
|
`Dimension` ↔ `Category` ↔ `Type`, but never drops a shared field — the
|
|
89
90
|
`audit-to-stories` parser depends on this shape:
|
|
@@ -98,8 +99,6 @@ lens may **add** fields and may relabel `Severity` ↔ `Impact` and
|
|
|
98
99
|
- **Recommendation & Rationale:** [how to remediate and why it matters]
|
|
99
100
|
- **Acceptance signal:** [the command or observable that proves this finding is
|
|
100
101
|
remediated]
|
|
101
|
-
- **Agent Prompt:**
|
|
102
|
-
`[A copy-pasteable, highly specific prompt to execute this remediation independently]`
|
|
103
102
|
```
|
|
104
103
|
|
|
105
104
|
## Severity scale
|
|
@@ -13,6 +13,7 @@ Self-check your change against this lens's concerns before you ship:
|
|
|
13
13
|
- [ ] Cycle detection.
|
|
14
14
|
- [ ] Dead-export detection.
|
|
15
15
|
- [ ] Hotspot ranking.
|
|
16
|
+
- [ ] Non-JS ecosystems.
|
|
16
17
|
- [ ] LLM triage on top.
|
|
17
18
|
- [ ] Documented architecture boundaries
|
|
18
19
|
- [ ] Automated boundary checks
|
|
@@ -19,6 +19,7 @@ Self-check your change against this lens's concerns before you ship:
|
|
|
19
19
|
- [ ] Dynamic imports
|
|
20
20
|
- [ ] Test-only seams
|
|
21
21
|
- [ ] Framework/registration hooks
|
|
22
|
+
- [ ] Non-JS ecosystems.
|
|
22
23
|
- [ ] Churn-by-complexity hotspot cap.
|
|
23
24
|
- [ ] Logic Complexity
|
|
24
25
|
- [ ] Duplication
|
|
@@ -10,10 +10,13 @@
|
|
|
10
10
|
|
|
11
11
|
Self-check your change against this lens's concerns before you ship:
|
|
12
12
|
|
|
13
|
-
- [ ] Workflow static analysis (`actionlint
|
|
13
|
+
- [ ] Workflow static analysis (`actionlint`, GitHub Actions only).
|
|
14
14
|
- [ ] Workflow security posture (`zizmor`).
|
|
15
15
|
- [ ] Container linting (`hadolint`), presence-gated on Dockerfiles.
|
|
16
16
|
- [ ] Pipeline reliability history (`gh run list`).
|
|
17
|
+
- [ ] Google Cloud Build (gated: `cloudbuild*.yaml` present).
|
|
18
|
+
- [ ] GitLab CI (gated: `.gitlab-ci.yml` present).
|
|
19
|
+
- [ ] Python toolchain (gated: Python manifests present).
|
|
17
20
|
- [ ] Redundancy & Duplication
|
|
18
21
|
- [ ] Performance Gaps
|
|
19
22
|
- [ ] Security & Compliance
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
|
|
11
11
|
Self-check your change against this lens's concerns before you ship:
|
|
12
12
|
|
|
13
|
-
- [ ] Dependency CVEs
|
|
13
|
+
- [ ] Dependency CVEs, per detected ecosystem.
|
|
14
14
|
- [ ] Secret scanning (`gitleaks` / `trufflehog`), with a grep fallback.
|
|
15
15
|
- [ ] Grep battery (deterministic fallback / augmentation).
|
|
16
16
|
- [ ] Manual surface review.
|
|
@@ -85,7 +85,7 @@ Project identity, filesystem roots, planner docs context, and the commands the c
|
|
|
85
85
|
| `paths.tempRoot` | Yes | `string` | `"temp"` | Repo-relative gitignored scratch root. Every temporary artifact — gate transcripts, audit reports, plan authoring dirs — lands under it. |
|
|
86
86
|
| `docsContextFiles` | No | `array<string>` | `["architecture.md","data-dictionary.md","decisions.md","patterns.md"]` | Files under `paths.docsRoot` the planner treats as standing context. Read digest-first — the docs digest names the file and the line range, and only the named section is pulled. |
|
|
87
87
|
| `commands` | No | `object` | — | Shell commands the close-validation chain spawns. Each is run from the repo root. |
|
|
88
|
-
| `commands.test` | No | `string` | `"npm test"` | Full test-suite command
|
|
88
|
+
| `commands.test` | No | `string` | `"npm test"` | Full test-suite command close's `test` gate spawns, and the identity its `test` credit is hashed under — the deposit `run-tests.js` makes, close's credit probe and `verify[]` credit all key on it, as does `mandrel doctor`'s `test-credit-path` check. Set it for a non-npm project (e.g. `python3 scripts/validation.py`); unset, it is `npm test`. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution). |
|
|
89
89
|
| `commands.typecheck` | No | `string` \| `null` | `null` | Static type-check command. `null` disables the gate for projects with no type layer; the empty string is rejected so a typo cannot silently disable it. |
|
|
90
90
|
| `commands.lint` | No | `string` \| `null` | `null` | Lint command run as a close-validation gate. `null` (the default) uses `npm run lint`; the gate is mandatory, so unlike `typecheck` this key cannot disable it. Point it at the scoped command your hooks already run to stop paying for a third whole-repo lint at close — the gate still lints the diff, and CI still owns whole-repo drift. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution), so wrap a multi-linter pair in one npm script and name that. |
|
|
91
91
|
| `commands.formatCheck` | No | `string` | `"npx biome format ."` | Non-mutating format verification run as a close-validation gate. |
|
|
@@ -81,7 +81,7 @@
|
|
|
81
81
|
"pattern": "([;&|`]|\\$\\()"
|
|
82
82
|
},
|
|
83
83
|
"minLength": 1,
|
|
84
|
-
"description": "Full test-suite command
|
|
84
|
+
"description": "Full test-suite command close's `test` gate spawns, and the identity its `test` credit is hashed under — the deposit `run-tests.js` makes, close's credit probe and `verify[]` credit all key on it, as does `mandrel doctor`'s `test-credit-path` check. Set it for a non-npm project (e.g. `python3 scripts/validation.py`); unset, it is `npm test`. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution).",
|
|
85
85
|
"default": "npm test"
|
|
86
86
|
},
|
|
87
87
|
"typecheck": {
|
|
@@ -48,7 +48,13 @@ Flags:
|
|
|
48
48
|
private | public | internal (default: private)
|
|
49
49
|
--operator-handle <name> GitHub handle for github.operatorHandle
|
|
50
50
|
--base-branch <name> Base branch (default: origin/HEAD or 'main')
|
|
51
|
-
--project-number <n> Projects V2 number/name (optional)
|
|
51
|
+
--project-number <n> Projects V2 number/name (optional). An empty
|
|
52
|
+
value or \`none\` skips the board. A non-
|
|
53
|
+
interactive run with no stored number skips it
|
|
54
|
+
unless a name/number is given.
|
|
55
|
+
--no-project Skip the Projects V2 board (labels are still
|
|
56
|
+
provisioned). GH_PROJECT_NUMBER set to empty or
|
|
57
|
+
\`none\` does the same.
|
|
52
58
|
--assume-yes Accept every default + approve GitHub-admin
|
|
53
59
|
mutations. A non-TTY run requires this (or
|
|
54
60
|
--approve-github-admin) — there is no operator
|
|
@@ -405,8 +411,25 @@ async function createGithubProject(state, execImpl = exec) {
|
|
|
405
411
|
return number;
|
|
406
412
|
}
|
|
407
413
|
|
|
408
|
-
/**
|
|
409
|
-
|
|
414
|
+
/** A stored number first, so a re-run never reads as a new board. */
|
|
415
|
+
function projectDefault(defaults, flags, opts) {
|
|
416
|
+
if (defaults.projectNumber) return defaults.projectNumber;
|
|
417
|
+
const interactive = opts.interactive ?? !flags?.['assume-yes'];
|
|
418
|
+
return interactive ? defaults.repo : null;
|
|
419
|
+
}
|
|
420
|
+
|
|
421
|
+
/**
|
|
422
|
+
* The Step 3 question list. `opts.interactive` (default: no `--assume-yes`)
|
|
423
|
+
* picks the project default: a non-interactive run never creates a board
|
|
424
|
+
* from the repo name — only a stored number or an explicit value selects one.
|
|
425
|
+
*/
|
|
426
|
+
export function buildQuestions(
|
|
427
|
+
defaults,
|
|
428
|
+
flags,
|
|
429
|
+
env = process.env,
|
|
430
|
+
lists = {},
|
|
431
|
+
opts = {},
|
|
432
|
+
) {
|
|
410
433
|
const owner = resolveOwnerForPicker(defaults, flags, env);
|
|
411
434
|
// Pre-fetched lists are empty when the owner was unknown up front, so the
|
|
412
435
|
// pickers fall back to a live fetch keyed off the typed `answers.owner`.
|
|
@@ -473,11 +496,11 @@ export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
|
|
|
473
496
|
key: 'projectNumber',
|
|
474
497
|
flag: 'project-number',
|
|
475
498
|
env: 'GH_PROJECT_NUMBER',
|
|
499
|
+
skipFlag: 'no-project',
|
|
476
500
|
message: 'New GitHub Project V2 name',
|
|
477
501
|
pickerMessage:
|
|
478
502
|
'GitHub Project V2 name - Select existing or press ENTER to create',
|
|
479
|
-
|
|
480
|
-
default: defaults.projectNumber || defaults.repo,
|
|
503
|
+
default: projectDefault(defaults, flags, opts),
|
|
481
504
|
required: false,
|
|
482
505
|
picker: {
|
|
483
506
|
list: (answers) => {
|
|
@@ -769,14 +792,51 @@ async function resolveOptIns(state) {
|
|
|
769
792
|
return optIns;
|
|
770
793
|
}
|
|
771
794
|
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
795
|
+
/**
|
|
796
|
+
* Approve each new resource separately. A declined repo aborts (nothing can
|
|
797
|
+
* continue without it); a declined project clears `projectNumber` and the run
|
|
798
|
+
* continues without a board, so labels are still provisioned.
|
|
799
|
+
*
|
|
800
|
+
* @returns {Promise<boolean>} false only when repo creation is declined.
|
|
801
|
+
*/
|
|
802
|
+
export async function approveCreation(
|
|
803
|
+
state,
|
|
804
|
+
answers,
|
|
805
|
+
creation,
|
|
806
|
+
confirm = confirmYesNo,
|
|
807
|
+
) {
|
|
808
|
+
if (state.flags['dry-run']) return true;
|
|
809
|
+
if (!(await approveNewRepo(state, answers, creation, confirm))) return false;
|
|
810
|
+
await approveNewProject(state, answers, creation, confirm);
|
|
811
|
+
return true;
|
|
812
|
+
}
|
|
813
|
+
|
|
814
|
+
async function approveNewRepo(state, answers, creation, confirm) {
|
|
815
|
+
if (!creation.newRepo) return true;
|
|
816
|
+
const ok = await confirm(
|
|
817
|
+
`Create the new GitHub repo ${answers.owner}/${answers.repo}?`,
|
|
818
|
+
state.interactive,
|
|
819
|
+
);
|
|
820
|
+
if (!ok) {
|
|
821
|
+
Logger.error(
|
|
822
|
+
'[Bootstrap] Repo creation declined — cannot continue without the repo. Exiting.',
|
|
823
|
+
);
|
|
775
824
|
}
|
|
776
|
-
return
|
|
777
|
-
|
|
825
|
+
return ok;
|
|
826
|
+
}
|
|
827
|
+
|
|
828
|
+
async function approveNewProject(state, answers, creation, confirm) {
|
|
829
|
+
if (!creation.newProject) return;
|
|
830
|
+
const ok = await confirm(
|
|
831
|
+
`Create the new GitHub Project V2 "${answers.projectNumber}"?`,
|
|
778
832
|
state.interactive,
|
|
779
833
|
);
|
|
834
|
+
if (ok) return;
|
|
835
|
+
answers.projectNumber = '';
|
|
836
|
+
creation.newProject = false;
|
|
837
|
+
Logger.info(
|
|
838
|
+
'[Bootstrap] Project creation declined — skipping the Projects V2 board and continuing.',
|
|
839
|
+
);
|
|
780
840
|
}
|
|
781
841
|
|
|
782
842
|
async function confirmSummary(state, answers, creation, projectsList) {
|
|
@@ -819,6 +879,7 @@ export async function collectAndConfirm(state) {
|
|
|
819
879
|
state.flags,
|
|
820
880
|
process.env,
|
|
821
881
|
lists,
|
|
882
|
+
{ interactive: state.interactive },
|
|
822
883
|
),
|
|
823
884
|
flags: state.flags,
|
|
824
885
|
interactive: state.interactive,
|
|
@@ -844,10 +905,7 @@ export async function collectAndConfirm(state) {
|
|
|
844
905
|
silentAccept = [];
|
|
845
906
|
continue;
|
|
846
907
|
}
|
|
847
|
-
if (!(await approveCreation(state, creation))) {
|
|
848
|
-
Logger.error(
|
|
849
|
-
'[Bootstrap] Creation declined — cannot continue without the repo/project. Exiting.',
|
|
850
|
-
);
|
|
908
|
+
if (!(await approveCreation(state, answers, creation))) {
|
|
851
909
|
return { ok: false, exit: 1 };
|
|
852
910
|
}
|
|
853
911
|
const optIns = await resolveOptIns(state);
|
|
@@ -855,7 +913,7 @@ export async function collectAndConfirm(state) {
|
|
|
855
913
|
}
|
|
856
914
|
}
|
|
857
915
|
|
|
858
|
-
function renderDryRunPlan(state) {
|
|
916
|
+
export function renderDryRunPlan(state) {
|
|
859
917
|
const a = state.answers ?? {};
|
|
860
918
|
const c = state.creation ?? {};
|
|
861
919
|
const flagList = Object.entries(state.flags ?? {}).map(([k, v]) =>
|
|
@@ -994,6 +1052,19 @@ export function persistProjectNumber(state) {
|
|
|
994
1052
|
return { ok: true, payload: {} };
|
|
995
1053
|
}
|
|
996
1054
|
|
|
1055
|
+
/**
|
|
1056
|
+
* `--with-project-board` decorates a board only when one was selected: with
|
|
1057
|
+
* the project skipped, `runBootstrap` would otherwise create one.
|
|
1058
|
+
*/
|
|
1059
|
+
export function resolveBoardDecoration(state) {
|
|
1060
|
+
if (state.withProjectBoard !== true) return false;
|
|
1061
|
+
if (String(state.answers?.projectNumber ?? '').length > 0) return true;
|
|
1062
|
+
Logger.info(
|
|
1063
|
+
'[Bootstrap] Projects V2 board skipped — skipping board decoration (--with-project-board ignored).',
|
|
1064
|
+
);
|
|
1065
|
+
return false;
|
|
1066
|
+
}
|
|
1067
|
+
|
|
997
1068
|
/** Step 6b — GitHub-side bootstrap. Honours `--skip-github`. */
|
|
998
1069
|
export async function executeGithubBootstrap(state) {
|
|
999
1070
|
if (state.flags['skip-github']) {
|
|
@@ -1004,7 +1075,7 @@ export async function executeGithubBootstrap(state) {
|
|
|
1004
1075
|
state.report.github = await runGithubBootstrap(state.answers, {
|
|
1005
1076
|
assumeYes: state.assumeYes,
|
|
1006
1077
|
githubAdminApproved: state.githubAdminApproved === true,
|
|
1007
|
-
withProjectBoard: state
|
|
1078
|
+
withProjectBoard: resolveBoardDecoration(state),
|
|
1008
1079
|
reapConflictingWorkflows: Boolean(
|
|
1009
1080
|
state.flags['reap-conflicting-workflows'],
|
|
1010
1081
|
),
|
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
6
|
import path from 'node:path';
|
|
7
|
+
import { sortBySeverity } from '../findings/severity.js';
|
|
7
8
|
import { RISK_LABELS, TYPE_LABELS } from '../label-constants.js';
|
|
8
9
|
import { serialize } from '../story-body/story-body.js';
|
|
9
10
|
import { definesAuditLabel } from './audit-label-taxonomy.js';
|
|
@@ -12,6 +13,7 @@ import {
|
|
|
12
13
|
renderFingerprintFooter,
|
|
13
14
|
renderSemanticKeyFooter,
|
|
14
15
|
} from './finding-adapter.js';
|
|
16
|
+
import { findingBullets, STORY_FINDING_FIELDS } from './finding-bullets.js';
|
|
15
17
|
|
|
16
18
|
// Deliberately no `agent::` state label: audit prose is not ready for pickup.
|
|
17
19
|
// `/mandrel-plan` stamps `agent::ready` once enriched; an absent state is a
|
|
@@ -55,14 +57,14 @@ function changesFromGroup(group) {
|
|
|
55
57
|
}
|
|
56
58
|
|
|
57
59
|
/**
|
|
58
|
-
* A checkable end-state anchored on title and primary file,
|
|
59
|
-
*
|
|
60
|
+
* A checkable end-state anchored on title and primary file, for a finding
|
|
61
|
+
* whose lens wrote no Acceptance signal.
|
|
60
62
|
*
|
|
61
63
|
* @param {object} finding
|
|
64
|
+
* @param {string} title
|
|
62
65
|
* @returns {string}
|
|
63
66
|
*/
|
|
64
|
-
function
|
|
65
|
-
const title = (finding.title ?? 'finding').trim();
|
|
67
|
+
function synthesizedAcceptance(finding, title) {
|
|
66
68
|
const primaryFile =
|
|
67
69
|
Array.isArray(finding.files) && finding.files.length > 0
|
|
68
70
|
? finding.files[0]
|
|
@@ -71,8 +73,22 @@ function acceptanceItemFromFinding(finding) {
|
|
|
71
73
|
return `${title} is remediated${where}: the recommended end-state holds and the finding is no longer reproducible`;
|
|
72
74
|
}
|
|
73
75
|
|
|
76
|
+
/**
|
|
77
|
+
* The lens's own Acceptance signal when it wrote one, else the synthesized
|
|
78
|
+
* end-state — never the verbatim recommendation, which stays in `## Findings`.
|
|
79
|
+
*
|
|
80
|
+
* @param {object} finding
|
|
81
|
+
* @returns {string}
|
|
82
|
+
*/
|
|
83
|
+
function acceptanceItemFromFinding(finding) {
|
|
84
|
+
const title = (finding.title ?? 'finding').trim();
|
|
85
|
+
return finding.acceptanceSignal
|
|
86
|
+
? `${title} — ${finding.acceptanceSignal}`
|
|
87
|
+
: synthesizedAcceptance(finding, title);
|
|
88
|
+
}
|
|
89
|
+
|
|
74
90
|
function acceptanceCriteriaFromGroup(group) {
|
|
75
|
-
return (group.findings ?? []).map(acceptanceItemFromFinding);
|
|
91
|
+
return sortBySeverity(group.findings ?? []).map(acceptanceItemFromFinding);
|
|
76
92
|
}
|
|
77
93
|
|
|
78
94
|
/**
|
|
@@ -107,13 +123,31 @@ function dependencyRefs(deps, issueByGroupKey) {
|
|
|
107
123
|
.map((n) => `#${n}`);
|
|
108
124
|
}
|
|
109
125
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
126
|
+
/**
|
|
127
|
+
* `####`, never `###`: the story-body parser reads a one-word `##`/`###`
|
|
128
|
+
* heading as a canonical section, so a finding titled `Verify` would bleed
|
|
129
|
+
* its bullets into `verify[]`.
|
|
130
|
+
*
|
|
131
|
+
* @param {object} finding
|
|
132
|
+
* @returns {string} a heading and the finding's present fields.
|
|
133
|
+
*/
|
|
134
|
+
function findingBlock(finding) {
|
|
135
|
+
return [
|
|
136
|
+
`#### ${finding.title}`,
|
|
137
|
+
'',
|
|
138
|
+
...findingBullets(finding, STORY_FINDING_FIELDS),
|
|
139
|
+
].join('\n');
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* One block per finding, worst first, carrying the remediation detail the
|
|
144
|
+
* acceptance list deliberately leaves out.
|
|
145
|
+
*
|
|
146
|
+
* @param {object} group
|
|
147
|
+
* @returns {string}
|
|
148
|
+
*/
|
|
149
|
+
function findingsSection(group) {
|
|
150
|
+
return sortBySeverity(group.findings).map(findingBlock).join('\n\n');
|
|
117
151
|
}
|
|
118
152
|
|
|
119
153
|
/**
|
|
@@ -204,9 +238,9 @@ export function buildStoryBody({ group, edges = [], issueByGroupKey = null }) {
|
|
|
204
238
|
const body = [
|
|
205
239
|
canonicalSections,
|
|
206
240
|
'',
|
|
207
|
-
'##
|
|
241
|
+
'## Findings',
|
|
208
242
|
'',
|
|
209
|
-
|
|
243
|
+
findingsSection(group),
|
|
210
244
|
'',
|
|
211
245
|
'## Context',
|
|
212
246
|
'',
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Per-finding markdown bullets shared by the standalone Story body and the
|
|
3
|
+
* `/mandrel-plan` seed, so both render a finding's fields identically. Pure.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/** `[label, finding key]` pairs, in the order each surface lists them. */
|
|
7
|
+
export const STORY_FINDING_FIELDS = Object.freeze([
|
|
8
|
+
['Severity', 'severity'],
|
|
9
|
+
['Location', 'location'],
|
|
10
|
+
['Current State', 'currentState'],
|
|
11
|
+
['Recommendation', 'recommendation'],
|
|
12
|
+
]);
|
|
13
|
+
|
|
14
|
+
export const SEED_FINDING_FIELDS = Object.freeze([
|
|
15
|
+
['Location', 'location'],
|
|
16
|
+
['Recommendation', 'recommendation'],
|
|
17
|
+
['Acceptance signal', 'acceptanceSignal'],
|
|
18
|
+
]);
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Parsed fields are already trimmed; an empty or absent one is omitted rather
|
|
22
|
+
* than rendered as a placeholder.
|
|
23
|
+
*
|
|
24
|
+
* @param {object} finding
|
|
25
|
+
* @param {ReadonlyArray<readonly [string, string]>} fields
|
|
26
|
+
* @param {string} [indent='']
|
|
27
|
+
* @returns {string[]} one `- **Label:** value` line per present field.
|
|
28
|
+
*/
|
|
29
|
+
export function findingBullets(finding, fields, indent = '') {
|
|
30
|
+
return fields
|
|
31
|
+
.filter(([, key]) => finding[key])
|
|
32
|
+
.map(([label, key]) => `${indent}- **${label}:** ${finding[key]}`);
|
|
33
|
+
}
|
|
@@ -394,7 +394,8 @@ function parseBlockFields(bodyLines) {
|
|
|
394
394
|
* files: string[],
|
|
395
395
|
* currentState: string,
|
|
396
396
|
* recommendation: string,
|
|
397
|
-
*
|
|
397
|
+
* location: string,
|
|
398
|
+
* acceptanceSignal: string,
|
|
398
399
|
* rawFields: Record<string,string>,
|
|
399
400
|
* sourceReport: string,
|
|
400
401
|
* }>}
|
|
@@ -417,13 +418,13 @@ export function parseAuditReport({ markdown, sourceReport, repoRoot }) {
|
|
|
417
418
|
const currentState = fields['current state'] ?? '';
|
|
418
419
|
const recommendation =
|
|
419
420
|
fields['recommendation & rationale'] ?? fields.recommendation ?? '';
|
|
420
|
-
const
|
|
421
|
+
const location = fields.location ?? '';
|
|
422
|
+
const acceptanceSignal = fields['acceptance signal'] ?? '';
|
|
421
423
|
const fileSet = new Set([
|
|
422
424
|
...deriveTitleFile(block.title, repoRoot),
|
|
423
425
|
...deriveLocationFiles(fields, repoRoot),
|
|
424
426
|
...extractFilePaths(currentState, repoRoot),
|
|
425
427
|
...extractFilePaths(recommendation, repoRoot),
|
|
426
|
-
...extractFilePaths(agentPrompt, repoRoot),
|
|
427
428
|
]);
|
|
428
429
|
|
|
429
430
|
return {
|
|
@@ -434,7 +435,8 @@ export function parseAuditReport({ markdown, sourceReport, repoRoot }) {
|
|
|
434
435
|
files: [...fileSet],
|
|
435
436
|
currentState,
|
|
436
437
|
recommendation,
|
|
437
|
-
|
|
438
|
+
location,
|
|
439
|
+
acceptanceSignal,
|
|
438
440
|
rawFields: fields,
|
|
439
441
|
sourceReport,
|
|
440
442
|
};
|
|
@@ -3,12 +3,13 @@
|
|
|
3
3
|
* Pure: returns a string.
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
|
-
import { SEVERITIES } from '../findings/severity.js';
|
|
6
|
+
import { SEVERITIES, sortBySeverity } from '../findings/severity.js';
|
|
7
7
|
import { auditLabelFooterForFindings } from './audit-label-taxonomy.js';
|
|
8
8
|
import {
|
|
9
9
|
renderFingerprintFooter,
|
|
10
10
|
renderSemanticKeyFooter,
|
|
11
11
|
} from './finding-adapter.js';
|
|
12
|
+
import { findingBullets, SEED_FINDING_FIELDS } from './finding-bullets.js';
|
|
12
13
|
|
|
13
14
|
const DIMENSION_LABEL = {
|
|
14
15
|
security: 'Security',
|
|
@@ -43,12 +44,17 @@ function tallyDimensions(findings) {
|
|
|
43
44
|
return tally;
|
|
44
45
|
}
|
|
45
46
|
|
|
46
|
-
|
|
47
|
+
/** `2 High, 1 Medium` — non-zero levels only, highest first. */
|
|
48
|
+
function formatTally(findings) {
|
|
47
49
|
const sev = tallySeverities(findings);
|
|
48
|
-
|
|
49
|
-
const tallyParts = SEVERITY_ORDER.filter((k) => sev[k] > 0)
|
|
50
|
+
return SEVERITY_ORDER.filter((k) => sev[k] > 0)
|
|
50
51
|
.map((k) => `${sev[k]} ${k.charAt(0).toUpperCase() + k.slice(1)}`)
|
|
51
52
|
.join(', ');
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
function formatProblemStatement(findings) {
|
|
56
|
+
const dimensions = tallyDimensions(findings);
|
|
57
|
+
const tallyParts = formatTally(findings);
|
|
52
58
|
const topDims = [...dimensions.entries()]
|
|
53
59
|
.sort((a, b) => b[1] - a[1])
|
|
54
60
|
.slice(0, 3)
|
|
@@ -57,35 +63,44 @@ function formatProblemStatement(findings) {
|
|
|
57
63
|
return `An audit sweep surfaced ${findings.length} findings (${tallyParts}) concentrated in ${dimsPhrase}. These require remediation to restore release posture.`;
|
|
58
64
|
}
|
|
59
65
|
|
|
66
|
+
/**
|
|
67
|
+
* A count per dimension, not recommendation text: each finding's fix lives
|
|
68
|
+
* under it in MVP Scope, so repeating a truncated sample here only misleads.
|
|
69
|
+
*
|
|
70
|
+
* @param {object[]} findings
|
|
71
|
+
* @returns {string}
|
|
72
|
+
*/
|
|
60
73
|
function formatRecommendedDirection(findings) {
|
|
61
|
-
const byDim =
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
lines.push(`- **${label}** — ${head || 'See linked findings.'}`);
|
|
71
|
-
}
|
|
72
|
-
return lines.join('\n');
|
|
74
|
+
const byDim = Map.groupBy(findings, (f) => f.dimension);
|
|
75
|
+
return [...byDim.entries()]
|
|
76
|
+
.sort(([a], [b]) => String(a).localeCompare(String(b)))
|
|
77
|
+
.map(([dim, list]) => {
|
|
78
|
+
const label = DIMENSION_LABEL[dim] ?? dim;
|
|
79
|
+
const noun = list.length === 1 ? 'finding' : 'findings';
|
|
80
|
+
return `- **${label}** — ${list.length} ${noun} (${formatTally(list)})`;
|
|
81
|
+
})
|
|
82
|
+
.join('\n');
|
|
73
83
|
}
|
|
74
84
|
|
|
75
85
|
/**
|
|
76
86
|
* Flat, not grouped: the seed must not pre-decide the Story partition; that
|
|
77
|
-
* is the planner's cohesion call.
|
|
87
|
+
* is the planner's cohesion call. Worst first, each finding carrying its own
|
|
88
|
+
* Location, Recommendation and Acceptance signal so the planner need not
|
|
89
|
+
* reopen the source report.
|
|
78
90
|
*
|
|
79
91
|
* @param {object[]} findings
|
|
80
92
|
* @returns {string}
|
|
81
93
|
*/
|
|
82
94
|
function formatFindingsList(findings) {
|
|
83
|
-
return findings
|
|
95
|
+
return sortBySeverity(findings)
|
|
84
96
|
.map((f) => {
|
|
85
97
|
const label = DIMENSION_LABEL[f.dimension] ?? f.dimension;
|
|
86
98
|
const file = f.files?.[0] ? ` (\`${f.files[0]}\`)` : '';
|
|
87
99
|
const severity = f.severity ? `${f.severity} · ` : '';
|
|
88
|
-
|
|
100
|
+
const headline = `- **${f.title}** — ${severity}${label}${file}`;
|
|
101
|
+
return [headline, ...findingBullets(f, SEED_FINDING_FIELDS, ' ')].join(
|
|
102
|
+
'\n',
|
|
103
|
+
);
|
|
89
104
|
})
|
|
90
105
|
.join('\n');
|
|
91
106
|
}
|
|
@@ -11,8 +11,9 @@ import fs from 'node:fs';
|
|
|
11
11
|
import path from 'node:path';
|
|
12
12
|
|
|
13
13
|
/**
|
|
14
|
-
* Mirrors what the bootstrap writes; `.claude/commands/`
|
|
15
|
-
*
|
|
14
|
+
* Mirrors what the bootstrap writes; the `.claude/commands/` and
|
|
15
|
+
* `.claude/agents/` projections are generated by `prepare` and gitignored,
|
|
16
|
+
* so both are absent.
|
|
16
17
|
*
|
|
17
18
|
* @type {readonly string[]}
|
|
18
19
|
*/
|
|
@@ -81,7 +81,7 @@ export function buildMutationManifest(ctx = {}) {
|
|
|
81
81
|
target: rel('.gitignore'),
|
|
82
82
|
action: 'merge',
|
|
83
83
|
detail:
|
|
84
|
-
'Ignore .claude/commands/ (generated), .mcp.json + .env (carry secrets), and the per-clone install ledger.',
|
|
84
|
+
'Ignore the .claude/commands/ and .claude/agents/ projections (generated by prepare), .mcp.json + .env (carry secrets), and the per-clone install ledger.',
|
|
85
85
|
reversible: true,
|
|
86
86
|
},
|
|
87
87
|
);
|
|
@@ -101,7 +101,7 @@ export function buildMutationManifest(ctx = {}) {
|
|
|
101
101
|
target: rel('package.json'),
|
|
102
102
|
action: 'merge',
|
|
103
103
|
detail:
|
|
104
|
-
'Seed/merge the sync:commands, prepare, and bootstrap npm scripts.',
|
|
104
|
+
'Seed/merge the sync:commands, sync:agents, prepare, and bootstrap npm scripts. `prepare` is guarded: it exits 0 without writing when .agents/scripts/ is absent (a manifest-only container `npm ci`), and otherwise regenerates the .claude/commands/ and .claude/agents/ projections — both gitignored.',
|
|
105
105
|
reversible: true,
|
|
106
106
|
},
|
|
107
107
|
{
|