@haus-tech/haus-workflow 4.8.0 → 4.9.0

package/library/global/skills/request/scripts/compare-scores.mjs

@@ -6,9 +6,17 @@
  * prosa) och inringningens golv- och takankare. Prosa (why, drivers,
  * rationale) jämförs ALDRIG.
  *
- * Skriver LIKA (exit 0) eller OLIKA + diffrader (exit 1) på stdout; varningar
- * går på stderr. Vid OLIKA väljer dispatchern ALDRIG en körning och räknar
- * ALDRIG medelvärde — posten eskaleras till granskaren med båda inringningarna.
+ * Toleransregel: en poängskillnad ≤ 0,5 med samma outcome och confidence är
+ * prisbrus, inte oenighet. En ankarskillnad tolereras dessutom bara när banden
+ * överlappar eller angränsar; icke-angränsande band är hård diff även vid samma
+ * poäng. LIKA_TOLERANS hör till LIKA-familjen (exit 0) med
+ * en deterministisk vinnare (högsta poängen, skyddar marginalen). Den
+ * skriver aldrig om en fil och räknar aldrig fram ett medelvärde.
+ *
+ * Skriver LIKA, LIKA_TOLERANS (exit 0) eller OLIKA + diffrader (exit 1) på
+ * stdout; varningar går på stderr. Vid OLIKA väljer dispatchern ALDRIG en
+ * körning och räknar ALDRIG medelvärde — posten eskaleras till granskaren med
+ * båda inringningarna.
  *
  * Exit 2 = jämförelsen kan inte göras alls (dispatcherns fel, aldrig LIKA) —
  * rälsen bor i lib.mjs och delas med compare-classifications.
@@ -37,14 +45,56 @@ if (a.outcome !== b.outcome) diffs.push(`outcome: ${show(a.outcome)} ↔ ${show(
 // säkerhet är information granskaren ska se, precis som klassningens konfidenssida.
 if (a.confidence !== b.confidence)
   diffs.push(`confidence: ${show(a.confidence)} ↔ ${show(b.confidence)}`)
+// Toleransregel (beslut 2026-08-28, ADR-0078): en poängskillnad inom 0,5 med
+// samma outcome och confidence är prisbrus, inte oenighet. Båda pilotfallens
+// eskaleringar gällde Δ = 0,25 och kostade ett helt nytt varv styck. Högsta
+// poängen gäller (skyddar marginalen); ett medelvärde räknas fortfarande aldrig.
+const TOLERANS = 0.5
+
+/**
+ * Ankarnummer på skalan A1..A17. Golv null (under-A1-fallet) läses som 0, alltså
+ * steget under A1. Ett ankare som inte går att tolka ger null och behandlas som
+ * icke-angränsande, så en oläslig inringning aldrig kan tystas som brus.
+ */
+const ankarNr = (v) => {
+  if (v === null || v === undefined) return 0
+  const m = /^A(\d+)$/.exec(String(v))
+  return m ? Number(m[1]) : null
+}
+/**
+ * Inringningarna får toleransbehandling bara när de faktiskt pekar på samma del
+ * av skalan: överlappande eller angränsande band. Två körningar som landar på
+ * samma poäng men ringar in A5/A6 respektive A11/A12 är inte prisbrus, det är
+ * precis den drift dubbelkörningen finns för att visa, även när summan råkar bli
+ * densamma.
+ */
+const nastanSammaBand = (fa, ta, fb, tb) => {
+  const [l1, h1, l2, h2] = [ankarNr(fa), ankarNr(ta), ankarNr(fb), ankarNr(tb)]
+  if ([l1, h1, l2, h2].some((n) => n === null)) return false
+  return l1 <= h2 + 1 && l2 <= h1 + 1
+}
+
+const tolerans = []
 if (a.outcome === 'POANG' && b.outcome === 'POANG') {
-  if (a.score !== b.score) diffs.push(`score: ${show(a.score)} ↔ ${show(b.score)}`)
+  const delta = Math.abs(a.score - b.score)
+  const inomTolerans = Number.isFinite(delta) && delta <= TOLERANS
+  if (a.score !== b.score)
+    (inomTolerans ? tolerans : diffs).push(`score: ${show(a.score)} ↔ ${show(b.score)}`)
   const fa = a.bracket?.floor?.anchor ?? null
   const fb = b.bracket?.floor?.anchor ?? null
   const ta = a.bracket?.ceiling?.anchor ?? null
   const tb = b.bracket?.ceiling?.anchor ?? null
-  if (fa !== fb) diffs.push(`bracket.floor.anchor: ${show(fa)} ↔ ${show(fb)}`)
-  if (ta !== tb) diffs.push(`bracket.ceiling.anchor: ${show(ta)} ↔ ${show(tb)}`)
+  const ankarDiffs = []
+  if (fa !== fb) ankarDiffs.push(`bracket.floor.anchor: ${show(fa)} ↔ ${show(fb)}`)
+  if (ta !== tb) ankarDiffs.push(`bracket.ceiling.anchor: ${show(ta)} ↔ ${show(tb)}`)
+  ;(inomTolerans && nastanSammaBand(fa, ta, fb, tb) ? tolerans : diffs).push(...ankarDiffs)
 }
 
-reportDiffs(diffs)
+if (diffs.length === 0 && tolerans.length > 0) {
+  const winner = b.score > a.score ? 2 : 1
+  console.log(`LIKA_TOLERANS: högsta gäller ${Math.max(a.score, b.score)} (körning ${winner})`)
+  for (const t of tolerans) console.log(`- ${t}`)
+  process.exit(0)
+}
+// Hårda diffar visas tillsammans med toleransraderna: granskaren ska se helheten.
+reportDiffs([...diffs, ...tolerans])

package/library/global/skills/request/scripts/contract-check.mjs

@@ -13,7 +13,7 @@
  */
 import { readFileSync } from 'node:fs'
 
-import { refDriftWarning } from './lib.mjs'
+import { refDriftWarning, norm, quoteOk } from './lib.mjs'
 
 const argv = process.argv.slice(2)
 let expectId = null
@@ -47,9 +47,6 @@ for (const [rel, expected] of Object.entries(EXPECTED_REFS)) {
   const w = refDriftWarning(rel, expected)
   if (w) warnings.push(w)
 }
-// Markdown-betoning (**fet**, *kursiv*, `kod`) strippas före jämförelse — ett
-// citat som återges utan källans markeringar är fortfarande ordagrant.
-const norm = (s) => s.replace(/[*`]/g, '').replace(/\s+/g, ' ').trim()
 let doc
 try {
   doc = JSON.parse(readFileSync(jsonPath, 'utf8'))
@@ -69,17 +66,9 @@ try {
   process.exit(2)
 }
 
-/** Ett "ordagrant" citat får hoppa med [...] och kortas med inledande/avslutande …
- *  — varje kvarvarande segment måste vara exakt substräng av underlaget.
- *  Ett citat som blir tomt efter filtreringen är INTE ordagrant (annars vore
- *  "[...]" ett giltigt belägg för vad som helst). */
-const quoteOk = (q) => {
-  const segments = q
-    .split(/\s*\[(?:\.\.\.|…)\]\s*/)
-    .map((seg) => norm(seg.replace(/^(\.\.\.|…)|(\.\.\.|…)$/g, '')))
-    .filter((seg) => seg.length > 0)
-  return segments.length > 0 && segments.every((seg) => source.includes(seg))
-}
+// quoteOk kommer från lib.mjs (delad med quote-repair.mjs); bind källan lokalt
+// så befintliga anropsställen (`ok(f.belagg)` osv.) förblir oförändrade.
+const ok = (q) => quoteOk(q, source)
 
 /** Alla strängvärden ur ett godtyckligt värde (drivers kan vara objekt). */
 const collectStrings = (v) => {
@@ -254,7 +243,7 @@ if (doc.classification !== undefined) {
     // inte låg kvalitet.
     if (!f.belagg || norm(f.belagg).length === 0)
       problems.push(`fråga ${f.id}: belägg saknas (obligatoriskt, ordagrant citat)`)
-    else if (!quoteOk(f.belagg))
+    else if (!ok(f.belagg))
       problems.push(
         `fråga ${f.id}: belägg är inte ordagrant citat ur underlaget: "${f.belagg.slice(0, 70)}..."`,
       )
@@ -296,7 +285,7 @@ if (doc.classification !== undefined) {
   for (const [i, d] of (Array.isArray(doc.drivers) ? doc.drivers : []).entries())
     for (const str of collectStrings(d))
       for (const m of str.matchAll(/["“”„«»]([^"“”„«»]{15,})["“”„«»]/g))
-        if (!quoteOk(m[1]))
+        if (!ok(m[1]))
           problems.push(
             `drivers[${i}]: citat är inte ordagrant ur underlaget: "${m[1].slice(0, 70)}..."`,
           )

package/library/global/skills/request/scripts/lib.mjs

@@ -111,3 +111,18 @@ export function reportDiffs(diffs) {
   for (const d of diffs) console.log(`- ${d}`)
   process.exit(1)
 }
+
+/** Markdown-betoning strippas före jämförelse: ett citat som återges utan
+ *  källans fetstil- eller `kod`-markeringar är fortfarande ordagrant. */
+export const norm = (s) => s.replace(/[*`]/g, '').replace(/\s+/g, ' ').trim()
+
+/** Ett "ordagrant" citat får hoppa med [...] och kortas med inledande/avslutande …
+ *  Varje kvarvarande segment måste vara exakt substräng av det normaliserade
+ *  underlaget. Tomt efter filtrering = INTE ordagrant. */
+export const quoteOk = (q, normalizedSource) => {
+  const segments = q
+    .split(/\s*\[(?:\.\.\.|…)\]\s*/)
+    .map((seg) => norm(seg.replace(/^(\.\.\.|…)|(\.\.\.|…)$/g, '')))
+    .filter((seg) => seg.length > 0)
+  return segments.length > 0 && segments.every((seg) => normalizedSource.includes(seg))
+}

package/library/global/skills/request/scripts/quote-repair.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * Deterministisk citaträttning FÖRE omdispatch. Pilotsessionerna 2026-08-28
+ * visade att classifiern komponerar belägg i stället för att citera (4 av 4
+ * förstapass fälldes av contract-check), och varje fällning kostade en full
+ * omkörning på 6-9 min. Det här scriptet räddar det räddningsbara: ett citat
+ * som inte är exakt substräng ersätts med sin ENTYDIGT närmaste källmening.
+ * Ingen entydig träff = ingen rättning (hellre omdispatch än fel belägg), och
+ * skrivningen är allt eller inget så en halvrättad fil aldrig arkiveras.
+ * En kandidat med annan polaritet än citatet (se NEGATIONER) är aldrig giltig:
+ * rättningen får byta form på pekaren, aldrig vända påståendet.
+ *
+ * Rättar samma fält som contract-check kontrollerar: classification.fragor[].belagg
+ * samt citattecken-omgärdade segment (>= 15 tecken) i score-JSON:ens drivers.
+ * Bedömer aldrig innehåll; byter aldrig mening, bara formen på pekaren.
+ *
+ * Användning: node quote-repair.mjs <run.json> <spec.md> [impact.md]
+ * Stdout: "RÄTTAT (N):" + rader, "ORÄTTBART (N):" + rader, eller "INGET ATT RÄTTA".
+ * Exit 0 = inga orättbara citat kvar (rättade eller inga), 1 = orättbara kvar
+ * (filen orörd), 2 = användningsfel/oläsbar input (dispatcherfel).
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+
+import { norm, quoteOk } from './lib.mjs'
+
+const [jsonPath, specPath, impactPath] = process.argv.slice(2)
+if (!jsonPath || !specPath) {
+  console.error('användning: node quote-repair.mjs <run.json> <spec.md> [impact.md]')
+  process.exit(2)
+}
+let doc, sourceRaw
+try {
+  doc = JSON.parse(readFileSync(jsonPath, 'utf8'))
+  sourceRaw =
+    readFileSync(specPath, 'utf8') + '\n' + (impactPath ? readFileSync(impactPath, 'utf8') : '')
+} catch (e) {
+  console.error(`kunde inte läsa input: ${e.message}`)
+  process.exit(2)
+}
+const source = norm(sourceRaw)
+
+// Kandidater: källans meningar (rad- och meningsgränser) plus par av
+// angränsande meningar, så ett tvåmeningscitat kan få en exakt motsvarighet.
+const sentences = sourceRaw
+  .split(/\n+|(?<=[.!?])\s+(?=[A-ZÅÄÖ0-9])/u)
+  .map((s) => s.trim())
+  .filter((s) => norm(s).length >= 15)
+const candidates = [...sentences]
+for (let i = 0; i + 1 < sentences.length; i++)
+  candidates.push(`${sentences[i]} ${sentences[i + 1]}`)
+
+const tokens = (s) =>
+  new Set(
+    norm(s)
+      .toLowerCase()
+      .split(/[^\p{L}\p{N}]+/u)
+      .filter(Boolean),
+  )
+const dice = (A, B) => {
+  let inter = 0
+  for (const t of A) if (B.has(t)) inter++
+  return (2 * inter) / (A.size + B.size || 1)
+}
+
+/**
+ * Polaritetsvakt. Dice över tokenmängder är blind för negation: "Ingen" är ett
+ * ord av nio, men vänder påståendet. Utan den här listan "rättas" ett belägg som
+ * säger att behörighetslogik ÄNDRAS till källmeningen som säger att den INTE
+ * ändras, och contract-check släpper igenom det, alltså tvärtemot vad
+ * citatgrinden finns för. Ett citat får bara ersättas av en kandidat med exakt
+ * samma uppsättning negationsord.
+ */
+const NEGATIONER = new Set([
+  'ingen',
+  'inga',
+  'inget',
+  'inte',
+  'icke',
+  'aldrig',
+  'utan',
+  'ej',
+  'saknas',
+  'varken',
+])
+const negationer = (s) => {
+  const found = []
+  for (const t of tokens(s)) if (NEGATIONER.has(t)) found.push(t)
+  return found.sort().join(' ')
+}
+
+// Entydighetskravet är själva säkerhetsregeln: bästa träffen måste vara både
+// nära nog (>= 0.6) och klart ensam (marginal >= 0.15), annars rättas inget.
+// Polaritetsvakten går FÖRE poängsättningen: en kandidat med annan uppsättning
+// negationsord är aldrig en giltig ersättare, hur nära den än ligger i Dice.
+// En par-kandidat som bara är bästa träffen med en angränsande mening bilagd
+// (delsträngsöverlapp åt endera hållet) är samma källplats, inte en
+// konkurrerande: annars slår varannan stark enmeningsträff ut sig själv på
+// marginalkravet så snart en granne delar ett enda vanligt ord.
+const findReplacement = (quote) => {
+  const q = tokens(quote)
+  const pol = negationer(quote)
+  const scored = candidates
+    .filter((c) => negationer(c) === pol)
+    .map((c) => ({ c, s: dice(q, tokens(c)) }))
+    .sort((a, b) => b.s - a.s)
+  const best = scored[0]
+  if (!best || best.s < 0.6) return null
+  const second =
+    scored.find((x) => x.c !== best.c && !x.c.includes(best.c) && !best.c.includes(x.c))?.s ?? 0
+  if (best.s - second >= 0.15 && quoteOk(best.c, source)) return best.c
+  return null
+}
+
+const trunc = (s) => (s.length > 60 ? `${s.slice(0, 60)}…` : s)
+// Citattecken i en ersättning som ska splitsas IN mellan citattecken skulle
+// stänga citatet för tidigt: strängen blir obalanserad och nästa läsning ser ett
+// annat citat än det som godkändes. Sådana kandidater refuseras.
+const CITATTECKEN = /["“”„«»]/
+const repaired = []
+const unfixable = []
+const fixQuote = (val, label, forbidQuoteChars = false) => {
+  if (quoteOk(val, source)) return val
+  const r = findReplacement(val)
+  if (r && !(forbidQuoteChars && CITATTECKEN.test(r))) {
+    repaired.push(`- ${label}: "${trunc(val)}" → "${trunc(r)}"`)
+    return r
+  }
+  unfixable.push(`- ${label}: "${trunc(val)}"`)
+  return val
+}
+
+if (doc.classification && typeof doc.classification === 'object') {
+  for (const f of Array.isArray(doc.classification.fragor) ? doc.classification.fragor : [])
+    if (f && typeof f.belagg === 'string' && norm(f.belagg).length > 0)
+      f.belagg = fixQuote(f.belagg, `fråga ${f.id}`)
+} else if (doc.outcome !== undefined) {
+  // Samma citat-regex som contract-check: raka och typografiska citattecken.
+  const fixInString = (str, label) =>
+    str.replace(
+      /(["“”„«»])([^"“”„«»]{15,})(["“”„«»])/g,
+      (_m, o, inner, c) => o + fixQuote(inner, label, true) + c,
+    )
+  const walk = (v, label) =>
+    typeof v === 'string'
+      ? fixInString(v, label)
+      : Array.isArray(v)
+        ? v.map((x) => walk(x, label))
+        : v && typeof v === 'object'
+          ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x, label)]))
+          : v
+  if (Array.isArray(doc.drivers)) doc.drivers = doc.drivers.map((d, i) => walk(d, `drivers[${i}]`))
+}
+
+if (unfixable.length > 0) {
+  console.log(`ORÄTTBART (${unfixable.length}):`)
+  for (const u of unfixable) console.log(u)
+  process.exit(1)
+}
+if (repaired.length > 0) {
+  writeFileSync(jsonPath, JSON.stringify(doc, null, 2) + '\n')
+  console.log(`RÄTTAT (${repaired.length}):`)
+  for (const r of repaired) console.log(r)
+} else {
+  console.log('INGET ATT RÄTTA')
+}
+process.exit(0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haus-tech/haus-workflow",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Haus AI workflow CLI for Claude Code.",
   "type": "module",
   "bin": {
@@ -17,7 +17,9 @@
     "library/global",
     "library/catalog",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "docs/before-you-start.md",
+    "docs/glossary.md"
   ],
   "scripts": {
     "build": "rm -rf dist && esbuild src/cli.ts --bundle --packages=external --platform=node --format=esm --outdir=dist --external:@inquirer/checkbox",
@@ -39,6 +41,7 @@
     "verify:full": "node scripts/verify.mjs --coverage",
     "check:contract-behavior": "node --import tsx scripts/contract-behavior-check.mjs",
     "check:mutation-table": "node scripts/check-mutation-table.mjs",
+    "check:docs-site": "node scripts/check-docs-site.mjs",
     "postinstall": "node ./scripts/postinstall.mjs || true",
     "prepare": "lefthook install || true",
     "security:audit": "yarn npm audit -A -R --severity high --environment production"