@tekyzinc/gsd-t 5.1.13 → 5.2.11

package/bin/gsd-t-logging-scaffolder.cjs

@@ -21,6 +21,9 @@
 const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
+// M102 — the marker-block idempotent doc-writer was extracted here into the ONE
+// shared module both this scaffolder and bin/gsd-t-env-registry.cjs call.
+const { upsertMarkedDocBlock } = require("./gsd-t-doc-marker.cjs");
 
 const VALID_BACKENDS = ["db-table", "local-sqlite", "local-jsonl"];
 
@@ -182,24 +185,9 @@ function writeChoiceToProjectDocs(projectDir, envelope) {
   const targetPath = candidates.find((p) => fs.existsSync(p)) || candidates[0];
 
   const block = docBlock(envelope);
-  let content = "";
-  if (fs.existsSync(targetPath)) {
-    content = fs.readFileSync(targetPath, "utf8");
-  } else {
-    const dir = path.dirname(targetPath);
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  }
-
-  if (content.includes(DOC_MARKER_START) && content.includes(DOC_MARKER_END)) {
-    const startIdx = content.indexOf(DOC_MARKER_START);
-    const endIdx = content.indexOf(DOC_MARKER_END) + DOC_MARKER_END.length;
-    content = content.slice(0, startIdx) + block + content.slice(endIdx);
-  } else {
-    content = content.replace(/\s*$/, "") + "\n\n" + block + "\n";
-  }
-
-  fs.writeFileSync(targetPath, content, "utf8");
-  return targetPath;
+  // M102 — delegate to the ONE shared marker-block writer (byte-identical logic
+  // to the former inline replace/append; extracted so env-registry reuses it).
+  return upsertMarkedDocBlock(targetPath, DOC_MARKER_START, DOC_MARKER_END, block);
 }
 
 // ─── Seam envelope builder ──────────────────────────────────────────────────

package/bin/gsd-t-verify-gate.cjs

@@ -307,6 +307,8 @@ function _detectDefaultTrack2(projectDir, notes) {
 
   plan.push({ id: 'logging-envelope', cmd: 'node', args: [path.join(__dirname, 'gsd-t-logging-envelope-check.cjs'), '--project', projectDir], timeoutMs: 30000 }); // M100 D3: structural trace+audit envelope gate, FAIL-CLOSED
 
+  plan.push({ id: 'env-registry', cmd: 'node', args: [path.join(__dirname, 'gsd-t-env-registry-check.cjs'), '--project', projectDir], timeoutMs: 30000 }); // M102 D3: no-secret-in-registry + rule-without-table gate, FAIL-CLOSED
+
   // secrets — gitleaks (PATH detection deferred to runtime)
   if (_hasOnPath('gitleaks')) {
     plan.push({

package/bin/gsd-t.js

@@ -2999,6 +2999,16 @@ const PROJECT_BIN_TOOLS = [
   // ship to every project or the consumers can't classify. Same propagation class as
   // gsd-t-graph-store-resolver.cjs above. [[project_global_bin_propagation_gap]]
   "gsd-t-graph-availability.cjs",
+  // M102 — Environment Registry. The shared marker-block doc-writer + the
+  // registry helper (record/lookup/detect/add-permission/ensure-gitignore).
+  // Sandboxed workflows (init/populate + provisioning execute/quick tasks) call
+  // the registry via project-local Bash, and the registry `require`s the shared
+  // writer at load — BOTH must ship or the registry throws / the writer is a
+  // second copy. Same propagation class as the graph tools above.
+  // [[project_global_bin_propagation_gap]]
+  // Plus the verify-gate lint (gsd-t-verify-gate.cjs invokes it via __dirname,
+  // so it must sit alongside the gate in the project's bin/).
+  "gsd-t-doc-marker.cjs", "gsd-t-env-registry.cjs", "gsd-t-env-registry-check.cjs",
 ];
 
 // Files that older versions of this installer copied into project bin/ but

package/commands/gsd-t-init.md

@@ -296,6 +296,12 @@ docs/
 
 These are the living documents that persist across milestones and keep institutional knowledge alive. The `infrastructure.md` is especially important — it captures the exact commands for provisioning cloud resources, setting up databases, managing secrets, and deploying, so this knowledge doesn't get lost between sessions.
 
+The `infrastructure.md` template ships with a marker-delimited `## Environments` table (`<!-- gsd-t-env-registry:start -->` / `:end`) — the committed, **secret-free** connection registry (M102). It is created empty by init and populated by the two triggers:
+- **Greenfield (record-at-create):** whenever this project later BUILDS/PROVISIONS/CONFIGURES an environment (a local test DB, a remote server, credentials, or hands the user setup instructions), record the map row in the SAME pass:
+  `node bin/gsd-t-env-registry.cjs record '{"projectDir":".","scope":"local","kind":"postgres","host":"localhost","port":"5432","name":"appdb","authMethod":"password","secretVault":"local (.env)","secretEnvVarName":"DATABASE_URL","fetchCommand":"read $DATABASE_URL from .env","connectCommand":"psql \"$DATABASE_URL\""}'`
+  Records only the MAP + vault pointer + env-var NAME + fetch/connect commands — **never a secret VALUE** (a literal password/token in a command is REJECTED). `scope=prod` defaults `read-only=YES`.
+- Also run `node bin/gsd-t-env-registry.cjs ensure-gitignore .` so `.env` is gitignored (auto-add + report; secret-leak precheck).
+
 ## Step 8: Ensure README.md Exists
 
 If no `README.md` exists, create one with:

package/commands/gsd-t-populate.md

@@ -29,6 +29,13 @@ Scan this codebase and populate the GSD-T documentation. Analyze the actual code
 - List Credentials and Secrets from .env.example (local) and any secret manager configs
 - Document Deployment from CI/CD configs, Dockerfiles, cloud configs
 - Document Logging and Monitoring from any logging setup or dashboard configs
+- **Back-fill the `## Environments` registry (M102 — brownfield capture).** For an existing project whose non-local environments are undocumented, back-fill the map-only Environments table WITHOUT ever reading or writing a secret VALUE:
+  1. `node bin/gsd-t-env-registry.cjs detect .` → proposes the vault + fetch command from `.env.example` var NAMES, connection-string SHAPES, and `vercel.json`/`.vercel` (Vercel) · `cloudbuild.yaml`/`.gcloudignore` (Google Secret Manager) · neon dep (Neon) · plain `.env` (local). Map only — never a value.
+  2. Confirm/fill gaps with the human, then `node bin/gsd-t-env-registry.cjs record '<json>'` per environment (upsert by `(scope, kind)` — a re-provision replaces the stale row).
+  3. `node bin/gsd-t-env-registry.cjs ensure-gitignore .` — auto-add `.env` to `.gitignore` if missing + report.
+  - **No-Fallback-Ever:** a genuinely undocumented environment reached for the first time HALTs → detect → ask → record → `add-permission` → proceed. NEVER guess a connection string, NEVER grep transcripts to rediscover.
+  - **Leak remediation (secret found in a URL/command):** before recording, run `node bin/gsd-t-env-registry.cjs propose-remediation . '<command>'`. If it reports `needed:true`, STOP and tell the user *what* leaked (`detectedSecret`), then ASK **rotate or move** (`choices.rotate` / `choices.move`) — each time, do not assume. On their answer: store the (rotated or existing) secret into the detected `vault` (directly where possible — e.g. `vercel env add`, write to `.env`; else instruct the user to create/rotate it), then record the row with the `rewrittenCommand` ($VAR form). NEVER commit the literal secret.
+  - **Local-literal switch (per project):** by default every row uses `$VAR` (strict). A project may opt in via `.gsd-t/env-registry-config.json` → `{"allowLocalLiteral": true}` to allow a LITERAL secret in `scope=local` rows only (testing convenience). `staging`/`prod` are ALWAYS strict. A relaxed local write returns a one-time "committed file → git history" warning — surface it.
 
 ## Graph Structural Slice — who-imports + cluster (M94-D10)
 

package/commands/gsd-t-quick.md

@@ -25,8 +25,8 @@ Spawn path is `autoSpawnHeadless({command, spawnType, projectDir, sessionContext
 
 Per `.gsd-t/contracts/model-selection-contract.md` v1.0.0.
 
-- **Default**: `sonnet` (`selectModel({phase: "quick"})`) — routine one-off task.
-- **Mechanical subroutines** (demote to `haiku`): test runners (`selectModel({phase: "quick", task_type: "test_runner"})`).
+- **Default**: `sonnet` (per `bin/gsd-t-model-tier-policy.cjs`, phase `quick`) — routine one-off task.
+- **Mechanical subroutines** (demote to `haiku`): test runners.
 - **Red Team (Step 5.5)**: `opus` — adversarial reasoning always runs at top tier.
 - **Escalation**: `/advisor` convention-based fallback from `bin/advisor-integration.js` at declared high-stakes sub-decisions (see `.gsd-t/M35-advisor-findings.md`). Never silently downgrade the model or skip Red Team / doc-ripple under context pressure — M35 removed that behavior.
 

package/commands/gsd-t-test-sync.md

@@ -6,7 +6,7 @@ You are maintaining test coverage as code changes. Your job is to identify stale
 
 Per `.gsd-t/contracts/model-selection-contract.md` v1.0.0.
 
-- **Default**: `sonnet` (`selectModel({phase: "test-sync"})`) — test alignment is routine refactoring work.
+- **Default**: `sonnet` (per `bin/gsd-t-model-tier-policy.cjs`, phase `test-sync`) — test alignment is routine refactoring work.
 - **Escalation**: `/advisor` convention-based fallback from `bin/advisor-integration.js` when a test touches a contract boundary or requires judgment about what "missing coverage" means. Never silently skip test-sync under context pressure — M35 removed that behavior.
 
 This command is:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.1.13",
+  "version": "5.2.11",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/CLAUDE-global.md

@@ -96,9 +96,22 @@ NEED TO UNDERSTAND SOMETHING?
   ├── Is it about what to build? → Read docs/requirements.md
   ├── Is it about how to deploy/operate? → Read docs/infrastructure.md
   ├── Is it about domain interfaces? → Read .gsd-t/contracts/
+  ├── Is it about reaching a non-local environment (DB/server URL, creds, perms)? → Read the `## Environments` registry in docs/infrastructure.md
   └── Not documented? → Research, then DOCUMENT IT
 ```
 
+## Environment Access — read-first, HALT-and-document (M102)
+
+**Before reaching ANY non-local environment (a staging/prod DB, a remote server, an external service), READ the `## Environments` registry in `docs/infrastructure.md` FIRST.** It is the committed, **secret-free** map of every environment — host, port, db, auth method, which vault holds the secret, the env-var NAME, and the connect command (secrets referenced as `$VAR`, never as a literal value).
+
+- **On a HIT** — use the recorded connect command; the secret is pulled from its vault at runtime via the env-var NAME.
+- **On a MISS (no row) — HALT and document. NEVER guess a connection string, NEVER grep transcripts to rediscover it** (No-Fallback-Ever). Then: `detect` the env → ask the human to confirm/fill → `record` the map row → `add-permission` (broad-glob) → proceed. The registry self-heals staleness because a re-provision upserts by `(scope, kind)`.
+- **Record-at-create (greenfield):** whenever GSD-T BUILDS/PROVISIONS an environment, record its map row in the SAME pass (it has the URL + creds right then).
+- **Never write a secret VALUE into the registry** — only the vault name + env-var NAME + a `$VAR`-referencing command. A literal secret is rejected by `recordEnvironment` and by the `gsd-t-verify` env-registry gate. If a secret is found in a URL/command, the capture flow OFFERS to move it into the vault (rotate-or-move, user's choice) and replace it with a `$VAR`.
+- **Local-literal switch:** a project may opt in via `.gsd-t/env-registry-config.json` `{"allowLocalLiteral": true}` to allow a literal secret in `scope=local` rows only; `staging`/`prod` stay strict.
+
+Details: `.gsd-t/contracts/env-registry-contract.md`.
+
 
 
 # Versioning

package/templates/CLAUDE-project.md

@@ -23,7 +23,7 @@ Contract-driven development methodology for Claude Code. npm package providing s
 
 ```
 bin/                     — CLI entry (gsd-t.js) + orchestrators (orchestrator.js, design-orchestrator.js)
-                           + support modules (gsd-t-context-brief.cjs, cli-preflight.cjs, gsd-t-verify-gate.cjs, model-selector.js, …)
+                           + support modules (gsd-t-context-brief.cjs, cli-preflight.cjs, gsd-t-verify-gate.cjs, gsd-t-model-tier-policy.cjs, …)
 commands/                — slash commands for Claude Code (GSD-T workflow + utility)
 templates/               — document + prompt + stack templates
   CLAUDE-{global,project}.md, requirements.md, architecture.md, workflows.md,

package/templates/infrastructure.md

@@ -68,6 +68,46 @@ cp .env.example .env
 {command}
 ```
 
+<!-- gsd-t-env-registry:start -->
+## Environments
+
+> **Map, not secrets.** This table records only WHERE an environment lives and
+> HOW to reach it — host/port/name/auth-method/which-vault-holds-the-secret/the
+> env-var NAME/the fetch + connect commands. It NEVER stores a secret VALUE.
+> The value lives in the vault (`.env` / Vercel / Neon / Google Secret Manager)
+> and is pulled at runtime via the env-var NAME. A missing row → HALT and
+> document (detect → ask → record → proceed); never guess a connection string,
+> never grep transcripts to rediscover.
+
+| id | scope | kind | host | port | db/name | auth method | secret vault | secret env-var NAME | fetch command | connect command | access gotchas | read-only default | recorded |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+<!-- gsd-t-env-registry:end -->
+
+<!--
+  Column notes:
+    scope             = local | staging | prod
+    kind              = postgres | mysql | redis | http-api | ssh-host | ...
+    secret vault      = local (.env) | Vercel | Neon | Google Secret Manager | ...
+    secret env-var NAME = e.g. DATABASE_URL_PROD  — the NAME only, NEVER the value
+    host              = POSITIVE shape: localhost | IPv4 | dotted DNS hostname |
+                        short lowercase service name (letters+hyphen, no digits, e.g. db, postgres)
+    db/name           = short lowercase snake identifier (<=16, e.g. binvoice_prod, analytics)
+    auth method       = ENUMERATED — password | iam | oauth | oauth2 | service-account |
+                        ssh-key | api-key | none | scram-sha-256 | md5 | trust | token | key | ...
+    fetch command     = how to pull the secret from its vault (e.g. `vercel env pull`)
+                        POSITIVE allowlist: a token is accepted ONLY if it IS a $VAR/${VAR} ref,
+                        a flag, a hostname/IP, a .env dotfile, or a curated CLI/db word.
+                        Any OTHER bare literal is REJECTED (move it to an env var, reference as $VAR).
+    connect command   = references the env-var by name: `psql "$DATABASE_URL_PROD"` (same allowlist)
+    access gotchas    = ENUMERATED — vpn | ip-allowlist | ssh-tunnel | bastion | none,
+                        optionally `via <hostname>` (e.g. `ssh-tunnel via bastion.example.com`).
+                        Free prose is FORBIDDEN (nowhere for a secret to hide).
+    read-only default = YES for scope=prod unless a human explicitly recorded write-ok
+  There is deliberately NO secret-value column — a row is structurally incapable
+  of holding a secret. Populated by `gsd-t-env-registry` (record-at-create +
+  capture-on-first-need).
+-->
+
 ## Credentials & Secrets
 
 ### Local (.env)

package/bin/model-selector.js

@@ -1,234 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * GSD-T Model Selector — surgical per-phase model tier assignment
- *
- * Replaces the v2.x "silent downgrade under context pressure" behavior with
- * declarative per-phase tier assignments. Callers ask `selectModel({phase, ...})`
- * and get back `{model, reason, escalation_hook}` — the tier decision is
- * deterministic, driven by the rules table below, and does NOT depend on
- * session context percentage.
- *
- * Contract: .gsd-t/contracts/model-selection-contract.md v1.0.0 (M35 T4)
- * Findings: .gsd-t/M35-advisor-findings.md (convention-based /advisor fallback)
- *
- * Zero external dependencies.
- */
-
-// ── Tiers ───────────────────────────────────────────────────────────────────
-// M85: FABLE tier added alongside HAIKU/SONNET/OPUS.
-// Contract: .gsd-t/contracts/model-tier-policy-contract.md v1.0.0 § "Stage Policy"
-
-const TIERS = Object.freeze({
-  HAIKU: "haiku",
-  SONNET: "sonnet",
-  OPUS: "opus",
-  FABLE: "fable",
-});
-
-const DEFAULT_TIER = TIERS.SONNET;
-
-// ── Escalation hook block (convention-based /advisor fallback) ──────────────
-//
-// Per `.gsd-t/M35-advisor-findings.md`, Claude Code's native /advisor has no
-// programmable API at subagent scope. This block is injected into the subagent
-// prompt at declared escalation points on sonnet-tier phases where the
-// orchestrator has flagged a high-stakes sub-decision.
-//
-// Kept as a constant so all consumers (command files, advisor-integration.js,
-// M35-advisor-findings.md) reference the same canonical text.
-
-const ESCALATION_HOOK = [
-  "## Escalation Hook — /advisor convention-based fallback",
-  "",
-  "Before finalizing your answer for this phase, stop and consider:",
-  "1. Is this decision high-stakes? (architecture, contract design, security boundary,",
-  "   data-loss risk, cross-module refactor, adversarial QA verdict)",
-  "2. Would a more capable model produce a materially better answer?",
-  "3. Are you confident in the assumptions you're making?",
-  "",
-  "If YES to any of the above, do ONE of the following:",
-  "- Escalate internally: spend an extra reasoning pass re-examining the decision",
-  "  from first principles. Document the re-examination in your output.",
-  "- Spawn a nested opus subagent: use the Task tool with",
-  "  `subagent_type: \"general-purpose\"` and include `model: opus` in the spawn.",
-  "",
-  "Record in your output whether you escalated: set `ESCALATED_VIA_ADVISOR=true` or",
-  "`ESCALATED_VIA_ADVISOR=false` on a line by itself near the end of your report.",
-].join("\n");
-
-// ── Declarative phase rules table ───────────────────────────────────────────
-//
-// Each rule maps (phase, task_type) → tier. The first matching rule wins.
-// `task_type` is optional — when absent, the rule matches any task within
-// that phase. Order the rules from most-specific to least-specific.
-//
-// Tier assignments mirror `.gsd-t/M35-definition.md` Part B and the Model
-// Assignments section of the GSD-T global CLAUDE template:
-//   - haiku:  strictly mechanical — test runners, branch guards, file checks,
-//             JSON validation, no judgment
-//   - sonnet: routine code work — execute step 2, test-sync, doc-ripple wiring,
-//             quick fixes, integration wiring, debug fix-apply
-//   - opus:   high-stakes reasoning — partition, discuss, Red Team, verify
-//             judgment, debug root-cause, contract/architecture design
-
-const PHASE_RULES = Object.freeze([
-  // Phase: execute
-  { phase: "execute", task_type: "test_runner",    model: TIERS.HAIKU,  reason: "Mechanical test-suite runner — zero judgment" },
-  { phase: "execute", task_type: "branch_guard",   model: TIERS.HAIKU,  reason: "Mechanical branch-name check — zero judgment" },
-  { phase: "execute", task_type: "file_check",     model: TIERS.HAIKU,  reason: "Mechanical file-existence check — zero judgment" },
-  { phase: "execute", task_type: "qa",             model: TIERS.SONNET, reason: "QA evaluation needs judgment per M31 tier refinement" },
-  { phase: "execute", task_type: "red_team",       model: TIERS.OPUS,   reason: "Adversarial QA benefits most from top tier" },
-  { phase: "execute",                              model: TIERS.SONNET, reason: "Routine task execution — sonnet is the M35 default for routine work", hasEscalation: true },
-
-  // Phase: wave (the wave orchestrator itself)
-  { phase: "wave",                                 model: TIERS.SONNET, reason: "Wave orchestration dispatches per-phase subagents; the orchestrator itself is routine coordination", hasEscalation: true },
-
-  // Phase: quick
-  { phase: "quick", task_type: "test_runner",      model: TIERS.HAIKU,  reason: "Mechanical test-suite runner — zero judgment" },
-  { phase: "quick",                                model: TIERS.SONNET, reason: "Routine one-off task — sonnet default" },
-
-  // Phase: integrate
-  { phase: "integrate", task_type: "test_runner",  model: TIERS.HAIKU,  reason: "Mechanical integration test runner — zero judgment" },
-  { phase: "integrate",                            model: TIERS.SONNET, reason: "Integration wiring is routine coordination work" },
-
-  // Phase: debug
-  { phase: "debug", task_type: "fix_apply",           model: TIERS.SONNET, reason: "Applying a known fix is routine code work" },
-  { phase: "debug", task_type: "root_cause",          model: TIERS.OPUS,   reason: "Root-cause analysis is high-stakes reasoning" },
-  // M85: cycle-2 escalation — when debug cycle-1 (opus) has not resolved the issue,
-  // cycle-2 escalates to Fable. The debug DEFAULT (cycle-1/general) remains opus —
-  // no existing rule is altered (AC f, no silent degradation). This is a DOCUMENTED
-  // MIRROR for Task-based/bin/ callers; the live enforcement is in the debug workflow
-  // ternary (D3-T3); the D4 lint guards that ternary.
-  // API shape: selectModel({ phase: "debug", task_type: "cycle_2_escalation" }) → fable
-  { phase: "debug", task_type: "cycle_2_escalation",  model: TIERS.FABLE,  reason: "Cycle-2 debug escalation — Fable after opus cycle-1 has not resolved; no existing rule altered (AC f)" },
-  { phase: "debug",                                   model: TIERS.OPUS,   reason: "Debug default is high-stakes — prefer opus unless the task_type says otherwise" },
-
-  // Phase: partition — high-stakes architectural decomposition
-  { phase: "partition",                            model: TIERS.OPUS,   reason: "Domain partitioning is architectural reasoning — high stakes" },
-
-  // Phase: discuss — multi-perspective design exploration
-  { phase: "discuss",                              model: TIERS.OPUS,   reason: "Design exploration benefits from top-tier reasoning" },
-
-  // Phase: plan — task-list authoring
-  { phase: "plan",                                 model: TIERS.SONNET, reason: "Task decomposition is structured work — sonnet with escalation hook", hasEscalation: true },
-
-  // Phase: verify — final quality judgment before milestone complete
-  { phase: "verify",                               model: TIERS.OPUS,   reason: "Milestone verification is the final quality gate — high stakes" },
-
-  // Phase: test-sync — keeping tests aligned with code
-  { phase: "test-sync",                            model: TIERS.SONNET, reason: "Test alignment is routine refactoring work" },
-
-  // Phase: doc-ripple — downstream document updates
-  { phase: "doc-ripple",                           model: TIERS.SONNET, reason: "Documentation updates are routine prose editing" },
-
-  // Phase: red_team — explicit adversarial QA phase (separate from execute task_type)
-  { phase: "red_team",                             model: TIERS.OPUS,   reason: "Adversarial QA — always opus, the incentive is to find bugs" },
-
-  // Phase: qa — explicit standalone QA phase
-  { phase: "qa",                                   model: TIERS.SONNET, reason: "QA per M31 refinement — sonnet produces fewer false negatives than haiku" },
-]);
-
-// Complexity-signal overrides. If the caller provides `complexity_signals`,
-// these can bump a sonnet decision to opus regardless of phase rule.
-const COMPLEXITY_OVERRIDES = Object.freeze({
-  cross_module_refactor: TIERS.OPUS,
-  security_boundary:     TIERS.OPUS,
-  data_loss_risk:        TIERS.OPUS,
-  contract_design:       TIERS.OPUS,
-});
-
-// ── Public API ──────────────────────────────────────────────────────────────
-
-/**
- * Select the model tier for a subagent spawn.
- *
- * @param {object} args
- * @param {string} args.phase           — required; one of the phase names above
- * @param {string} [args.task_type]     — optional task_type for finer-grained rules
- * @param {string} [args.domain_type]   — optional, currently unused (reserved for future per-domain rules)
- * @param {object} [args.complexity_signals] — optional object, keys matching COMPLEXITY_OVERRIDES escalate sonnet→opus
- * @returns {{model: string, reason: string, escalation_hook: string|null}}
- */
-function selectModel(args) {
-  if (!args || typeof args !== "object") {
-    return {
-      model: DEFAULT_TIER,
-      reason: "No args provided — default to routine tier (sonnet)",
-      escalation_hook: null,
-    };
-  }
-
-  const { phase, task_type, complexity_signals } = args;
-
-  if (!phase || typeof phase !== "string") {
-    return {
-      model: DEFAULT_TIER,
-      reason: "No phase provided — default to routine tier (sonnet)",
-      escalation_hook: null,
-    };
-  }
-
-  // First pass: find the most-specific matching rule.
-  let matched = null;
-  for (const rule of PHASE_RULES) {
-    if (rule.phase !== phase) continue;
-    if (rule.task_type && rule.task_type !== task_type) continue;
-    matched = rule;
-    break;
-  }
-
-  if (!matched) {
-    return {
-      model: DEFAULT_TIER,
-      reason: `Unknown phase "${phase}" — fallback to routine tier (sonnet)`,
-      escalation_hook: null,
-    };
-  }
-
-  let model = matched.model;
-  let reason = matched.reason;
-
-  // Complexity-signal overrides: bump sonnet → opus if any flagged signal is truthy.
-  if (model === TIERS.SONNET && complexity_signals && typeof complexity_signals === "object") {
-    for (const key of Object.keys(complexity_signals)) {
-      if (!complexity_signals[key]) continue;
-      const override = COMPLEXITY_OVERRIDES[key];
-      if (override && override !== model) {
-        model = override;
-        reason = `${reason} (escalated to ${override} by complexity signal: ${key})`;
-        break;
-      }
-    }
-  }
-
-  // Escalation hook is only injected on sonnet phases flagged as high-stakes-adjacent.
-  // Haiku phases have no hook (mechanical, no judgment). Opus phases have no hook
-  // (already at top tier — nowhere to escalate).
-  let escalation_hook = null;
-  if (model === TIERS.SONNET && matched.hasEscalation) {
-    escalation_hook = ESCALATION_HOOK;
-  }
-
-  return { model, reason, escalation_hook };
-}
-
-/**
- * Return the canonical list of phase names the selector knows about.
- * Used by tests and documentation tooling to assert coverage.
- */
-function listPhases() {
-  const seen = new Set();
-  for (const rule of PHASE_RULES) seen.add(rule.phase);
-  return [...seen].sort();
-}
-
-module.exports = {
-  selectModel,
-  listPhases,
-  TIERS,
-  DEFAULT_TIER,
-  ESCALATION_HOOK,
-  PHASE_RULES,
-  COMPLEXITY_OVERRIDES,
-};