bareloop 0.55.0 → 0.57.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.
Files changed (92) hide show
  1. package/CHANGELOG.md +82 -0
  2. package/README.md +3 -3
  3. package/bareloop.context.md +69 -209
  4. package/package.json +2 -2
  5. package/src/authorflow.js +164 -340
  6. package/src/authoring.js +7 -127
  7. package/src/authorjob.js +139 -472
  8. package/src/authorreadout.js +24 -368
  9. package/src/authorrun.js +21 -215
  10. package/src/behaviour.js +14 -0
  11. package/src/blockasks.js +43 -0
  12. package/src/bundlerun.js +4 -1
  13. package/src/checkblock.js +798 -0
  14. package/src/checklist.js +128 -0
  15. package/src/checkpick.js +39 -312
  16. package/src/checkwords.js +3 -1
  17. package/src/cli.js +3 -3
  18. package/src/declaredclose.js +38 -108
  19. package/src/destpoint.js +4 -2
  20. package/src/draftspend.js +46 -0
  21. package/src/facts.js +8 -1
  22. package/src/index.js +3 -43
  23. package/src/interviewrun.js +13 -8
  24. package/src/job.js +20 -1
  25. package/src/jobblock.js +11 -46
  26. package/src/judged.js +13 -1229
  27. package/src/kinds.js +5 -347
  28. package/src/noteask.js +124 -0
  29. package/src/pagedry.js +27 -5
  30. package/src/pagemap.js +15 -3
  31. package/src/pagerules.js +18 -3
  32. package/src/panel/authorroutes.js +24 -6
  33. package/src/panel/authorsession.js +222 -177
  34. package/src/panel/importrun.js +0 -1
  35. package/src/panel/index.html +198 -26
  36. package/src/panel/jobplan.js +87 -33
  37. package/src/panel/server.js +74 -68
  38. package/src/panel/status.js +3 -0
  39. package/src/pickrecord.js +34 -55
  40. package/src/placerule.js +355 -0
  41. package/src/planrun.js +2 -48
  42. package/src/promptregisters.js +13 -17
  43. package/src/providerrows.js +0 -36
  44. package/src/providers.js +4 -25
  45. package/src/questionbox.js +104 -0
  46. package/src/rowedit.js +115 -0
  47. package/src/rubricstep.js +234 -127
  48. package/src/run.js +11 -16
  49. package/src/userrun.js +60 -112
  50. package/types/authorflow.d.ts +41 -197
  51. package/types/authoring.d.ts +1 -14
  52. package/types/authorjob.d.ts +35 -59
  53. package/types/authorreadout.d.ts +10 -88
  54. package/types/behaviour.d.ts +12 -0
  55. package/types/blockasks.d.ts +36 -0
  56. package/types/checkblock.d.ts +376 -0
  57. package/types/checklist.d.ts +134 -0
  58. package/types/checkpick.d.ts +8 -140
  59. package/types/cli.d.ts +1 -3
  60. package/types/declaredclose.d.ts +7 -33
  61. package/types/destpoint.d.ts +2 -0
  62. package/types/draftspend.d.ts +21 -0
  63. package/types/index.d.ts +2 -4
  64. package/types/job.d.ts +8 -0
  65. package/types/jobblock.d.ts +8 -38
  66. package/types/judged.d.ts +7 -357
  67. package/types/kinds.d.ts +3 -104
  68. package/types/noteask.d.ts +76 -0
  69. package/types/pagedry.d.ts +13 -0
  70. package/types/pagemap.d.ts +4 -0
  71. package/types/pagerules.d.ts +7 -0
  72. package/types/panel/authorsession.d.ts +47 -5
  73. package/types/panel/jobgrid.d.ts +8 -8
  74. package/types/panel/jobplan.d.ts +48 -10
  75. package/types/panel/server.d.ts +27 -18
  76. package/types/panel/status.d.ts +5 -0
  77. package/types/pickrecord.d.ts +20 -13
  78. package/types/placerule.d.ts +194 -0
  79. package/types/planrun.d.ts +1 -22
  80. package/types/providerrows.d.ts +0 -31
  81. package/types/providers.d.ts +3 -19
  82. package/types/questionbox.d.ts +87 -0
  83. package/types/rowedit.d.ts +32 -0
  84. package/types/rubricstep.d.ts +100 -48
  85. package/types/run.d.ts +9 -19
  86. package/types/userrun.d.ts +0 -1
  87. package/src/calibrate.js +0 -702
  88. package/src/cardauthor.js +0 -502
  89. package/src/fitcheck.js +0 -166
  90. package/types/calibrate.d.ts +0 -201
  91. package/types/cardauthor.d.ts +0 -358
  92. package/types/fitcheck.d.ts +0 -113
package/src/pickrecord.js CHANGED
@@ -3,7 +3,7 @@
3
3
  // and to its guardrail's exact words, never to a line or rule number: both are recomputed on the new card. This file is the only writer of a record's entries
4
4
  // (`entriesFromAnswers`) and the only reader that decides keep-or-ask (`matchRecord`); the logic is the one F146 / F146b proved (poc/m10-am17/keep-picks-am18.mjs).
5
5
  // Throws away: line and rule numbers (recomputed), the model's words (it never sees a pick), a pick whose line or guardrail words no longer match.
6
- import { readFileSync } from 'node:fs';
6
+ import { readFileSync, writeFileSync } from 'node:fs';
7
7
  import path from 'node:path';
8
8
 
9
9
  /** the record's file, inside a drafting session folder only (never a run folder) */
@@ -11,7 +11,7 @@ export const RECORD_FILE = 'picks-record.json';
11
11
  /** the exact words a kept pick is marked with in the draft log, the Audit and the plan card (M10 am17 (6)) */
12
12
  export const KEPT_WORDS = 'kept from last draft';
13
13
 
14
- /** @typedef {{lineWords: string, occurrence: number, ruleText: string, added: string|null, check: Record<string, any>|null, own: boolean, left: boolean}} Entry */
14
+ /** @typedef {{lineWords: string, occurrence: number, ruleText: string, added?: string|null, check: Record<string, any>|null, own: boolean, left: boolean}} Entry */
15
15
  /** @typedef {{line: number, rule: number, text: string}} Rule */
16
16
 
17
17
  const norm = (/** @type {unknown} */ t) => String(t).toLowerCase().replace(/\s+/g, ' ').trim();
@@ -35,9 +35,9 @@ export function lineKeys(lines) {
35
35
  }
36
36
 
37
37
  /**
38
- * The entries for answers just given, numbered on THIS card (the answer redraft's card: its line and rule numbers are the ones the asks carried).
38
+ * The entries for answers just given, numbered on THIS card (the answer redraft's card: its line and rule numbers are the ones the asks carried; the rule's text is the FINAL rule's words).
39
39
  * @param {{n: number, text: string}[]} lines @param {Rule[]} rules
40
- * @param {{line: number, rule: number, check?: Record<string, any>|null, added?: string|null, own?: boolean}[]} picks @param {{line: number, rule: number}[]} left
40
+ * @param {{line: number, rule: number, check?: Record<string, any>|null, own?: boolean}[]} picks @param {{line: number, rule: number}[]} left
41
41
  * @returns {Entry[]}
42
42
  */
43
43
  export function entriesFromAnswers(lines, rules, picks, left) {
@@ -52,82 +52,43 @@ export function entriesFromAnswers(lines, rules, picks, left) {
52
52
  const out = [];
53
53
  for (const p of picks) {
54
54
  const b = base(p.line, p.rule);
55
- if (b) out.push({ ...b, added: typeof p.added === 'string' ? p.added : null, check: p.check ?? null, own: p.own === true, left: false });
55
+ if (b) out.push({ ...b, check: p.check ?? null, own: p.own === true, left: false });
56
56
  }
57
57
  for (const l of left) {
58
58
  const b = base(l.line, l.rule);
59
- if (b) out.push({ ...b, added: null, check: null, own: false, left: true });
59
+ if (b) out.push({ ...b, check: null, own: false, left: true });
60
60
  }
61
61
  return out;
62
62
  }
63
63
 
64
64
  /**
65
65
  * Decide, for the card in hand, which stored picks are kept and which guardrails must be asked.
66
- * A pick is KEPT when the job line with its words (same order among equal lines) still has its source guardrail with the exact words and, if the pick wrote a `~` line,
67
- * that line with its exact words too. Otherwise the pick is dropped (never partly kept) and its guardrails are asked: a pair broken on one side is ONE ask, so the
68
- * partner left on the card is folded (neither asked nor given the old check) - except an EDITED added line (M10 am21): that one is asked (`pairRule` = its source's number) and the source is folded. Pure.
66
+ * A pick is KEPT when the job line with its words (same order among equal lines) still has a guardrail with the pick's exact words. One rule in, one rule out (hamr 2026-11-14): an answer REPLACED the
67
+ * rule it was asked about, so the stored words are the final rule's words and there is no second line to pair; a rule whose words changed is simply new and asked. Pure.
69
68
  * @param {Entry[]} entries @param {{n: number, text: string}[]} lines @param {Rule[]} rules every guardrail the call settles
70
- * @returns {{picks: {line: number, rule: number, check: Record<string, any>|null, added?: string, own?: boolean}[], left: {line: number, rule: number}[],
71
- * kept: {line: number, rule: number, entry: Entry}[], askRules: (Rule & {pairRule?: number})[]}}
69
+ * @returns {{picks: {line: number, rule: number, check: Record<string, any>|null, own?: boolean}[], left: {line: number, rule: number}[],
70
+ * kept: {line: number, rule: number, entry: Entry}[], askRules: Rule[]}}
72
71
  */
73
72
  export function matchRecord(entries, lines, rules) {
74
73
  const byKey = new Map([...lineKeys(lines)].map(([n, k]) => [`${k.lineWords}#${k.occurrence}`, n]));
75
74
  /** @type {Set<string>} */
76
75
  const claimed = new Set();
77
- /** @type {Set<string>} */
78
- const folded = new Set();
79
- /** @type {Map<string, number>} an edited added line (by id) -> the rule number of the source it was paired with (M10 am21) */
80
- const edited = new Map();
81
- const free = (/** @type {number} */ n, /** @type {string} */ text) => rules.find((r) => r.line === n && !claimed.has(id(r)) && !folded.has(id(r)) && norm(r.text) === norm(text));
82
76
  const kept = [];
83
- /** @type {{e: Entry, n: number|undefined}[]} */
84
- const broken = [];
85
77
  for (const e of Array.isArray(entries) ? entries : []) {
86
78
  const n = byKey.get(`${e.lineWords}#${e.occurrence}`);
87
- const src = n === undefined ? undefined : free(n, e.ruleText);
88
- if (src) claimed.add(id(src)); // held while the partner is looked for, so a pair never takes one rule twice
89
- const add = n === undefined || !src || e.added === null ? undefined : free(n, e.added);
90
- if (n !== undefined && src && (e.added === null || add)) {
91
- if (add) claimed.add(id(add));
92
- kept.push({ line: n, rule: src.rule, entry: e });
93
- } else {
94
- if (src) claimed.delete(id(src));
95
- broken.push({ e, n });
96
- }
97
- }
98
- // a pair broken on one side is ONE pick, so ONE ask: the partner that is left folds into it (it keeps no old check and is not asked on its own)
99
- for (const { e, n } of broken) {
100
- if (e.added === null) continue;
101
- if (n === undefined) {
102
- // the line's own words changed: it is a new line, all its guardrails are asked; its old `~` line with its source still there rides the source's ask
103
- for (const l of lines) {
104
- const s = free(l.n, e.ruleText);
105
- const a = s ? rules.find((r) => r.line === l.n && r !== s && !claimed.has(id(r)) && !folded.has(id(r)) && norm(r.text) === norm(e.added ?? '')) : undefined;
106
- if (a) { folded.add(id(a)); break; }
107
- }
108
- continue;
109
- }
110
- const src = free(n, e.ruleText);
111
- const add = free(n, e.added);
112
- if (src && !add) {
113
- // the added line was edited (or deleted): the unclaimed rule right after the source on that line is it. M10 am21: the ONE ask is about THAT line's words
114
- // (it carries the source's number as `pairRule`, the rule its pick is kept under); the source rides it and is not asked on its own
115
- const p = rules.find((r) => r.line === n && r.rule > src.rule && !claimed.has(id(r)) && !folded.has(id(r)));
116
- if (p) { folded.add(id(src)); edited.set(id(p), src.rule); }
117
- } else if (add && !src) {
118
- // the source was edited: the unclaimed rule right before the added line is it; the old added line rides that ask
119
- const p = [...rules].reverse().find((r) => r.line === n && r.rule < add.rule && !claimed.has(id(r)) && !folded.has(id(r)));
120
- if (p) folded.add(id(add));
121
- }
79
+ const src = n === undefined ? undefined : rules.find((r) => r.line === n && !claimed.has(id(r)) && norm(r.text) === norm(e.ruleText));
80
+ if (!src) continue;
81
+ claimed.add(id(src));
82
+ kept.push({ line: /** @type {number} */ (n), rule: src.rule, entry: e });
122
83
  }
123
84
  const picks = [];
124
85
  const left = [];
125
86
  for (const k of kept) {
126
87
  const e = k.entry;
127
88
  if (e.left) left.push({ line: k.line, rule: k.rule });
128
- else picks.push({ line: k.line, rule: k.rule, check: e.check, ...(e.added === null ? {} : { added: e.added }), ...(e.own ? { own: true } : {}) });
89
+ else picks.push({ line: k.line, rule: k.rule, check: e.check, ...(e.own ? { own: true } : {}) });
129
90
  }
130
- return { picks, left, kept, askRules: rules.filter((r) => !claimed.has(id(r)) && !folded.has(id(r))).map((r) => (edited.has(id(r)) ? { ...r, pairRule: edited.get(id(r)) } : r)) };
91
+ return { picks, left, kept, askRules: rules.filter((r) => !claimed.has(id(r))) };
131
92
  }
132
93
 
133
94
  /**
@@ -143,3 +104,21 @@ export function readRecordFile(file) {
143
104
 
144
105
  /** where a drafting session folder keeps its record @param {string} planDir */
145
106
  export const recordPath = (planDir) => path.join(planDir, RECORD_FILE);
107
+
108
+ /**
109
+ * The Drop/Add choices a draft's person made on the confirm card (hamr 2026-11-13, N-2), carried the same way as the picks: tied to the line's words and the row's own name, never to a number.
110
+ * @param {string} file @returns {{lineWords: string, occurrence: number, tail: string, choice: string}[]|null}
111
+ */
112
+ export function readRowChoices(file) {
113
+ try {
114
+ const j = JSON.parse(readFileSync(file, 'utf8'));
115
+ return Array.isArray(j?.rowChoices) ? j.rowChoices.filter((/** @type {any} */ e) => e && typeof e.lineWords === 'string' && Number.isInteger(e.occurrence) && typeof e.tail === 'string' && (e.choice === 'drop' || e.choice === 'add')) : null;
116
+ } catch { return null; }
117
+ }
118
+
119
+ /** write a part of the record without losing the other: `patch` is `{picks}` or `{rowChoices}` @param {string} file @param {Record<string, any>} patch */
120
+ export function writeRecordPart(file, patch) {
121
+ let cur = {};
122
+ try { const j = JSON.parse(readFileSync(file, 'utf8')); if (j && typeof j === 'object' && !Array.isArray(j)) cur = j; } catch { /* no record yet */ }
123
+ writeFileSync(file, `${JSON.stringify({ ...cur, ...patch })}\n`, { mode: 0o600 });
124
+ }
@@ -0,0 +1,355 @@
1
+ // PLACE RULES (docs/product/ITEM33-BUILD.md, "Place rules build spec (hamr go 2026-11-11)").
2
+ //
3
+ // A check whose words hold a version or a date ("the newest release is 0.55.0") is true only while the input stays as it is, so code refuses
4
+ // it as week-only. A PLACE RULE keeps it: it names WHERE the value sits (the first heading at one level of a changelog) instead of WHAT the
5
+ // value is. The signed fact carries the rule; at run start, before any provider call, CODE reads the run's own copy of the input with the rule
6
+ // and the value it finds is bound, in memory only, as that fact's phrase for the planner and the close. No model chooses or reads anything here.
7
+ //
8
+ // This module is the graduation (a REWRITE, never a copy) of the round-3 POC (F321). Pure except `lastPlaceRead`, which reads earlier runs' spines.
9
+
10
+ import { existsSync, readFileSync } from 'node:fs';
11
+
12
+ /** the two rule kinds on the menu: the version in a heading, and the date on the same heading line */
13
+ export const PLACE_KINDS = Object.freeze(['headingBetween', 'headingDateAfter']);
14
+ /** the end-of-line end mark */
15
+ export const EOL = '$EOL';
16
+ /** the field a place rule may carry */
17
+ export const PLACE_FIELDS = Object.freeze(['kind', 'prefix', 'end', 'shape', 'skip']);
18
+ /** the closed list of reasons a read can end not found */
19
+ export const PLACE_REASONS = Object.freeze(['mixed-levels', 'no-heading-line', 'first-heading-mismatch', 'end-mark-missing', 'capture-not-shape', 'only-skipped-headings', 'no-date-on-line', 'no-file', 'empty-text']);
20
+ /** plain words for each reason, from code (the person never reads a raw code) */
21
+ export const PLAIN_REASONS = Object.freeze({
22
+ 'mixed-levels': 'the file writes its version headings at more than one level',
23
+ 'no-heading-line': 'the file has no heading at the level the rule reads',
24
+ 'first-heading-mismatch': 'the newest heading does not start the way the rule says',
25
+ 'end-mark-missing': 'the newest heading does not have the mark the rule reads up to',
26
+ 'capture-not-shape': 'the newest heading does not carry a version number',
27
+ 'only-skipped-headings': 'the file has only an Unreleased heading and no release after it',
28
+ 'no-date-on-line': 'the newest heading line carries no date',
29
+ 'no-file': 'the input could not be read',
30
+ 'empty-text': 'the input is empty',
31
+ });
32
+
33
+ const SHAPES = /** @type {Record<string, RegExp>} */ ({ semver: /^\d+\.\d+\.\d+$/, 'iso-date': /^\d{4}-\d{2}-\d{2}$/ });
34
+ const DATE_FIND = /\d{4}-\d{2}-\d{2}/;
35
+ const FENCE = /^\s{0,3}(```|~~~)/;
36
+ /** a heading carries a semver iff its text starts with an optional "[", an optional "v", then X.Y.Z (token-bounded) */
37
+ const SEMVER_HEADING = /^(#{1,6}) \[?v?(\d+\.\d+\.\d+)(?!\d|\.\d)/;
38
+
39
+ /**
40
+ * @typedef {{kind: 'headingBetween'|'headingDateAfter', prefix: string, end: string, shape: string, skip: string[]}} PlaceRule
41
+ * @typedef {{found: true, value: string, lineIndex: number}|{found: false, reason: string}} PlaceRead
42
+ */
43
+
44
+ /**
45
+ * Why a rule is not a legal place rule, or null when it is. Pure.
46
+ * @param {unknown} rule @returns {string|null}
47
+ */
48
+ export function placeRuleProblem(rule) {
49
+ if (rule === null || typeof rule !== 'object' || Array.isArray(rule)) return 'a place rule is {kind, prefix, end, shape, skip}';
50
+ const r = /** @type {Record<string, any>} */ (rule);
51
+ for (const k of Object.keys(r)) if (!PLACE_FIELDS.includes(k)) return `"${k}" is not a field of a place rule (fields: ${PLACE_FIELDS.join(', ')})`;
52
+ if (!PLACE_KINDS.includes(r.kind)) return `kind is one of ${PLACE_KINDS.join(' | ')}`;
53
+ if (typeof r.prefix !== 'string' || !/^#+ /.test(r.prefix)) return 'prefix starts with # marks and a space';
54
+ if (typeof r.end !== 'string' || r.end === '') return 'end is the mark the value is read up to (or $EOL)';
55
+ if (typeof r.shape !== 'string' || !Object.hasOwn(SHAPES, r.shape)) return `shape is one of ${Object.keys(SHAPES).join(' | ')}`;
56
+ if (!Array.isArray(r.skip) || r.skip.some((/** @type {unknown} */ s) => typeof s !== 'string')) return 'skip is a list of words';
57
+ return null;
58
+ }
59
+
60
+ /**
61
+ * Heading lines at the rule's level: lines outside ``` / ~~~ fences that start with the level mark (for example "## "). Pure.
62
+ * @param {string} text @param {string} prefix @returns {{i: number, line: string}[]}
63
+ */
64
+ export function levelLines(text, prefix) {
65
+ const mark = `${/^#+/.exec(prefix)?.[0] ?? '#'} `;
66
+ let fenced = false;
67
+ /** @type {{i: number, line: string}[]} */
68
+ const out = [];
69
+ text.split(/\r?\n/).forEach((line, i) => {
70
+ if (FENCE.test(line)) { fenced = !fenced; return; }
71
+ if (!fenced && line.startsWith(mark)) out.push({ i, line });
72
+ });
73
+ return out;
74
+ }
75
+
76
+ /**
77
+ * The mixed-level guard: every non-fenced heading line is scanned; semver-carrying headings at MORE THAN ONE level mean mixed. A heading with no
78
+ * semver (a "# Changelog" title, "### Fixed") is ignored. It only ever turns a read into not found, never into a value.
79
+ * @param {string} text @returns {boolean}
80
+ */
81
+ export function mixedLevels(text) {
82
+ let fenced = false;
83
+ /** @type {Set<number>} */
84
+ const levels = new Set();
85
+ for (const line of text.split(/\r?\n/)) {
86
+ if (FENCE.test(line)) { fenced = !fenced; continue; }
87
+ if (fenced) continue;
88
+ const m = SEMVER_HEADING.exec(line);
89
+ if (m) levels.add(m[1].length);
90
+ }
91
+ return levels.size > 1;
92
+ }
93
+
94
+ /** @param {string} reason @returns {{found: false, reason: string}} */
95
+ const nf = (reason) => ({ found: false, reason });
96
+
97
+ /**
98
+ * The STRICT first-heading read. It reads only the first heading line at the rule's level; it must match prefix + end + shape, else not found, and
99
+ * it never looks further down. One exception: a capture that is exactly a skip word ("Unreleased") moves to the NEXT heading at that level,
100
+ * ONCE (a second skip word is not found). Pure.
101
+ * @param {PlaceRule} rule @param {string} text
102
+ * @returns {{found: true, cap: string, after: string, lineIndex: number}|{found: false, reason: string}}
103
+ */
104
+ function selectFirst(rule, text) {
105
+ if (!text || !text.trim()) return nf('empty-text');
106
+ if (mixedLevels(text)) return nf('mixed-levels');
107
+ const hs = levelLines(text, rule.prefix);
108
+ if (!hs.length) return nf('no-heading-line');
109
+ let k = 0;
110
+ let skipped = false;
111
+ for (;;) {
112
+ const { i, line } = hs[k];
113
+ if (!line.startsWith(rule.prefix)) return nf('first-heading-mismatch');
114
+ const rest = line.slice(rule.prefix.length);
115
+ const e = rule.end === EOL ? rest.length : rest.indexOf(rule.end);
116
+ if (e < 0) return nf('end-mark-missing');
117
+ const cap = rest.slice(0, e).trim();
118
+ if (rule.skip.some((s) => s.toLowerCase() === cap.toLowerCase())) {
119
+ if (skipped) return nf('only-skipped-headings');
120
+ skipped = true;
121
+ k += 1;
122
+ if (k >= hs.length) return nf('only-skipped-headings');
123
+ continue;
124
+ }
125
+ if (!SHAPES[rule.shape].test(cap)) return nf('capture-not-shape');
126
+ return { found: true, cap, after: rule.end === EOL ? '' : rest.slice(e + rule.end.length), lineIndex: i };
127
+ }
128
+ }
129
+
130
+ /**
131
+ * Read one rule against one input text: the run-start function, code only. A rule that is not legal throws (the signed spec was validated, so a bad one
132
+ * is a defect, never a read).
133
+ * @param {PlaceRule} rule @param {string} text @returns {PlaceRead}
134
+ */
135
+ export function readPlace(rule, text) {
136
+ const bad = placeRuleProblem(rule);
137
+ if (bad !== null) throw new Error(`place rule: ${bad}`);
138
+ const sel = selectFirst(rule, text);
139
+ if (!sel.found) return sel;
140
+ if (rule.kind === 'headingBetween') return { found: true, value: sel.cap, lineIndex: sel.lineIndex };
141
+ const m = DATE_FIND.exec(sel.after);
142
+ if (!m || !SHAPES['iso-date'].test(m[0])) return nf('no-date-on-line');
143
+ return { found: true, value: m[0], lineIndex: sel.lineIndex };
144
+ }
145
+
146
+ // ---- drafting: fit a rule ---------------------------------------------------------------------------------------------------------------
147
+
148
+ const CANDIDATE_PREFIXES = ['## [', '## v', '## ', '# [', '# v', '# ', '### [', '### v', '### '];
149
+ const CANDIDATE_ENDS = [']', ' ', EOL];
150
+ /** the frozen candidate list: 9 prefixes crossed with 3 ends, prefix-major (27) */
151
+ export const PLACE_CANDIDATES = Object.freeze(CANDIDATE_PREFIXES.flatMap((prefix) => CANDIDATE_ENDS.map((end) => Object.freeze({ prefix, end }))));
152
+ /** the one skip word of a fitted rule: an "Unreleased" heading above the newest release */
153
+ const FIT_SKIP = Object.freeze(['Unreleased']);
154
+
155
+ /**
156
+ * Fit a place rule to a fact's own words, by CODE, at drafting. The words must be exactly one version (X.Y.Z) or exactly one ISO date; the frozen
157
+ * candidates are walked in order, and the first whose strict first-heading read on the input's own text returns exactly those words wins. Null =
158
+ * no fit (a version and a date together, any other words, another date form, a mixed-level file, no text, or no candidate reading them): the caller
159
+ * refuses the words as week-only exactly as before. Only the two kinds are handled. Pure.
160
+ * @param {string} words @param {string|null|undefined} text
161
+ * @returns {PlaceRule|null}
162
+ */
163
+ export function fitPlaceRule(words, text) {
164
+ if (typeof text !== 'string' || text.trim() === '') return null;
165
+ const w = String(words ?? '').trim();
166
+ const kind = SHAPES.semver.test(w) ? 'headingBetween' : (SHAPES['iso-date'].test(w) ? 'headingDateAfter' : null);
167
+ if (kind === null) return null;
168
+ for (const c of PLACE_CANDIDATES) {
169
+ /** @type {PlaceRule} */
170
+ const rule = { kind, prefix: c.prefix, end: c.end, shape: 'semver', skip: [...FIT_SKIP] };
171
+ const r = readPlace(rule, text);
172
+ if (r.found && r.value === w) return rule;
173
+ }
174
+ return null;
175
+ }
176
+
177
+ /** the only marks a heading piece may carry around its value: heading hashes, brackets, a dash, parentheses and spaces */
178
+ const HEADING_FURNITURE = /^[\s#[\]()\-\u2013\u2014]*$/;
179
+
180
+ /**
181
+ * STRIP (P1b, hamr 2026-11-11): the words of a phrase fact that are a piece of the newest release heading ("## [0.54.1]", "[0.54.1] -", "0.54.1",
182
+ * "2026-11-04", "## [0.54.1] - 2026-11-04") are stripped by code to their value(s). The words hold exactly one version (X.Y.Z, an optional leading v) and/or
183
+ * exactly one ISO date and nothing else but heading marks; each value is fitted with {@link fitPlaceRule} on the input's own text, and when both are
184
+ * present both must sit on the SAME first release heading line. Returns the values (version first) each with its rule, or null: two versions, two dates,
185
+ * any other word, another date form, a value that is not at the first release heading, no text. Pure.
186
+ * @param {string} words @param {string|null|undefined} text
187
+ * @returns {{kind: 'version'|'date', value: string, rule: PlaceRule}[]|null}
188
+ */
189
+ export function fitPlacePhrase(words, text) {
190
+ if (typeof text !== 'string' || text.trim() === '') return null;
191
+ const w = String(words ?? '');
192
+ const dates = w.match(/(?<![\w.])\d{4}-\d{2}-\d{2}(?!\d)/g) ?? [];
193
+ const noDates = w.replace(/(?<![\w.])\d{4}-\d{2}-\d{2}(?!\d)/g, ' ');
194
+ const versions = [...noDates.matchAll(/(?<![\w.])v?(\d+\.\d+\.\d+)(?!\d|\.\d)/g)].map((m) => m[1]);
195
+ if (dates.length > 1 || versions.length > 1 || dates.length + versions.length === 0) return null;
196
+ if (!HEADING_FURNITURE.test(noDates.replace(/(?<![\w.])v?\d+\.\d+\.\d+(?!\d|\.\d)/g, ' '))) return null;
197
+ /** @type {{kind: 'version'|'date', value: string, rule: PlaceRule}[]} */
198
+ const out = [];
199
+ for (const [kind, value] of /** @type {['version'|'date', string][]} */ ([...versions.map((v) => ['version', v]), ...dates.map((d) => ['date', d])])) {
200
+ const rule = fitPlaceRule(value, text);
201
+ if (rule === null) return null;
202
+ out.push({ kind, value, rule });
203
+ }
204
+ if (out.length === 2) {
205
+ const [a, b] = out.map((x) => readPlace(x.rule, text));
206
+ if (!a.found || !b.found || a.lineIndex !== b.lineIndex) return null;
207
+ }
208
+ return out;
209
+ }
210
+
211
+ // ---- the facts a spec carries -----------------------------------------------------------------------------------------------------------
212
+
213
+ /** @param {unknown} v @returns {v is Record<string, any>} */
214
+ const isRec = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
215
+
216
+ /**
217
+ * @typedef {{key: string, name: string, source: string, stage: number, part: number, fact: number, place: PlaceRule, phrase: string}} PlaceFact
218
+ */
219
+
220
+ /**
221
+ * Every place-rule fact of a spec, in stage / part / fact order. The key is the stage's name and the fact's name (both stable across the runs of one
222
+ * workflow), so an earlier run's record finds the same fact. Pure.
223
+ * @param {any} spec @returns {PlaceFact[]}
224
+ */
225
+ export function placeFactsOf(spec) {
226
+ /** @type {PlaceFact[]} */
227
+ const out = [];
228
+ const stages = Array.isArray(spec?.closeDecl?.stages) ? spec.closeDecl.stages : [];
229
+ stages.forEach((/** @type {any} */ st, /** @type {number} */ si) => {
230
+ if (!isRec(st) || st.kind !== 'rubric-step' || !isRec(st.params) || !Array.isArray(st.params.parts)) return;
231
+ st.params.parts.forEach((/** @type {any} */ p, /** @type {number} */ pi) => {
232
+ if (!isRec(p) || p.class !== 'fact' || !Array.isArray(p.facts)) return;
233
+ p.facts.forEach((/** @type {any} */ f, /** @type {number} */ fi) => {
234
+ if (!isRec(f) || f.shape !== 'phrase' || !isRec(f.place)) return;
235
+ out.push({ key: `${String(st.name)}/${String(f.name)}`, name: String(f.name), source: String(p.source), stage: si, part: pi, fact: fi, place: /** @type {PlaceRule} */ (f.place), phrase: String(f.phrase) });
236
+ });
237
+ });
238
+ });
239
+ return out;
240
+ }
241
+
242
+ /**
243
+ * A copy of the spec with each place fact's phrase replaced by the value the run read. The input spec is never touched (the signed spec and its hash
244
+ * stay as signed); the copy is for this run's planner and close only. A key with no value is left as the signed drafting words.
245
+ * @param {any} spec @param {Record<string, string>} values place-fact key to the value read @returns {any}
246
+ */
247
+ export function bindPlaceValues(spec, values) {
248
+ const bound = structuredClone(spec);
249
+ for (const f of placeFactsOf(bound)) {
250
+ if (Object.hasOwn(values, f.key)) bound.closeDecl.stages[f.stage].params.parts[f.part].facts[f.fact].phrase = values[f.key];
251
+ }
252
+ return bound;
253
+ }
254
+
255
+ /**
256
+ * The value the drafting words themselves hold for this rule: the first version for headingBetween, the first ISO date for headingDateAfter. Null when
257
+ * the words hold none. Used as "last read" when no earlier run has one.
258
+ * @param {PlaceRule} rule @param {string} words @returns {string|null}
259
+ */
260
+ export function valueInWords(rule, words) {
261
+ const m = rule.kind === 'headingBetween' ? /(?<![\d.])\d+\.\d+\.\d+(?!\d|\.\d)/.exec(words) : /(?<!\d)\d{4}-\d{2}-\d{2}(?!\d)/.exec(words);
262
+ return m === null ? null : m[0];
263
+ }
264
+
265
+ /**
266
+ * Re-read EVERY place fact against the run's own input text, one by one, before any spend. A row is same / new / notfound. Any notfound stops the run;
267
+ * otherwise the run proceeds with the new words.
268
+ * @param {{fact: PlaceFact, text: string|null, was: string|null}[]} items `text` null = the input could not be read
269
+ * @returns {{proceed: boolean, rows: {key: string, name: string, kind: string, found: boolean, value: string|null, was: string|null, reason: string|null}[], values: Record<string, string>}}
270
+ */
271
+ export function readPlaceRules(items) {
272
+ const rows = items.map(({ fact, text, was }) => {
273
+ const r = text === null ? /** @type {PlaceRead} */ ({ found: false, reason: 'no-file' }) : readPlace(fact.place, text);
274
+ return r.found
275
+ ? { key: fact.key, name: fact.name, kind: fact.place.kind, found: true, value: r.value, was, reason: null }
276
+ : { key: fact.key, name: fact.name, kind: fact.place.kind, found: false, value: null, was, reason: r.reason };
277
+ });
278
+ /** @type {Record<string, string>} */
279
+ const values = {};
280
+ for (const r of rows) if (r.found && r.value !== null) values[r.key] = r.value;
281
+ return { proceed: rows.every((r) => r.found), rows, values };
282
+ }
283
+
284
+ /** the end of the stop words: what the person can do, and that nothing ran or was spent */
285
+ export const STOP_TAIL = 'Reuse workflow and adjust the rules, or check the input. The run did not start. Nothing spent.';
286
+
287
+ /**
288
+ * The words of the $0 stop, plain words from code. Every rule is listed, found or not: "<name>: found <value>" (with "(was <last>)" when the value is
289
+ * new) or "<name>: not found (<plain reason>)", then the closing line. The reasons come only from the closed list.
290
+ * @param {{name: string, found: boolean, value: string|null, was: string|null, reason: string|null}[]} rows @returns {string}
291
+ */
292
+ export function stopWords(rows) {
293
+ const lines = rows.map((r) => {
294
+ if (!r.found) return `${r.name}: not found (${PLAIN_REASONS[/** @type {keyof typeof PLAIN_REASONS} */ (r.reason ?? 'no-file')] ?? 'the input could not be read'})`;
295
+ return `${r.name}: found ${r.value}${r.was !== null && r.was !== r.value ? ` (was ${r.was})` : ''}`;
296
+ });
297
+ return `${lines.join('\n')}\n${STOP_TAIL}`;
298
+ }
299
+
300
+ // ---- the record of a run: what was read, and what the last run read ---------------------------------------------------------------------
301
+
302
+ /** the plain words of the door's refusal when a place-rule run has no record of the values it read */
303
+ export const NO_PLACE_RECORD_WORDS = 'This run has no record of the values it read, so it cannot be checked again. Use Reuse workflow.';
304
+
305
+ /** the spine event a run writes, once, after job-start */
306
+ export const PLACE_EVENT = 'place-rules';
307
+
308
+ /**
309
+ * The values of the LAST `place-rules` record in a run's own events (key to value): what a RESUME of that run rebinds, since a resume does not re-read. Null when
310
+ * there is no record, or any of its rows was not found.
311
+ * @param {any[]} events @returns {Record<string, string>|null}
312
+ */
313
+ export function placeValuesOfEvents(events) {
314
+ const rec = Array.isArray(events) ? events.findLast((e) => isRec(e) && e.type === PLACE_EVENT && Array.isArray(e.rows)) : undefined;
315
+ if (rec === undefined || rec.rows.length === 0 || rec.rows.some((/** @type {any} */ r) => !isRec(r) || r.found !== true || typeof r.value !== 'string')) return null;
316
+ return Object.fromEntries(rec.rows.map((/** @type {any} */ r) => [String(r.key), r.value]));
317
+ }
318
+
319
+ /**
320
+ * What the newest EARLIER run of the same workflow read, per fact key: "last read". `rows` are the run list's rows (file order, oldest first). Candidates are
321
+ * the rows of the same job, newest first, at most {@link LAST_READ_LOOK} of them; the first whose spine holds a `place-rules` record of the same workflow key
322
+ * answers. An unreadable spine is skipped. Empty when there is none (the caller falls back to the drafting words).
323
+ * @param {{rows: {runid: string, job: string, spine: string}[], job: string, workflowKey: string, runid: string}} o @returns {Record<string, string>}
324
+ */
325
+ export function lastPlaceRead({ rows, job, workflowKey, runid }) {
326
+ let looked = 0;
327
+ for (const row of [...rows].reverse()) {
328
+ if (row.runid === runid || row.job !== job || typeof row.spine !== 'string' || !existsSync(row.spine)) continue;
329
+ if (looked >= LAST_READ_LOOK) break;
330
+ looked += 1;
331
+ /** @type {any[]} */
332
+ let events = [];
333
+ try { events = readFileSync(row.spine, 'utf8').split('\n').filter((l) => l.includes(`"${PLACE_EVENT}"`)).map((l) => JSON.parse(l)); } catch { continue; }
334
+ const rec = events.findLast((e) => isRec(e) && e.type === PLACE_EVENT && e.workflowKey === workflowKey && Array.isArray(e.rows));
335
+ if (rec !== undefined) return Object.fromEntries(rec.rows.filter((/** @type {any} */ r) => isRec(r) && r.found === true && typeof r.value === 'string').map((/** @type {any} */ r) => [String(r.key), r.value]));
336
+ }
337
+ return {};
338
+ }
339
+ /** how many earlier runs of the job are looked at for "last read" */
340
+ export const LAST_READ_LOOK = 25;
341
+
342
+ /**
343
+ * The Audit lines of a run's `place-rules` record, in plain words from code: "<name>: <value>" (with "(was <last>)" when the value is new) or
344
+ * "<name>: not found (<reason>)". Null when the run has no record.
345
+ * @param {any[]} events @returns {string[]|null}
346
+ */
347
+ export function placeRuleLines(events) {
348
+ const rec = Array.isArray(events) ? events.findLast((e) => isRec(e) && e.type === PLACE_EVENT && Array.isArray(e.rows)) : undefined;
349
+ if (rec === undefined) return null;
350
+ return rec.rows.filter(isRec).map((/** @type {any} */ r) => {
351
+ const name = String(r.key).split('/').pop();
352
+ if (r.found !== true) return `${name}: not found (${PLAIN_REASONS[/** @type {keyof typeof PLAIN_REASONS} */ (r.reason)] ?? 'the input could not be read'})`;
353
+ return `${name}: ${r.value}${typeof r.was === 'string' && r.was !== r.value ? ` (was ${r.was})` : ''}`;
354
+ });
355
+ }
package/src/planrun.js CHANGED
@@ -45,7 +45,6 @@ import { globToPrefix, redactSecrets, SECRET_PATTERNS } from './validate.js';
45
45
  import { startAttemptDiff } from './attemptdiff.js';
46
46
  import { validateBridge, loadGate, newestEligibleVersion, reuseEligibility, quarantinesCredit, QUARANTINED_CODE } from './bridges.js';
47
47
  import { extractArtifact, rateSourceFields } from './text.js';
48
- import { defaultJudgeLoop } from './judged.js';
49
48
  import { workerThinkingMode, thinkingCallOptions } from './thinking.js';
50
49
  export { rateSourceFields };
51
50
  import { createClock, isWallTimeout } from './clock.js';
@@ -848,21 +847,6 @@ ${scoutBlob || '(no scout notes)'}`;
848
847
  * @param {{in: number, out: number}|null} [opts.rates] the customer's own price for the worker's key row (USD per
849
848
  * 1K tokens, `ratesFor`) — handed to the one Loop that drives worker, scout and planner rounds, so they read
850
849
  * `rateSource:'caller'`; null = bare-agent's built-in guess. Not applied to a native (CLI) session, which reports its own cost.
851
- * @param {{in: number, out: number}|null} [opts.judgeRates] the same, for the judge's Loop
852
- * @param {string|null} [opts.judgeModel] softgreen — WHICH model that judge provider drives
853
- * (PRD item 32.1). Resolved by the CALLER (`resolveJudge`, src/judged.js: the spec's signed
854
- * `judge` override, else the job's own worker model), never pinned in this library. It
855
- * travels with `judgeProvider` or the judged stage stops as a wiring gap: a verdict whose
856
- * grader cannot be named is a floor nobody can attribute.
857
- * @param {any} [opts.judgeProvider] softgreen — the provider a JUDGED close stage runs its
858
- * locate call through, built by the CALLER from the RESOLVED judge identity (PRD item
859
- * 32.1: `resolveJudge`, src/judged.js — the spec's signed `judge` override, else the job's
860
- * own worker provider and model), never pinned in this library. Separate
861
- * from `provider`/`providerFor` on purpose: the judge tier is not a step knob and never
862
- * agent-selectable, and the worker's binding is not a legal stand-in for it. Absent is not
863
- * a fall-back — a judged stage with no seam instrument-STOPS as a wiring gap, the same
864
- * answer a native job with no `nativeProvider` gets. A close with no judged stage never
865
- * reads it.
866
850
  * @param {(type: string, data?: object) => object} opts.emit spine emitter (the caller's METERED emit)
867
851
  * @param {() => number} opts.remainingUsd the one wallet: what is left of the signed budget right now
868
852
  * @param {() => boolean} [opts.isUnpriced] has any round come back with a null cost? (F6) — the
@@ -1080,7 +1064,7 @@ ${scoutBlob || '(no scout notes)'}`;
1080
1064
  * 'branch-red' | 'cap-halt' | 'wall-halt' | 'stopped' | 'provider-red' | 'interpreter-red' |
1081
1065
  * 'step-stalled' | 'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
1082
1066
  */
1083
- export async function runPlan(job, { workdir, provider, nativeProvider, providerFor, judgeProvider = null, judgeModel = null, rates = null, judgeRates = null, emit, remainingUsd, isUnpriced = () => false, spendComplete = () => true, capRuns = 3, strikeLimit = STRIKE_LIMIT, closeTimeoutMs, closeDir = null, maxStepRounds = 40, layerRoot = false, readShim = false, scout = true, scoutRounds = SCOUT_ROUNDS, bridge = null, now, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, priorSpentUsd = 0, reviewDoor = null, doorRerun = null, resumable = true, stopFile = null, learnHints = null }) {
1067
+ export async function runPlan(job, { workdir, provider, nativeProvider, providerFor, rates = null, emit, remainingUsd, isUnpriced = () => false, spendComplete = () => true, capRuns = 3, strikeLimit = STRIKE_LIMIT, closeTimeoutMs, closeDir = null, maxStepRounds = 40, layerRoot = false, readShim = false, scout = true, scoutRounds = SCOUT_ROUNDS, bridge = null, now, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, priorSpentUsd = 0, reviewDoor = null, doorRerun = null, resumable = true, stopFile = null, learnHints = null }) {
1084
1068
  // MEMORY-CACHE: what the read shim (src/readshim.js) saved THIS run, summed across
1085
1069
  // every mkWorker's own shim instance (scout, drafter, each step's worker, the fix
1086
1070
  // worker) — one accumulator closed over by all of them, because the shim's ledger
@@ -1789,27 +1773,6 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
1789
1773
  // arbiter-owned fact reaches a stage: through the ctx, never through the
1790
1774
  // declaration. A command close has no human stage to hand it to.
1791
1775
  humanRuling: liveRuling,
1792
- // SOFTGREEN — the judged stage's paid seam and its meter, the same way: through
1793
- // the ctx, never the declaration. The seam is null unless the operator wired a
1794
- // pinned judge provider (a judged stage then STOPS as a wiring gap rather than
1795
- // grading on the worker's model). The meter emits a distinct `judge-round`
1796
- // record carrying the call's own honest cost — the SAME emit the worker rounds
1797
- // ride, so `runJob`'s ONE ledger accounts a close's spend exactly as it accounts
1798
- // an attempt's (a budget funds the attempt PLUS its close), and a null cost trips
1799
- // the same F6 pricing halt rather than being laundered into $0.
1800
- judgeLoop: judgeProvider ? (/** @type {{system: string}} */ o) => defaultJudgeLoop({ provider: judgeProvider, system: o.system, rates: judgeRates, thinking: job.thinking === true }) : null,
1801
- // the seam's other half (PRD item 32.1) — WHICH model that loop drives. Passed
1802
- // through untouched: this module resolves no judge, exactly as it constructs no
1803
- // provider. `runJudgedFloor` stops as a wiring gap when it is absent rather than
1804
- // falling back to a library pin, so a null here is a stop and never a default.
1805
- ...(judgeModel === null ? {} : { judgeModel }),
1806
- // F152/PRD 30.4 — the judge's locate call carried NO time bound at all: a
1807
- // live endpoint that accepts and never answers hung the process forever
1808
- // (measured), because an open socket is an active handle and no backstop
1809
- // can fire on it. The SAME derivation every worker round already uses,
1810
- // handed through as the FUNCTION (not a snapshot) so a retried locate call
1811
- // re-reads the remaining time rather than reusing the first attempt's.
1812
- callBounds,
1813
1776
  // REPORT-ONLY: what a rubric-step stage's cited checks read (bareguard `full.evidence`), recorded as `rubric-evidence` for the Result
1814
1777
  // tab's highlights. No verdict, gap, governor or money path reads it. Masked HERE with the run's one `scrub`: the `text` is a quote from
1815
1778
  // the frozen page record, and the spine is append-only. Masking moves offsets, so an entry whose text changed keeps NO spans.
@@ -1824,15 +1787,6 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
1824
1787
  }),
1825
1788
  ...(e.evidenceTotal !== undefined ? { evidenceTotal: e.evidenceTotal } : {}),
1826
1789
  }),
1827
- onJudgeCost: (/** @type {any} */ c) => emit('judge-round', {
1828
- stage: c.stage, path: c.path, attempt: c.attempt, label: c.label, model: c.model,
1829
- costUsd: c.costUsd, unpricedRounds: c.unpricedRounds,
1830
- // BA-21 provenance, through the SAME helper the worker rounds use — this record
1831
- // is on `spendProvenance`'s read list (src/ledger.js). The judge cost payload
1832
- // (src/kinds.js `onJudgeCost`) forwards the field when the judge Loop carried it
1833
- // (`defaultJudgeLoop`); a loop that metered no rate leaves the key absent (UNKNOWN).
1834
- ...rateSourceFields(c),
1835
- }),
1836
1790
  })
1837
1791
  : runStages(stages, scrub, closeOpts));
1838
1792
  /**
@@ -2163,7 +2117,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
2163
2117
  }
2164
2118
  const listed = await seedListing(workdir, s.seedRef);
2165
2119
  const v = listed.stop === null
2166
- ? validateCloseDecl(job.closeDecl, { at: 'closeDecl', listing: listed.files, verdictType: job.verdictType, writeScope: job.writeScope, jobLines: Array.isArray(job.jobLines) ? job.jobLines : null , inputLabels: inputLabelsOf(job.inputs) })
2120
+ ? validateCloseDecl(job.closeDecl, { at: 'closeDecl', listing: listed.files, verdictType: job.verdictType, jobLines: Array.isArray(job.jobLines) ? job.jobLines : null , inputLabels: inputLabelsOf(job.inputs) })
2167
2121
  : { ok: false, grounded: false, reds: [{ code: 'listing-unreadable', path: 'closeDecl', detail: listed.stop }] };
2168
2122
  emit('close-decl', {
2169
2123
  genre: job.closeDecl.genre,