peaks-loop 4.1.22 → 4.1.24
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/.claude-plugin/marketplace.json +12 -2
- package/CHANGELOG.md +184 -0
- package/dist/cli/commands/code-auto-compact-command.js +19 -1
- package/dist/cli/commands/code-gate-step-08-command.js +103 -105
- package/dist/cli/commands/code-gate-step-08-remedy.d.ts +10 -2
- package/dist/cli/commands/code-gate-step-08-remedy.js +11 -3
- package/dist/cli/commands/gate-commands-enforce.d.ts +23 -8
- package/dist/cli/commands/gate-commands-enforce.js +27 -12
- package/dist/cli/commands/observability-commands-hotspots.d.ts +54 -0
- package/dist/cli/commands/observability-commands-hotspots.js +222 -0
- package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
- package/dist/cli/commands/observability-commands-near-miss.js +105 -0
- package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
- package/dist/cli/commands/observability-commands-queries.js +88 -47
- package/dist/cli/commands/observability-commands-session-row.d.ts +48 -0
- package/dist/cli/commands/observability-commands-session-row.js +201 -0
- package/dist/cli/commands/observability-commands.js +81 -20
- package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
- package/dist/services/artifacts/artifact-prerequisites.js +1 -1
- package/dist/services/artifacts/prerequisite-path-census.d.ts +47 -0
- package/dist/services/artifacts/prerequisite-path-census.js +100 -0
- package/dist/services/artifacts/prerequisite-path-resolver.js +32 -2
- package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
- package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
- package/dist/services/artifacts/rd-gate-event.js +211 -0
- package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
- package/dist/services/artifacts/rd-transition-gates.js +65 -24
- package/dist/services/hooks/output.d.ts +67 -1
- package/dist/services/hooks/output.js +74 -1
- package/dist/services/observability/aggregation-types.d.ts +21 -0
- package/dist/services/observability/aggregation.d.ts +12 -2
- package/dist/services/observability/aggregation.js +28 -3
- package/dist/services/observability/compliance-judge.d.ts +77 -0
- package/dist/services/observability/compliance-judge.js +143 -0
- package/dist/services/observability/compliance-spec.d.ts +96 -0
- package/dist/services/observability/compliance-spec.js +29 -0
- package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
- package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
- package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
- package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
- package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
- package/dist/services/observability/hotspot-attribution-summary.js +74 -0
- package/dist/services/observability/hotspot-rows.d.ts +47 -0
- package/dist/services/observability/hotspot-rows.js +89 -0
- package/dist/services/observability/hotspot-shared.d.ts +207 -0
- package/dist/services/observability/hotspot-shared.js +127 -0
- package/dist/services/observability/hotspot-sources.d.ts +55 -0
- package/dist/services/observability/hotspot-sources.js +142 -0
- package/dist/services/observability/hotspots.d.ts +47 -0
- package/dist/services/observability/hotspots.js +47 -0
- package/dist/services/observability/near-miss-attempts.d.ts +175 -0
- package/dist/services/observability/near-miss-attempts.js +223 -0
- package/dist/services/observability/near-miss-coverage.d.ts +109 -0
- package/dist/services/observability/near-miss-coverage.js +108 -0
- package/dist/services/observability/near-miss-denominator.d.ts +81 -0
- package/dist/services/observability/near-miss-denominator.js +75 -0
- package/dist/services/observability/near-miss-difference.d.ts +98 -0
- package/dist/services/observability/near-miss-difference.js +135 -0
- package/dist/services/observability/near-miss-facts.d.ts +165 -0
- package/dist/services/observability/near-miss-facts.js +101 -0
- package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
- package/dist/services/observability/near-miss-gate-events.js +106 -0
- package/dist/services/observability/near-miss-gates.d.ts +108 -0
- package/dist/services/observability/near-miss-gates.js +135 -0
- package/dist/services/observability/near-miss-records.d.ts +93 -0
- package/dist/services/observability/near-miss-records.js +87 -0
- package/dist/services/observability/near-miss.d.ts +148 -0
- package/dist/services/observability/near-miss.js +203 -0
- package/dist/services/observability/observability-schema.d.ts +17 -2
- package/dist/services/observability/observability-schema.js +21 -1
- package/dist/services/observability/owner-skill-map.d.ts +92 -0
- package/dist/services/observability/owner-skill-map.js +164 -0
- package/dist/services/observability/repair-cycle-metric.js +6 -3
- package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
- package/dist/services/observability/report-formatter-hotspots.js +76 -0
- package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
- package/dist/services/observability/report-formatter-near-miss.js +234 -0
- package/dist/services/observability/report-formatter.d.ts +49 -3
- package/dist/services/observability/report-formatter.js +55 -14
- package/dist/services/observability/retro-attribution.d.ts +129 -0
- package/dist/services/observability/retro-attribution.js +134 -0
- package/dist/services/observability/session-metric-rows.d.ts +153 -0
- package/dist/services/observability/session-metric-rows.js +184 -0
- package/dist/services/skills/presence-role.js +9 -2
- package/dist/services/standards/loop-engineering-readiness-lint.d.ts +15 -1
- package/dist/services/standards/loop-engineering-readiness-lint.js +27 -9
- package/dist/shared/incrementing-number.d.ts +57 -0
- package/dist/shared/incrementing-number.js +13 -0
- package/dist/skills/peaks-maker/index.js +43 -30
- package/output-styles/peaks-skill-swarm.md +2 -2
- package/package.json +5 -5
- package/scripts/install-skills-bundles.mjs +6 -1
- package/scripts/install-skills.mjs +10 -1
- package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
- package/skills/bee/peaks-prd/SKILL.md +1 -1
- package/skills/bee/peaks-qa/SKILL.md +1 -1
- package/skills/bee/peaks-rd/SKILL.md +1 -1
- package/skills/bee/peaks-reviewer/SKILL.md +1 -1
- package/skills/bee/peaks-sc/SKILL.md +1 -1
- package/skills/bee/peaks-security-audit/SKILL.md +1 -1
- package/skills/bee/peaks-txt/SKILL.md +1 -1
- package/skills/bee/peaks-ui/SKILL.md +1 -1
- package/skills/peaks-audit/SKILL.md +1 -1
- package/skills/peaks-code/SKILL.md +1 -1
- package/skills/peaks-content/SKILL.md +1 -1
- package/skills/peaks-doctor/SKILL.md +1 -1
- package/skills/peaks-final-review/SKILL.md +1 -1
- package/skills/peaks-ide/SKILL.md +1 -1
- package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
- package/skills/peaks-maker/SKILL.md +125 -0
- package/skills/peaks-mut/SKILL.md +297 -0
- package/skills/peaks-race-code/SKILL.md +1 -1
- package/skills/peaks-resume/SKILL.md +1 -1
- package/skills/peaks-slice-decompose/SKILL.md +1 -1
- package/skills/peaks-solo/SKILL.md +1 -1
- package/skills/peaks-sop/SKILL.md +1 -1
- package/skills/peaks-status/SKILL.md +1 -1
- package/skills/peaks-test/SKILL.md +1 -1
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/artifacts/prerequisite-path-census.ts`
|
|
3
|
+
*
|
|
4
|
+
* Every path shape that can reach the prerequisite missing list, as one
|
|
5
|
+
* de-duplicated list.
|
|
6
|
+
*
|
|
7
|
+
* WHY THIS EXISTS. The owner-skill map has to cover the paths the gates
|
|
8
|
+
* actually demand, and the gates read ONE table. Reading that table through
|
|
9
|
+
* a census function means the coverage check and the gate can never
|
|
10
|
+
* disagree about which paths exist — a second hand-written list would drift
|
|
11
|
+
* from the table on the first table change.
|
|
12
|
+
*
|
|
13
|
+
* THE THREE SOURCES OF A MISSING PATH. `checkPrerequisites` builds its
|
|
14
|
+
* missing list from three places, and a census that reads only the first
|
|
15
|
+
* would leave the other two uncovered:
|
|
16
|
+
*
|
|
17
|
+
* 1. the table loop — the canonical `relativePath`, plus the legacy tiers
|
|
18
|
+
* (`legacyRelativePath` / `legacyRelativePaths`) the resolver probes
|
|
19
|
+
* before it calls a file absent;
|
|
20
|
+
* 2. the judged-declaration refusals — the security artifact's own
|
|
21
|
+
* location, which the resolver reports verbatim;
|
|
22
|
+
* 3. the handoff capsule's gate-evidence declaration — a key that names a
|
|
23
|
+
* file that is not on disk, reported under the KEY's name, and the
|
|
24
|
+
* unreadable-capsule shape beside it.
|
|
25
|
+
*
|
|
26
|
+
* The `<rid>` placeholder is left in place on the table paths: this is the
|
|
27
|
+
* table's own shape, and the owner lookup is a prefix match, so the
|
|
28
|
+
* placeholder is irrelevant to it.
|
|
29
|
+
*
|
|
30
|
+
* THE KEY SET IS READ, NOT COPIED. `GATE_EVIDENCE_KEYS` is the one
|
|
31
|
+
* definition of the gate-evidence vocabulary, and a second copy of it here
|
|
32
|
+
* would be the same drift hole this census exists to close. The failure
|
|
33
|
+
* statuses are held in a `Record` keyed by the reader's own status type, so
|
|
34
|
+
* a status added to that type fails the build here until this census
|
|
35
|
+
* accounts for it.
|
|
36
|
+
*/
|
|
37
|
+
/**
|
|
38
|
+
* Every `relativePath` any request type demands, every legacy tier the
|
|
39
|
+
* resolver probes for one, every judged-declaration tier the security audit
|
|
40
|
+
* can live at, and every gate-evidence shape a declaration can report —
|
|
41
|
+
* de-duplicated and sorted.
|
|
42
|
+
*
|
|
43
|
+
* The judged tiers are read from `securityArtifactTiers` in their defining
|
|
44
|
+
* module, not copied here. `securityTiers` is the seam a test uses to inject
|
|
45
|
+
* a tier list; production callers pass nothing.
|
|
46
|
+
*/
|
|
47
|
+
export declare function allPrerequisitePaths(securityTiers?: (rid: string) => readonly string[]): readonly string[];
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/artifacts/prerequisite-path-census.ts`
|
|
3
|
+
*
|
|
4
|
+
* Every path shape that can reach the prerequisite missing list, as one
|
|
5
|
+
* de-duplicated list.
|
|
6
|
+
*
|
|
7
|
+
* WHY THIS EXISTS. The owner-skill map has to cover the paths the gates
|
|
8
|
+
* actually demand, and the gates read ONE table. Reading that table through
|
|
9
|
+
* a census function means the coverage check and the gate can never
|
|
10
|
+
* disagree about which paths exist — a second hand-written list would drift
|
|
11
|
+
* from the table on the first table change.
|
|
12
|
+
*
|
|
13
|
+
* THE THREE SOURCES OF A MISSING PATH. `checkPrerequisites` builds its
|
|
14
|
+
* missing list from three places, and a census that reads only the first
|
|
15
|
+
* would leave the other two uncovered:
|
|
16
|
+
*
|
|
17
|
+
* 1. the table loop — the canonical `relativePath`, plus the legacy tiers
|
|
18
|
+
* (`legacyRelativePath` / `legacyRelativePaths`) the resolver probes
|
|
19
|
+
* before it calls a file absent;
|
|
20
|
+
* 2. the judged-declaration refusals — the security artifact's own
|
|
21
|
+
* location, which the resolver reports verbatim;
|
|
22
|
+
* 3. the handoff capsule's gate-evidence declaration — a key that names a
|
|
23
|
+
* file that is not on disk, reported under the KEY's name, and the
|
|
24
|
+
* unreadable-capsule shape beside it.
|
|
25
|
+
*
|
|
26
|
+
* The `<rid>` placeholder is left in place on the table paths: this is the
|
|
27
|
+
* table's own shape, and the owner lookup is a prefix match, so the
|
|
28
|
+
* placeholder is irrelevant to it.
|
|
29
|
+
*
|
|
30
|
+
* THE KEY SET IS READ, NOT COPIED. `GATE_EVIDENCE_KEYS` is the one
|
|
31
|
+
* definition of the gate-evidence vocabulary, and a second copy of it here
|
|
32
|
+
* would be the same drift hole this census exists to close. The failure
|
|
33
|
+
* statuses are held in a `Record` keyed by the reader's own status type, so
|
|
34
|
+
* a status added to that type fails the build here until this census
|
|
35
|
+
* accounts for it.
|
|
36
|
+
*/
|
|
37
|
+
import { PREREQUISITES_BY_TYPE } from './artifact-prerequisites.js';
|
|
38
|
+
import { GATE_EVIDENCE_KEYS } from '../prd/handoff-types.js';
|
|
39
|
+
import { securityArtifactTiers } from '../audit-independent/judged-declaration-check.js';
|
|
40
|
+
/**
|
|
41
|
+
* The failure statuses, keyed so that the type checks BOTH ways: a status
|
|
42
|
+
* added to the reader's union fails the build here until this record names
|
|
43
|
+
* it, and a status dropped from that union fails here as an excess key.
|
|
44
|
+
*/
|
|
45
|
+
const GATE_EVIDENCE_FAILURE_STATUSES = {
|
|
46
|
+
'read-error': true,
|
|
47
|
+
'frontmatter-malformed': true,
|
|
48
|
+
'field-not-map': true,
|
|
49
|
+
'value-not-string': true
|
|
50
|
+
};
|
|
51
|
+
/**
|
|
52
|
+
* The two sources of a missing path that do NOT come from the prereq table:
|
|
53
|
+
* the judged-declaration tiers and the gate-evidence declaration shapes.
|
|
54
|
+
*
|
|
55
|
+
* They are read from OTHER modules' definitions rather than from the table,
|
|
56
|
+
* and they are gathered apart from the table walk so that
|
|
57
|
+
* `allPrerequisitePaths` stays inside the lint complexity ceiling.
|
|
58
|
+
*/
|
|
59
|
+
function addNonTablePaths(paths, securityTiers) {
|
|
60
|
+
// The `<rid>` placeholder stays in place, as it does on the table paths.
|
|
61
|
+
for (const tier of securityTiers('<rid>')) {
|
|
62
|
+
paths.add(tier);
|
|
63
|
+
}
|
|
64
|
+
for (const key of GATE_EVIDENCE_KEYS) {
|
|
65
|
+
paths.add(`gateEvidence.${key}`);
|
|
66
|
+
}
|
|
67
|
+
for (const status of Object.keys(GATE_EVIDENCE_FAILURE_STATUSES)) {
|
|
68
|
+
paths.add(`gateEvidence(${status})`);
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Every `relativePath` any request type demands, every legacy tier the
|
|
73
|
+
* resolver probes for one, every judged-declaration tier the security audit
|
|
74
|
+
* can live at, and every gate-evidence shape a declaration can report —
|
|
75
|
+
* de-duplicated and sorted.
|
|
76
|
+
*
|
|
77
|
+
* The judged tiers are read from `securityArtifactTiers` in their defining
|
|
78
|
+
* module, not copied here. `securityTiers` is the seam a test uses to inject
|
|
79
|
+
* a tier list; production callers pass nothing.
|
|
80
|
+
*/
|
|
81
|
+
export function allPrerequisitePaths(securityTiers = securityArtifactTiers) {
|
|
82
|
+
const paths = new Set();
|
|
83
|
+
for (const table of Object.values(PREREQUISITES_BY_TYPE)) {
|
|
84
|
+
for (const requirements of Object.values(table)) {
|
|
85
|
+
if (requirements === undefined)
|
|
86
|
+
continue;
|
|
87
|
+
for (const requirement of requirements) {
|
|
88
|
+
paths.add(requirement.relativePath);
|
|
89
|
+
if (requirement.legacyRelativePath !== undefined) {
|
|
90
|
+
paths.add(requirement.legacyRelativePath);
|
|
91
|
+
}
|
|
92
|
+
for (const legacy of requirement.legacyRelativePaths ?? []) {
|
|
93
|
+
paths.add(legacy);
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
addNonTablePaths(paths, securityTiers);
|
|
99
|
+
return [...paths].sort();
|
|
100
|
+
}
|
|
@@ -44,7 +44,8 @@ async function resolvePrerequisiteAbsolutePath(sessionRoot, prerequisite, reques
|
|
|
44
44
|
const dir = dirname(exact);
|
|
45
45
|
// The on-disk suffix is the SLUG of this basename — the writer lowercases the
|
|
46
46
|
// rid — so a mixed-case rid used to be reported absent with the file on disk.
|
|
47
|
-
const
|
|
47
|
+
const stem = slugifyDescription(basename(exact).replace(/\.md$/, ''));
|
|
48
|
+
const suffix = `-${stem}.md`;
|
|
48
49
|
let entries;
|
|
49
50
|
try {
|
|
50
51
|
entries = await readdir(dir);
|
|
@@ -53,8 +54,37 @@ async function resolvePrerequisiteAbsolutePath(sessionRoot, prerequisite, reques
|
|
|
53
54
|
// TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
|
|
54
55
|
return null;
|
|
55
56
|
}
|
|
57
|
+
// Number-first form (`003-<rid>.md`, the `qa/test-cases/` shape).
|
|
56
58
|
const match = entries.find((name) => NUMBERED_PREFIX_RE.test(name) && name.endsWith(suffix));
|
|
57
|
-
|
|
59
|
+
if (match !== undefined)
|
|
60
|
+
return join(dir, match);
|
|
61
|
+
return resolveKindFirstNumbered(entries, dir, stem, requestId);
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* The OTHER numbered form: the writer numbers AFTER the kind for `audit/` and
|
|
65
|
+
* `rd/` (`audit/security-003-<rid>.md`). `NUMBERED_PREFIX_RE` is anchored at the
|
|
66
|
+
* start of the name, so the number-first scan above can never see it — and the
|
|
67
|
+
* evidence was reported missing with the file on disk.
|
|
68
|
+
*
|
|
69
|
+
* The kind is this prerequisite's basename with the rid stripped (`security-`),
|
|
70
|
+
* so a look-alike such as `security-backup-<rid>.md` carries no number prefix and
|
|
71
|
+
* another rid's `security-003-<other>.md` fails the exact-shape check. Both stay
|
|
72
|
+
* unresolved, which is the correct verdict for a prereq whose evidence is absent.
|
|
73
|
+
*/
|
|
74
|
+
function resolveKindFirstNumbered(entries, dir, stem, requestId) {
|
|
75
|
+
const ridSlug = slugifyDescription(requestId);
|
|
76
|
+
const ridSuffix = `-${ridSlug}`;
|
|
77
|
+
if (!stem.endsWith(ridSuffix))
|
|
78
|
+
return null;
|
|
79
|
+
const kind = stem.slice(0, -ridSuffix.length);
|
|
80
|
+
const name = entries.find((entry) => {
|
|
81
|
+
if (!entry.startsWith(`${kind}-`))
|
|
82
|
+
return false;
|
|
83
|
+
const rest = entry.slice(kind.length + 1);
|
|
84
|
+
const numbered = NUMBERED_PREFIX_RE.exec(rest);
|
|
85
|
+
return numbered !== null && rest.slice(numbered[0].length) === `${ridSlug}.md`;
|
|
86
|
+
});
|
|
87
|
+
return name !== undefined ? join(dir, name) : null;
|
|
58
88
|
}
|
|
59
89
|
/**
|
|
60
90
|
* Resolve a prerequisite to an on-disk path, with a 2-tier fallback
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { emitObservabilityEvent } from '../observability/observability-service.js';
|
|
2
|
+
import { ownerSkillForPath } from '../observability/owner-skill-map.js';
|
|
2
3
|
/**
|
|
3
4
|
* Slice C of v2.11.1 — observability hook #7/7. Fire-and-forget per PRD Q4. The
|
|
4
5
|
* synchronous emit never throws and never blocks the prereq check's return
|
|
@@ -21,7 +22,18 @@ export function emitPrereqTransitionEvent(opts) {
|
|
|
21
22
|
artifactRole: opts.role,
|
|
22
23
|
to: opts.newState,
|
|
23
24
|
prereqOk: opts.result.ok,
|
|
24
|
-
missingCount: opts.result.missing.length
|
|
25
|
+
missingCount: opts.result.missing.length,
|
|
26
|
+
// The LIST, not only its length: the count says how many artifacts were
|
|
27
|
+
// missing, and the list says which ones and which skill owns each, so a
|
|
28
|
+
// reader can name the skill that failed to deliver. Ownership is per
|
|
29
|
+
// missing item; an aggregate owner is the reader's job, not the
|
|
30
|
+
// writer's.
|
|
31
|
+
missing: opts.result.missing.map((m) => ({
|
|
32
|
+
path: m.path,
|
|
33
|
+
description: m.description,
|
|
34
|
+
kind: m.kind,
|
|
35
|
+
ownerSkill: ownerSkillForPath(m.path)
|
|
36
|
+
}))
|
|
25
37
|
}
|
|
26
38
|
}, { projectRoot: opts.projectRoot });
|
|
27
39
|
}
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
import type { RequestType } from './artifact-prerequisites.js';
|
|
2
|
+
import type { RdGatePhase, RdGateViolationKind } from './rd-transition-gates.js';
|
|
3
|
+
/** The gates the RD transition layer decides, by their stable ids. */
|
|
4
|
+
export type RdGateId = 'file-size-ratchet' | 'declared-type-corroboration' | 'claim-table';
|
|
5
|
+
/**
|
|
6
|
+
* Every gate id, as a list.
|
|
7
|
+
*
|
|
8
|
+
* A consumer that has to RECOGNISE a gate id cannot re-type the union: a
|
|
9
|
+
* second copy of the vocabulary is a list that rots, and it rots silently —
|
|
10
|
+
* a gate id added upstream would not be in the copy, so a gate that PASSED
|
|
11
|
+
* would be read as "not a gate we know" and never counted as evaluated.
|
|
12
|
+
*/
|
|
13
|
+
export declare const RD_GATE_IDS: readonly RdGateId[];
|
|
14
|
+
/** What the gate decided about the transition. */
|
|
15
|
+
export type RdGateOutcome = 'pass' | 'block' | 'bypass';
|
|
16
|
+
/**
|
|
17
|
+
* Every gate outcome, as a list.
|
|
18
|
+
*
|
|
19
|
+
* A consumer that has to RECOGNISE an outcome cannot re-type the union: a
|
|
20
|
+
* second copy of the vocabulary is a list that rots, and it rots SILENTLY —
|
|
21
|
+
* an outcome added upstream would not be in the copy, so the reader would
|
|
22
|
+
* treat a `pass` as "not a pass" and report a slice that evaluated every gate
|
|
23
|
+
* as one that skipped one.
|
|
24
|
+
*/
|
|
25
|
+
export declare const RD_GATE_OUTCOMES: readonly RdGateOutcome[];
|
|
26
|
+
/**
|
|
27
|
+
* Whether a value is one of the gate outcomes this build knows.
|
|
28
|
+
*
|
|
29
|
+
* An outcome this build does not know is UNREADABLE, not "not evaluated" —
|
|
30
|
+
* the two are different facts, and only the second one is a finding.
|
|
31
|
+
*/
|
|
32
|
+
export declare function isRdGateOutcome(value: unknown): value is RdGateOutcome;
|
|
33
|
+
/** The ids of the gates the bypass note names, in the note's order. */
|
|
34
|
+
export declare function notedGateIds(phase: RdGatePhase): readonly RdGateId[];
|
|
35
|
+
/**
|
|
36
|
+
* The gates that are live for a transition, by its phase and by whether the
|
|
37
|
+
* declared type is tooling-only.
|
|
38
|
+
*/
|
|
39
|
+
export declare function liveGateIds(phase: RdGatePhase, judged: boolean): readonly RdGateId[];
|
|
40
|
+
/** The prose the bypass note uses for one gate id. */
|
|
41
|
+
export declare function gateLabel(gateId: RdGateId): string;
|
|
42
|
+
/**
|
|
43
|
+
* Why ONE gate did not run, when the transition was bypassed.
|
|
44
|
+
*
|
|
45
|
+
* PER GATE, not the shared note: the note the artifact carries names the
|
|
46
|
+
* skipped gates in prose, and it does not name every gate that stood down —
|
|
47
|
+
* so it cannot be the reason for all of them. The note stays the prose; this
|
|
48
|
+
* is the machine-facing explanation.
|
|
49
|
+
*/
|
|
50
|
+
export declare function bypassReason(gateId: RdGateId, phase: RdGatePhase): string;
|
|
51
|
+
/**
|
|
52
|
+
* Why the claim table could not be evaluated. The causes are DIFFERENT facts
|
|
53
|
+
* — no artifact at all, or a table some rid never filled in — and a consumer
|
|
54
|
+
* has to be able to tell them apart. (The third cause, a diff that could not
|
|
55
|
+
* be obtained, is a `block` with its own `violationKind`.)
|
|
56
|
+
*/
|
|
57
|
+
export declare function claimTableReason(artifactCount: number, missingCount: number): string;
|
|
58
|
+
/** The transition a gate decision belongs to. */
|
|
59
|
+
export type RdGateContext = {
|
|
60
|
+
readonly projectRoot: string;
|
|
61
|
+
readonly sessionId: string;
|
|
62
|
+
readonly sliceRid: string;
|
|
63
|
+
readonly phase: RdGatePhase;
|
|
64
|
+
/**
|
|
65
|
+
* The declared type of the slice, as the transition judged it. It travels
|
|
66
|
+
* with the event because the LIVE SET depends on it: a consumer that wants
|
|
67
|
+
* to know whether a gate was applicable has to read it HERE, not from the
|
|
68
|
+
* request artifact — `peaks request retag` rewrites the artifact's type
|
|
69
|
+
* line with no state guard, so the artifact carries the CURRENT type, not
|
|
70
|
+
* the type the transition ran under. A metric that has to re-read mutable
|
|
71
|
+
* session state is not reproducible from the events alone.
|
|
72
|
+
*/
|
|
73
|
+
readonly declaredType: RequestType;
|
|
74
|
+
};
|
|
75
|
+
/** The decision half of a gate event: what the gate decided, and why. */
|
|
76
|
+
export type RdGateDecision = {
|
|
77
|
+
readonly violationKind?: RdGateViolationKind | undefined;
|
|
78
|
+
readonly reason?: string | undefined;
|
|
79
|
+
};
|
|
80
|
+
/** The recorder for ONE transition: it fills in the transition's identity. */
|
|
81
|
+
export type RdGateRecorder = (gateId: RdGateId, outcome: RdGateOutcome, decision?: RdGateDecision) => void;
|
|
82
|
+
/** Bind the transition's identity, once. */
|
|
83
|
+
export declare function rdGateRecorder(context: RdGateContext): RdGateRecorder;
|
|
84
|
+
/**
|
|
85
|
+
* Record ONE gate decision in the session's observability stream.
|
|
86
|
+
*
|
|
87
|
+
* The detail carries the DECLARED TYPE, not a derived "was this slice
|
|
88
|
+
* tooling-only" boolean: the type is the more informative datum, and a consumer
|
|
89
|
+
* that has to re-read the request artifact to learn whether a gate was live
|
|
90
|
+
* cannot reproduce the answer from the events alone.
|
|
91
|
+
*
|
|
92
|
+
* The optional fields carry `| undefined` on purpose: this repository
|
|
93
|
+
* compiles with `exactOptionalPropertyTypes`, so a caller that forwards a
|
|
94
|
+
* possibly-absent value could not pass it to a plain optional property.
|
|
95
|
+
*/
|
|
96
|
+
export declare function emitRdGateEvent(opts: {
|
|
97
|
+
readonly projectRoot: string;
|
|
98
|
+
readonly sessionId: string;
|
|
99
|
+
readonly sliceRid: string;
|
|
100
|
+
readonly gateId: RdGateId;
|
|
101
|
+
readonly phase: RdGatePhase;
|
|
102
|
+
readonly declaredType: RequestType;
|
|
103
|
+
readonly outcome: RdGateOutcome;
|
|
104
|
+
readonly violationKind?: RdGateViolationKind | undefined;
|
|
105
|
+
readonly reason?: string | undefined;
|
|
106
|
+
}): void;
|
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The gate layer's event vocabulary: the stable ids the RD transition gates
|
|
3
|
+
* are known by, and the ONE function that writes a gate decision into the
|
|
4
|
+
* observability stream.
|
|
5
|
+
*
|
|
6
|
+
* WHY THE IDS ARE STABLE STRINGS. A gate decision is only useful if a reader
|
|
7
|
+
* can ask "which gate blocked?" — across sessions, and across versions of
|
|
8
|
+
* this repository. A reader that has to recognise the CODE that produced the
|
|
9
|
+
* event cannot ask that question at all, which is how the gate layer stayed
|
|
10
|
+
* invisible until now.
|
|
11
|
+
*
|
|
12
|
+
* WHY THE EMITTER LIVES HERE AND NOT IN THE OBSERVABILITY SERVICE. The service
|
|
13
|
+
* module is at its file-size cap, and this file owns the gate vocabulary: the
|
|
14
|
+
* ids, the outcomes, and the prose the bypass note uses for them. The service
|
|
15
|
+
* keeps the schema-and-write half it has always owned.
|
|
16
|
+
*
|
|
17
|
+
* THE RECORDER IS CURRIED. One transition has ONE identity — the project, the
|
|
18
|
+
* session, the slice and the phase — and every decision it makes shares it.
|
|
19
|
+
* The recorder binds that identity once, so a decision costs one line at the
|
|
20
|
+
* call site and cannot forget which slice it belongs to.
|
|
21
|
+
*
|
|
22
|
+
* FIRE-AND-FORGET BY CONTRACT. The gate's verdict must not change because an
|
|
23
|
+
* event could not be written, so nothing here throws.
|
|
24
|
+
*/
|
|
25
|
+
import { emitObservabilityEvent } from '../observability/observability-service.js';
|
|
26
|
+
import { OBSERVABILITY_SCHEMA_VERSION } from '../observability/observability-schema.js';
|
|
27
|
+
/**
|
|
28
|
+
* Every gate id, as a list.
|
|
29
|
+
*
|
|
30
|
+
* A consumer that has to RECOGNISE a gate id cannot re-type the union: a
|
|
31
|
+
* second copy of the vocabulary is a list that rots, and it rots silently —
|
|
32
|
+
* a gate id added upstream would not be in the copy, so a gate that PASSED
|
|
33
|
+
* would be read as "not a gate we know" and never counted as evaluated.
|
|
34
|
+
*/
|
|
35
|
+
export const RD_GATE_IDS = [
|
|
36
|
+
'file-size-ratchet',
|
|
37
|
+
'declared-type-corroboration',
|
|
38
|
+
'claim-table'
|
|
39
|
+
];
|
|
40
|
+
/**
|
|
41
|
+
* Every gate outcome, as a list.
|
|
42
|
+
*
|
|
43
|
+
* A consumer that has to RECOGNISE an outcome cannot re-type the union: a
|
|
44
|
+
* second copy of the vocabulary is a list that rots, and it rots SILENTLY —
|
|
45
|
+
* an outcome added upstream would not be in the copy, so the reader would
|
|
46
|
+
* treat a `pass` as "not a pass" and report a slice that evaluated every gate
|
|
47
|
+
* as one that skipped one.
|
|
48
|
+
*/
|
|
49
|
+
export const RD_GATE_OUTCOMES = ['pass', 'block', 'bypass'];
|
|
50
|
+
/**
|
|
51
|
+
* Whether a value is one of the gate outcomes this build knows.
|
|
52
|
+
*
|
|
53
|
+
* An outcome this build does not know is UNREADABLE, not "not evaluated" —
|
|
54
|
+
* the two are different facts, and only the second one is a finding.
|
|
55
|
+
*/
|
|
56
|
+
export function isRdGateOutcome(value) {
|
|
57
|
+
return typeof value === 'string' && RD_GATE_OUTCOMES.includes(value);
|
|
58
|
+
}
|
|
59
|
+
/** The prose each gate id carries in the bypass note. */
|
|
60
|
+
const GATE_LABELS = {
|
|
61
|
+
'file-size-ratchet': 'file-size ratchet',
|
|
62
|
+
'declared-type-corroboration': 'declared-type corroboration',
|
|
63
|
+
'claim-table': 'claim table'
|
|
64
|
+
};
|
|
65
|
+
/**
|
|
66
|
+
* The gates the bypass NOTE names, per phase. This is NOT the live set: the
|
|
67
|
+
* note names the gates a reader is TOLD about, while `liveGateIds` is the set
|
|
68
|
+
* of checks that were actually APPLICABLE — a gate that was live and skipped
|
|
69
|
+
* has to be recorded even when the note does not name it.
|
|
70
|
+
*
|
|
71
|
+
* The note and this list are two readings of ONE table: the note's prose is
|
|
72
|
+
* built from these ids, so the text that names the skipped gates cannot drift
|
|
73
|
+
* from the prose the artifact carries.
|
|
74
|
+
*/
|
|
75
|
+
const NOTED_GATE_IDS = {
|
|
76
|
+
implemented: ['file-size-ratchet', 'declared-type-corroboration'],
|
|
77
|
+
'qa-handoff': ['declared-type-corroboration'],
|
|
78
|
+
'handed-off': ['declared-type-corroboration']
|
|
79
|
+
};
|
|
80
|
+
/** The ids of the gates the bypass note names, in the note's order. */
|
|
81
|
+
export function notedGateIds(phase) {
|
|
82
|
+
return NOTED_GATE_IDS[phase];
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* The gates that are LIVE for a transition: the checks that WOULD run if the
|
|
86
|
+
* transition were not bypassed.
|
|
87
|
+
*
|
|
88
|
+
* A live gate that produced no verdict was SKIPPED; a gate that is not live
|
|
89
|
+
* was never applicable to that transition. The two must be tellable apart, or
|
|
90
|
+
* a skipped gate is indistinguishable from a gate that does not exist for the
|
|
91
|
+
* slice — the invisible state this stream exists to remove.
|
|
92
|
+
*
|
|
93
|
+
* DERIVED FROM THE SOURCE, not from the note. `runRdTransitionGates` runs the
|
|
94
|
+
* size ratchet at `implemented` and, for a declared type that is NOT
|
|
95
|
+
* tooling-only, runs NOTHING else — the type rule is a no-op there and the
|
|
96
|
+
* claim table is never read. For a tooling-only declared type the type rule
|
|
97
|
+
* and the claim table run at every phase, and the size ratchet joins them at
|
|
98
|
+
* `implemented`.
|
|
99
|
+
*/
|
|
100
|
+
const LIVE_GATE_IDS = {
|
|
101
|
+
implemented: {
|
|
102
|
+
tooling: ['file-size-ratchet', 'declared-type-corroboration', 'claim-table'],
|
|
103
|
+
product: ['file-size-ratchet']
|
|
104
|
+
},
|
|
105
|
+
'qa-handoff': {
|
|
106
|
+
tooling: ['declared-type-corroboration', 'claim-table'],
|
|
107
|
+
product: []
|
|
108
|
+
},
|
|
109
|
+
'handed-off': {
|
|
110
|
+
tooling: ['declared-type-corroboration', 'claim-table'],
|
|
111
|
+
product: []
|
|
112
|
+
}
|
|
113
|
+
};
|
|
114
|
+
/**
|
|
115
|
+
* The gates that are live for a transition, by its phase and by whether the
|
|
116
|
+
* declared type is tooling-only.
|
|
117
|
+
*/
|
|
118
|
+
export function liveGateIds(phase, judged) {
|
|
119
|
+
return LIVE_GATE_IDS[phase][judged ? 'tooling' : 'product'];
|
|
120
|
+
}
|
|
121
|
+
/** The prose the bypass note uses for one gate id. */
|
|
122
|
+
export function gateLabel(gateId) {
|
|
123
|
+
return GATE_LABELS[gateId];
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* What each gate was NOT able to check, when the transition was bypassed.
|
|
127
|
+
*/
|
|
128
|
+
const BYPASS_DETAIL = {
|
|
129
|
+
'file-size-ratchet': ', so no file was measured against the cap',
|
|
130
|
+
'declared-type-corroboration': ', so the declared type was never judged against the change set',
|
|
131
|
+
'claim-table': ', so no rid claim was checked against the working tree'
|
|
132
|
+
};
|
|
133
|
+
/**
|
|
134
|
+
* Why ONE gate did not run, when the transition was bypassed.
|
|
135
|
+
*
|
|
136
|
+
* PER GATE, not the shared note: the note the artifact carries names the
|
|
137
|
+
* skipped gates in prose, and it does not name every gate that stood down —
|
|
138
|
+
* so it cannot be the reason for all of them. The note stays the prose; this
|
|
139
|
+
* is the machine-facing explanation.
|
|
140
|
+
*/
|
|
141
|
+
export function bypassReason(gateId, phase) {
|
|
142
|
+
return (`the ${gateLabel(gateId)} was not evaluated: --allow-incomplete bypassed the rd ` +
|
|
143
|
+
`${phase} gates${BYPASS_DETAIL[gateId]}`);
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* Why the claim table could not be evaluated. The causes are DIFFERENT facts
|
|
147
|
+
* — no artifact at all, or a table some rid never filled in — and a consumer
|
|
148
|
+
* has to be able to tell them apart. (The third cause, a diff that could not
|
|
149
|
+
* be obtained, is a `block` with its own `violationKind`.)
|
|
150
|
+
*/
|
|
151
|
+
export function claimTableReason(artifactCount, missingCount) {
|
|
152
|
+
if (artifactCount === 0) {
|
|
153
|
+
return ('the claim table could not be evaluated: the session has no RD artifact, so no rid ' +
|
|
154
|
+
'declares the paths it touched and an unclaimed source change cannot be ruled out');
|
|
155
|
+
}
|
|
156
|
+
return (`the claim table could not be evaluated: ${missingCount} of ${artifactCount} RD artifacts ` +
|
|
157
|
+
'declare no "## Changed paths" section, and an incomplete table cannot prove that no ' +
|
|
158
|
+
'source change is unclaimed');
|
|
159
|
+
}
|
|
160
|
+
/** Bind the transition's identity, once. */
|
|
161
|
+
export function rdGateRecorder(context) {
|
|
162
|
+
return (gateId, outcome, decision) => {
|
|
163
|
+
emitRdGateEvent({
|
|
164
|
+
...context,
|
|
165
|
+
gateId,
|
|
166
|
+
outcome,
|
|
167
|
+
violationKind: decision?.violationKind,
|
|
168
|
+
reason: decision?.reason
|
|
169
|
+
});
|
|
170
|
+
};
|
|
171
|
+
}
|
|
172
|
+
/**
|
|
173
|
+
* Record ONE gate decision in the session's observability stream.
|
|
174
|
+
*
|
|
175
|
+
* The detail carries the DECLARED TYPE, not a derived "was this slice
|
|
176
|
+
* tooling-only" boolean: the type is the more informative datum, and a consumer
|
|
177
|
+
* that has to re-read the request artifact to learn whether a gate was live
|
|
178
|
+
* cannot reproduce the answer from the events alone.
|
|
179
|
+
*
|
|
180
|
+
* The optional fields carry `| undefined` on purpose: this repository
|
|
181
|
+
* compiles with `exactOptionalPropertyTypes`, so a caller that forwards a
|
|
182
|
+
* possibly-absent value could not pass it to a plain optional property.
|
|
183
|
+
*/
|
|
184
|
+
export function emitRdGateEvent(opts) {
|
|
185
|
+
const detail = {
|
|
186
|
+
gateId: opts.gateId,
|
|
187
|
+
phase: opts.phase,
|
|
188
|
+
declaredType: opts.declaredType,
|
|
189
|
+
outcome: opts.outcome
|
|
190
|
+
};
|
|
191
|
+
if (opts.violationKind !== undefined)
|
|
192
|
+
detail['violationKind'] = opts.violationKind;
|
|
193
|
+
if (opts.reason !== undefined)
|
|
194
|
+
detail['reason'] = opts.reason;
|
|
195
|
+
try {
|
|
196
|
+
emitObservabilityEvent({
|
|
197
|
+
schemaVersion: OBSERVABILITY_SCHEMA_VERSION,
|
|
198
|
+
ts: new Date().toISOString(),
|
|
199
|
+
sessionId: opts.sessionId,
|
|
200
|
+
category: 'gate',
|
|
201
|
+
sliceRid: opts.sliceRid,
|
|
202
|
+
detail
|
|
203
|
+
}, { projectRoot: opts.projectRoot });
|
|
204
|
+
}
|
|
205
|
+
catch (error) {
|
|
206
|
+
// Fire-and-forget: the gate's verdict must not change because the event
|
|
207
|
+
// could not be written. `error` is held so the block is not an empty
|
|
208
|
+
// catch — swallowing it IS the contract, not an oversight.
|
|
209
|
+
void error;
|
|
210
|
+
}
|
|
211
|
+
}
|
|
@@ -24,6 +24,12 @@
|
|
|
24
24
|
* table cannot prove "nobody claimed it", and guessing there would blame one
|
|
25
25
|
* slice for another's change. When it does not run, the returned note says so:
|
|
26
26
|
* a silently skipped check is indistinguishable from a passing one.
|
|
27
|
+
*
|
|
28
|
+
* EVERY DECISION IS RECORDED. Each gate that runs emits one `gate` event
|
|
29
|
+
* carrying its stable id, the phase, the declared type and what it decided
|
|
30
|
+
* (`pass` / `block` / `bypass`), so the layer that decides can be read back
|
|
31
|
+
* instead of inferred from the absence of an error. A refusal is recorded
|
|
32
|
+
* BEFORE it is thrown.
|
|
27
33
|
*/
|
|
28
34
|
import type { RequestType } from './artifact-prerequisites.js';
|
|
29
35
|
import { type RequestArtifactState } from './request-artifact-state-helpers.js';
|