@holmes-lab/holmes-kit 0.35.8 → 0.35.10

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 CHANGED
@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
  <!-- @implements A-SPEC-209 -->
8
+ ## [0.35.10] - 2026-10-06
9
+
10
+ ### Changed
11
+
12
+ - **A Stop block says who acts next** (A-SPEC-247.1). Measured in a live session: the Stop gate repeated the same
13
+ violations on more than eight stops while every exit needed the operator, and the text named neither the pending
14
+ request nor who had to act. The block now lists each violation under one of two headings. *Waiting on the
15
+ operator* — an ART-4 whose document, or an open critical finding whose id, already has a pending request in the
16
+ approval queue; the line carries the request id and says the operator decides it, in the session's approval
17
+ dialog or with `holmes-kit approve`. *The session acts* — everything else, with the act that clears it (for ART-4:
18
+ anchor real covering tests, or retire a withdrawn design with `spec_retire`; for an open critical: fix, re-review,
19
+ then record `resolved`). Only the text changed: which violations block, the block cap and constitution debt are
20
+ as before, and a violation that waits on the operator still blocks. The first line of the block is unchanged.
21
+
22
+ ## [0.35.9] - 2026-10-06
23
+
24
+ ### Security
25
+
26
+ - **The single-key approval screen shows in full what it asks about** (A-SPEC-497.4). In `holmes-kit approve --watch`
27
+ on a terminal, an item whose subject did not fit its row was shown as `… (258자 잘림)` and one keypress approved
28
+ it — most of the command was never on the screen. Such an item's full text is now printed before the keys are
29
+ offered, and `v` shows the details of any item without deciding anything (`[a]approve [v]details [d]deny
30
+ [q]question [s]skip`). The text comes from the same escaped, capped renderer the line-based screen's `[v]` uses.
31
+ `holmes-kit approve --status` shows recent outcomes if you want to review what was approved this way.
32
+
8
33
  ## [0.35.8] - 2026-10-06
9
34
 
10
35
  ### Added
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- 60474c12-muvgbymb
1
+ 68b1cf14-muvvonaz
@@ -14,7 +14,7 @@ export interface KeyStream {
14
14
  * rejects with AbortError: leaving is not deciding. No deadline anywhere: the MAIN LANE's whole
15
15
  * point is that a human terminal can wait forever (H-SPEC-497).
16
16
  */
17
- export declare function decideByKey(stream: KeyStream, _item: Pick<PendingRequest, 'id'>): Promise<'granted' | 'denied' | 'skipped' | {
17
+ export declare function decideByKey(stream: KeyStream, _item: Pick<PendingRequest, 'id'>, onView?: () => void): Promise<'granted' | 'denied' | 'skipped' | {
18
18
  question: string;
19
19
  }>;
20
20
  /**
@@ -5,7 +5,7 @@ exports.decideByKey = decideByKey;
5
5
  exports.presentByKey = presentByKey;
6
6
  exports.defaultWaitIdle = defaultWaitIdle;
7
7
  exports.runWatch = runWatch;
8
- // @implements A-SPEC-262.2
8
+ // @implements A-SPEC-262.2, A-SPEC-497.4
9
9
  //
10
10
  // The RESIDENCE of the decision surface. S-262.1 made the surface's CONTENT (transcript-zero
11
11
  // references, context, one-key/batch); this is a thin polling loop over that content, so a request
@@ -16,6 +16,8 @@ exports.runWatch = runWatch;
16
16
  // existing runInteractive, and waits between polls when the queue is empty.
17
17
  const approval_queue_1 = require("../governance/approval-queue");
18
18
  const approve_1 = require("./approve");
19
+ const approve_context_1 = require("./approve-context");
20
+ const screen_safe_1 = require("./screen-safe");
19
21
  // @implements A-SPEC-497.2
20
22
  /**
21
23
  * ONE raw keypress decides an item — a/d/q/s; q collects one follow-up line (the question).
@@ -23,7 +25,7 @@ const approve_1 = require("./approve");
23
25
  * rejects with AbortError: leaving is not deciding. No deadline anywhere: the MAIN LANE's whole
24
26
  * point is that a human terminal can wait forever (H-SPEC-497).
25
27
  */
26
- function decideByKey(stream, _item) {
28
+ function decideByKey(stream, _item, onView) {
27
29
  return new Promise((resolve, reject) => {
28
30
  let questionMode = false;
29
31
  let line = '';
@@ -69,6 +71,11 @@ function decideByKey(stream, _item) {
69
71
  questionMode = true;
70
72
  continue;
71
73
  }
74
+ // @implements A-SPEC-497.4 — seeing is not deciding: the details are shown and the same item keeps waiting.
75
+ if (ch === 'v' && onView) {
76
+ onView();
77
+ continue;
78
+ }
72
79
  // any other key: not a decision — keep listening
73
80
  }
74
81
  };
@@ -85,8 +92,14 @@ function decideByKey(stream, _item) {
85
92
  async function presentByKey(root, io, actor, stream, state) {
86
93
  for (const p of state.pending) {
87
94
  io.print(`\n─ ${(0, approve_1.subjectCells)('─ ', p)}`);
88
- io.print('[a]approve [d]deny [q]question [s]skip > ');
89
- const d = await decideByKey(stream, p);
95
+ // @implements A-SPEC-497.4 — owner report 2026-10-05: the row ended in a notice that 258 characters were cut, and one key approved it. A
96
+ // clipped subject is a subject the operator did not see, so it is shown in full before any key is offered; `v`
97
+ // shows the details of any item. The renderer is the line-based screen's own `[v]` — nothing is rendered here.
98
+ const details = () => io.print((0, approve_context_1.renderDecisionContext)(root, p));
99
+ if ((0, screen_safe_1.isClipped)(p.target, (0, approve_1.subjectRoom)('─ ', p)))
100
+ details();
101
+ io.print('[a]approve [v]details [d]deny [q]question [s]skip > ');
102
+ const d = await decideByKey(stream, p, details);
90
103
  if (d === 'granted') {
91
104
  const r = (0, approve_1.grantRequest)(root, p.id, { actor });
92
105
  io.print(r.ok ? `✓ approved — ${(0, approve_1.subjectCells)('✓ approved — ', p)}` : `✗ ${r.reason}`);
@@ -21,9 +21,14 @@ import type { KnownDefect, MalformedMarker } from '../rtm/known-defects';
21
21
  *
22
22
  * Pure: no I/O, no clocks. The hooks supply loaded specs + evidence.
23
23
  */
24
+ /**
25
+ * @implements A-SPEC-247.1 — `findingId` rides on an ART-7 open-critical violation, so the Stop text can ask the
26
+ * approval queue about that finding without reading the detail text.
27
+ */
24
28
  export interface ConstitutionViolation {
25
29
  article: string;
26
30
  detail: string;
31
+ findingId?: string;
27
32
  }
28
33
  export interface ConstitutionContext {
29
34
  specs: Spec[];
@@ -180,7 +180,7 @@ function verifyConstitution(ctx) {
180
180
  // (the CLI catches and exits 0). The gate must never be crashable by its own evidence.
181
181
  const gist = typeof f.summary === 'string' && f.summary ? ` (${f.summary.slice(0, 80)})` : '';
182
182
  if (f.status === 'open' && f.severity === 'critical') {
183
- v.push({ article: 'ART-7', detail: `finding ${f.id}${gist}: 열린 치명 발견 — 결함을 고치고 재리뷰로 resolved 를 기록하기 전까지 이 작업은 완료될 수 없습니다` });
183
+ v.push({ article: 'ART-7', detail: `finding ${f.id}${gist}: 열린 치명 발견 — 결함을 고치고 재리뷰로 resolved 를 기록하기 전까지 이 작업은 완료될 수 없습니다`, ...(typeof f.id === 'string' ? { findingId: f.id } : {}) });
184
184
  continue;
185
185
  }
186
186
  // @implements A-SPEC-191 (§4c) — the judgement class ART-6 exists to reject ("sealed in an
@@ -36,6 +36,14 @@ export declare function collectCiVerdicts(root: string, now?: Date): CiVerdict[]
36
36
  * Pure and testable: evaluateStop takes the loaded spec set (+ optional evidence); the CLI does I/O.
37
37
  */
38
38
  export interface StopEvidence {
39
+ /**
40
+ * @implements A-SPEC-247.1
41
+ * The approval queue's pending requests, supplied by the hook. They decide only which HEADING a blocking line is
42
+ * printed under; absent means every line is printed as the session's. Never read for the verdict.
43
+ */
44
+ pendingRequests?: Pick<PendingRequest, 'id' | 'target'>[];
45
+ /** The launcher the block text prints before `holmes-kit approve` (default: this platform's npx). */
46
+ launcher?: string;
39
47
  /** A-SPEC id -> number of real test cases (`it(`/`test(`) found in test files anchored to it. */
40
48
  testCasesByAspec?: Record<string, number>;
41
49
  /**
@@ -260,12 +268,32 @@ export declare function evaluateStop(specs: Spec[], evidence?: StopEvidence): {
260
268
  violations?: {
261
269
  article: string;
262
270
  detail: string;
271
+ findingId?: string;
263
272
  }[];
264
273
  tracked?: {
265
274
  article: string;
266
275
  detail: string;
267
276
  }[];
268
277
  };
278
+ /**
279
+ * @implements A-SPEC-247.1
280
+ * The text of a Stop block: every violation under the heading that says who acts next.
281
+ *
282
+ * Measured 2026-10-04: the gate repeated the same three violations on more than eight stops while every exit needed
283
+ * the operator, and the text named neither the pending request nor who acts. A first design made those violations
284
+ * "waiting" so the stop would be acknowledged; a review found that an acknowledged stop clears debt, so a session
285
+ * could end its turn with one tool call. That design is withdrawn: this function decides TEXT and nothing else.
286
+ *
287
+ * A violation waits on the operator only when the approval queue holds a pending request for its own subject: the
288
+ * leading document id of an ART-4, the finding id FIELD of an ART-7 open critical. No id is read out of ART-7 prose,
289
+ * so the diverged-resolution and unreadable-ledger shapes are always the session's. The first line is unchanged, and
290
+ * no request id has to be copied into a command.
291
+ */
292
+ export declare function stopBlockText(violations: {
293
+ article: string;
294
+ detail: string;
295
+ findingId?: string;
296
+ }[], pending: Pick<PendingRequest, 'id' | 'target'>[], launcher: string): string;
269
297
  /**
270
298
  * @implements A-SPEC-134
271
299
  * Pure decision for the constitution-debt state at a turn boundary. Replaces the Stop gate's silent
@@ -50,6 +50,7 @@ exports.governanceLostPreflight = governanceLostPreflight;
50
50
  exports.outsideAnyProject = outsideAnyProject;
51
51
  exports.trackedLines = trackedLines;
52
52
  exports.evaluateStop = evaluateStop;
53
+ exports.stopBlockText = stopBlockText;
53
54
  exports.stopDebtAction = stopDebtAction;
54
55
  exports.acknowledgeStop = acknowledgeStop;
55
56
  exports.describeTokenHealth = describeTokenHealth;
@@ -812,7 +813,8 @@ function evaluateStop(specs, evidence) {
812
813
  const problems = violations.map((x) => `[${x.article}] ${x.detail}`);
813
814
  // @implements A-SPEC-247 — structured list so the caller can ask acknowledgeStop which of these
814
815
  // are waiting on an owner. Mirrors `problems` exactly, including the two synthesized below.
815
- const structured = violations.map((x) => ({ article: x.article, detail: x.detail }));
816
+ // @implements A-SPEC-247.1 — an ART-7 open critical keeps its finding id, which the block text asks the queue about.
817
+ const structured = violations.map((x) => ({ article: x.article, detail: x.detail, ...(x.findingId !== undefined ? { findingId: x.findingId } : {}) }));
816
818
  // Tampered audit trail blocks finishing — wires the provenance chain's verify into the live gate
817
819
  // (review finding: verify() previously had no product caller, so the chain's guarantee was inert).
818
820
  if (evidence?.provenance && !evidence.provenance.ok) {
@@ -852,8 +854,6 @@ function evaluateStop(specs, evidence) {
852
854
  }
853
855
  if (problems.length === 0)
854
856
  return { block: false, ...(tracked ? { tracked } : {}) };
855
- const shown = problems.slice(0, 20);
856
- const more = problems.length > shown.length ? `\n…and ${problems.length - shown.length} more` : '';
857
857
  // @implements A-SPEC-134 — the distinct articles feed the constitution-debt state on a cap-yield.
858
858
  const articles = [...new Set(violations.map((x) => x.article)
859
859
  .concat(evidence?.provenance && !evidence.provenance.ok ? ['ART-2'] : [])
@@ -866,10 +866,66 @@ function evaluateStop(specs, evidence) {
866
866
  articles,
867
867
  violations: structured,
868
868
  ...(tracked ? { tracked } : {}),
869
- reason: `[Holmes-Kit] constitution gate: ${problems.length} article violation(s) must be ` +
870
- `fixed before finishing:\n${shown.join('\n')}${more}`,
869
+ // @implements A-SPEC-247.1 — the same lines, each under the heading that says who acts next. Text only.
870
+ reason: stopBlockText(structured, evidence?.pendingRequests ?? [], evidence?.launcher ?? (0, npx_bin_1.npxBin)()),
871
871
  };
872
872
  }
873
+ /** The leading document id of an ART-4 detail (`T-SPEC-752.4: declared coverage …`). */
874
+ const LEADING_SPEC_ID_RE = /^([A-Z]-SPEC-\d+(?:\.\d+)?)\b/;
875
+ const REQUEST_ID_RE = /^req-[0-9a-f]+$/;
876
+ const STOP_BLOCK_LINES = 20;
877
+ /**
878
+ * @implements A-SPEC-247.1
879
+ * The text of a Stop block: every violation under the heading that says who acts next.
880
+ *
881
+ * Measured 2026-10-04: the gate repeated the same three violations on more than eight stops while every exit needed
882
+ * the operator, and the text named neither the pending request nor who acts. A first design made those violations
883
+ * "waiting" so the stop would be acknowledged; a review found that an acknowledged stop clears debt, so a session
884
+ * could end its turn with one tool call. That design is withdrawn: this function decides TEXT and nothing else.
885
+ *
886
+ * A violation waits on the operator only when the approval queue holds a pending request for its own subject: the
887
+ * leading document id of an ART-4, the finding id FIELD of an ART-7 open critical. No id is read out of ART-7 prose,
888
+ * so the diverged-resolution and unreadable-ledger shapes are always the session's. The first line is unchanged, and
889
+ * no request id has to be copied into a command.
890
+ */
891
+ function stopBlockText(violations, pending, launcher) {
892
+ const requestFor = new Map();
893
+ for (const p of Array.isArray(pending) ? pending : []) {
894
+ if (typeof p?.target !== 'string' || typeof p?.id !== 'string' || !REQUEST_ID_RE.test(p.id))
895
+ continue;
896
+ if (!requestFor.has(p.target))
897
+ requestFor.set(p.target, p.id);
898
+ }
899
+ const operator = [];
900
+ const session = [];
901
+ for (const v of Array.isArray(violations) ? violations : []) {
902
+ const line = `[${v.article}] ${v.detail}`;
903
+ const subject = v.article === 'ART-4' ? (LEADING_SPEC_ID_RE.exec(String(v.detail)) ?? [])[1]
904
+ : v.article === 'ART-7' ? v.findingId : undefined;
905
+ const request = subject === undefined ? undefined : requestFor.get(subject);
906
+ if (request !== undefined) {
907
+ operator.push(`${line} — request ${request} is pending: the operator decides it, in the session's approval dialog or with ${launcher} holmes-kit approve`);
908
+ }
909
+ else if (v.article === 'ART-4') {
910
+ session.push(`${line} — anchor real covering tests, or, when the design is withdrawn, retire the spec with spec_retire`);
911
+ }
912
+ else if (v.article === 'ART-7' && v.findingId !== undefined) {
913
+ session.push(`${line} — fix the defect, have it re-reviewed, then record resolved with review_record (that asks the operator for a grant)`);
914
+ }
915
+ else {
916
+ session.push(line);
917
+ }
918
+ }
919
+ const total = operator.length + session.length;
920
+ const shownOperator = operator.slice(0, STOP_BLOCK_LINES);
921
+ const shownSession = session.slice(0, STOP_BLOCK_LINES - shownOperator.length);
922
+ const lines = [`[Holmes-Kit] constitution gate: ${total} article violation(s) must be fixed before finishing:`];
923
+ if (shownOperator.length > 0)
924
+ lines.push('Waiting on the operator:', ...shownOperator);
925
+ if (shownSession.length > 0)
926
+ lines.push('The session acts:', ...shownSession);
927
+ return lines.join('\n') + (total > STOP_BLOCK_LINES ? `\n…and ${total - STOP_BLOCK_LINES} more` : '');
928
+ }
873
929
  /**
874
930
  * @implements A-SPEC-134
875
931
  * Pure decision for the constitution-debt state at a turn boundary. Replaces the Stop gate's silent
@@ -1569,7 +1625,14 @@ if (require.main === module) {
1569
1625
  catch { /* the notice is best-effort */ }
1570
1626
  for (const notice of exports.STOP_NOTICES)
1571
1627
  process.stderr.write(`[Holmes-Kit] ${notice}\n`);
1572
- let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}), ...(ci ? { ci } : {}), ...(dist ? { dist } : {}), ...(analysis ? { analysis } : {}), ...(semantic ? { semantic } : {}), ...(forbiddenEdges ? { forbiddenEdges } : {}), ...(cycles ? { cycles } : {}) });
1628
+ // @implements A-SPEC-247.1 — the queue decides which heading a blocking line is printed under, nothing else.
1629
+ // Unreadable: every line is printed as the session's, which is what the text said before this slice.
1630
+ let pendingRequests = [];
1631
+ try {
1632
+ pendingRequests = require('../governance/approval-queue').readQueue(stopProjectRoot()).pending;
1633
+ }
1634
+ catch { /* text only */ }
1635
+ let out = evaluateStop(specs, { pendingRequests, testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}), ...(ci ? { ci } : {}), ...(dist ? { dist } : {}), ...(analysis ? { analysis } : {}), ...(semantic ? { semantic } : {}), ...(forbiddenEdges ? { forbiddenEdges } : {}), ...(cycles ? { cycles } : {}) });
1573
1636
  // @implements A-SPEC-534.4 — track mode records ART-8 findings without blocking: surface them so
1574
1637
  // the operator observes RED-first gaps before an owner promotes the posture to strict.
1575
1638
  // @implements A-SPEC-559.2 — spec-evolution trigger (observe-first, NEVER blocks): a dirty
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "//": "@implements A-SPEC-209",
3
3
  "name": "@holmes-lab/holmes-kit",
4
- "version": "0.35.8",
4
+ "version": "0.35.10",
5
5
  "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
6
6
  "main": "dist/holmes/mcp/server.js",
7
7
  "types": "dist/holmes/mcp/server.d.ts",