harness-everything 0.28.0 → 0.30.0

package/docs/system-one-suggestion-gates.md

@@ -0,0 +1,292 @@
+# System One suggestion gates
+
+Status: **proposed, pending owner review**. Once the owner approves it, this
+document is frozen for the next candidate of each stage. Decided in the
+[#233 design correction](https://github.com/dyphn1/Harness-everything/issues/233#issuecomment-5842359628)
+(one event, matched against every option); research evidence is in
+[#255](https://github.com/dyphn1/Harness-everything/issues/255).
+
+This document supersedes the table in
+[system-one-intent-gates.md](system-one-intent-gates.md). That table stays
+as the historical contract for the runs made under it. It also supersedes
+the model-quality part of
+[system-one-routing.md#rollout-gates](system-one-routing.md#rollout-gates).
+`evaluate.relevanceGates` still implements the superseded table. The code
+change follows this document (docs → RED → GREEN) in its own commit.
+
+## Principle
+
+1. **One event, scored against every option.** For a prompt, the scorer
+   returns an independent relevance `p_i ∈ [0, 1]` for every option of the
+   stage catalog. Scores do not sum to 1 and are never renormalized into a
+   simplex. With CUA-S1 this is the per-option logit passed through a
+   sigmoid. Upstream `tinyx` already encodes each option separately and
+   scores it against the context, so one forward pass scores every option.
+2. **Suggestions, not verdicts.** Output is advice to the agent. A wrong
+   suggestion costs little; a confident wrong suggestion, or a long list the
+   agent must read, costs trust and tokens. Gates therefore measure
+   *trustworthy confidence* and *suggestion coverage under a noise cap*,
+   not exact accuracy.
+3. **Deterministic controls stay outside learned scoring.** Tier structural
+   floor, explicit workflow requests, action/security approval, scope and
+   memory ownership and the Rule of 3 are unchanged. Abstention always falls
+   back to the lexical path.
+
+## Readout per stage
+
+All stages share the scoring and the calibration. Only the readout differs.
+
+| Stage | Catalog | Readout | Cap |
+| --- | --- | --- | --- |
+| Validity | `actionable`, `invalid` | `invalid` at or above its threshold → stop: no tier, workflow, intent or skill suggestion; the host agent decides | — |
+| Intent | the 12 intents of [system-one-intent.md](system-one-intent.md) | set: every intent at or above its threshold, highest `p` first, truncated at the cap | 3 |
+| Tier | `tier1`, `tier2`, `tier3` | composed (see [Tier composition](#tier-composition)): tier3 when `feature` or `refactor` reaches its intent threshold; otherwise the tier scorer's pick; final tier = max(that, structural floor); none → abstain | 1 |
+| Workflow | the router's strategies (`direct-single`, `iterative-single`, `fable-staged`, `fable-parallel`, `fable-multi-agent-workspace`) | pick one, same rule; an explicit workflow request always wins | 1 |
+| Skills | canonical skills, scored against their descriptions | set, same rule | 3 |
+
+The cap of 3 for set stages comes from AGENTS.md rule 10: a suggested skill
+must be read before it can be dismissed, so each extra suggestion has a
+reading cost. The cap is part of the readout, so noise is bounded by
+construction; the gates then judge what survives the cap.
+
+Stages run in table order: validity, intent, tier, workflow, skills. Tier
+reads the intent scores, so intent runs before it.
+
+### Tier composition
+
+Tier rules v2 (owner decision, 2026-09-26): tier3 covers new features,
+refactors, changes to definitions, and cross-repository or cross-component
+work, whatever the width of the change; tier1 is a clear bounded action
+(Git, status, lookup, direct answer); tier2 is a bounded modification.
+
+Whether a prompt asks for a feature or a refactor is an intent question,
+and the intent stage already scores it. The tier stage therefore does not
+learn that part again:
+
+1. **Intent part.** tier3 when the calibrated score of `feature` or
+   `refactor` is at or above that intent's threshold (either one fires; not
+   "is the top intent", which a small intent scorer rarely satisfies).
+2. **Scope part.** The deterministic structural floor (cross-repository,
+   cross-component, macro scope) sets tier3 as before.
+3. **Tier scorer.** Otherwise the tier scorer picks, trained on the
+   breadth-based labels, so it separates tier1 from tier2 and keeps the
+   breadth-based tier3.
+
+Over-reading `feature`/`refactor` moves a prompt one tier up, which the
+gates count as acceptable; missing it moves it down, which they count as
+under-tier. The composition is therefore tuned for intent recall on those
+two intents.
+
+Evidence (#265, validation, five seeds): composed with the CUA-S1 intent
+scorer, acceptable precision 0.82 and under-tier 0.13, against 0.77 and
+0.22 for a tier scorer trained directly on rules-v2 labels.
+
+**Holdout.** The owner decided not to re-review the tier holdout under
+rules v2. Its gold follows the older rules, and rules v2 only moves labels
+up (tier1 or tier2 to tier3). So underRate on the old gold stays valid, and
+a tier3 pick for tier2 gold counts as acceptable. A tier3 pick for a
+tier1-gold feature prompt counts as an error, which makes
+acceptablePrecision slightly pessimistic; the count of such cases is
+reported beside it.
+
+`unclassified`/`null` is not an option in the new readout. It is the
+abstain outcome: no option reaches its threshold.
+
+**The scorer only sees the current prompt.** It never receives earlier
+turns. A prompt whose text alone carries no actionable request is
+`invalid`: System One makes no suggestion, and the host agent, which has
+the conversation, decides. Validity runs first; the later stages run only
+on `actionable` prompts.
+
+## Calibration and thresholds
+
+- **Calibration.** A monotone per-option map (isotonic or Platt, chosen and
+  recorded before fitting) from raw `p` to calibrated `p`, fitted on
+  validation only. Needed because a model trained on soft teacher scores
+  outputs a *relevance degree* (0.5 = "secondary relevance"), not a
+  probability of being relevant. Gates read calibrated `p`.
+- **Suggest threshold `τ_i`.** One per option, fitted on validation
+  (max-F1 against the validation truth), 2-fold CV reported.
+- **Confident band.** Calibrated `p ≥ 0.8`. A confident suggestion is a
+  claim that at least 8 in 10 such suggestions are relevant.
+- Calibration maps, thresholds, cap, band and this document are frozen
+  before a holdout run. Nothing is refit after it.
+
+## Truth
+
+| Split | Relevant set | Primary |
+| --- | --- | --- |
+| Train / validation | teacher score ≥ 0.4, after owner intent overrides and exclusions | teacher primary |
+| Intent holdout | owner `gold ∪ secondary` | owner `gold` |
+| Tier holdout | owner `gold` tier; `null` means abstention is correct | — |
+
+### Invalid prompts
+
+Some prompts cannot be judged from their text: a go-ahead (`go`, `好`,
+`完成了`), an option pick, a change verb with no object (`修正一下`),
+feedback on earlier work (`還是一樣的錯誤`), a pointer to earlier content
+(`請依照需求實作`), a paste with no request, or chatter. The small model
+does not try to recover the missing context. It marks them `invalid` and
+hands them to the host agent (the external LLM), which sees the whole
+conversation. Deterministic controls (action gates, scope and memory
+ownership, the Rule of 3) apply unchanged. The noise-gate experiment (#265)
+showed that tier labels given to such prompts from session context were
+what kept a text-only model unsure.
+
+- **Definition.** A holdout case is invalid when the frozen rules
+  (`rule_v2` in `scripts/system-one-noise-experiment.py`, #265) match its
+  text or its owner gold is `null`. The owner reviews that list before the
+  holdout run; the list is then frozen with the rest of step 4 below.
+- **Scoring.** On an invalid case, the model is correct when it returns
+  `invalid` (or abstains); any tier, intent or skill suggestion is an error
+  for that case. Invalid cases are excluded from the later stages' metrics
+  and reported as invalid recall. On actionable cases, returning `invalid`
+  is reported as invalid false-positive rate.
+- **Size.** The rules mark 9 of 215 tier-holdout cases (6 `null`, 2 `tier1`,
+  1 `tier2`) and 3 of 222 intent-holdout cases; the tier holdout has 20
+  `null` cases in all. The holdouts were built with most continuations
+  removed, so the validity gate is read on validation until a reviewed
+  invalid set exists.
+
+## Metrics
+
+Set stages (intent, skills), over actionable prompts:
+
+| Metric | Definition |
+| --- | --- |
+| suggestionCoverage | share of prompts with at least one suggestion |
+| confidentCoverage | share of prompts with at least one confident suggestion |
+| primaryHit | share of prompts whose primary is among the suggestions |
+| suggestionPrecision | relevant suggestions / all suggestions |
+| confidentPrecision | relevant confident suggestions / all confident suggestions |
+| ECE | expected calibration error over all (prompt, option) pairs, 10 equal-width bins of calibrated `p` against set membership |
+| Brier | mean squared error of calibrated `p` against set membership |
+| per-option precision / recall / support | support = holdout prompts where the option is relevant |
+| cardinality | mean and p95 suggestions per prompt, share of prompts at the cap |
+| recall | relevant suggestions / relevant options (reported) |
+
+ECE alone rewards a timid model that never says anything confident; it is
+gated together with confidentCoverage, never alone.
+
+Pick stages (tier, workflow):
+
+| Metric | Definition |
+| --- | --- |
+| coverage | share of actionable prompts that get a pick |
+| acceptablePrecision | picks equal to gold or one tier above it, among picks |
+| underRate | picks below gold, among picks |
+| exactPrecision | picks equal to gold, among picks (reported) |
+| ECE / Brier | as for set stages, one-vs-rest per option |
+
+One tier above gold is acceptable because over-routing adds process;
+under-routing skips obligations, so it has its own hard gate.
+
+Every stage also reports family consistency (same family, same top
+option), repeatability, latency, artifact size and policy evidence.
+
+## Gates
+
+### Intent (holdout)
+
+Anchors are validation-proxy measurements, not holdout results: the
+fine-tuned Laya reference, capped at 3 with in-sample thresholds, reaches
+coverage 0.97, primary hit 0.75, precision 0.63, raw-`p ≥ 0.6` precision
+0.85 and ECE 0.06. Holdout truth is stricter, so bars sit below it.
+
+| Gate | Bar |
+| --- | --- |
+| suggestionCoverage | ≥ 0.90 |
+| primaryHit | ≥ 0.65 |
+| suggestionPrecision | ≥ 0.60 |
+| confidentCoverage | ≥ 0.40 |
+| confidentPrecision | ≥ 0.75 (the 0.8 claim minus about two standard errors at about 250 confident suggestions) |
+| ECE | ≤ 0.10 |
+| per-intent precision, support ≥ 20 | ≥ 0.40 |
+| family consistency (top suggestion) | ≥ 0.70 (owner gold 0.80) |
+
+### Tier (holdout)
+
+| Gate | Bar |
+| --- | --- |
+| acceptablePrecision | ≥ 0.85 (the owner's advisory bar, now counting one tier above gold) |
+| underRate | ≤ 0.05 |
+| coverage | ≥ 0.60 |
+| ECE | ≤ 0.10 |
+| invalid recall (invalid cases) | reported; ≥ 0.80 on validation invalid rows |
+| invalid false-positive rate (actionable cases) | ≤ 0.05 |
+
+Tier bars have no validation anchor from a relevance-native tier model
+yet. The first tier candidate reports its validation numbers first, and
+these bars are confirmed or amended in this document **before** its
+holdout run, never after.
+
+### Workflow and skills
+
+No reviewed holdout exists for these stages, so they cannot be promoted.
+Before any gate applies, each needs:
+
+- a fixed catalog document (skills: option text written for scoring; the
+  current 96-byte option limit truncates skill descriptions, so the
+  checkpoint's `option_tokens` must be sized for them);
+- an owner-reviewed, family-disjoint holdout of at least 200 cases, at
+  least 50 each in English and Traditional Chinese;
+- the paired lexical baseline on that holdout.
+
+Their gates take the shape of tier (workflow) and intent (skills). A
+learned stage must also be no worse than the lexical baseline on
+primaryHit/suggestionPrecision (skills) or acceptablePrecision (workflow)
+in the same paired run.
+
+### Every stage
+
+| Gate | Bar |
+| --- | --- |
+| repeatability | identical scores and suggestions across two runs |
+| warm p95 | ≤ 250 ms, with the host record ([latency note](system-one-intent-gates.md#latency-note)) |
+| deployable artifact | CPU only, checkpoint ≤ 10 MB, installed by `npm run system-one:install` with pinned hashes |
+| structural controls | unchanged, rollback path live |
+| policyEvidence / liveHostEvidence | reported; required before the default changes from `shadow` |
+
+The artifact gate encodes the #255 decision: Laya is a teacher and a
+ceiling reference, never a production candidate.
+
+## Evaluation order
+
+1. Train on train rows only.
+2. Fit calibration and thresholds on validation (2-fold CV reported).
+3. **Qualify on validation.** Report every metric above against the
+   validation truth. A candidate may spend a holdout run only if it meets
+   the holdout bars on validation *and* passes the deployable-artifact
+   gate. Otherwise it stays a validation result.
+4. Freeze the checkpoint hash, calibration, thresholds, evaluator
+   revision and this document.
+5. Score the holdout once, with two runs for repeatability.
+6. A fail is final for that candidate. A new candidate restarts at step 1
+   with a recorded reason.
+
+## Holdout budget
+
+Every holdout run spends the holdout a little: each published result makes
+later choices less independent. Each run is recorded in the evidence
+directory with candidate hash, date and aggregate result.
+
+- Intent holdout, spent before this document: n-gram intent v1,
+  fine-tuned Laya (single-winner), fine-tuned Laya (relevance shadow).
+- Tier holdout, spent before this document: tinyx v1 and the n-gram
+  versions reported in #233, plus the lexical baseline.
+
+Under this document, each holdout allows **one** further candidate run.
+Before a second run, the owner adds at least 50 freshly reviewed cases (at
+least 20 per language) that no earlier candidate or threshold saw, and the
+gates are read on the enlarged holdout.
+
+Earlier holdout results are historical. They are never re-scored under
+these gates to claim a pass.
+
+## Non-goals
+
+- The single-winner path (`contract.decide`, n-gram provider, lexical
+  fallback) stays live as rollback until a stage is promoted.
+- The intent taxonomy and the owner-reviewed holdouts do not change here.
+- Private prompts never enter this repository; public evidence holds
+  aggregates, hashes and per-option metrics only.

package/docs/system-one-training.md

@@ -56,7 +56,7 @@ prompts written by an agent, not by the owner. VS Code terminal notifications
 - **Deduplication**: exact duplicates after whitespace normalization are dropped. The first
   occurrence is kept.
 - **Holdout leakage**: a prompt is dropped if its character-trigram Jaccard similarity to any
-  holdout prompt is at least 0.5. The same applies if either prompt contains the other after
+  prompt of the tier or intent holdout is at least 0.5. The same applies if either prompt contains the other after
   normalization and the shorter one is more than 12 characters long. This matters because
   the holdout includes rewrites of local prompt shapes.
 - **Family**: the source session. Prompts from one conversation never span splits.
@@ -65,10 +65,11 @@ prompts written by an agent, not by the owner. VS Code terminal notifications
 
 ## Privacy
 
-- Collected prompts and labels stay on the local machine under
-  `~/.agents/harness-everything/system-one/training/` and are **never committed**. The
-  repository holds only the scripts, aggregate statistics and the SHA-256 of each dataset
-  file.
+- Collected prompts and labels are **never committed to this public repository**. They
+  live under `~/.agents/harness-everything/system-one/training/` on the owner's machine.
+  A curated copy, for cloud sessions, is in the owner's private repository
+  `dyphn1/harness-system-one-data` (`training/` is the `--data-dir`). This repository holds
+  only the scripts, aggregate statistics and the SHA-256 of each dataset file.
 - Email addresses and user home paths are replaced with placeholders before storage. Names
   and product terms are not reliably detectable and remain.
 - The released weights come from a 4-way byte-level classifier with about 0.7M parameters. It
@@ -88,6 +89,31 @@ prompts written by an agent, not by the owner. VS Code terminal notifications
     labels already written. Every returned index must be labeled exactly once with
     `tier1`, `tier2`, `tier3` or `null`. A malformed batch is retried once and then
     recorded as failed. It is never partially accepted.
+  - `--model` and `--engine codex` choose another labeler; the label rows record it.
+    `--batch N` changes the batch size.
+  - `--task intent --scores` asks for [relevance scores](system-one-intent.md#relevance-scores).
+    Each reply names a primary and scores every intent from 0 to 1 in steps of 0.05. A
+    reply is malformed when it misses an intent, leaves the scale, ties two scores above 0,
+    has more than eight zeros, names a primary that is not the unique top score of at
+    least 0.6, or has a `null` primary with an intent above 0.2. The owner chose Haiku
+    for this labeling.
+  - `--scale` scales each non-`null` scored label so its top score is 1: every score is
+    divided by the top score. Haiku puts most top scores at 0.75 to 0.85, and the owner
+    chose to read them as relative (2026-09-24). The bands and the secondary intents are
+    derived from the scaled scores; the row keeps the model's scores as `raw`.
+  - `--escalate-model M` labels a prompt a second time with model `M` when the first
+    label lags:
+    - `--escalate-margin R`: the relative margin, (top − second) / top, is below `R`.
+      The owner chose this lagging indicator to keep Sonnet to few prompts. `R` = 0.3
+      sends about 11% of Haiku's non-`null` training labels to Sonnet; it was read from
+      that distribution, not from the holdout. A `null` label is never escalated.
+    - Otherwise `--escalate-below` (default 0.8): the top score is below it. On the
+      training prompts this sent 69% to Sonnet, and the owner stopped it for its cost.
+  - The second label replaces the first; when the second run fails, the first label
+    stays. The label rows record the model that produced them, and a resumed run skips
+    prompts that were already escalated. The holdout check reports how many prompts were
+    escalated. `rescale --in A --out B` rewrites a label file with scaled labels (last
+    row per prompt).
 - **Labeler check**: the labeler labels the 215 holdout prompts once, before any training
   data is labeled. The report gives agreement with the owner's gold and the per-class recall.
   - Labeling proceeds only when agreement is at least 80%.
@@ -104,7 +130,38 @@ prompts written by an agent, not by the owner. VS Code terminal notifications
 
 ## Training and calibration
 
-- **Model**: a new `cua_s1` `tinyx` scorer built with `make_system`.
+- **Tier engine**: `scripts/system-one-train-ngram.py` trains the `ngram` transport, a
+  multinomial logistic regression over hashed character n-gram features. Featurization
+  follows [system-one-routing.md](system-one-routing.md#n-gram-provider-phase-4).
+  - The trainer uses torch for the optimizer only. The features are stdlib Python and match
+    the Node provider exactly.
+  - The configuration (`nmax`, class weighting, weight decay) is chosen on validation
+    macro-F1. The first exploration picked `nmax` 3, square-root inverse-frequency class
+    weights and a weight decay of 1e-4.
+  - The output is the `.bin` weights, the `.json` sidecar and validation scores for
+    calibration.
+- **Intent engine**: the same trainer with `--task intent` trains the intent stage
+  ([system-one-intent.md](system-one-intent.md)).
+  - Labels come from `labels-intent.jsonl`, and owner corrections from
+    `owner-overrides-intent.jsonl`. `owner-excluded.jsonl` applies to both stages. The
+    catalog comes from the intent holdout.
+  - Targets are soft. The primary gets 1.0 when there is no secondary intent. Otherwise
+    the primary gets 0.6 and the secondary intents share 0.4 equally. `null` maps to
+    `unclassified` with 1.0.
+  - Validation scores keep each row's secondary intents for calibration.
+  - `--target scores` trains on the scored labels in `labels-intent-scores.jsonl`
+    instead. Each intent is its own binary target with its score as the soft value, and
+    the loss is a per-intent binary cross-entropy. `unclassified` scores 0.6 when the
+    primary is `null` and 0 otherwise. An owner override without scores counts as 0.6
+    for its primary and 0.4 for its secondary intents. The class weights come from the
+    score mass of each intent.
+  - The artifact format is unchanged. The provider still returns the softmax over the
+    same logits, which ranks the intents in relevance order, so the contract's
+    probability vector and the calibration below stay as they are. Handing the absolute
+    relevance bands to the skills stage is a separate contract change.
+- The `tinyx` path below is kept for comparison. Its first checkpoint learned little beyond
+  class priors.
+- **Model** (`tinyx`): a new `cua_s1` `tinyx` scorer built with `make_system`.
   - Config: `width` 128, `rank` 128, `layers` 2, `heads` 4, `context_tokens` 1024 and
     `option_tokens` 96.
   - Weights are initialized fresh, not from the forms checkpoint, whose domain and
@@ -116,7 +173,12 @@ prompts written by an agent, not by the owner. VS Code terminal notifications
   - The epoch with the lowest validation negative log-likelihood is kept.
   - The checkpoint metadata records the dataset hashes, the config and the validation metrics.
 - **Calibration**: `minConfidence` and `minMargin` are chosen on validation to maximize
-  coverage, subject to an accepted precision of at least 98%. The router currently uses the
+  coverage, subject to an accepted precision of at least 85% (the owner's advisory target).
+  For the intent stage (`--task intent`), accepted precision is the mean graded agreement
+  of accepted rows. A predicted secondary is any other intent whose probability reaches
+  `secondaryThreshold`. That threshold is chosen from 0.05 to 0.50 in steps of 0.05, to
+  maximize micro-F1 against the labeled secondary intents, and it is chosen before the
+  acceptance thresholds. The router currently uses the
   Phase 0 defaults (0.9 and 0.2). Carrying calibrated thresholds into the manifest is a
   separate contract change.
 

package/harness-everything/SKILL.md

@@ -4,7 +4,7 @@ description: "Route software/project work through Harness: classify tier/topolog
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.26.0
+  version: 0.30.0
 ---
 
 # Harness Everything

package/harness-everything/scripts/kernel-router.js

@@ -105,6 +105,15 @@ function persistWorkflow(contract, payload, prompt) {
   return { ...context, hooksRoot, retained: false, memoryCapability };
 }
 
+// Printed last so it is the nearest instruction when the turn ends (docs/system-one-observations.md#label-line).
+function printLabelContract() {
+  console.log('\n=> TURN LABEL LINE (MUST, EVERY TURN — short answers, lookups and trivial edits included):');
+  console.log('   - The last line of your final message MUST be one hidden label line with your own post-work judgement, not a copy of the router tier above:');
+  console.log('     <!-- harness-label {"v":1,"validity":"actionable|invalid","contextDependent":true|false,"tier":"tier1|tier2|tier3|null","intents":["up to 3 of explain,discuss,git,fix,edit,feature,refactor,review,test,docs,plan,investigate"],"workflow":"strategy id or null","skills":["skills used"]} -->');
+  console.log('   - tier1: answer, lookup, status or git operation with no code change; tier2: bounded change; tier3: new feature, refactor, redefinition or cross-component work. Use null only when validity is invalid.');
+  console.log('   - It is invisible in rendered Markdown and records local training data; it never gates routing.');
+}
+
 function run(raw) {
   const promptArg = process.argv.slice(2).join(' ');
   let payload = null;
@@ -162,6 +171,7 @@ function run(raw) {
   } else {
     console.log('   - Runtime state was not persisted; reminders may be less precise, but execution remains available.');
   }
+  printLabelContract();
   if (failure) console.error('[Workflow Reminder] routing state was not persisted: ' + failure.message);
   if (result && result.status !== 0) console.error('[Workflow Reminder] router returned status ' + result.status + '; contract observation is degraded, not blocking.');
 }

package/harness-everything/scripts/system-one/catalogs.js

@@ -0,0 +1,35 @@
+'use strict';
+// Fixed System One catalogs, one per stage (docs/system-one-routing.md#staged-classification).
+// Option order is the scorer's output order; changing it invalidates trained weights.
+const { TIER_OPTIONS } = require('./router');
+const INTENT_OPTIONS = Object.freeze([
+  { id: 'explain', text: 'Answer a question or explain how something works.' },
+  { id: 'discuss', text: 'Weigh options, give an opinion or settle a decision.' },
+  { id: 'git', text: 'Git or GitHub housekeeping: commit, push, branch, pull request.' },
+  { id: 'fix', text: 'Repair wrong behavior: a bug, crash, failing test or build.' },
+  { id: 'edit', text: 'Change an existing value, setting, text or behavior on request.' },
+  { id: 'feature', text: 'Add new behavior: a command, option, format or script.' },
+  { id: 'refactor', text: 'Restructure or unify existing code without new behavior.' },
+  { id: 'review', text: 'Evaluate an existing artifact against a standard.' },
+  { id: 'test', text: 'Run tests or builds, or write tests as the main deliverable.' },
+  { id: 'docs', text: 'Write or edit documentation as the main deliverable.' },
+  { id: 'plan', text: 'Produce a plan, specification or breakdown before implementation.' },
+  { id: 'investigate', text: 'Find facts or a cause and report back without changing anything.' },
+  { id: 'unclassified', text: 'Unclear intent, insufficient context or outside these categories.' },
+].map(Object.freeze));
+const CATALOGS = Object.freeze({ tier: TIER_OPTIONS, intent: INTENT_OPTIONS });
+// Gold labels of a stage: its catalog ids, with the abstaining option recorded as null.
+function goldLabels(task) {
+  if (!Object.hasOwn(CATALOGS, task)) throw new TypeError('unknown-task');
+  return CATALOGS[task].map(o => (o.id === 'unclassified' ? null : o.id));
+}
+// Stages whose labels carry secondary intents beside the primary choice (docs/system-one-intent.md).
+const MULTI = Object.freeze(['intent']);
+// Secondary labels: distinct catalog ids other than the primary; none when the primary abstains.
+function validSecondary(task, primary, secondary) {
+  if (!MULTI.includes(task)) return secondary === undefined;
+  const ids = goldLabels(task).filter(g => g !== null);
+  return Array.isArray(secondary) && new Set(secondary).size === secondary.length
+    && secondary.every(s => ids.includes(s) && s !== primary) && (primary !== null || secondary.length === 0);
+}
+module.exports = { INTENT_OPTIONS, CATALOGS, MULTI, goldLabels, validSecondary };

package/harness-everything/scripts/system-one/contract.js

@@ -42,4 +42,48 @@ function decide(req, res, policy = {}) {
   return { status: reason === 'scored' ? 'accepted' : 'abstain', reason,
     selectedId: reason === 'scored' ? ranked[0].id : null, confidence, margin, model: { ...res.model } };
 }
-module.exports = { createRequest, validateRequest, decide };
+// Relevance-native decisions (#233): every option except unclassified is an
+// independent Bernoulli against its own threshold. No simplex rule applies:
+// the raw probabilities must each stand in 0..1 but need not sum to one.
+function validThresholds(req, thresholds) {
+  const ids = req.options.map(o => o.id).filter(id => id !== 'unclassified');
+  if (!thresholds || typeof thresholds !== 'object' || Array.isArray(thresholds)) return false;
+  const keys = Object.keys(thresholds);
+  return keys.length === ids.length && ids.every(id => probability(thresholds[id]))
+    && keys.every(k => ids.includes(k));
+}
+function decideIntents(req, res, policy = {}) {
+  validateRequest(req);
+  if (!policy || typeof policy !== 'object' || Array.isArray(policy)
+    || Object.keys(policy).some(k => !['domain', 'thresholds'].includes(k))
+    || !validThresholds(req, policy.thresholds)) fail('invalid-policy');
+  const { domain = 'harness-routing-v1', thresholds } = policy;
+  if (!text(domain)) fail('invalid-policy');
+  const empty = { status: 'invalid-output', reason: 'invalid-response', selectedId: null,
+    confidence: null, margin: null, model: null, intents: null };
+  if (!exact(res, ['schemaVersion', 'requestHash', 'catalogHash', 'model', 'scores'])
+    || res.schemaVersion !== 1 || res.requestHash !== req.requestHash || res.catalogHash !== req.catalogHash
+    || !exact(res.model, ['id', 'revision', 'domain']) || !Object.values(res.model).every(v => text(v))
+    || !Array.isArray(res.scores) || res.scores.length !== req.options.length
+    || res.scores.some((s, i) => !exact(s, ['id', 'probability']) || s.id !== req.options[i].id || !probability(s.probability))) return empty;
+  const model = { ...res.model };
+  if (model.domain !== domain) {
+    return { status: 'abstain', reason: 'domain-mismatch', selectedId: null,
+      confidence: null, margin: null, model, intents: null };
+  }
+  const intents = {};
+  for (const s of res.scores) {
+    if (s.id === 'unclassified') continue;
+    intents[s.id] = { probability: s.probability, fired: s.probability >= thresholds[s.id] };
+  }
+  const fired = Object.entries(intents).filter(([, v]) => v.fired).sort((a, b) => b[1].probability - a[1].probability);
+  if (!fired.length) {
+    return { status: 'abstain', reason: 'no-intent-fired', selectedId: null,
+      confidence: null, margin: null, model, intents };
+  }
+  const rest = Object.values(intents).filter(v => v !== fired[0][1]).map(v => v.probability);
+  const confidence = fired[0][1].probability;
+  return { status: 'accepted', reason: 'scored', selectedId: fired[0][0], confidence,
+    margin: confidence - Math.max(...rest, 0), model, intents };
+}
+module.exports = { createRequest, validateRequest, decide, decideIntents };