@holmes-lab/holmes-kit 0.40.0 → 0.41.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/CHANGELOG.md +312 -0
- package/README.md +79 -5
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/approve-context.js +4 -3
- package/dist/holmes/cli/approve.js +22 -12
- package/dist/holmes/cli/autonomy.d.ts +21 -0
- package/dist/holmes/cli/autonomy.js +35 -5
- package/dist/holmes/cli/doctor.js +58 -6
- package/dist/holmes/cli/index.js +394 -267
- package/dist/holmes/cli/init.js +17 -6
- package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
- package/dist/holmes/cli/interactive-prompt.js +98 -16
- package/dist/holmes/cli/ledger-witness.d.ts +61 -0
- package/dist/holmes/cli/ledger-witness.js +212 -0
- package/dist/holmes/cli/playbook-skills.d.ts +3 -56
- package/dist/holmes/cli/playbook-skills.js +26 -349
- package/dist/holmes/config/config.d.ts +21 -0
- package/dist/holmes/config/config.js +22 -3
- package/dist/holmes/governance/approval-queue.d.ts +65 -1
- package/dist/holmes/governance/approval-queue.js +279 -9
- package/dist/holmes/governance/autonomous-shell.d.ts +13 -1
- package/dist/holmes/governance/autonomous-shell.js +157 -4
- package/dist/holmes/governance/autonomy.d.ts +216 -0
- package/dist/holmes/governance/autonomy.js +1162 -10
- package/dist/holmes/governance/install-manifest.d.ts +7 -4
- package/dist/holmes/governance/install-manifest.js +144 -14
- package/dist/holmes/governance/ledger-witness.d.ts +63 -0
- package/dist/holmes/governance/ledger-witness.js +296 -0
- package/dist/holmes/governance/provenance-chain.d.ts +8 -1
- package/dist/holmes/governance/provenance-chain.js +23 -4
- package/dist/holmes/governance/push-gate-runner.d.ts +2 -0
- package/dist/holmes/governance/push-gate-runner.js +40 -3
- package/dist/holmes/governance/push-gate.d.ts +13 -2
- package/dist/holmes/governance/push-gate.js +106 -14
- package/dist/holmes/governance/recorded-pairs.d.ts +4 -0
- package/dist/holmes/governance/recorded-pairs.js +25 -1
- package/dist/holmes/governance/session-context.d.ts +7 -0
- package/dist/holmes/governance/session-context.js +34 -6
- package/dist/holmes/guardrail/advisory-line.d.ts +102 -0
- package/dist/holmes/guardrail/advisory-line.js +718 -0
- package/dist/holmes/guardrail/anchor-scope-text.d.ts +9 -0
- package/dist/holmes/guardrail/anchor-scope-text.js +7 -0
- package/dist/holmes/guardrail/command-traits.d.ts +102 -0
- package/dist/holmes/guardrail/command-traits.js +379 -0
- package/dist/holmes/guardrail/fixtures/manager-builtins.json +23 -0
- package/dist/holmes/guardrail/fixtures/npm-commands.json +7 -0
- package/dist/holmes/guardrail/impact-gate.d.ts +6 -0
- package/dist/holmes/guardrail/impact-gate.js +32 -5
- package/dist/holmes/guardrail/outward-acts.d.ts +47 -0
- package/dist/holmes/guardrail/outward-acts.js +1102 -0
- package/dist/holmes/guardrail/refusal-codes.js +8 -1
- package/dist/holmes/guardrail/refusal-templates.d.ts +15 -0
- package/dist/holmes/guardrail/refusal-templates.js +71 -0
- package/dist/holmes/guardrail/risk-classifier.d.ts +22 -6
- package/dist/holmes/guardrail/risk-classifier.js +12 -118
- package/dist/holmes/guardrail/shell-lexer.d.ts +69 -0
- package/dist/holmes/guardrail/shell-lexer.js +567 -0
- package/dist/holmes/guardrail/write-target.js +7 -1
- package/dist/holmes/hooks/pre-tool-use.d.ts +71 -0
- package/dist/holmes/hooks/pre-tool-use.js +1466 -14
- package/dist/holmes/hooks/session-start.js +27 -1
- package/dist/holmes/hooks/stop.d.ts +7 -0
- package/dist/holmes/hooks/stop.js +39 -2
- package/dist/holmes/mcp/elicit-approval.d.ts +0 -21
- package/dist/holmes/mcp/elicit-approval.js +5 -2
- package/dist/holmes/mcp/handlers/approval-ask.js +3 -2
- package/dist/holmes/mcp/handlers/entity-integration.d.ts +1 -1
- package/dist/holmes/mcp/handlers/entity-integration.js +9 -6
- package/dist/holmes/mcp/handlers/entity-renumber.js +2 -1
- package/dist/holmes/mcp/handlers/entity-store.js +7 -2
- package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts +13 -0
- package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
- package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -0
- package/dist/holmes/mcp/handlers/operator-inspection.js +25 -4
- package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -1
- package/dist/holmes/mcp/handlers/spec-approval.js +28 -10
- package/dist/holmes/mcp/handlers/spec-lifecycle.js +10 -7
- package/dist/holmes/mcp/handlers/test-execution.d.ts +470 -3
- package/dist/holmes/mcp/handlers/test-execution.js +201 -21
- package/dist/holmes/mcp/handlers.d.ts +473 -8
- package/dist/holmes/mcp/handlers.js +6 -1
- package/dist/holmes/mcp/maintenance-analyze.d.ts +5 -0
- package/dist/holmes/mcp/maintenance-analyze.js +4 -2
- package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
- package/dist/holmes/mcp/maintenance-evidence.js +4 -1
- package/dist/holmes/mcp/tool-schemas.js +16 -10
- package/dist/holmes/project/baseline.d.ts +15 -2
- package/dist/holmes/project/baseline.js +11 -6
- package/dist/holmes/project/bounded-io.d.ts +1 -0
- package/dist/holmes/project/bounded-io.js +4 -2
- package/dist/holmes/project/change-source.d.ts +4 -0
- package/dist/holmes/project/change-source.js +13 -5
- package/dist/holmes/project/playbook-reference.d.ts +50 -0
- package/dist/holmes/project/playbook-reference.js +259 -0
- package/dist/holmes/project/playbook-skill-states.d.ts +94 -0
- package/dist/holmes/project/playbook-skill-states.js +396 -0
- package/dist/holmes/project/root.d.ts +9 -1
- package/dist/holmes/project/root.js +26 -3
- package/dist/holmes/project/running-package.d.ts +15 -0
- package/dist/holmes/project/running-package.js +87 -0
- package/dist/holmes/review/evidence-mode.d.ts +21 -0
- package/dist/holmes/review/evidence-mode.js +33 -0
- package/dist/holmes/review/head-worktree.d.ts +55 -0
- package/dist/holmes/review/head-worktree.js +329 -0
- package/dist/holmes/review/mrp.js +13 -3
- package/dist/holmes/review/run-provenance.d.ts +45 -0
- package/dist/holmes/review/run-provenance.js +314 -0
- package/dist/holmes/review/test-evidence.d.ts +174 -0
- package/dist/holmes/review/test-evidence.js +330 -2
- package/dist/holmes/review/test-reports.d.ts +94 -0
- package/dist/holmes/review/test-reports.js +382 -0
- package/dist/holmes/review/test-runner.d.ts +178 -65
- package/dist/holmes/review/test-runner.js +551 -319
- package/dist/holmes/review/test-units.d.ts +159 -0
- package/dist/holmes/review/test-units.js +814 -0
- package/dist/holmes/spec/entity-integration-transaction.d.ts +19 -2
- package/dist/holmes/spec/entity-integration-transaction.js +68 -7
- package/package.json +5 -2
- package/playbooks/publish/PLAYBOOK.md +2 -1
|
@@ -37,7 +37,7 @@ exports.detectInstallMode = detectInstallMode;
|
|
|
37
37
|
exports.buildSessionStartOutput = buildSessionStartOutput;
|
|
38
38
|
exports.staleWiredServerLine = staleWiredServerLine;
|
|
39
39
|
exports.driftNudge = driftNudge;
|
|
40
|
-
// @implements A-SPEC-531.2, A-SPEC-734, A-SPEC-476.1, A-SPEC-251.5
|
|
40
|
+
// @implements A-SPEC-794.84, A-SPEC-531.2, A-SPEC-734, A-SPEC-476.1, A-SPEC-251.5, A-SPEC-333.2, A-SPEC-333.4, A-SPEC-333.5
|
|
41
41
|
// The SessionStart banner hook. It emits the intro (+ optional update notice) as additionalContext,
|
|
42
42
|
// which Claude Code delivers to BOTH the human transcript and the agent context — the "human and
|
|
43
43
|
// agent" delivery REQ-531 asks for. The update refresh is a DETACHED, fire-and-forget child so the
|
|
@@ -184,6 +184,22 @@ if (require.main === module) {
|
|
|
184
184
|
let buf = '';
|
|
185
185
|
process.stdin.on('data', (c) => (buf += c));
|
|
186
186
|
process.stdin.on('end', () => {
|
|
187
|
+
// @implements A-SPEC-333.2, A-SPEC-333.4 — the first act: every SessionStart (startup, resume, clear, compact) opens a
|
|
188
|
+
// new warning epoch for the session, so what may be gone from the reader's context is said again. Nothing before it
|
|
189
|
+
// can fail and leave an old epoch standing. Fail-quiet: no epoch means every warning is said in full.
|
|
190
|
+
try {
|
|
191
|
+
const raw = JSON.parse(buf || '{}');
|
|
192
|
+
if (typeof raw.session_id === 'string' && raw.session_id !== '') {
|
|
193
|
+
const { openEpoch } = require('../guardrail/advisory-line');
|
|
194
|
+
const { resolveProjectRoot } = require('../project/root');
|
|
195
|
+
// A-SPEC-333.5 — the source tells the epoch whether the next compact boundary is its own
|
|
196
|
+
openEpoch(resolveProjectRoot(process.cwd()).root, raw.session_id, {
|
|
197
|
+
...(typeof raw.transcript_path === 'string' ? { transcriptPath: raw.transcript_path } : {}),
|
|
198
|
+
...(typeof raw.source === 'string' ? { source: raw.source } : {})
|
|
199
|
+
});
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
catch { /* the banner is never a gate */ }
|
|
187
203
|
try {
|
|
188
204
|
const out = buildSessionStartOutput({
|
|
189
205
|
version: pkgVersion(),
|
|
@@ -210,6 +226,16 @@ if (require.main === module) {
|
|
|
210
226
|
out.hookSpecificOutput.additionalContext += '\n' + line;
|
|
211
227
|
}
|
|
212
228
|
catch { /* the banner is never a gate */ }
|
|
229
|
+
// @implements A-SPEC-794.84 — requests no requester can follow up close unrun 24 hours after their last filing; one
|
|
230
|
+
// line says how many. Fail-open: a failure leaves every request as it was.
|
|
231
|
+
try {
|
|
232
|
+
const { closeExpiredRequests } = require('../governance/approval-queue');
|
|
233
|
+
const { resolveProjectRoot } = require('../project/root');
|
|
234
|
+
const n = closeExpiredRequests(resolveProjectRoot(process.cwd()).root, Date.now());
|
|
235
|
+
if (n > 0)
|
|
236
|
+
out.hookSpecificOutput.additionalContext += `\n[Holmes-Kit] ${n} approval request${n === 1 ? '' : 's'} without a requester closed unrun after 24 hours (closed-expired); asking again files a new request`;
|
|
237
|
+
}
|
|
238
|
+
catch { /* the banner is never a gate */ }
|
|
213
239
|
// @implements A-SPEC-554.1 — remind the human of the current autonomy posture (surface only, the
|
|
214
240
|
// headless hook never decides), and clean up an expired/invalid session marker. Fail-open.
|
|
215
241
|
try {
|
|
@@ -318,6 +318,13 @@ export declare function trackedLines(tracked?: {
|
|
|
318
318
|
article: string;
|
|
319
319
|
detail: string;
|
|
320
320
|
}[]): string[];
|
|
321
|
+
/**
|
|
322
|
+
* @implements A-SPEC-794.96 (S1) — principle 7's seam is the working tree: in Holmes-Kit's own repository, a gate-file
|
|
323
|
+
* change (staged, unstaged or untracked) that no open person-seal window names keeps the turn from ending. Two ways out
|
|
324
|
+
* only, and the same change set gives the same text (the consecutive-block cap still applies). Null where there is
|
|
325
|
+
* nothing to judge (no src/holmes, git cannot answer, no principle 7 change).
|
|
326
|
+
*/
|
|
327
|
+
export declare function principle7StopReason(root: string, specsDir: string, nowIso: string): string | null;
|
|
321
328
|
export declare function evaluateStop(specs: Spec[], evidence?: StopEvidence): {
|
|
322
329
|
block: boolean;
|
|
323
330
|
reason?: string;
|
|
@@ -52,6 +52,7 @@ exports.rolledBackLedgers = rolledBackLedgers;
|
|
|
52
52
|
exports.governanceLostPreflight = governanceLostPreflight;
|
|
53
53
|
exports.outsideAnyProject = outsideAnyProject;
|
|
54
54
|
exports.trackedLines = trackedLines;
|
|
55
|
+
exports.principle7StopReason = principle7StopReason;
|
|
55
56
|
exports.evaluateStop = evaluateStop;
|
|
56
57
|
exports.stopBlockText = stopBlockText;
|
|
57
58
|
exports.stopDebtAction = stopDebtAction;
|
|
@@ -66,7 +67,7 @@ exports.collectForbiddenEdgeJudgement = collectForbiddenEdgeJudgement;
|
|
|
66
67
|
exports.stopSharedScan = stopSharedScan;
|
|
67
68
|
exports.scanCodeCycles = scanCodeCycles;
|
|
68
69
|
exports.writeGuardCount = writeGuardCount;
|
|
69
|
-
// @implements A-SPEC-734, A-SPEC-772.1, A-SPEC-770.3, A-SPEC-770.7, A-SPEC-774.21, A-SPEC-778.1, A-SPEC-476.1, A-SPEC-792.1, A-SPEC-102.10, A-SPEC-102.12, A-SPEC-222.10, A-SPEC-222.12, A-SPEC-222.13
|
|
70
|
+
// @implements A-SPEC-794.97, A-SPEC-794.96, A-SPEC-734, A-SPEC-772.1, A-SPEC-770.3, A-SPEC-770.7, A-SPEC-774.21, A-SPEC-778.1, A-SPEC-476.1, A-SPEC-792.1, A-SPEC-102.10, A-SPEC-102.12, A-SPEC-222.10, A-SPEC-222.12, A-SPEC-222.13, A-SPEC-564.7
|
|
70
71
|
// @implements A-SPEC-769.9, A-SPEC-769.10, A-SPEC-769.11
|
|
71
72
|
const fs = __importStar(require("node:fs"));
|
|
72
73
|
// @implements A-SPEC-549.3 — evaluateStop's messages are English here; the Hangul-absence guard
|
|
@@ -823,6 +824,33 @@ function trackedLines(tracked) {
|
|
|
823
824
|
return `[Holmes-Kit] ${article}${label ? ` ${label}` : ''} (track): ${details.join(' | ')}`;
|
|
824
825
|
});
|
|
825
826
|
}
|
|
827
|
+
/**
|
|
828
|
+
* @implements A-SPEC-794.96 (S1) — principle 7's seam is the working tree: in Holmes-Kit's own repository, a gate-file
|
|
829
|
+
* change (staged, unstaged or untracked) that no open person-seal window names keeps the turn from ending. Two ways out
|
|
830
|
+
* only, and the same change set gives the same text (the consecutive-block cap still applies). Null where there is
|
|
831
|
+
* nothing to judge (no src/holmes, git cannot answer, no principle 7 change).
|
|
832
|
+
*/
|
|
833
|
+
function principle7StopReason(root, specsDir, nowIso) {
|
|
834
|
+
// A-SPEC-794.97 (B-M1) — a consumer repository reads no specs: the rule applies only where src/holmes exists
|
|
835
|
+
const p7 = require('../governance/autonomy');
|
|
836
|
+
if (!p7.isHolmesKitOwnRepo(root))
|
|
837
|
+
return null; // A-SPEC-794.97 r4b (L5)
|
|
838
|
+
let specs;
|
|
839
|
+
try {
|
|
840
|
+
specs = (0, pre_tool_use_1.readSpecsSync)(specsDir);
|
|
841
|
+
}
|
|
842
|
+
catch {
|
|
843
|
+
specs = [];
|
|
844
|
+
}
|
|
845
|
+
const v = p7.principle7Verdict(root, specs, Date.parse(nowIso));
|
|
846
|
+
if (v === null)
|
|
847
|
+
return null;
|
|
848
|
+
// A-SPEC-794.97 r4b (M2) — what a window saw is recorded whether or not another file is unopened
|
|
849
|
+
p7.recordWindowBlobs(root, nowIso, v);
|
|
850
|
+
if (v.unopened.length === 0)
|
|
851
|
+
return null;
|
|
852
|
+
return `[Holmes-Kit] ${p7.principle7RefusalText(v.unopened, v.base, { headSeen: v.headSeen, localOnly: v.localOnly })}`;
|
|
853
|
+
}
|
|
826
854
|
function evaluateStop(specs, evidence) {
|
|
827
855
|
// L1: the Stop gate IS the constitution's re-verification point — every turn boundary re-runs the
|
|
828
856
|
// inviolable articles (ART-2 RTM, ART-3 validity incl. 4-quadrant GWT, ART-4 coverage evidence).
|
|
@@ -1753,8 +1781,10 @@ if (require.main === module) {
|
|
|
1753
1781
|
const sum = sc.summarizeTranscript(text.split('\n'));
|
|
1754
1782
|
if (sum.turns > 0) {
|
|
1755
1783
|
sc.appendSessionContext(root, {
|
|
1784
|
+
// @implements A-SPEC-564.7 — the record names its counting rule, so a reader never adds it to an
|
|
1785
|
+
// older per-record count.
|
|
1756
1786
|
kind: 'usage', sessionKey: sessionId, models: sum.models, usage: sum.usage,
|
|
1757
|
-
turns: sum.turns, ...(sum.truncated ? { truncated: true } : {}), ts: new Date().toISOString(),
|
|
1787
|
+
turns: sum.turns, ...(sum.truncated ? { truncated: true } : {}), count: sc.USAGE_COUNT_RULE, ts: new Date().toISOString(),
|
|
1758
1788
|
});
|
|
1759
1789
|
}
|
|
1760
1790
|
}
|
|
@@ -1883,6 +1913,13 @@ if (require.main === module) {
|
|
|
1883
1913
|
}
|
|
1884
1914
|
catch { /* awareness is best-effort; a failure leaves the block intact */ }
|
|
1885
1915
|
}
|
|
1916
|
+
// @implements A-SPEC-794.96 (S1) — after the acknowledgement, so a queued request never waives it
|
|
1917
|
+
try {
|
|
1918
|
+
const p7 = principle7StopReason(stopProjectRoot(), specsDir, new Date().toISOString());
|
|
1919
|
+
if (p7 !== null)
|
|
1920
|
+
out = { ...out, block: true, reason: out.block && out.reason ? `${out.reason}\n${p7}` : p7 };
|
|
1921
|
+
}
|
|
1922
|
+
catch { /* the working-tree read is best-effort; the gate's other rules stand */ }
|
|
1886
1923
|
const guard = decideStopGuard(out.block, guardCountOrZero(sessionId));
|
|
1887
1924
|
const persisted = writeGuardCount(sessionId, guard.nextCount);
|
|
1888
1925
|
// @implements A-SPEC-778.1 — in a run, each blocked Stop goes on the run's log, and the cap yield stalls the run
|
|
@@ -1,24 +1,3 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* The decision comes INTO the session (REQ-263): an approval-shaped refusal (spec_approve without a
|
|
3
|
-
* covering HOLMES_APPROVAL) becomes an in-session question when the client advertises the MCP
|
|
4
|
-
* elicitation capability — the human answers at the point of decision, on the screen they are
|
|
5
|
-
* already looking at, and the tool call completes in place. No capability, an error, a timeout, or
|
|
6
|
-
* a dismissed window all degrade LOSSLESSLY to the current refusal + queue hint.
|
|
7
|
-
*
|
|
8
|
-
* TRUST MODEL (H-SPEC-263): an elicitation response is produced by the harness UI from a human —
|
|
9
|
-
* the model cannot forge it through tool arguments (the request travels server→client, off the tool
|
|
10
|
-
* surface). But the trust boundary sits at the harness, closer than the out-of-band env/grant
|
|
11
|
-
* channels an operator injects from a shell. Hence: (a) the kind allow-list below is conservative —
|
|
12
|
-
* soft-governance approvals only, hard-hitl (nonce-opened shell/config-write) stays out and
|
|
13
|
-
* widening it is a spec revision; (b) every grant is ledgered under an `elicitation:<client>` actor
|
|
14
|
-
* so audits can tell the channel apart; (c) grants are single-use by construction — the synthesized
|
|
15
|
-
* approval lives only inside the one call and is never persisted.
|
|
16
|
-
*
|
|
17
|
-
* PURE — no SDK import, no I/O. The server wires `Server.elicitInput` around these shapes; handlers
|
|
18
|
-
* receive an injected callback and never see the server instance, so tests drive every branch with
|
|
19
|
-
* a fake elicitor.
|
|
20
|
-
*/
|
|
21
|
-
/** Approval kinds that may ask in-session. Widening this set is a spec revision, not a drive-by. */
|
|
22
1
|
export declare const ELICITABLE_KINDS: ReadonlySet<string>;
|
|
23
2
|
/**
|
|
24
3
|
* @implements A-SPEC-540.1
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
"use strict";
|
|
2
|
-
// @implements A-SPEC-718.2, A-SPEC-718, A-SPEC-263.1, A-SPEC-732, A-SPEC-770.3, A-SPEC-770.6, A-SPEC-792.1
|
|
2
|
+
// @implements A-SPEC-794.90, A-SPEC-794.81, A-SPEC-718.2, A-SPEC-718, A-SPEC-263.1, A-SPEC-732, A-SPEC-770.3, A-SPEC-770.6, A-SPEC-792.1
|
|
3
3
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
4
4
|
exports.MAX_PRESENTATIONS = exports.WAIT_FOR_PERSON_MS = exports.ELICIT_TIMEOUT_MS = exports.ELICITABLE_KINDS = void 0;
|
|
5
5
|
exports.elicitationDisabled = elicitationDisabled;
|
|
@@ -32,7 +32,10 @@ exports.interpretElicitResult = interpretElicitResult;
|
|
|
32
32
|
*/
|
|
33
33
|
/** Approval kinds that may ask in-session. Widening this set is a spec revision, not a drive-by. */
|
|
34
34
|
// @implements A-SPEC-752.10 — `governance-wiring`: re-applying the binding the registry already names (never choosing one).
|
|
35
|
-
|
|
35
|
+
// A-SPEC-794.81 — un-seal and retire are asked in the form under their own kinds
|
|
36
|
+
// A-SPEC-794.90 — the transition kinds come from the one table (read at load; the table module does no I/O at load)
|
|
37
|
+
const { SPEC_TRANSITION_KIND } = require('../governance/approval-queue');
|
|
38
|
+
exports.ELICITABLE_KINDS = new Set([...Object.values(SPEC_TRANSITION_KIND), 'review-resolve', 'governance-wiring']);
|
|
36
39
|
/** The `HOLMES_ELICIT` values that turn the in-client prompt OFF. */
|
|
37
40
|
const ELICIT_DISABLED_TOKENS = new Set(['off', '0', 'false', 'no', 'disabled']);
|
|
38
41
|
/**
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.FORM_WAITS_FOR_PERSON = void 0;
|
|
4
4
|
exports.createApprovalAskHandlers = createApprovalAskHandlers;
|
|
5
|
-
// @implements A-SPEC-718.4, A-SPEC-792.1, A-SPEC-779.7, A-SPEC-245.9, A-SPEC-794.31, A-SPEC-794.33,A-SPEC-794.32
|
|
5
|
+
// @implements A-SPEC-794.84, A-SPEC-718.4, A-SPEC-792.1, A-SPEC-779.7, A-SPEC-245.9, A-SPEC-794.31, A-SPEC-794.33,A-SPEC-794.32
|
|
6
6
|
/**
|
|
7
7
|
* approval_ask — the person decides a pending request in the session's approval form, so no approval needs a typed
|
|
8
8
|
* command (owner audit 2026-10-20). Since A-SPEC-779.4 neither the agent's shell nor the session's `!` can run
|
|
@@ -44,8 +44,9 @@ function createApprovalAskHandlers(context) {
|
|
|
44
44
|
// @implements A-SPEC-794.31, A-SPEC-794.32 — when no request is found, a development-build one is named in words,
|
|
45
45
|
// and no form is shown; a decidable request is never refused for it (the answer of a lookup that failed)
|
|
46
46
|
// A-SPEC-794.33 — on the exact id only: approval_ask names a request by its whole id (B-2)
|
|
47
|
+
// A-SPEC-794.84 — a request closed unrun says so
|
|
47
48
|
if (!request)
|
|
48
|
-
return { ok: false, id, reason: (0, approval_queue_1.devFiledRefusal)((0, approval_queue_1.readQueue)(root), id, true) ?? `no pending request ${oneLine(id, 40)} in the approval inbox or this machine's refusal log` };
|
|
49
|
+
return { ok: false, id, reason: (0, approval_queue_1.devFiledRefusal)((0, approval_queue_1.readQueue)(root), id, true) ?? (0, approval_queue_1.closedExpiredNote)((0, approval_queue_1.readQueue)(root, { includeAllKinds: true }), id) ?? `no pending request ${oneLine(id, 40)} in the approval inbox or this machine's refusal log` };
|
|
49
50
|
const client = context.clientName();
|
|
50
51
|
const attestation = context.attestation();
|
|
51
52
|
if ((0, elicit_approval_1.elicitationDisabled)(context.env()))
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { type DerivedRebuild } from '../../spec/entity-integration-discharge';
|
|
2
2
|
import { EntityIntegrationPlan } from '../../spec/entity-integration-transaction';
|
|
3
3
|
export type IntegrationSealTransition = {
|
|
4
|
-
kind: 'spec-unsealed';
|
|
4
|
+
kind: 'spec-unsealed' | 'spec-retired';
|
|
5
5
|
id: string;
|
|
6
6
|
} | {
|
|
7
7
|
kind: 'spec-approved';
|
|
@@ -94,9 +94,10 @@ function renumberedMappingInputs(steps, renames = []) {
|
|
|
94
94
|
}
|
|
95
95
|
function integrationSealTransitions(operation) {
|
|
96
96
|
const transitions = [];
|
|
97
|
+
const retired = (0, entity_integration_transaction_1.retiredSpecIds)(operation); // A-SPEC-794.92 (M-1)
|
|
97
98
|
for (const step of operation.steps) {
|
|
98
99
|
if (step.phase === 'unseal' && step.specId)
|
|
99
|
-
transitions.push({ kind: 'spec-unsealed', id: step.specId });
|
|
100
|
+
transitions.push({ kind: retired.has(step.specId) ? 'spec-retired' : 'spec-unsealed', id: step.specId });
|
|
100
101
|
else if (step.phase === 'approve' && step.specId) {
|
|
101
102
|
if (typeof step.change.after !== 'string')
|
|
102
103
|
throw new entity_store_1.EntityStoreError('audit-conflict', 'Approve step ' + step.specId + ' publishes no document.');
|
|
@@ -222,8 +223,9 @@ function createEntityIntegrationHandlers(context) {
|
|
|
222
223
|
const grants = new Set(), authorities = new Set(), usedGrantRefs = new Set();
|
|
223
224
|
const spentHere = []; // A-SPEC-245.15 (item 2): the grants this act spent still authorize its later steps
|
|
224
225
|
const grantRef = (approval) => 'grant-use:' + (0, entity_transaction_1.entityContentVersion)(JSON.stringify({ actor: approval.actor, token: approval.token, nonce: approval.nonce, scope: approval.scope, expires: approval.expires }));
|
|
225
|
-
|
|
226
|
-
|
|
226
|
+
// A-SPEC-794.85 — a spec step's authority is its transition's kind, from the one table
|
|
227
|
+
const requireAuthority = (specId, transition = 'seal') => {
|
|
228
|
+
const action = { kind: specId ? approval_queue_1.SPEC_TRANSITION_KIND[transition] : 'config-write', target: specId ?? target };
|
|
227
229
|
const resolved = (0, approval_grants_1.resolveApproval)(bound.root, env, action, new Date().toISOString(), spentHere);
|
|
228
230
|
if (!resolved)
|
|
229
231
|
throw new entity_store_1.EntityStoreError(specId ? 'spec-approval-required' : 'approval-required', 'Current authority is required for this integration.' + (0, approval_queue_1.queueHint)(bound.root, { ...action, why: 'Integrate the exact Git inputs while preserving entity identity and official seal transitions.' }));
|
|
@@ -296,10 +298,11 @@ function createEntityIntegrationHandlers(context) {
|
|
|
296
298
|
for (const transition of integrationSealTransitions(operation)) {
|
|
297
299
|
if (events.some(event => event.kind === transition.kind && event.inputs?.includes(transition.id) && event.inputs?.includes(binding[0])))
|
|
298
300
|
continue;
|
|
299
|
-
const sealAuthority = requireAuthority(transition.id);
|
|
301
|
+
const sealAuthority = requireAuthority(transition.id, transition.kind === 'spec-unsealed' ? 'unseal' : transition.kind === 'spec-retired' ? 'retire' : 'seal');
|
|
300
302
|
ledger.append({ ts: new Date().toISOString(), actor: sealAuthority.approval.actor, kind: transition.kind,
|
|
301
|
-
summary: transition.kind === 'spec-
|
|
302
|
-
|
|
303
|
+
summary: transition.kind === 'spec-approved' ? 'approved ' + transition.id + ' sealing ' + transition.digest
|
|
304
|
+
: (transition.kind === 'spec-retired' ? 'retired ' : 'unsealed ') + transition.id + ' (integration ' + operation.operationId + ')',
|
|
305
|
+
inputs: transition.kind === 'spec-approved' ? [transition.id, transition.digest, binding[0]] : [transition.id, binding[0]],
|
|
303
306
|
rationale: sealAuthority.approval.rationale, authorization: (0, provenance_chain_1.authorizationRef)(sealAuthority.approval.actor, sealAuthority.approval.token) });
|
|
304
307
|
}
|
|
305
308
|
ledger.append({ ts: new Date().toISOString(), actor: authority.approval.actor, kind: 'entity-integrated', summary: 'Completed Git entity integration ' + operation.operationId,
|
|
@@ -121,7 +121,8 @@ function createEntityRenumberHandlers(context) {
|
|
|
121
121
|
const spentHere = []; // A-SPEC-245.15 (item 2): the grants this act spent still authorize its later steps
|
|
122
122
|
const grantRef = (approval) => 'grant-use:' + (0, entity_transaction_1.entityContentVersion)(JSON.stringify({ actor: approval.actor, token: approval.token, nonce: approval.nonce, scope: approval.scope, expires: approval.expires }));
|
|
123
123
|
const requireAuthority = (specId) => {
|
|
124
|
-
|
|
124
|
+
// A-SPEC-794.85 — a renumbered sealed document keeps its seal: the seal's kind, from the one table
|
|
125
|
+
const action = { kind: specId ? approval_queue_1.SPEC_TRANSITION_KIND.seal : 'config-write', target: specId ?? target };
|
|
125
126
|
const resolved = (0, approval_grants_1.resolveApproval)(bound.root, env, action, new Date().toISOString(), spentHere);
|
|
126
127
|
if (!resolved)
|
|
127
128
|
throw new entity_store_1.EntityStoreError(specId ? 'spec-approval-required' : 'approval-required', 'Current authority is required for this renumber operation.' + (0, approval_queue_1.queueHint)(bound.root, { ...action, why: 'Preserve UUIDs and the official approval closure while renumbering.' }));
|
|
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
36
|
exports.createEntityStoreHandlers = createEntityStoreHandlers;
|
|
37
|
-
// @implements A-SPEC-627, A-SPEC-627.1, A-SPEC-222.10, A-SPEC-222.12
|
|
37
|
+
// @implements A-SPEC-794.85, A-SPEC-627, A-SPEC-627.1, A-SPEC-222.10, A-SPEC-222.12
|
|
38
38
|
// @implements A-SPEC-642, A-SPEC-245.9, A-SPEC-245.15
|
|
39
39
|
// @implements A-SPEC-641
|
|
40
40
|
// @implements A-SPEC-638
|
|
@@ -149,7 +149,12 @@ function createEntityStoreHandlers(context) {
|
|
|
149
149
|
let result;
|
|
150
150
|
try {
|
|
151
151
|
result = (0, entity_store_1.recoverEntityStore)(context.storeRoot, plan, (before, after, inventory) => {
|
|
152
|
-
|
|
152
|
+
// A-SPEC-794.85 — the journal's target status names the transition, and the table its kind (an interrupted
|
|
153
|
+
// un-seal or retirement is recovered by its own kind, never by a seal's); an unsupported one asks for nothing
|
|
154
|
+
const transition = before ? (0, approval_queue_1.specTransitionOfStatus)(after.status) : null;
|
|
155
|
+
if (transition === null)
|
|
156
|
+
throw new entity_store_1.EntityStoreError('unsupported-recovery', 'Unsupported specification transition.');
|
|
157
|
+
const specAction = { kind: approval_queue_1.SPEC_TRANSITION_KIND[transition], target: after.id };
|
|
153
158
|
const requireAuthority = () => {
|
|
154
159
|
const authority = (0, approval_grants_1.resolveApproval)(bound.root, env, specAction, new Date().toISOString(), spentHere);
|
|
155
160
|
if (!authority)
|
|
@@ -4,6 +4,19 @@ import { DecisionRecord, DecisionCitation } from '../../rtm/rtm-builder';
|
|
|
4
4
|
import { ContentSource } from '../../context/bundler';
|
|
5
5
|
import { MaintenanceGroundTruth, MaintenanceAnalysis } from '../maintenance-analyze';
|
|
6
6
|
import { Basis } from '../basis';
|
|
7
|
+
/**
|
|
8
|
+
* @implements A-SPEC-293.1 — the working tree's changes against HEAD, tracked and untracked, bounded; undefined when there
|
|
9
|
+
* are none or git cannot say (the caller then keeps the axis disclosed as not assessed).
|
|
10
|
+
* @implements A-SPEC-333.8 — both lists are relative to the analysed root (`--relative`, as `ls-files` already is), so a
|
|
11
|
+
* change elsewhere in the repository is not this analysis's; both children run inert under one deadline; governing
|
|
12
|
+
* documents are taken first, and a cut list says so.
|
|
13
|
+
* @implements A-SPEC-333.9 — a timeout here is the analysis's own deadline, not the root's slowness: it is not recorded,
|
|
14
|
+
* so it blocks no later git call for this root.
|
|
15
|
+
*/
|
|
16
|
+
export declare function workingTreeChanges(root: string, deadlineMs?: number): {
|
|
17
|
+
files: string[];
|
|
18
|
+
truncated: boolean;
|
|
19
|
+
} | undefined;
|
|
7
20
|
export interface MaintenanceAnalysisContext {
|
|
8
21
|
listSpecs(): Promise<Spec[]>;
|
|
9
22
|
foreignRootReason(root?: string): string | null;
|
|
@@ -33,8 +33,9 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
33
33
|
};
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.workingTreeChanges = workingTreeChanges;
|
|
36
37
|
exports.createMaintenanceAnalysisHandlers = createMaintenanceAnalysisHandlers;
|
|
37
|
-
// @implements A-SPEC-476.1, A-SPEC-745, A-SPEC-469.1,A-SPEC-469.2, A-SPEC-741, A-SPEC-741.1, A-SPEC-612, A-SPEC-100.2, A-SPEC-128, A-SPEC-189, A-SPEC-267, A-SPEC-268, A-SPEC-269, A-SPEC-277, A-SPEC-283, A-SPEC-290, A-SPEC-292, A-SPEC-293, A-SPEC-378, A-SPEC-388, A-SPEC-418, A-SPEC-478, A-SPEC-571.2, A-SPEC-573.4, A-SPEC-578.5, A-SPEC-734, A-SPEC-278.3
|
|
38
|
+
// @implements A-SPEC-476.1, A-SPEC-745, A-SPEC-469.1,A-SPEC-469.2, A-SPEC-741, A-SPEC-741.1, A-SPEC-612, A-SPEC-100.2, A-SPEC-128, A-SPEC-189, A-SPEC-267, A-SPEC-268, A-SPEC-269, A-SPEC-277, A-SPEC-283, A-SPEC-290, A-SPEC-292, A-SPEC-293, A-SPEC-378, A-SPEC-388, A-SPEC-418, A-SPEC-478, A-SPEC-571.2, A-SPEC-573.4, A-SPEC-578.5, A-SPEC-734, A-SPEC-278.3, A-SPEC-293.1, A-SPEC-333.8, A-SPEC-333.9
|
|
38
39
|
const fs = __importStar(require("node:fs"));
|
|
39
40
|
const path = __importStar(require("node:path"));
|
|
40
41
|
const node_child_process_1 = require("node:child_process");
|
|
@@ -60,6 +61,47 @@ const maintenance_analyze_1 = require("../maintenance-analyze");
|
|
|
60
61
|
const maintenance_evidence_1 = require("../maintenance-evidence");
|
|
61
62
|
const defuse_bound_1 = require("../defuse-bound");
|
|
62
63
|
const bounded_io_1 = require("../../project/bounded-io");
|
|
64
|
+
/** At most this many paths from the working tree's own diff (A-SPEC-293.1). */
|
|
65
|
+
const ARCHITECTURE_BASIS_MAX = 2000;
|
|
66
|
+
/** The two git children together finish within this (A-SPEC-333.8). */
|
|
67
|
+
const ARCHITECTURE_BASIS_DEADLINE_MS = 5000;
|
|
68
|
+
/**
|
|
69
|
+
* @implements A-SPEC-293.1 — the working tree's changes against HEAD, tracked and untracked, bounded; undefined when there
|
|
70
|
+
* are none or git cannot say (the caller then keeps the axis disclosed as not assessed).
|
|
71
|
+
* @implements A-SPEC-333.8 — both lists are relative to the analysed root (`--relative`, as `ls-files` already is), so a
|
|
72
|
+
* change elsewhere in the repository is not this analysis's; both children run inert under one deadline; governing
|
|
73
|
+
* documents are taken first, and a cut list says so.
|
|
74
|
+
* @implements A-SPEC-333.9 — a timeout here is the analysis's own deadline, not the root's slowness: it is not recorded,
|
|
75
|
+
* so it blocks no later git call for this root.
|
|
76
|
+
*/
|
|
77
|
+
function workingTreeChanges(root, deadlineMs = ARCHITECTURE_BASIS_DEADLINE_MS) {
|
|
78
|
+
const started = Date.now();
|
|
79
|
+
const run = (args) => {
|
|
80
|
+
const left = deadlineMs - (Date.now() - started);
|
|
81
|
+
if (left <= 0)
|
|
82
|
+
return undefined;
|
|
83
|
+
const r = (0, bounded_io_1.gitOnce)(root, args, 'worktree', { timeout: left, env: (0, bounded_io_1.inertGitConfig)((0, root_1.cleanSubprocessEnv)()), record: false });
|
|
84
|
+
return r.status === 0 && !r.error ? r.stdout : undefined;
|
|
85
|
+
};
|
|
86
|
+
const tracked = run(['diff', '--name-only', '-z', '--relative', 'HEAD']);
|
|
87
|
+
const untracked = tracked === undefined ? undefined : run(['ls-files', '--others', '--exclude-standard', '-z']);
|
|
88
|
+
if (tracked === undefined || untracked === undefined)
|
|
89
|
+
return undefined;
|
|
90
|
+
const all = new Set();
|
|
91
|
+
for (const f of `${tracked}\0${untracked}`.split('\0')) {
|
|
92
|
+
// the governance store's runtime state (evidence, ledgers, caches) is not a change: an analysis persisted a moment
|
|
93
|
+
// ago must not change the next one. Its documents (.ax/decisions, .ax/specs) are kept: they are the axis.
|
|
94
|
+
if (f === '' || (f.startsWith('.ax/') && !f.startsWith('.ax/decisions/') && !f.startsWith('.ax/specs/')))
|
|
95
|
+
continue;
|
|
96
|
+
all.add(f);
|
|
97
|
+
}
|
|
98
|
+
if (all.size === 0)
|
|
99
|
+
return undefined;
|
|
100
|
+
const governing = (0, test_scope_1.architectureGoverningFiles)([...all]);
|
|
101
|
+
const rest = [...all].filter((f) => !governing.includes(f));
|
|
102
|
+
const files = [...governing, ...rest].slice(0, ARCHITECTURE_BASIS_MAX);
|
|
103
|
+
return { files, truncated: all.size > files.length };
|
|
104
|
+
}
|
|
63
105
|
/** @implements A-SPEC-759 — at most this many changed files have their HEAD text read for the missing-new-file finding. */
|
|
64
106
|
const MISSING_NEW_FILES_PRIOR_READS = 50;
|
|
65
107
|
function createMaintenanceAnalysisHandlers(context) {
|
|
@@ -82,6 +124,11 @@ function createMaintenanceAnalysisHandlers(context) {
|
|
|
82
124
|
head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { maxBuffer: bounded_io_1.GIT_MAX_BUFFER, timeout: 5000, encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
|
|
83
125
|
}
|
|
84
126
|
catch { /* non-git */ }
|
|
127
|
+
// @implements A-SPEC-293.1 — no list from the caller: the working tree's own diff assesses the architecture axis
|
|
128
|
+
// (and nothing else). A clean or non-git tree passes nothing, so the axis stays disclosed as not assessed.
|
|
129
|
+
const basis = a.changedFiles === undefined && head !== '' ? workingTreeChanges(root) : undefined;
|
|
130
|
+
const architectureBasis = basis?.files;
|
|
131
|
+
const changedFilesSource = a.changedFiles !== undefined ? 'caller' : architectureBasis ? 'git-diff-default' : 'none';
|
|
85
132
|
const unsupportedLanguages = new Set();
|
|
86
133
|
// @implements A-SPEC-741 — the paths too, so the analysis can tell an unreadable file that may
|
|
87
134
|
// be this request's target from one that is unrelated. Bounded: a vendored tree must not grow it.
|
|
@@ -124,6 +171,7 @@ function createMaintenanceAnalysisHandlers(context) {
|
|
|
124
171
|
specFingerprint: `count:${specs.length}/fp:${detail.specs ?? 'unknown'}`,
|
|
125
172
|
},
|
|
126
173
|
changedFiles: a.changedFiles,
|
|
174
|
+
...(architectureBasis ? { architectureBasis } : {}),
|
|
127
175
|
// @implements A-SPEC-290 — the stored run record. Freshness is judged inside the analysis
|
|
128
176
|
// against its own basis, so a record from another commit is reported as stale rather than
|
|
129
177
|
// quietly used.
|
|
@@ -346,6 +394,14 @@ function createMaintenanceAnalysisHandlers(context) {
|
|
|
346
394
|
const blind = context.specStoreBlindReason(root, specs.length);
|
|
347
395
|
if (blind !== null)
|
|
348
396
|
result.unknowns = [blind, ...result.unknowns];
|
|
397
|
+
result.changedFilesSource = changedFilesSource;
|
|
398
|
+
// @implements A-SPEC-333.8 — what the default basis is, and is not, said where the answer is read
|
|
399
|
+
if (basis) {
|
|
400
|
+
result.unknowns = [...result.unknowns,
|
|
401
|
+
"The architecture axis was assessed from the working tree's diff against HEAD under this root; it holds no file the request has yet to change, so pass changedFiles to assess those."];
|
|
402
|
+
if (basis.truncated)
|
|
403
|
+
result.unknowns.push(`The architecture basis was cut at ${ARCHITECTURE_BASIS_MAX} working-tree files (decision and C-SPEC documents first); files past the cut were not assessed.`);
|
|
404
|
+
}
|
|
349
405
|
if (a.persist) {
|
|
350
406
|
// @implements A-SPEC-277 — record WHAT WAS ANALYSED, not just which paths. HEAD cannot see
|
|
351
407
|
// an uncommitted edit to the analysed file; a content digest can.
|
|
@@ -360,7 +416,8 @@ function createMaintenanceAnalysisHandlers(context) {
|
|
|
360
416
|
// product actually predicted.
|
|
361
417
|
result.persistedTo = (0, maintenance_evidence_1.writeArtifact)(path.join(root, maintenance_evidence_1.EVIDENCE_DIR), (0, maintenance_evidence_1.artifactFrom)(analysis, new Date().toISOString(), fileDigests,
|
|
362
418
|
// @implements A-SPEC-278.3 — the request and the caller's changed files travel with the prediction.
|
|
363
|
-
|
|
419
|
+
// A-SPEC-293.1 — the default diff is never recorded as the caller's list (the gate reads that as "named")
|
|
420
|
+
{ request: a.request, changedFiles: a.changedFiles, changedFilesSource }));
|
|
364
421
|
}
|
|
365
422
|
// @implements A-SPEC-578.5 — the response, and only the response, is bounded. Measured
|
|
366
423
|
// 2026-09-09: the full shape is 187,174 characters (~47k tokens) and the harness refuses
|
|
@@ -11,6 +11,8 @@ export interface ApprovalRequestState {
|
|
|
11
11
|
state: 'pending' | 'held' | 'granted' | 'unusable' | 'claimed' | 'expired' | 'consumed' | 'denied' | 'revoked' | 'withdrawn';
|
|
12
12
|
question?: string;
|
|
13
13
|
reason?: string;
|
|
14
|
+
/** @implements A-SPEC-794.85 — which act the request is for: spec-approve, spec-unseal or spec-retire. */
|
|
15
|
+
kind?: string;
|
|
14
16
|
/** @implements A-SPEC-245.9 (1b-6) — for a live grant: "single use, until <time>" or "single use, no time limit". */
|
|
15
17
|
validity?: string;
|
|
16
18
|
ts?: string;
|
|
@@ -36,7 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
36
36
|
exports.approvalRequestOf = approvalRequestOf;
|
|
37
37
|
exports.nextActionOf = nextActionOf;
|
|
38
38
|
exports.createOperatorInspectionHandlers = createOperatorInspectionHandlers;
|
|
39
|
-
// @implements A-SPEC-605, A-SPEC-605.1, A-SPEC-779.3, A-SPEC-245.17, A-SPEC-794.33, A-SPEC-794.34, A-SPEC-794.35, A-SPEC-794.37, A-SPEC-794.40, A-SPEC-794.41, A-SPEC-794.42, A-SPEC-794.44
|
|
39
|
+
// @implements A-SPEC-794.85, A-SPEC-605, A-SPEC-605.1, A-SPEC-779.3, A-SPEC-245.17, A-SPEC-794.33, A-SPEC-794.34, A-SPEC-794.35, A-SPEC-794.37, A-SPEC-794.40, A-SPEC-794.41, A-SPEC-794.42, A-SPEC-794.44
|
|
40
40
|
// @implements A-SPEC-642, A-SPEC-245.9, A-SPEC-245.15
|
|
41
41
|
// @implements A-SPEC-631
|
|
42
42
|
// @implements A-SPEC-768
|
|
@@ -59,9 +59,23 @@ const approval_queue_1 = require("../../governance/approval-queue");
|
|
|
59
59
|
* this reads it. Read-only; an unreadable queue is no request.
|
|
60
60
|
*/
|
|
61
61
|
function approvalRequestOf(root, specId) {
|
|
62
|
+
// @implements A-SPEC-794.85 — the spec's seal, un-seal and retirement requests: an open one (pending or held) first,
|
|
63
|
+
// the latest of them; else the latest decided one. 794.81 split the kinds and this looked up the seal's only.
|
|
62
64
|
try {
|
|
63
|
-
const id = (0, approval_queue_1.approvalRequestId)('spec-approve', specId);
|
|
64
65
|
const q = (0, approval_queue_1.readQueue)(root);
|
|
66
|
+
const states = Object.values(approval_queue_1.SPEC_TRANSITION_KIND)
|
|
67
|
+
.map((kind) => { const s = requestStateOf(root, q, kind, specId); return s && { ...s, kind }; })
|
|
68
|
+
.filter((s) => s !== undefined);
|
|
69
|
+
const latest = (xs) => [...xs].sort((a, b) => (b.ts ?? '').localeCompare(a.ts ?? ''))[0];
|
|
70
|
+
return latest(states.filter((s) => s.state === 'pending' || s.state === 'held')) ?? latest(states);
|
|
71
|
+
}
|
|
72
|
+
catch {
|
|
73
|
+
return undefined;
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
function requestStateOf(root, q, kind, specId) {
|
|
77
|
+
try {
|
|
78
|
+
const id = (0, approval_queue_1.approvalRequestId)(kind, specId);
|
|
65
79
|
const pending = q.pending.find((p) => p.id === id);
|
|
66
80
|
const hold = q.holds[id];
|
|
67
81
|
if (pending?.hold || hold) {
|
|
@@ -79,7 +93,7 @@ function approvalRequestOf(root, specId) {
|
|
|
79
93
|
// (A-M2: an expired, other-target or other-workspace file read `granted` here while it covered nothing)
|
|
80
94
|
// @implements A-SPEC-245.17 (item 4) — a grant past its expiry (or with an empty one) is expired, not granted
|
|
81
95
|
// @implements A-SPEC-245.18 (5c) — an expiry that is not a date is expired too: `grantedStateOf`, the one order (794.37)
|
|
82
|
-
const grant = (0, approval_grants_1.requestGrantState)(root, id, { kind
|
|
96
|
+
const grant = (0, approval_grants_1.requestGrantState)(root, id, { kind, target: specId }, new Date().toISOString());
|
|
83
97
|
const state = (0, approval_grants_1.grantedStateOf)({ covers: grant.state === 'covers', claimed: grant.state === 'claimed', ...(d.consumedTs ? { consumedTs: d.consumedTs } : {}), ...(d.expires !== undefined ? { expires: d.expires } : {}) }, Date.now());
|
|
84
98
|
if (state === 'live')
|
|
85
99
|
return { id, state: 'granted', validity: (0, approve_1.grantValidityText)(d.expires), ts: d.ts };
|
|
@@ -105,8 +119,15 @@ function approvalRequestOf(root, specId) {
|
|
|
105
119
|
* because nothing in the response said what to do once the seal was there.
|
|
106
120
|
*/
|
|
107
121
|
function nextActionOf(described, request) {
|
|
108
|
-
|
|
122
|
+
// @implements A-SPEC-794.90 — the advice names the act its request is for: an un-seal or a retirement waiting on a
|
|
123
|
+
// sealed spec is not "sealed — stop polling"
|
|
124
|
+
const act = request?.kind === approval_queue_1.SPEC_TRANSITION_KIND.unseal ? 'spec_unseal' : request?.kind === approval_queue_1.SPEC_TRANSITION_KIND.retire ? 'spec_retire' : 'spec_approve';
|
|
125
|
+
if (described.sealed && act === 'spec_approve')
|
|
109
126
|
return 'sealed — stop polling this id; call spec_slice_approve or spec_approve for the next unsealed spec of the chain (spec_next names it).';
|
|
127
|
+
const advice = adviceFor(described, request);
|
|
128
|
+
return act === 'spec_approve' ? advice : advice.replace(/\bspec_approve\b/g, act);
|
|
129
|
+
}
|
|
130
|
+
function adviceFor(described, request) {
|
|
110
131
|
switch (request?.state) {
|
|
111
132
|
case 'held': return `held — the operator asks: ${request.question ?? '(no question recorded)'}. Resolve it in the spec or tests, then call spec_approve again.`;
|
|
112
133
|
case 'denied': return `denied — ${request.reason ?? 'no reason recorded'}. Do not re-request the same act; report it to the user.`;
|
|
@@ -6,6 +6,8 @@ import { ElicitOutcome } from '../elicit-approval';
|
|
|
6
6
|
import { ApprovalIntent } from '../approval-intent';
|
|
7
7
|
import { ApprovalAdapter } from '../approval-adapters';
|
|
8
8
|
export interface SpecApprovalContext {
|
|
9
|
+
/** @implements A-SPEC-794.85 — the MCP server instance this handler runs in (`<pid>:<startedAt>`), recorded on a seal. */
|
|
10
|
+
serverInstance?: () => string | undefined;
|
|
9
11
|
store: SpecStore;
|
|
10
12
|
resolver(specs: Spec[]): (id: string) => Spec | null;
|
|
11
13
|
projectRootOf(root: string): string;
|
|
@@ -110,7 +112,7 @@ export declare function createSpecApprovalHandlers(context: SpecApprovalContext)
|
|
|
110
112
|
advisoryIds?: Partial<Record<string, string>> | undefined;
|
|
111
113
|
killsAdvisory?: import("../../review/kills-check").KillsAdvisory | undefined;
|
|
112
114
|
fttFulfilment?: import("../../rtm/ftt-fulfilment").FttFulfilment | undefined;
|
|
113
|
-
impactAdvisoryUnavailable?: "
|
|
115
|
+
impactAdvisoryUnavailable?: "unreadable" | "empty" | undefined;
|
|
114
116
|
impactGraph?: {
|
|
115
117
|
status: "current" | "stale" | "unverified";
|
|
116
118
|
sourceCommit: string | null;
|