@patwoodman/dsh-sdlc-flow-core 0.0.0-stage → 0.4.0-beta.14

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SDLC Orchestrator contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @patwoodman/dsh-sdlc-flow-core — host services
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The runtime authority of the orchestrator: task engine and state machine,
+scheduler, router, verifier, integration manager, evidence log, escalation
+ledger, worker manager and recovery. It owns the SQLite state in `.sdlc/`.
+
+**Never install this into a worker profile.** Mounting it there would start a
+second scheduler and a second writer against `sdlc.db` (errata E6 in the spec).
+Worker profiles mount [`@patwoodman/dsh-sdlc-flow-guard`](https://www.npmjs.com/package/@patwoodman/dsh-sdlc-flow-guard)
+and [`@patwoodman/dsh-sdlc-flow-tools`](https://www.npmjs.com/package/@patwoodman/dsh-sdlc-flow-tools)
+only.
+
+## Install
+
+Installed as a bundle by the worker-free profiles (`sdlc-probe`) and as a module
+dependency of [`@patwoodman/dsh-sdlc-flow`](https://www.npmjs.com/package/@patwoodman/dsh-sdlc-flow):
+
+```sh
+dsh plugin --profile <profile> add @patwoodman/dsh-sdlc-flow-core
+```
+
+## Requirements
+
+- `@deepseek-ai/dsh` `>=0.2.0-rc.2 <0.3.0-0`
+- Node.js ≥ 22.5 (`node:sqlite`)
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,51 @@
+# sdlc-core — host services (spec v3 C.1/C.2).
+#
+# HOST BUNDLE. This package declares the runtime authority: task engine, state
+# transitions, scheduler, router, verifier, integration manager, evidence,
+# escalation and worker dispatch. It must NEVER be installed into a worker
+# profile — mounting it there would start a second scheduler and a second
+# writer against sdlc.db (errata E6). install-local.mjs and doctor.mjs assert
+# the partition.
+#
+# NOTE (discrepancy D2): spec C.1's inline comment shows sdlc-core declaring
+# both cordis.patch.yml and presets.patch.yml. The 26 preset rows live in
+# @patwoodman/dsh-sdlc-flow-presets (C.1 body text); declaring them here as well would
+# produce duplicate loader row ids and fail M0-02-no-dup-ids. Core therefore
+# declares host rows only.
+- insert:
+    - id: sdlc-tasks
+      name: '@patwoodman/dsh-sdlc-flow-core/services'
+      config:
+        service: tasks
+    - id: sdlc-scheduler
+      name: '@patwoodman/dsh-sdlc-flow-core/services'
+      config:
+        service: scheduler
+    - id: sdlc-router
+      name: '@patwoodman/dsh-sdlc-flow-core/services'
+      config:
+        service: router
+    - id: sdlc-verifier
+      name: '@patwoodman/dsh-sdlc-flow-core/services'
+      config:
+        service: verifier
+    - id: sdlc-integration
+      name: '@patwoodman/dsh-sdlc-flow-core/services'
+      config:
+        service: integration
+    - id: sdlc-evidence
+      name: '@patwoodman/dsh-sdlc-flow-core/services'
+      config:
+        service: evidence
+    - id: sdlc-escalation
+      name: '@patwoodman/dsh-sdlc-flow-core/services'
+      config:
+        service: escalation
+    - id: sdlc-worker-mgr
+      name: '@patwoodman/dsh-sdlc-flow-core/services'
+      config:
+        service: worker-mgr
+    - id: sdlc-recovery
+      name: '@patwoodman/dsh-sdlc-flow-core/services'
+      config:
+        service: recovery

package/icon.svg

@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Universal SDLC Orchestrator">
+  <defs>
+    <linearGradient id="sdlc-bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#1e3a8a"/>
+      <stop offset="1" stop-color="#0e7490"/>
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="14" fill="url(#sdlc-bg)"/>
+  <g fill="none" stroke="#e0f2fe" stroke-width="2.4" stroke-linecap="round">
+    <path d="M32 17v9"/>
+    <path d="M32 34v4"/>
+    <path d="M24 44l-8 6"/>
+    <path d="M40 44l8 6"/>
+  </g>
+  <g fill="#e0f2fe">
+    <circle cx="32" cy="13" r="4.6"/>
+    <circle cx="32" cy="29" r="4.6"/>
+    <circle cx="19" cy="47" r="4.6"/>
+    <circle cx="45" cy="47" r="4.6"/>
+  </g>
+  <g fill="#0e7490">
+    <circle cx="32" cy="13" r="1.7"/>
+    <circle cx="32" cy="29" r="1.7"/>
+    <circle cx="19" cy="47" r="1.7"/>
+    <circle cx="45" cy="47" r="1.7"/>
+  </g>
+  <path d="M27.5 39.5l4.5 4.5 4.5-4.5" fill="none" stroke="#67e8f9" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/lib/a11y.js

@@ -0,0 +1,126 @@
+/**
+ * packages/sdlc-core/src/a11y.js — the always-on accessibility floor (spec v3 B.5).
+ *
+ * B.5 names three checks that are ALWAYS on, owned by the Accessibility
+ * Engineer: basic contrast on primary text, images have alt text, and form
+ * controls have label associations — plus keyboard focus must be visible on
+ * every interactive element. These are pure predicates over a DOM description
+ * so they run in the gate suite without a browser; the Playwright layer feeds
+ * them real measurements.
+ */
+
+/** WCAG relative luminance for a #rgb / #rrggbb colour. */
+export function relativeLuminance(hex) {
+  const value = String(hex).replace(/^#/, '');
+  const full = value.length === 3 ? value.split('').map((c) => c + c).join('') : value;
+  if (!/^[0-9a-fA-F]{6}$/.test(full)) throw new Error(`invalid colour: ${hex}`);
+  const channel = (c) => {
+    const v = parseInt(c, 16) / 255;
+    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+  };
+  const r = channel(full.slice(0, 2));
+  const g = channel(full.slice(2, 4));
+  const b = channel(full.slice(4, 6));
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** WCAG contrast ratio between two colours (1..21). */
+export function contrastRatio(foreground, background) {
+  const l1 = relativeLuminance(foreground);
+  const l2 = relativeLuminance(background);
+  const [hi, lo] = l1 >= l2 ? [l1, l2] : [l2, l1];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/**
+ * WCAG 2.1 AA thresholds: 4.5:1 for normal text, 3:1 for large text (≥18.66px
+ * bold or ≥24px) and for UI components.
+ */
+export function meetsContrast(foreground, background, { large = false, level = 'AA' } = {}) {
+  const ratio = contrastRatio(foreground, background);
+  const threshold = level === 'AAA' ? (large ? 4.5 : 7) : (large ? 3 : 4.5);
+  return { pass: ratio >= threshold, ratio: Number(ratio.toFixed(2)), threshold };
+}
+
+/** Every meaningful image must carry a non-empty alt attribute. */
+export function checkAltText(images = []) {
+  const violations = [];
+  for (const img of images) {
+    if (img.decorative) continue; // role="presentation"/aria-hidden is legitimate
+    if (!img.alt || String(img.alt).trim() === '') {
+      violations.push({ check: 'alt-text', element: img.selector ?? img.src ?? '<img>', reason: 'missing alt text' });
+    }
+  }
+  return violations;
+}
+
+/** Every form control must have a label association (for/id, aria-label or aria-labelledby). */
+export function checkLabels(controls = []) {
+  const violations = [];
+  for (const control of controls) {
+    const labelled = Boolean(control.label) || Boolean(control['aria-label']) || Boolean(control['aria-labelledby']);
+    if (!labelled) {
+      violations.push({ check: 'label-association', element: control.selector ?? control.name ?? '<control>', reason: 'no label association' });
+    }
+  }
+  return violations;
+}
+
+/** Keyboard focus must be visible on every interactive element. */
+export function checkFocusVisible(elements = []) {
+  const violations = [];
+  for (const element of elements) {
+    if (!element.interactive) continue;
+    if (element.focusVisible === false) {
+      violations.push({ check: 'focus-visible', element: element.selector ?? '<element>', reason: 'no visible focus indicator' });
+    }
+  }
+  return violations;
+}
+
+/**
+ * Run the floor. `measurements` come from either the Playwright layer or a
+ * fixture; absence of a measurement is a SKIP for that check, never a pass.
+ */
+export function runA11yFloor({ images = null, controls = null, interactive = null, textSamples = null, enabled = true } = {}) {
+  if (!enabled) return { pass: true, checks: [{ check: 'a11y-floor', status: 'skipped:disabled' }] };
+  const checks = [];
+  const violations = [];
+
+  const add = (name, data, fn) => {
+    if (data == null) { checks.push({ check: name, status: 'skipped:no-measurement' }); return; }
+    const found = fn(data);
+    violations.push(...found);
+    checks.push({ check: name, status: found.length ? 'fail' : 'pass', violations: found.length });
+  };
+
+  add('alt-text', images, checkAltText);
+  add('label-association', controls, checkLabels);
+  add('focus-visible', interactive, checkFocusVisible);
+
+  if (textSamples == null) {
+    checks.push({ check: 'contrast', status: 'skipped:no-measurement' });
+  } else {
+    const contrastViolations = [];
+    for (const sample of textSamples) {
+      const result = meetsContrast(sample.color, sample.background, { large: sample.large });
+      if (!result.pass) {
+        contrastViolations.push({ check: 'contrast', element: sample.selector ?? '<text>', reason: `ratio ${result.ratio} < ${result.threshold}` });
+      }
+    }
+    violations.push(...contrastViolations);
+    checks.push({ check: 'contrast', status: contrastViolations.length ? 'fail' : 'pass', violations: contrastViolations.length });
+  }
+
+  return {
+    pass: violations.length === 0,
+    // A stable, documented order (A11Y_FLOOR_CHECKS) so evidence bundles are
+    // comparable across runs.
+    checks: checks.sort((a, b) => A11Y_FLOOR_CHECKS.indexOf(a.check) - A11Y_FLOOR_CHECKS.indexOf(b.check)),
+    violations,
+  };
+}
+
+export const A11Y_FLOOR_CHECKS = ['contrast', 'alt-text', 'label-association', 'focus-visible'];
+
+export default { contrastRatio, meetsContrast, checkAltText, checkLabels, checkFocusVisible, runA11yFloor, A11Y_FLOOR_CHECKS };

package/lib/budget.js

@@ -0,0 +1,167 @@
+/**
+ * packages/sdlc-core/src/budget.js — per-attempt vs per-task budgets (spec v3 B.7).
+ *
+ * Semantics fixed in v3:
+ *   - `max_attempts` is PER TASK.
+ *   - `max_duration_ms`, `max_cost_usd`, `max_tokens` are PER ATTEMPT; the task
+ *     also carries derived cumulative limits `attempts × per-attempt`, which the
+ *     scheduler checks before dispatch.
+ *   - A run that exceeds its per-attempt wall clock is killed by the timeout
+ *     policy (soft at 80 %, hard at 100 %).
+ *   - A task whose CUMULATIVE limits are exhausted moves to ESCALATED, not
+ *     FAILED, so the decision is explicit.
+ */
+
+export const RISK_BUDGET_DEFAULTS = Object.freeze({
+  R1: { maxAttempts: 2, maxDurationMs: 1800000, maxCostUsd: 2.0, maxTokens: 200000 },
+  R2: { maxAttempts: 3, maxDurationMs: 3600000, maxCostUsd: 5.0, maxTokens: 400000 },
+  R3: { maxAttempts: 3, maxDurationMs: 7200000, maxCostUsd: 15.0, maxTokens: 1000000 },
+  R4: { maxAttempts: 4, maxDurationMs: 14400000, maxCostUsd: 50.0, maxTokens: 3000000 },
+});
+
+export const PROJECT_BUDGET_DEFAULTS = Object.freeze({
+  maxCostUsd: 200.0,
+  maxDurationMs: 86400000,
+  maxParallelWorkers: 'auto',
+});
+
+export const SOFT_BUDGET_RATIO = 0.8;
+
+export function budgetsForRisk(risk, perTask = RISK_BUDGET_DEFAULTS) {
+  return { ...(perTask[risk] ?? perTask.R2) };
+}
+
+/** The canonical task-contract budget keys, per spec B.3.1 / H.1 (snake_case). */
+export const BUDGET_ALIASES = {
+  max_attempts: 'maxAttempts',
+  maxAttempts: 'maxAttempts',
+  max_duration_ms: 'maxDurationMs',
+  maxDurationMs: 'maxDurationMs',
+  max_cost_usd: 'maxCostUsd',
+  maxCostUsd: 'maxCostUsd',
+  max_tokens: 'maxTokens',
+  maxTokens: 'maxTokens',
+};
+
+/**
+ * Normalize a task-contract `budgets` block. B.3.1 writes snake_case
+ * (`max_attempts`, `max_duration_ms`, …) while the internal model is camelCase;
+ * BOTH are accepted so a spec-shaped contract round-trips without translation by
+ * the caller. Unknown keys are reported rather than silently dropped.
+ *
+ * @returns {{budget:object, unknownKeys:string[]}}
+ */
+export function normalizeTaskBudget(budgets, risk = 'R2', perTask = RISK_BUDGET_DEFAULTS) {
+  const base = budgetsForRisk(risk, perTask);
+  if (budgets == null) return { budget: base, unknownKeys: [] };
+  const unknownKeys = [];
+  const out = { ...base };
+  for (const [key, value] of Object.entries(budgets)) {
+    const canonical = BUDGET_ALIASES[key];
+    if (!canonical) { unknownKeys.push(key); continue; }
+    out[canonical] = typeof value === 'number' ? value : Number(value);
+  }
+  return { budget: out, unknownKeys };
+}
+
+/** Derive the cumulative (whole-task) ceilings from a per-attempt budget. */
+export function cumulativeBudgets(perAttempt) {
+  return {
+    maxAttempts: perAttempt.maxAttempts,
+    maxDurationMs: perAttempt.maxDurationMs * perAttempt.maxAttempts,
+    maxCostUsd: round6(perAttempt.maxCostUsd * perAttempt.maxAttempts),
+    maxTokens: perAttempt.maxTokens * perAttempt.maxAttempts,
+  };
+}
+
+function round6(n) {
+  return Math.round(n * 1e6) / 1e6;
+}
+
+/**
+ * Scheduler gate before dispatch.
+ * @returns {{ok:boolean, reason?:string}} `BUDGET_EXHAUSTED` blocks dispatch.
+ */
+export function checkDispatch({ attempt = 0, spentCostUsd = 0, spentTokens = 0, spentDurationMs = 0 } = {}, budget) {
+  const cumulative = cumulativeBudgets(budget);
+  if (attempt >= budget.maxAttempts) return { ok: false, reason: 'BUDGET_EXHAUSTED:max_attempts' };
+  if (spentCostUsd >= cumulative.maxCostUsd) return { ok: false, reason: 'BUDGET_EXHAUSTED:cost' };
+  if (spentTokens >= cumulative.maxTokens) return { ok: false, reason: 'BUDGET_EXHAUSTED:tokens' };
+  if (spentDurationMs >= cumulative.maxDurationMs) return { ok: false, reason: 'BUDGET_EXHAUSTED:duration' };
+  return { ok: true };
+}
+
+/** Project-level run budget. */
+export function checkProjectBudget({ spentCostUsd = 0, spentDurationMs = 0 } = {}, projectBudget = PROJECT_BUDGET_DEFAULTS) {
+  if (projectBudget.maxCostUsd != null && spentCostUsd >= projectBudget.maxCostUsd) {
+    return { ok: false, reason: 'BUDGET_EXHAUSTED:project-cost' };
+  }
+  if (projectBudget.maxDurationMs != null && spentDurationMs >= projectBudget.maxDurationMs) {
+    return { ok: false, reason: 'BUDGET_EXHAUSTED:project-duration' };
+  }
+  return { ok: true };
+}
+
+/** Timeout policy thresholds for a single run (B.3.2). */
+export function timeoutThresholds(maxDurationMs, now = () => Date.now()) {
+  const start = now();
+  return {
+    startedAt: start,
+    softAt: start + maxDurationMs * SOFT_BUDGET_RATIO,
+    hardAt: start + maxDurationMs,
+    phase(t = now()) {
+      if (t >= start + maxDurationMs) return 'hard';
+      if (t >= start + maxDurationMs * SOFT_BUDGET_RATIO) return 'soft';
+      return 'ok';
+    },
+  };
+}
+
+/**
+ * Post-run accounting. Returns the next action the scheduler must take.
+ * `exhausted` ⇒ ESCALATED (explicit decision), `overrun` ⇒ kill/retry path.
+ *
+ * `taskSpend` is THIS task's spend from earlier attempts — it feeds the task
+ * cumulative cost ceiling. `projectSpend` is the whole project's spend and is
+ * used ONLY for the project ceiling; conflating the two let an unrelated task's
+ * spend escalate a task that had barely started.
+ */
+export function evaluateRun({
+  attempt = 0,
+  run = { costUsd: 0, tokens: 0, durationMs: 0 },
+  taskBudget,
+  taskSpend = { costUsd: 0 },
+  projectBudget = PROJECT_BUDGET_DEFAULTS,
+  projectSpend = { costUsd: 0, durationMs: 0 },
+} = {}) {
+  const perAttemptOver =
+    (run.costUsd ?? 0) > taskBudget.maxCostUsd ||
+    (run.tokens ?? 0) > taskBudget.maxTokens ||
+    (run.durationMs ?? 0) > taskBudget.maxDurationMs;
+
+  const cumulative = cumulativeBudgets(taskBudget);
+  const nextAttempt = attempt + 1;
+  const cumulativeExhausted =
+    nextAttempt >= taskBudget.maxAttempts ||
+    (taskSpend.costUsd ?? 0) + (run.costUsd ?? 0) >= cumulative.maxCostUsd;
+
+  const project = checkProjectBudget(
+    { spentCostUsd: (projectSpend.costUsd ?? 0) + (run.costUsd ?? 0), spentDurationMs: (projectSpend.durationMs ?? 0) + (run.durationMs ?? 0) },
+    projectBudget,
+  );
+
+  if (!project.ok) return { action: 'block', reason: project.reason, perAttemptOver, cumulativeExhausted };
+  if (cumulativeExhausted) return { action: 'escalate', reason: 'BUDGET_EXHAUSTED:cumulative', perAttemptOver, cumulativeExhausted };
+  if (perAttemptOver) return { action: 'retry', reason: 'PER_ATTEMPT_BUDGET_EXCEEDED', perAttemptOver, cumulativeExhausted };
+  return { action: 'continue', reason: null, perAttemptOver, cumulativeExhausted };
+}
+
+/** Provider 429 backpressure: exponential cooldown, capped (B.7). */
+export function backoffDelay(attempt, { baseMs = 1000, capMs = 60000 } = {}) {
+  return Math.min(capMs, baseMs * 2 ** Math.max(0, attempt));
+}
+
+export default {
+  RISK_BUDGET_DEFAULTS, PROJECT_BUDGET_DEFAULTS, budgetsForRisk, cumulativeBudgets,
+  checkDispatch, checkProjectBudget, evaluateRun, timeoutThresholds, backoffDelay,
+};

package/lib/complexity/index.js

@@ -0,0 +1,160 @@
+/**
+ * packages/sdlc-core/src/complexity/index.js — complexity engine v2 (spec v3 B.1).
+ *
+ * Pure arithmetic: every feature has a deterministic extraction rule and is
+ * normalized to [0,1] before weighting; the weights sum to exactly 1.0, so
+ * `score ∈ [0,1]` by construction. LLM involvement is limited to producing the
+ * structured estimate (the integers/booleans below) — never the score.
+ *
+ * Determinism contract: same repo state + same requirement ⇒ same score.
+ *
+ * NOTE ON SPEC G.2.1: the illustrative unit test in Part G asserts
+ * `normalizeFeature('files', 1) < 0.1`. The normative formula in B.1 is
+ * `min(ln(1+F)/ln(201), 1)`, which yields ≈0.131 for F=1. Part B is normative,
+ * so the formula is implemented as written and the test asserts the real value
+ * (see SDLC_IMPLEMENTATION_NOTES.md, discrepancy D1).
+ */
+
+/** Feature weights — must sum to exactly 1.0 (asserted in unit tests). */
+export const WEIGHTS = Object.freeze({
+  d: 0.15,
+  f: 0.10,
+  i: 0.15,
+  db: 0.10,
+  sec: 0.10,
+  ui: 0.10,
+  e: 0.10,
+  dep: 0.10,
+  t: 0.10,
+});
+
+export const FILE_SCALE_LN = Math.log(201);
+
+export const BANDS = Object.freeze([
+  { name: 'Tiny', lo: 0.0, hi: 0.25 },
+  { name: 'Small', lo: 0.25, hi: 0.45 },
+  { name: 'Medium', lo: 0.45, hi: 0.65 },
+  { name: 'Large', lo: 0.65, hi: 0.8 },
+  { name: 'Enterprise', lo: 0.8, hi: 1.0 },
+]);
+
+function clamp01(n) {
+  if (Number.isNaN(n) || n == null) return 0;
+  return Math.min(1, Math.max(0, n));
+}
+
+function intIn(value, lo, hi, fallback = 0) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(hi, Math.max(lo, Math.trunc(n)));
+}
+
+function bool01(value) {
+  return value ? 1 : 0;
+}
+
+/**
+ * Normalize a single feature. Exported because Part K.3 property-tests each
+ * normalization for monotonicity and range.
+ */
+export function normalizeFeature(name, value) {
+  switch (name) {
+    case 'domains': return clamp01(intIn(value, 0, 1000, 0) / 5);
+    case 'files': {
+      const f = intIn(value, 0, 1000, 0);
+      return clamp01(Math.log(1 + f) / FILE_SCALE_LN);
+    }
+    case 'integrations': return clamp01(intIn(value, 0, 1000, 0) / 5);
+    case 'external_deps': return clamp01(intIn(value, 0, 1000, 0) / 10);
+    case 'testing': {
+      const t = Number(value);
+      if (t >= 1) return 1;
+      if (t >= 0.5) return 0.5;
+      return 0;
+    }
+    case 'db': case 'sec': case 'ui': case 'dep': return bool01(value);
+    default: throw new Error(`unknown feature: ${name}`);
+  }
+}
+
+/** Band lookup; half-open `[lo, hi)` except the last band, which is closed. */
+export function bandFor(score, bands = BANDS) {
+  const s = clamp01(score);
+  for (let i = 0; i < bands.length; i += 1) {
+    const b = bands[i];
+    const isLast = i === bands.length - 1;
+    if (s >= b.lo && (isLast ? s <= b.hi : s < b.hi)) return b.name;
+  }
+  return bands[bands.length - 1].name;
+}
+
+/**
+ * Security classifier for the `sec` feature (B.1): a security-sensitive
+ * `allowed_paths` glob OR a requirement mentioning auth/authz/payments/PII.
+ */
+export const SECURITY_PATH_PATTERNS = [
+  '**/auth*', '**/*auth*', '**/*token*', '**/*secret*', '**/*credential*',
+  '**/crypto*', '**/*permission*', '**/*session*', '**/*cors*', '**/*csrf*',
+];
+export const SECURITY_REQUIREMENT_TERMS = [
+  'auth', 'authz', 'authorization', 'authentication', 'payment', 'pii',
+  'password', 'credential', 'secret', 'token', 'permission', 'encrypt',
+  'oauth', 'sso', 'login',
+];
+
+/**
+ * Compute the complexity score.
+ * @param {object} input structured estimate (validated integers/booleans)
+ * @returns {{score:number, band:string, normalized:object, weights:object}}
+ */
+export function computeComplexity(input = {}) {
+  const normalized = {
+    d: normalizeFeature('domains', input.domains),
+    f: normalizeFeature('files', input.files),
+    i: normalizeFeature('integrations', input.integrations),
+    db: normalizeFeature('db', input.db),
+    sec: normalizeFeature('sec', input.sec),
+    ui: normalizeFeature('ui', input.ui),
+    e: normalizeFeature('external_deps', input.external_deps),
+    dep: normalizeFeature('dep', input.dep),
+    t: normalizeFeature('testing', input.testing),
+  };
+  const score = clamp01(
+    WEIGHTS.d * normalized.d +
+    WEIGHTS.f * normalized.f +
+    WEIGHTS.i * normalized.i +
+    WEIGHTS.db * normalized.db +
+    WEIGHTS.sec * normalized.sec +
+    WEIGHTS.ui * normalized.ui +
+    WEIGHTS.e * normalized.e +
+    WEIGHTS.dep * normalized.dep +
+    WEIGHTS.t * normalized.t,
+  );
+  return { score, band: bandFor(score), normalized, weights: WEIGHTS };
+}
+
+/** Detect the project's impure `sec` flag from repo/requirement context (B.1). */
+export function deriveSec({ allowedPaths = [], requirement = '' } = {}) {
+  for (const p of allowedPaths) {
+    if (/(^|[\/_.-])(auth|token|secret|credential|crypto|permission|session|cors|csrf)/i.test(String(p))) return true;
+  }
+  const text = String(requirement).toLowerCase();
+  return SECURITY_REQUIREMENT_TERMS.some((t) => text.includes(t));
+}
+
+/**
+ * task_class (B.8): trivial = single-file/mechanical, architectural =
+ * contracts/schemas/cross-cutting, normal = everything else.
+ */
+export function classifyTask({ estimate = {}, domains = [], objective = '' } = {}) {
+  const files = Number(estimate.files ?? 0);
+  const text = String(objective).toLowerCase();
+  const architectural = domains.some((d) =>
+    ['architecture', 'database', 'data-pipeline', 'integration', 'security'].includes(d),
+  ) || /schema|migration|contract|interface|architecture|refactor|cross-cutting/.test(text);
+  if (architectural) return 'architectural';
+  if (files <= 1 && domains.length <= 1) return 'trivial';
+  return 'normal';
+}
+
+export default { computeComplexity, normalizeFeature, bandFor, WEIGHTS, BANDS, classifyTask };