@dzhechkov/harness-cli 0.4.1 → 0.4.3

package/dist/cli.js

@@ -10,15 +10,15 @@ import { execFileSync, execSync, spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { homedir, tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
-import { createSkill, getSkillInfo, isTargetName, listSkills, runDoctor, runInit, resolvePackageSkillRoots, PACKAGE_SKILL_LAYOUTS, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, buildParityMatrix, TARGET_CAPABILITIES, TARGET_SHORT_LABELS, WORKFLOW_TEMPLATES_RETIRED_MESSAGE, parsePlan, isParseErrors, validatePlan, normalizePlan, planDigest, toTraceProjection, renderPlan, mergeRender, lint, lintExitCode, LOOP_BLOBS, parseTrace, assembleTimeline, runInvariants, renderTimelineHtml, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, mirrorEntriesToVector, patternVectorEntry, readMemoryLearningConfig, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns, clearAgentdbQuarantine, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveCostLedger, renderCostLedger, verifyCostLedgerReport, writeCostLedgerJsonl, COST_LEDGER_SCOPE, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, EVENT_CHAIN_TAIL_BYTES, EMPTY_LOG_TAIL, readTailInfo, appendChainedLines, verifyEventChainText, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, generateSigningKeypair, evaluateGuard, resolveRules, auditRecord, guardExitCode, DEFAULT_RULES, parsePnpmLockImporters, scannableStubPath, 
+import { createSkill, getSkillInfo, isTargetName, listSkills, runDoctor, runInit, resolvePackageSkillRoots, PACKAGE_SKILL_LAYOUTS, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, buildParityMatrix, TARGET_CAPABILITIES, TARGET_SHORT_LABELS, WORKFLOW_TEMPLATES_RETIRED_MESSAGE, parsePlan, isParseErrors, validatePlan, normalizePlan, planDigest, toTraceProjection, renderPlan, mergeRender, lint, lintExitCode, LOOP_BLOBS, parseTrace, assembleTimeline, runInvariants, renderTimelineHtml, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, mirrorEntriesToVector, patternVectorEntry, readMemoryLearningConfig, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns, clearAgentdbQuarantine, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveCostLedger, renderCostLedger, verifyCostLedgerReport, writeCostLedgerJsonl, COST_LEDGER_SCOPE, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, parseWeeklyResetAnchor, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, EVENT_CHAIN_TAIL_BYTES, EMPTY_LOG_TAIL, readTailInfo, appendChainedLines, verifyEventChainText, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, generateSigningKeypair, evaluateGuard, resolveRules, auditRecord, guardExitCode, DEFAULT_RULES, parsePnpmLockImporters, scannableStubPath, 
 // guard-promotion (feature guard-promotion, scout idea #1)
-assembleCandidates, renderPromotionReport, renderPromotionAdr, normalizePromotionState, nextPromotionState, globMatch, promotionAdrRelPath, DEFAULT_WINDOW_DAYS, DEFAULT_PERIODS, MAX_CONTENT_FETCHES, BUILTIN_COVERAGE, decideProvenance, isInsideTree, signManifest, verifyManifest, listSignablePackFiles, assertKeyOutsideTree, decidePublishGate, collectPackageFacts, planReleaseGates, selectAffectedPackages, classifyGateExecutions, buildFailureIssue, buildReleaseNotes, releaseTagName, firstOutputLine, formatPublishError, MANIFEST_NAME, SBOM_NAME, buildArchitectureMap, renderMapHuman, findArchitectureDrift, renderDriftReport, scanWorkspacePackages, loadSubsystemManifest, loadProductVision, checkFeatureAgainstArchitecture, renderArchCheck, planProjectSkills, guidanceForStage, renderInjectionReport, analyzeCorpus, renderRakeReport, renderCriticSection, rakeAsLesson, rakeReward, DEFAULT_RAKE_THRESHOLDS, streamSessionEvents, findLatestTranscript, detectProcessRakes, buildRetro, renderRetro, retroLessonText, PROCESS_SIGNATURES, RETRO_DOMAIN, scanForSetup, buildSetupPlan, scaffoldFromSpec, renderScaffoldPreview, readExistingForScaffold, assembleChallengeContext, buildChallengeBrief, planDiscriminationCheck, classifyDiscrimination, pickAdversaryModel, CHALLENGE_QUESTIONS, loadOutcomes, renderOutcomes, statsForKey, selectAutoCost, recordProvisional, finalizeOutcome, COST_LADDER, splitScenarios, budgetPlan, selectWinner, proseScopeOk, renderProseDiff, readScenarioIds, DEFAULT_MAX_JUDGE_RUNS, collectDeliveryFacts, planDeliveryCheck, renderDeliveryBrief, classifyDelivery, isUsablePlaneResult, renderDeliveryReview, scanSkillsLayout, parseInitFacts, verifyRegistration, buildContentProbePrompt, classifyContentProbe, renderContentProbe, findNonRegistrableSkillDirs, assembleCompoundingReport, 
+assembleCandidates, renderPromotionReport, renderPromotionAdr, normalizePromotionState, nextPromotionState, globMatch, promotionAdrRelPath, DEFAULT_WINDOW_DAYS, DEFAULT_PERIODS, MAX_CONTENT_FETCHES, BUILTIN_COVERAGE, decideProvenance, isInsideTree, signManifest, verifyManifest, listSignablePackFiles, assertKeyOutsideTree, decidePublishGate, collectPackageFacts, planReleaseGates, selectAffectedPackages, classifyGateExecutions, buildFailureIssue, buildReleaseNotes, releaseTagName, firstOutputLine, formatPublishError, MANIFEST_NAME, SBOM_NAME, buildArchitectureMap, renderMapHuman, findArchitectureDrift, renderDriftReport, scanWorkspacePackages, loadSubsystemManifest, loadProductVision, checkFeatureAgainstArchitecture, renderArchCheck, planProjectSkills, guidanceForStage, renderInjectionReport, analyzeCorpus, renderRakeReport, renderCriticSection, rakeAsLesson, rakeReward, DEFAULT_RAKE_THRESHOLDS, streamSessionEvents, findLatestTranscript, detectProcessRakes, buildRetro, renderRetro, retroLessonText, PROCESS_SIGNATURES, RETRO_DOMAIN, scanForSetup, buildSetupPlan, scaffoldFromSpec, renderScaffoldPreview, readExistingForScaffold, assembleChallengeContext, buildChallengeBrief, planDiscriminationCheck, classifyDiscrimination, pickAdversaryModel, CHALLENGE_QUESTIONS, loadOutcomes, renderOutcomes, statsForKey, selectAutoCost, recordProvisional, finalizeOutcome, harvestStageOutcomes, recommendModels, planFeed, GRADE_SUCCESS_FLOOR, COST_LADDER, splitScenarios, budgetPlan, selectWinner, proseScopeOk, renderProseDiff, readScenarioIds, DEFAULT_MAX_JUDGE_RUNS, collectDeliveryFacts, planDeliveryCheck, renderDeliveryBrief, classifyDelivery, isUsablePlaneResult, renderDeliveryReview, scanSkillsLayout, parseInitFacts, verifyRegistration, buildContentProbePrompt, classifyContentProbe, renderContentProbe, findNonRegistrableSkillDirs, assembleCompoundingReport, 
 // Cold-vs-warm EPOCH RUNNER (feature epoch-replay) — orchestrates + scores, never calls a model.
 replayableInstances, buildWorkOrder, buildJudgePrompts, unblindJudgments, verifyWorkOrder, isValidMargin, DIGEST_HONEST_SCOPE, scoreEpochReplay, generateMockOutcomes, renderEpochReplayResult, renderWorkOrderSummary, renderJudgePromptsSummary, WORK_ORDER_KIND, DEFAULT_MOCK_N, DEFAULT_MOCK_SEED, scoreRun, renderScorecard, renderCompoundingReport, readReinforcementState, readQuarantineState, registrationExitCode, renderRegistrationReport, 
 // Smart Backlog (feature smart-backlog) — goal-directed idea pipeline over the Brain vector engine.
-readBacklogConfig, readIdeas, writeIdeas, ideaId, dedupIdea, readGoalMap, readGoalMapDetailed, parseEffort, ensureBacklogGitignored, isSafeId, alignIdea, mirrorIdeaVector, ensureBacklogEmbedForm, readBacklogEmbedFormVersion, recordAbsorption, DEDUP_EMBED_FORM_VERSION, snapshotIdeas, spinRoulette, rankRoulette, seededRng, eligibleIdeas, stageEnrichment, buildJiraDraft, resolveJiraAdapter, makeBacklogIO, harmonizeBacklog, transitionIdeas, BACKLOG_BACKENDS, applyDomainBoost, DZ_OWNED_TASK_TYPES, applyExportHoldout, DEFAULT_HELD_OUT_DOMAINS, canonicalDomainKey, readAgentdbRowsByTaskType, heldOutAfterOptIn, renderHoldoutNote, renderSharedStoreAdvice, decideVectorExport, countDisplacedByCut, renderDomainBoostNote, renderDomainCutNote, parseReqeDebt, buildReqeBrief, settleReqeDebt, renderReqeList, REQE_SCOPE, 
+readBacklogConfig, readIdeas, writeIdeas, ideaId, dedupIdea, readGoalMap, readGoalMapDetailed, parseEffort, ensureBacklogGitignored, isSafeId, alignIdea, mirrorIdeaVector, ensureBacklogEmbedForm, readBacklogEmbedFormVersion, recordAbsorption, DEDUP_EMBED_FORM_VERSION, snapshotIdeas, spinRoulette, rankRoulette, seededRng, eligibleIdeas, stageEnrichment, buildJiraDraft, resolveJiraAdapter, makeBacklogIO, harmonizeBacklog, transitionIdeas, editIdea, clearEmbedStale, BACKLOG_BACKENDS, applyDomainBoost, DZ_OWNED_TASK_TYPES, applyExportHoldout, DEFAULT_HELD_OUT_DOMAINS, canonicalDomainKey, readAgentdbRowsByTaskType, heldOutAfterOptIn, renderHoldoutNote, renderSharedStoreAdvice, decideVectorExport, countDisplacedByCut, renderDomainBoostNote, renderDomainCutNote, parseReqeDebt, buildReqeBrief, settleReqeDebt, renderReqeList, REQE_SCOPE, 
 // Mutation gate (feature ha-mutation-gate) — break each named protection, run the suite, require red.
-parseMutationRegistry, applyMutationToText, countFailingTests, classifyBaseline, classifyRunFailure, classifyMutationOutcome, mutationGateExitCode, summarizeMutationResults, renderMutationReport, } from '@dzhechkov/harness-core';
+parseMutationRegistry, applyMutationToText, countFailingTests, classifyBaseline, classifyRunFailure, classifyMutationOutcome, mutationGateExitCode, summarizeMutationResults, renderMutationReport, TRACE_BUNDLE_LEDGER_PATH, TRACE_BUNDLE_SCHEMA, TRACE_BUNDLE_RUN_META_FILE, buildBundle, serializeBundle, parseBundle, planImport, } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
 import { scanGitHub, analyzeRepo, generateReport, deepAnalyze, scanAllSources, ScoutMemory } from '@dzhechkov/scout';
 const USAGE = `dz - DZ cross-platform harness CLI
@@ -39,6 +39,8 @@ Usage:
   dz workflow blobs [--check]                               (list/self-check the subsystem blob registry)
   dz workflow-lint <script.js> [--plan <plan.json>] [--require-plan|--legacy] [--json]   (layer-1 gate; exit 0/1/3 — inconclusive is never a pass)
   dz workflow-trace <runDir|--slug <s>|--run <id>> [--invariants <plan.json>] [--html <out.html>] [--json]   (timeline + SEQ invariant runner)
+  dz workflow-trace export <run> --o <file> [--include-pairs --yes] [--strict]   (one run's telemetry as ONE movable file: events, not aggregates; degradation is typed and LOUD, --strict fails closed)
+  dz workflow-trace import <bundle> --into <root> [--force] [--with-pairs]       (reconstruct that run under an explicit root; FAIL-CLOSED — never writes over a run that already has content)
   dz install <npm-pkg> [--target <name>] [--project <dir>] [--force]
   dz bundle  [--preset <name> | --select id,id,...] [--out <dir>] [--skills-dir <dir>] [--force]   (portable self-contained skill bundles for a generic/LangGraph consumer)
   dz doctor  [--project <dir>] [--pubkey <path>] [--require-signing]   (health + signature check of installed packs)
@@ -65,6 +67,8 @@ Usage:
   dz backlog roulette [--pick <N>] [--seed <n>] [--commit] [--project <dir>] [--json]   (WEIGHTED draw over eligible ideas: alignment^alpha * recencyDecay * 1/effort, seeded; --pick N = ranked shortlist; --commit flips the pick to in-progress)
   dz backlog ship <id> [<id>…] [--reason <t>] [--dry-run] [--project <dir>] [--json]   (mark work DONE: new|enriched|in-progress → shipped, removing it from the roulette pool — run it after finishing a task; short id prefixes ok, ambiguous = loud error)
   dz backlog drop <id> [<id>…] [--reason <t>] [--dry-run] [--project <dir>] [--json]   (retire an idea: new|enriched|in-progress → dropped)
+  dz backlog edit <id> --text "<new>" | --append "<more>" [--dry-run] [--project <dir>] [--json]   (rewrite ONE idea's text, preserving every other field; re-embeds the dedup vector, and on a failed re-embed MARKS the record embedStale so dedup refuses to trust it — previous text preserved in .dz/backlog/edits.jsonl)
+  dz routing recommend [--tier <t>] [--apply] [--json]   (per-stage args.models suggestion from REAL telemetry — harness records + imported run-meta sidecars — printed WITH its basis: n runs, window, the grade-floor rule, skip reasons; qe is FORCED cross-family of code; --apply feeds .dz/routing-outcomes.json idempotently by runId)
   dz backlog reopen <id> [<id>…] [--reason <t>] [--dry-run] [--project <dir>] [--json]   (back to the pool: shipped|dropped|in-progress → new)
   dz backlog enrich <id> [--project <dir>] [--json]                        (stage the idea2prd input scaffold in features/<slug>/ and hand off to the idea2prd-manual skill — the CLI never fabricates a PRD)
   dz backlog jira <id> [--project <dir>] [--json]                          (draft a Jira issue via the configurable adapter (backlog.jira.adapter: jira-mcp|copilot-mcp|none); none writes an auditable jira-outbox/<id>.json stub)
@@ -90,7 +94,7 @@ Usage:
   dz brain expand <kuId> [--source <slug>] [--json]                    (full-content lookup for a citation kuId; --json emits the full KU object)
   dz brain init  [--project <dir>] [--k <N>]                           (wire the grounding hook into .claude/settings.json — opt-in)
   dz statusline [--json] [--install] [--project <dir>]                 (live self-learning panel for Claude Code's status bar; reads the CC JSON payload from STDIN)
-  dz statusline --fa-record --slug <s> --step "<label>" [--recalled <n>] [--stored <n>] [--mode <m>]   (feature-adr: record live per-run learning state → 📐 panel segment)
+  dz statusline --fa-record --slug <s> --step "<label>" [--kind <feature-adr|loop>] [--recalled <n>] [--stored <n>] [--mode <m>]   (feature-adr: record live per-run learning state → 📐 panel segment)
   dz usage [--json] [--project <dir>] | dz usage --calibrate --session <pct> --weekly <pct> [--model fable=<pct>] [--project <dir>]  (ESTIMATE Claude usage from fixed reset windows; optional per-model weekly binding; exit 0 ALWAYS; pct=null when limits unconfigured)
   dz usage --by-stage [--run <runId> | --slug <slug>] [--epsilon <0..1>] [--write <file.jsonl>] [--json]   (per-stage cost ledger for ONE feature-adr run + the reconciliation invariant: accounted + unaccounted = run total; verdict BALANCED | DEFECT | INSUFFICIENT_DATA; local transcript ESTIMATES — catches ATTRIBUTION errors, not pricing errors)
   dz claim-check [paths...] [--json] [--fail-on high|medium|none] [--project <dir>]  (enforce the Integrity Rule: flag untagged/overstated accuracy claims; default scan = root README.md + every discovered package's README.md + features/*/08_qe_report.md + docs/**/*.md (historical feature artifacts are NOT scanned — pass paths explicitly); exit 1 only at/above --fail-on, default high)
@@ -758,7 +762,244 @@ function cmdWorkflowLint(options, flags, cwd, write) {
 /** `dz workflow-trace` — timeline + invariant runner over a run's trace.jsonl. Scope is CAPPED
  * (AM-8): <runDir|--slug|--run>, --invariants, --html, --json. NO watch/filter/compare/search/
  * retention/access-control — adding one needs an ADR amendment (the surface test pins this). */
+/** The tool version stamped into a bundle's provenance. Unknown is honest; a throw is not. */
+function traceBundleToolVersion() {
+    try {
+        const req = createRequire(import.meta.url);
+        const pkg = req('../package.json');
+        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Resolve a run the SAME three ways the timeline reader does — positional, --slug, --run — so a
+ * bundle can never address a run by a scheme the rest of the command does not understand. */
+function resolveTraceRun(options, cwd, positional) {
+    const slug = options.get('slug');
+    const runId = options.get('run');
+    if (positional !== undefined && positional !== '') {
+        return { runDir: resolve(cwd, positional), slug: slug ?? null, runId: runId ?? null };
+    }
+    if (slug !== undefined)
+        return { runDir: resolve(cwd, 'features', slug), slug, runId: runId ?? null };
+    if (runId !== undefined)
+        return { runDir: resolve(cwd, '.dz', 'loop-trace', runId), slug: slug ?? null, runId };
+    return null;
+}
+/** Every harness workflow record under the project, already parsed. An unparseable file is SKIPPED
+ * here rather than guessed at — the pure half answers `unreadable` from what it is handed. */
+function readHarnessRecords(cwd) {
+    const out = [];
+    const base = join(cwd, 'roam', 'claude-state');
+    if (!existsSync(base))
+        return out;
+    let sessions = [];
+    try {
+        sessions = readdirSync(base);
+    }
+    catch {
+        return out;
+    }
+    for (const session of sessions) {
+        const dir = join(base, session, 'workflows');
+        if (!existsSync(dir))
+            continue;
+        let names = [];
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (!name.endsWith('.json'))
+                continue;
+            try {
+                out.push(JSON.parse(readFileSync(join(dir, name), 'utf-8')));
+            }
+            catch { /* skipped, never guessed */ }
+        }
+    }
+    return out;
+}
+/** `dz workflow-trace export` — one run's telemetry as ONE movable file. */
+function cmdWorkflowTraceExport(options, flags, cwd, write) {
+    const out = options.get('o') ?? options.get('out');
+    const run = resolveTraceRun(options, cwd, options.get('_positional_1'));
+    if (run === null || out === undefined || out === '') {
+        write('dz workflow-trace export: usage — dz workflow-trace export <runDir|--slug <s>|--run <id>> --o <file> [--include-pairs --yes] [--strict]');
+        return 1;
+    }
+    const wantPairs = flags.has('include-pairs');
+    if (wantPairs && !flags.has('yes')) {
+        write('dz workflow-trace export: --include-pairs needs --yes — training pairs may carry TARGET-REPO CODE and full prompts, so shipping them off this machine is a second, explicit decision');
+        return 1;
+    }
+    const readSlot = (abs, origin) => existsSync(abs)
+        ? { present: true, member: { origin, content: readFileSync(abs, 'utf-8') } }
+        : { present: false, reason: `absent on disk at ${origin}` };
+    const trace = readSlot(join(run.runDir, 'trace.jsonl'), 'trace.jsonl');
+    const checkpoints = readSlot(join(run.runDir, '.fa-state', 'checkpoints.jsonl'), '.fa-state/checkpoints.jsonl');
+    const ledgerAbs = join(cwd, TRACE_BUNDLE_LEDGER_PATH);
+    // An empty trailing line is not a malformed row — hand the pure half only real lines, or the
+    // bundle reports a phantom parse failure on every well-formed ledger (MEASURED on first run).
+    const ledgerLines = existsSync(ledgerAbs)
+        ? readFileSync(ledgerAbs, 'utf-8').split('\n').filter((line) => line.trim() !== '')
+        : null;
+    const pairFiles = [];
+    if (wantPairs && run.slug !== null) {
+        const pairDir = join(cwd, '.dz', 'fa-training', run.slug);
+        if (existsSync(pairDir)) {
+            for (const name of readdirSync(pairDir)) {
+                if (!name.endsWith('.jsonl'))
+                    continue;
+                pairFiles.push({ origin: `.dz/fa-training/${run.slug}/${name}`, content: readFileSync(join(pairDir, name), 'utf-8') });
+            }
+        }
+    }
+    const bundle = buildBundle({
+        sourceRoot: cwd,
+        runAddress: options.get('_positional_1') ?? (run.slug !== null ? `--slug ${run.slug}` : `--run ${String(run.runId)}`),
+        slug: run.slug,
+        runId: run.runId,
+        toolVersion: traceBundleToolVersion(),
+        createdAt: null,
+        trace,
+        checkpoints,
+        ledgerLines,
+        ...(ledgerLines === null ? { ledgerReason: `no ledger at ${TRACE_BUNDLE_LEDGER_PATH}` } : {}),
+        includePairs: wantPairs,
+        pairFiles: wantPairs ? pairFiles : null,
+        records: readHarnessRecords(cwd),
+    });
+    try {
+        mkdirSync(dirname(resolve(cwd, out)), { recursive: true });
+        writeFileSync(resolve(cwd, out), serializeBundle(bundle));
+    }
+    catch (err) {
+        write(`dz workflow-trace export: could not write ${out} — ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    // Degradation is NAMED, never silent — and exactly one reason is actionable.
+    let degraded = 0;
+    if (!bundle.trace.present) {
+        degraded++;
+        write(`dz workflow-trace export: trace absent — ${bundle.trace.reason}`);
+    }
+    if (!bundle.checkpoints.present) {
+        degraded++;
+        write(`dz workflow-trace export: checkpoints absent — ${bundle.checkpoints.reason}`);
+    }
+    if (!bundle.ledger.present) {
+        degraded++;
+        write(`dz workflow-trace export: ledger absent — ${String(bundle.ledger.reason)}`);
+    }
+    if (!bundle.runMeta.resolved) {
+        degraded++;
+        const reason = bundle.runMeta.reason;
+        write(reason === 'layout-unrecognised'
+            ? 'dz workflow-trace export: runMeta UNRESOLVED (layout-unrecognised) — the harness workflow-record layout CHANGED; update the reader in harness-core/src/trace-bundle.ts. This is the one reason that needs action'
+            : `dz workflow-trace export: runMeta unresolved (${reason}) — no action needed, this is history or absence, not a layout change`);
+    }
+    write(`dz workflow-trace export: wrote ${out} (${bundle.schema}; ledger rows scanned ${bundle.ledger.scanned}, matched ${bundle.ledger.matched}, malformed ${bundle.ledger.malformed})`);
+    if (degraded > 0 && flags.has('strict')) {
+        write(`dz workflow-trace export: --strict — ${degraded} member(s) degraded, failing closed`);
+        return 1;
+    }
+    return 0;
+}
+/** `dz workflow-trace import` — reconstruct a run under an explicit root. FAIL-CLOSED. */
+function cmdWorkflowTraceImport(options, flags, cwd, write) {
+    const file = options.get('_positional_1');
+    const into = options.get('into');
+    if (file === undefined || file === '' || into === undefined || into === '') {
+        write('dz workflow-trace import: usage — dz workflow-trace import <bundle.json> --into <root> [--force] [--with-pairs]');
+        return 1;
+    }
+    const abs = resolve(cwd, file);
+    if (!existsSync(abs)) {
+        write(`dz workflow-trace import: no such bundle: ${file}`);
+        return 1;
+    }
+    const parsed = parseBundle(readFileSync(abs, 'utf-8'));
+    if (!parsed.ok) {
+        write(parsed.reason === 'unknown-schema'
+            ? `dz workflow-trace import: REFUSED — unknown bundle schema "${parsed.found}"; this dz reads ${TRACE_BUNDLE_SCHEMA}. A future bundle is never best-effort parsed`
+            : parsed.reason === 'member-shape'
+                ? `dz workflow-trace import: REFUSED — member "${parsed.member}" fails its shape check; a partial import is never left behind`
+                : 'dz workflow-trace import: REFUSED — the bundle is not parseable JSON');
+        return 1;
+    }
+    const bundle = parsed.bundle;
+    const root = resolve(cwd, into);
+    const runDirRel = bundle.provenance.slug !== null ? join('features', bundle.provenance.slug) : join('.dz', 'loop-trace', String(bundle.provenance.runId ?? 'unknown-run'));
+    const runDirAbs = join(root, runDirRel);
+    let runDirHasContent = false;
+    try {
+        runDirHasContent = existsSync(runDirAbs) && readdirSync(runDirAbs).length > 0;
+    }
+    catch {
+        runDirHasContent = false;
+    }
+    let runIdentity = null;
+    const metaAbs = join(runDirAbs, TRACE_BUNDLE_RUN_META_FILE);
+    if (existsSync(metaAbs)) {
+        try {
+            const meta = JSON.parse(readFileSync(metaAbs, 'utf-8'));
+            runIdentity = {
+                slug: typeof meta.slug === 'string' ? meta.slug : null,
+                runId: typeof meta.runId === 'string' ? meta.runId : null,
+            };
+        }
+        catch {
+            runIdentity = null;
+        }
+    }
+    const plan = planImport(bundle, {
+        runDir: runDirRel,
+        existingPaths: [],
+        runDirHasContent,
+        runIdentity,
+        force: flags.has('force'),
+        withPairs: flags.has('with-pairs'),
+        bundleName: basename(abs),
+    });
+    if (!plan.ok) {
+        for (const refusal of plan.refusals)
+            write(`dz workflow-trace import: REFUSED ${refusal.path} — ${refusal.reason}`);
+        write('dz workflow-trace import: nothing was written');
+        return 1;
+    }
+    let written = 0;
+    const failures = [];
+    for (const entry of plan.writes) {
+        const target = join(root, entry.path);
+        try {
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, entry.content);
+            written++;
+        }
+        catch (err) {
+            failures.push(`${entry.path} — ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Report what ACTUALLY landed, computed from the writes, not from the plan.
+    for (const skipped of plan.refusals)
+        write(`dz workflow-trace import: skipped ${skipped.path} — ${skipped.reason}`);
+    for (const failure of failures)
+        write(`dz workflow-trace import: FAILED ${failure}`);
+    write(`dz workflow-trace import: wrote ${written} of ${plan.writes.length} member(s) under ${into}`);
+    return failures.length > 0 ? 1 : 0;
+}
 function cmdWorkflowTrace(options, flags, cwd, write) {
+    // Two subcommands ride the SAME run addressing as the timeline reader (AM-8 keeps the surface
+    // capped; these are bundle transport, not new query verbs).
+    const sub = options.get('_positional_0');
+    if (sub === 'export')
+        return cmdWorkflowTraceExport(options, flags, cwd, write);
+    if (sub === 'import')
+        return cmdWorkflowTraceImport(options, flags, cwd, write);
     const runDirArg = options.get('_positional_0');
     const slug = options.get('slug');
     const runId = options.get('run');
@@ -1212,11 +1453,13 @@ function cmdStatuslineInstall(options, cwd, write) {
 /**
  * `dz statusline --fa-record` — the entry point the `/feature-adr` pipeline calls at Steps 0/8/9 to
  * record its LIVE learning state (Pattern memory loop: pool / recalled / stored). Unlike the render
- * path this WRITES `.dz/feature-adr/learning-state.json` (via harness-core's best-effort
- * `writeFeatureAdrState`, which itself computes `pool` from the learned-pattern count).
+ * path this WRITES a per-slug `.dz/feature-adr/learning-state/*.json` slot (via harness-core's
+ * best-effort `writeFeatureAdrState`, which itself computes `pool` from the learned-pattern count).
  *
  * GUARD (feature-adr flag discipline): `--slug` and `--step` are required; a missing one exits 1
  * with a copy-paste example. `--recalled`/`--stored` default to 0 and reject non-numeric input.
+ * `--kind <feature-adr|loop>` identifies the producer, defaults to `feature-adr`, and rejects any
+ * other value rather than silently weakening panel arbitration.
  */
 function cmdStatuslineFaRecord(options, cwd, write) {
     const slug = (options.get('slug') ?? '').trim();
@@ -1248,10 +1491,16 @@ function cmdStatuslineFaRecord(options, cwd, write) {
     const reinforced = parseCount('reinforced');
     if (reinforced === undefined)
         return 1;
+    const kindRaw = options.get('kind') ?? 'feature-adr';
+    if (kindRaw !== 'feature-adr' && kindRaw !== 'loop') {
+        write(`dz statusline --fa-record: --kind must be feature-adr or loop (got "${kindRaw}")`);
+        write('  Example: dz statusline --fa-record --slug add-user-auth --step "Step 0" --kind feature-adr --recalled 5 --stored 2');
+        return 1;
+    }
     const mode = options.get('mode');
     const projectRoot = resolve(cwd, options.get('project') ?? '.');
     const state = writeFeatureAdrState(projectRoot, {
-        slug, step, recalled, stored,
+        kind: kindRaw, slug, step, recalled, stored,
         ...(reinforced > 0 ? { reinforced } : {}),
         ...(mode !== undefined && mode.trim() !== '' ? { mode: mode.trim() } : {}),
     });
@@ -1294,7 +1543,13 @@ function cmdStatusline(options, flags, cwd, write, readStdin) {
         // Live /feature-adr run in flight → PREPEND the pipeline learning segment to the base dz line.
         const fa = data.featureAdr;
         if (fa !== undefined) {
-            line = `📐 feature-adr ${fa.step} · 🎓 ${fa.pool} pool · ↑${fa.recalled} used · +${fa.stored} new · ↻${fa.reinforced ?? 0} reinforced · ${line}`;
+            // The producer marker reached data and arbitration in a previous round but not this label, so the bar asserted a pipeline that was not running.
+            if (fa.kind === 'loop') {
+                line = `🔁 loop ${fa.step} · ${line}`;
+            }
+            else {
+                line = `📐 feature-adr ${fa.step} · 🎓 ${fa.pool} pool · ↑${fa.recalled} used · +${fa.stored} new · ↻${fa.reinforced ?? 0} reinforced · ${line}`;
+            }
         }
         write(line);
         return 0;
@@ -1585,7 +1840,16 @@ function cmdUsage(options, optionLists, flags, cwd, write) {
         const s = u.sessionPct === null ? 'n/a' : '~' + u.sessionPct + '%';
         const binding = hasModelLimits && u.weeklyBindingModel !== undefined ? ' ' + u.weeklyBindingModel + '-bound' : '';
         const w = u.weeklyPct === null ? 'n/a' : '~' + u.weeklyPct + '%' + binding;
-        write('usage: session ' + s + ' (resets ' + clock(u.sessionResetsAt) + ') · week ' + w + ' (resets ' + clock(u.weeklyResetsAt) + ') · estimated');
+        // The weekly reset is WEEKLY: print the anchor verbatim (weekday + offset), not a bare clock
+        // time — 'resets 08:59' reads as daily and hides the weekday (idea c8513be9: the bare form
+        // misread a Monday reading as '41 minutes after the boundary' when the boundary was Wednesday's).
+        const weeklyAnchorLabel = typeof lim.weeklyResetAnchor === 'string' && lim.weeklyResetAnchor !== ''
+            ? lim.weeklyResetAnchor
+            : clock(u.weeklyResetsAt);
+        write('usage: session ' + s + ' (resets ' + clock(u.sessionResetsAt) + ') · week ' + w + ' (resets ' + weeklyAnchorLabel + ') · estimated');
+        if (typeof lim.weeklyResetAnchor === 'string' && parseWeeklyResetAnchor(lim.weeklyResetAnchor)?.offsetMinutes === undefined) {
+            write('  ⚠ weeklyResetAnchor has NO utc offset — the boundary follows the SERVER timezone, not your account\'s true reset instant (measured: the same moment lands a week apart under UTC vs +03:00). Pin it: "' + lim.weeklyResetAnchor + ' +03:00" (your offset) in .dz/config.json');
+        }
         // re-QE debt surfacing (backlog 6b40e667): the moment someone checks usage is the moment a
         // usage-switched self-review debt should be visible. Best-effort — never breaks the contract.
         try {
@@ -8371,6 +8635,55 @@ async function cmdBacklog(options, flags, cwd, write) {
             write('  (dry-run — nothing written; re-run without --dry-run to apply)');
         return report.ok ? 0 : 1;
     }
+    // ── edit — replace/extend ONE idea's text (idea 1fde7bf6). The verb exists because a hand-edit
+    // does not re-embed: the dedup vector keeps describing the OLD text. editIdea owns the text change
+    // and MARKS the record embedStale; this layer owns the async re-embed and clears the mark ONLY
+    // after the vector tier confirms. A failed re-embed is loud here AND enforced at the harm point:
+    // classifyDedup refuses vector candidacy for a marked record (ADR-001).
+    if (sub === 'edit') {
+        const id = options.get('_positional_1');
+        if (id === undefined)
+            return emitErr('an idea id is required: dz backlog edit <id> --text "<new>" | --append "<more>" [--dry-run]');
+        const report = editIdea(projectRoot, id, {
+            ...(options.get('text') !== undefined ? { text: options.get('text') } : {}),
+            ...(options.get('append') !== undefined ? { append: options.get('append') } : {}),
+            dryRun: flags.has('dry-run'),
+        });
+        let embed = 'skipped';
+        if (report.ok && report.written && report.id !== undefined) {
+            const updated = readIdeas(projectRoot).find((i) => i.id === report.id);
+            if (updated !== undefined) {
+                const mirror = await mirrorIdeaVector(projectRoot, updated);
+                if (mirror.mirrored > 0 && mirror.error === undefined && clearEmbedStale(projectRoot, report.id))
+                    embed = 'ok';
+                else
+                    embed = 'stale';
+            }
+            else
+                embed = 'stale';
+        }
+        if (json) {
+            write(JSON.stringify({ verb: 'edit', ...report, embed, exitCode: report.ok ? (embed === 'stale' ? 1 : 0) : 1 }, null, 2));
+            return report.ok ? (embed === 'stale' ? 1 : 0) : 1;
+        }
+        for (const e of report.errors)
+            write(`dz backlog edit: ${e}`);
+        if (report.ok && report.id !== undefined) {
+            if (!report.written && !report.dryRun)
+                write(`dz backlog edit: ${report.id} — text unchanged, nothing to do`);
+            else
+                write(`dz backlog edit${report.dryRun ? ' (dry-run)' : ''}: ${report.id}\n  was: ${report.previousText?.slice(0, 100)}\n  now: ${report.newText?.slice(0, 100)}`);
+            if (report.written) {
+                if (embed === 'ok')
+                    write('  vector re-embedded (dedup form) — the record is fully consistent');
+                else
+                    write('  ⚠ vector NOT re-embedded — the record is MARKED embedStale: dedup will refuse to trust its similarity until `dz vector reindex` repairs it (the text edit itself landed)');
+            }
+            if (report.dryRun)
+                write('  (dry-run — nothing written; re-run without --dry-run to apply)');
+        }
+        return report.ok ? (embed === 'stale' ? 1 : 0) : 1;
+    }
     if (sub === 'enrich') {
         const id = options.get('_positional_1');
         if (id === undefined)
@@ -8472,6 +8785,68 @@ function cmdRouting(options, flags, cwd, write) {
         repoRoot = execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8' }).trim() || cwd;
     }
     catch { /* not git */ }
+    // ── recommend — harvest real telemetry, print per-stage picks WITH THE BASIS, optionally feed the
+    // store (a9c3dd5c fn 3, ADR-001). Sources: live harness records + imported run-meta.json sidecars.
+    if (options.get('_positional_0') === 'recommend') {
+        const records = readHarnessRecords(repoRoot);
+        // imported runs (trace-bundle ADR-001 D4): run-meta sidecars carry runMeta.records of the SAME shape
+        for (const base of [join(repoRoot, 'features'), join(repoRoot, '.dz', 'loop-trace')]) {
+            if (!existsSync(base))
+                continue;
+            let names = [];
+            try {
+                names = readdirSync(base);
+            }
+            catch {
+                continue;
+            }
+            for (const name of names) {
+                const sidecar = join(base, name, 'run-meta.json');
+                if (!existsSync(sidecar))
+                    continue;
+                try {
+                    const meta = JSON.parse(readFileSync(sidecar, 'utf-8'));
+                    if (meta.runMeta?.resolved === true && Array.isArray(meta.runMeta.records))
+                        records.push(...meta.runMeta.records);
+                }
+                catch { /* an unreadable sidecar contributes nothing — counted below as noResult */ }
+            }
+        }
+        const harvest = harvestStageOutcomes(records);
+        const rec = recommendModels(harvest, { ...(options.get('tier') !== undefined ? { tier: options.get('tier') } : {}) });
+        if (flags.has('apply')) {
+            const fedPath = join(repoRoot, '.dz', 'routing-fed.json');
+            let alreadyFed = [];
+            try {
+                alreadyFed = JSON.parse(readFileSync(fedPath, 'utf-8'));
+            }
+            catch { /* first apply */ }
+            const plan = planFeed(harvest.samples, alreadyFed);
+            for (const sample of plan.toFeed)
+                finalizeOutcome(repoRoot, sample.stage, sample.tier, sample.model, sample.success);
+            try {
+                mkdirSync(join(repoRoot, '.dz'), { recursive: true });
+                writeFileSync(fedPath, JSON.stringify(plan.fedAfter));
+            }
+            catch (e) {
+                write(`dz routing recommend: fed ${plan.toFeed.length} sample(s) but could NOT persist the fed-set — a re-apply WILL double-count: ${e.message}`);
+                return 1;
+            }
+            write(`dz routing recommend --apply: fed ${plan.toFeed.length} sample(s) into .dz/routing-outcomes.json${plan.skippedRuns.length > 0 ? `; skipped ${plan.skippedRuns.length} already-fed run(s) (idempotent by runId)` : ''}`);
+        }
+        if (flags.has('json')) {
+            write(JSON.stringify({ recommendation: rec, exitCode: 0 }, null, 2));
+            return 0;
+        }
+        write(`dz routing recommend — args.models suggestion from ${rec.basis.runsUsed} run(s)${rec.basis.window !== null ? ` (${rec.basis.window.min.slice(0, 10)}..${rec.basis.window.max.slice(0, 10)})` : ''}:`);
+        for (const s of rec.perStage) {
+            write(`  ${s.stage.padEnd(14)} ${s.spec.padEnd(20)} ${s.insufficientData ? '[insufficient data — cold-start pick]' : '[quality bar met]'} ${s.pick.evidence}`);
+        }
+        write(`  basis: ${rec.basis.rule}`);
+        write(`  basis: skipped records — no result ${rec.basis.skipped.noResult}, no modelsUsed ${rec.basis.skipped.noModels} (predates model routing — history, not an error), no grade ${rec.basis.skipped.noGrade}, unknown model ${rec.basis.skipped.unknownModel}`);
+        write(`  basis: ${rec.basis.crossFamilyNote}`);
+        return 0;
+    }
     const stage = options.get('stage');
     const tier = options.get('tier');
     const model = options.get('model');