@skill-harness/cli 0.16.0 → 0.17.0

package/dist/learning.d.ts

@@ -6,7 +6,7 @@ export interface LearningUI {
     confirm(title: string, detail: string): Promise<boolean>;
     notify(text: string, level?: 'info' | 'warning' | 'error'): void;
 }
-export declare const LEARNING_HELP = "Learning \u2014 retained evidence, no model calls\n  learning                         open guided review (interactive terminal)\n  learning init --archive DIR --author NAME [--scope-item N] --confirm\n      [--scope TEXT --population TEXT only for a comparison-only archive without retained cases]\n  learning status [--json]          readiness; never automatic exposure\n  learning import                  list retained batches/comparisons\n  learning import --item N --name NAME --title TEXT --scope-note TEXT --confirm\n  learning cases NAME [--offset N]\n  learning evidence NAME --item N [--evidence N]   inspect only the selected case's retained sources\n  learning case NAME --item N --disposition confirmed_defect|expected_behavior|exemplar|uncertain|skip --note TEXT --confirm\n  learning comparisons\n  learning review NAME             guided complete-output review in a terminal\n  learning artifact NAME --variant A [--artifact N]\n  learning choose NAME --kind one|tie|none|insufficient [--variants A,B] --full-review --note TEXT --confirm\n  learning reveal NAME             requires durable full-scope quality receipt\n  learning decide NAME --disposition adopt|reject|defer --note TEXT --confirm\n  learning hypothesis NAME --name SLUG --intervention TEXT --prediction TEXT --disproof TEXT --downside TEXT --rollback TEXT --alternative TEXT --confirm\n  learning link NAME --cases BATCH --item N --hypothesis SLUG --confirm\n  learning trust sample FILE --name SLUG --title TEXT [--split calibration|heldout|tuning] --confirm\n  learning trust setup --cases NAME [--detector ID] [--split calibration|heldout|tuning] [--max-unflagged N]\n      [--attention N --minimum-resolved N --minimum-lower-bound T --expires DAYS] --confirm\n  learning trust status\n  learning trust label --cases NAME --item N --reference-author NAME --confirm\n  learning trust unflagged --item N --miss yes|no --evidence FILE --reference-author NAME --note TEXT --confirm\n  learning adoption NAME           scope/decision/readiness; activation is producer-owned\n  learning outcome NAME            inspect observed outcomes\n  learning outcome NAME --result success|confirmed-defect|unknown --artifact FILE --original-requirement FILE --current-requirement FILE --evidence FILE --reference-author NAME --note TEXT [--accepted-artifact FILE --acceptance-evidence FILE] --confirm\n  learning guide | current         installed portable guide / requirement register\nAll commands accept --state DIR (default .skill-harness/learning), --json for structured output.\n--confirm authorizes only the displayed local write, never models, acceptance or registry activation.\nNo raw manifest authoring. Import selects actual retained inputs. Exit zero is command completion, not quality.\nRegistry activation/rollback use /grants learning in interactive Pi, with independent authority.";
+export declare const LEARNING_HELP = "Learning \u2014 retained evidence, no model calls\n  learning                         open guided review (interactive terminal)\n  learning init --archive DIR --author NAME [--scope-item N] --confirm\n      [--scope TEXT --population TEXT only for a comparison-only archive without retained cases]\n  learning session help             whole-session retrospective import, timeline and annotations\n  learning status [--json]          readiness; never automatic exposure\n  learning import                  list retained batches/comparisons\n  learning import --item N --name NAME --title TEXT --scope-note TEXT --confirm\n  learning cases NAME [--offset N]\n  learning evidence NAME --item N [--evidence N]   inspect only the selected case's retained sources\n  learning case NAME --item N --disposition confirmed_defect|expected_behavior|exemplar|uncertain|skip --note TEXT --confirm\n  learning comparisons\n  learning review NAME             guided complete-output review in a terminal\n  learning artifact NAME --variant A [--artifact N]\n  learning choose NAME --kind one|tie|none|insufficient [--variants A,B] --full-review --note TEXT --confirm\n  learning reveal NAME             requires durable full-scope quality receipt\n  learning decide NAME --disposition adopt|reject|defer --note TEXT --confirm\n  learning hypothesis NAME --name SLUG --intervention TEXT --prediction TEXT --disproof TEXT --downside TEXT --rollback TEXT --alternative TEXT --confirm\n  learning link NAME --cases BATCH --item N --hypothesis SLUG --confirm\n  learning trust sample FILE --name SLUG --title TEXT [--split calibration|heldout|tuning] --confirm\n  learning trust setup --cases NAME [--detector ID] [--split calibration|heldout|tuning] [--max-unflagged N]\n      [--attention N --minimum-resolved N --minimum-lower-bound T --expires DAYS] --confirm\n  learning trust status\n  learning trust label --cases NAME --item N --reference-author NAME --confirm\n  learning trust unflagged --item N --miss yes|no --evidence FILE --reference-author NAME --note TEXT --confirm\n  learning adoption NAME           scope/decision/readiness; activation is producer-owned\n  learning outcome NAME            inspect observed outcomes\n  learning outcome NAME --result success|confirmed-defect|unknown --artifact FILE --original-requirement FILE --current-requirement FILE --evidence FILE --reference-author NAME --note TEXT [--accepted-artifact FILE --acceptance-evidence FILE] --confirm\n  learning guide | current         installed portable guide / requirement register\nAll commands accept --state DIR (default .skill-harness/learning), --json for structured output.\n--confirm authorizes only the displayed local write, never models, acceptance or registry activation.\nNo raw manifest authoring. Import selects actual retained inputs. Exit zero is command completion, not quality.\nRegistry activation/rollback use /grants learning in interactive Pi, with independent authority.";
 /** Escape terminal control/format characters in untrusted retained display text. Exact archive
  * bytes never change; output honestly identifies this as a display representation. */
 export declare function learningDisplay(text: string): string;

package/dist/learning.js

@@ -1,3 +1,4 @@
+import { runSessionLearning, reviewSessionLearning } from './session-learning.js';
 import { resolve, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
@@ -7,6 +8,7 @@ export const LEARNING_HELP = `Learning — retained evidence, no model calls
   learning                         open guided review (interactive terminal)
   learning init --archive DIR --author NAME [--scope-item N] --confirm
       [--scope TEXT --population TEXT only for a comparison-only archive without retained cases]
+  learning session help             whole-session retrospective import, timeline and annotations
   learning status [--json]          readiness; never automatic exposure
   learning import                  list retained batches/comparisons
   learning import --item N --name NAME --title TEXT --scope-note TEXT --confirm
@@ -107,7 +109,9 @@ export function formatLearningStatus(view) {
         lines.push(`Cases: ${c.title} (${c.name}) — ${c.state === 'ready' ? `${c.total} retained nomination(s)` : c.reason}`);
     for (const c of view.comparisons)
         lines.push(`Comparison: ${c.title} (${c.name}) — ${c.reason}${'decision' in c && c.decision ? `; decision: ${c.decision.disposition}` : ''}`);
-    if (!view.cases.length && !view.comparisons.length)
+    for (const s of view.sessions)
+        lines.push('Session: ' + s.title + ' (' + s.name + ') — ' + s.reason);
+    if (!view.cases.length && !view.comparisons.length && !view.sessions.length)
         lines.push('No inputs connected. Choose Connect retained input; missing evidence is not a failure or acceptance.');
     lines.push(formatLearningTrust(view.trust));
     return learningDisplay(lines.join('\n'));
@@ -128,7 +132,7 @@ export function formatLearningTrust(trust) {
 export async function runLearningCommand(argv, options = {}) {
     const { args, flags } = parse(argv), cwd = options.cwd ?? process.cwd(), directory = resolve(cwd, typeof flags.state === 'string' ? flags.state : '.skill-harness/learning');
     const out = options.write ?? console.log;
-    const emit = (value) => { out(flags.json ? JSON.stringify(value, null, 2) : typeof value === 'string' ? value : learningDisplay(JSON.stringify(value, null, 2))); return value; };
+    const emit = (value) => { out(flags.json ? JSON.stringify(value, null, 2) : typeof value === 'string' ? learningDisplay(value) : learningDisplay(JSON.stringify(value, null, 2))); return value; };
     const confirm = (preview, write) => {
         if (flags.confirm !== true)
             return emit({ state: 'confirmation-required', preview, next: 'Repeat with --confirm to authorize this exact local action.' });
@@ -139,6 +143,8 @@ export async function runLearningCommand(argv, options = {}) {
         init: ['archive', 'scope', 'population', 'author', 'scope-item'], status: [], import: ['item', 'name', 'title', 'scope-note'], cases: ['offset'], evidence: ['item', 'evidence'], case: ['item', 'disposition', 'note'], comparisons: [], review: [], artifact: ['variant', 'artifact'], choose: ['kind', 'variants', 'full-review', 'note'], reveal: [], decide: ['disposition', 'note'], hypothesis: ['name', 'intervention', 'prediction', 'disproof', 'downside', 'rollback', 'alternative'], link: ['cases', 'item', 'hypothesis'], trust: ['cases', 'item', 'detector', 'split', 'max-unflagged', 'attention', 'minimum-resolved', 'minimum-lower-bound', 'expires', 'name', 'title', 'reference-author', 'miss', 'evidence', 'note'], adoption: [], outcome: ['result', 'artifact', 'original-requirement', 'current-requirement', 'evidence', 'reference-author', 'note', 'accepted-artifact', 'acceptance-evidence'], guide: [], help: []
     };
     const command = args[0];
+    if (command === 'session')
+        return runSessionLearning(args.slice(1), flags, { cwd, directory, emit });
     if (command === 'guide' || command === 'current') {
         const file = command === 'guide' ? 'PRODUCT-GUIDE.md' : 'STATUS.md', base = dirname(fileURLToPath(import.meta.url));
         const selected = [resolve(base, '../docs', file), resolve(base, '../../../docs/factory', file)].find(p => existsSync(p));
@@ -441,12 +447,34 @@ export async function runLearningWizard(options) {
     const workspace = openLearningWorkspace(directory);
     for (;;) {
         const status = workspace.inspect(Date.now());
-        const selected = await ui.select('Learning — retained evidence, no model calls', ['Readiness', 'Connect retained input', 'Review cases', 'Review comparisons', 'Record adopt / reject / defer', 'Propose hypothesis', 'Link original hypothesis', 'Trust / independent labels', 'Adoption / outcomes', 'Done']);
+        const selected = await ui.select('Learning — retained evidence, no model calls', ['Readiness', 'Connect retained input', 'Import session', 'Review sessions', 'Review cases', 'Review comparisons', 'Record adopt / reject / defer', 'Propose hypothesis', 'Link original hypothesis', 'Trust / independent labels', 'Adoption / outcomes', 'Done']);
         if (!selected || selected === 'Done')
             return;
         try {
             if (selected === 'Readiness')
                 ui.notify(formatLearningStatus(status));
+            if (selected === 'Review sessions')
+                await reviewSessionLearning(directory, ui, learningDisplay);
+            if (selected === 'Import session') {
+                const session = await ui.input('Explicit Pi session JSONL path (no directory scanning)'), name = await ui.input('Short session name'), title = await ui.input('Session title');
+                if (!session || !name || !title)
+                    continue;
+                const ledger = await ui.input('Optional explicit pi-daddy grants.jsonl path'), feedback = await ui.input('Optional feedback file path');
+                const args = ['session', 'preview', '--session', session, '--state', directory, '--json'];
+                if (ledger)
+                    args.push('--ledger', ledger);
+                if (feedback)
+                    args.push('--feedback', feedback);
+                let raw = '';
+                await runLearningCommand(args, { cwd, write: t => { raw = t; } });
+                const preview = JSON.parse(raw);
+                await ui.editor('Session import preview — read only', learningDisplay(raw));
+                if (await ui.confirm('Retain these exact selected files privately?', 'May include sensitive session text. Inspect your selected files first. No automatic redaction, model calls or acceptance.')) {
+                    args[1] = 'import';
+                    args.push('--name', name, '--title', title, '--expected', preview.digest, '--confirm');
+                    await runLearningCommand(args, { cwd, write: t => ui.notify(learningDisplay(t)) });
+                }
+            }
             if (selected === 'Connect retained input') {
                 const catalog = catalogLearningArchive(status.configuration.archiveRoot, status.configuration.author), labels = catalog.map((c, i) => `${i + 1}. ${c.kind}: ${c.description}`);
                 if (!labels.length) {

package/dist/session-learning.d.ts

@@ -0,0 +1,12 @@
+import { openLearningWorkspace } from '@skill-harness/adapters';
+import type { LearningUI } from './learning.js';
+export declare const SESSION_HELP: string;
+export declare function formatSession(view: ReturnType<ReturnType<typeof openLearningWorkspace>['session']>): string;
+type Flags = Record<string, string | boolean>;
+export declare function runSessionLearning(args: string[], flags: Flags, options: {
+    cwd: string;
+    directory: string;
+    emit: (v: unknown) => unknown;
+}): Promise<unknown>;
+export declare function reviewSessionLearning(directory: string, ui: LearningUI, display: (s: string) => string): Promise<void>;
+export {};

package/dist/session-learning.js

@@ -0,0 +1,148 @@
+import { resolve, relative, isAbsolute, sep } from 'node:path';
+import { existsSync } from 'node:fs';
+import { prepareSessionImport, retainSessionImport, readRetainedSessionSource, sessionScope, createLearningWorkspace, openLearningWorkspace, learningFile, } from '@skill-harness/adapters';
+const text = (v, label) => { if (typeof v !== 'string' || !v.trim())
+    throw Error(label + ' is required'); return v; };
+export const SESSION_HELP = [
+    'Session learning — retrospective, no model calls',
+    '  learning session preview --session FILE [--ledger FILE --feedback FILE --artifact FILE]',
+    '      [--sources FILE]                    additional explicit {kind,path,executionId?} selections',
+    '  learning session import --session FILE ... --name NAME --title TEXT',
+    '      --expected DIGEST --confirm [--archive DIR --author NAME for a new workspace]',
+    '  learning session list',
+    '  learning session show NAME              timeline excerpts, model/tool/usage evidence and gaps',
+    '  learning session source NAME --item N   complete selected retained source, display only',
+    '  learning session note NAME --kind finding|proposal|acceptance|context --note TEXT',
+    '      --item N --line N --confirm         operator annotation, not calibrated quality or adoption',
+    'Use --state DIR to select a learning workspace; --json returns structured readback.',
+    'Preview writes nothing. Import retains exact selected bytes privately, including potentially sensitive',
+    'session content. Inspect selected files before confirming. No automatic discovery, redaction or export.',
+    'A changed preview needs a new digest. No running worker is contacted.',
+].join('\n');
+export function formatSession(view) {
+    const p = view.parent;
+    const lines = ['Session — ' + view.title, 'Session ID: ' + p.sessionId, 'Snapshot: ' + view.selectionDigest,
+        'Retrospective evidence; quality and acceptance are not inferred.',
+        p.userMessages + ' user messages · ' + p.assistantMessages + ' assistant messages · ' + view.attempts.length + ' ledger executions · ' + view.children.length + ' child transcripts',
+        'Last assistant stop: ' + (p.lastAssistantStop ?? 'unknown') + ' (not a completion or acceptance receipt)',
+        '', 'Models observed:', ...p.modelRecords.map(m => '  ' + m.provider + '/' + m.model + ': ' + m.messages + ' assistant records'),
+        '', 'Parent usage — reported sums only; not billing or combined child usage:',
+        ...Object.entries(p.usage.fields).map(([k, v]) => '  ' + k + ': ' + v.sum + ' (' + v.reportedMessages + '/' + p.assistantMessages + ' messages reported)'),
+        '', 'Delegations — operator-selected ledger, association not authenticated:',
+        ...view.attempts.map(a => '  ' + a.executionId + ' · ' + (a.agent ?? 'unknown') + ' · ' + a.state + ' · ' + (a.runningSeconds ?? '?') + ' s · ' + (a.pane ?? 'no pane')),
+        '', 'Child transcripts — separately reported, no combined token total:',
+        ...view.children.flatMap(c => [
+            '  Source ' + (c.source + 1) + ' · ' + c.session.sessionId + ' · ' + (c.executionId ?? 'unmapped execution'),
+            '  Last assistant stop: ' + (c.session.lastAssistantStop ?? 'unknown') + ' (not acceptance)',
+            ...c.session.modelRecords.map(m => '    ' + m.provider + '/' + m.model + ': ' + m.messages + ' assistant records'),
+            ...Object.entries(c.session.usage.fields).map(([k, v]) => '    ' + k + ': ' + v.sum + ' (' + v.reportedMessages + '/' + c.session.assistantMessages + ' messages reported)'),
+            ...c.session.timeline.map(e => '    line ' + e.line + ' · ' + e.kind + ': ' + e.excerpt),
+        ]),
+        '', 'Sources — use session source NAME --item N for complete retained bytes:',
+        ...view.sources.map((s, i) => '  ' + (i + 1) + '. ' + s.kind + ': ' + s.path + ' (' + s.bytes + ' bytes; ' + s.sha256 + ')'),
+        '', 'Chronological visible timeline — excerpts, not a complete artifact review:',
+        ...p.timeline.map(e => '  ' + (e.timestamp ?? 'unknown time') + ' · line ' + e.line + ' · ' + e.kind + ': ' + e.excerpt),
+        '', 'Operator annotations — not automatically verified labels:',
+        ...view.annotations.map(a => '  ' + a.kind + ' · source ' + a.item + ', line ' + a.line + ' · ' + a.author + ': ' + a.note),
+        '', 'Evidence gaps:', ...view.gaps.map(g => '  - ' + g)];
+    return lines.join('\n');
+}
+export async function runSessionLearning(args, flags, options) {
+    const { cwd, directory, emit } = options, [verb, name] = args;
+    const allowed = { preview: ['session', 'ledger', 'feedback', 'artifact', 'sources'], import: ['session', 'ledger', 'feedback', 'artifact', 'sources', 'name', 'title', 'expected', 'archive', 'author'], list: [], show: [], source: ['item'], note: ['kind', 'note', 'item', 'line'] };
+    if (!verb || verb === 'help')
+        return emit(SESSION_HELP);
+    if (!Object.hasOwn(allowed, verb) || args.length > (['show', 'source', 'note'].includes(verb) ? 2 : 1))
+        throw Error('unknown session command; use learning session help');
+    for (const key of Object.keys(flags))
+        if (!['state', 'json', 'confirm', 'help', ...allowed[verb]].includes(key))
+            throw Error('unsupported session option: --' + key);
+    if (verb === 'preview' || verb === 'import') {
+        const selections = [];
+        if (flags.session)
+            selections.push({ kind: 'parent', path: resolve(cwd, text(flags.session, '--session')) });
+        for (const kind of ['ledger', 'feedback', 'artifact'])
+            if (flags[kind])
+                selections.push({ kind, path: resolve(cwd, text(flags[kind], '--' + kind)) });
+        if (flags.sources) {
+            const raw = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(learningFile(resolve(cwd, text(flags.sources, '--sources')), 65536)));
+            if (!Array.isArray(raw))
+                throw Error('source selection file must be an array');
+            for (const s of raw) {
+                if (!s || typeof s !== 'object' || typeof s.path !== 'string')
+                    throw Error('invalid source selection');
+                selections.push({ ...s, path: resolve(cwd, s.path) });
+            }
+        }
+        const preview = prepareSessionImport(selections);
+        const summary = { state: 'preview', digest: preview.digest, sources: preview.sources, sessionId: preview.parent.sessionId,
+            userMessages: preview.parent.userMessages, assistantMessages: preview.parent.assistantMessages,
+            executions: preview.attempts.length, childTranscripts: preview.children.length, gaps: preview.gaps,
+            privacy: 'Exact source bytes, potentially sensitive, will be retained privately. Inspect sources first; no automatic redaction or publication.',
+            next: 'Repeat import with --expected ' + preview.digest + ' --confirm after reviewing the selected inputs.' };
+        if (verb === 'preview' || flags.confirm !== true)
+            return emit(summary);
+        if (flags.expected !== preview.digest)
+            throw Error('exact preview digest required; re-preview changed inputs');
+        const label = text(flags.name, '--name'), title = text(flags.title, '--title');
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(label) || title.length > 512)
+            throw Error('bounded session name/title required');
+        let workspace;
+        if (existsSync(directory)) {
+            if (flags.archive || flags.author)
+                throw Error('existing workspace already binds archive and author');
+            workspace = openLearningWorkspace(directory);
+        }
+        else {
+            const archiveRoot = resolve(cwd, text(flags.archive, '--archive for new workspace')), author = text(flags.author, '--author for new workspace');
+            const archiveRelative = relative(directory, archiveRoot);
+            if (!archiveRelative || (!isAbsolute(archiveRelative) && archiveRelative !== '..' && !archiveRelative.startsWith('..' + sep)))
+                throw Error('archive must be outside the workspace journal directory');
+            workspace = createLearningWorkspace(directory, { archiveRoot, author, population: 'pi-session:' + preview.parent.sessionId, scopeDigest: sessionScope(preview.parent, preview.sources.find(s => s.kind === 'parent').sha256) });
+        }
+        const previous = workspace.sessions().find(s => s.name === label);
+        if (previous) {
+            const old = workspace.session(label);
+            if (old.selectionDigest !== preview.digest || old.title !== title)
+                throw Error('session name already bound; use a new name for changed evidence');
+            return emit({ state: 'already-retained', name: label, manifestId: old.manifestId });
+        }
+        const manifestId = retainSessionImport(workspace.configuration().archiveRoot, preview, preview.digest);
+        workspace.bindSession({ name: label, title, manifestId });
+        return emit({ state: 'retained', name: label, manifestId, sources: preview.sources.length, acceptance: 'not-assessed', next: 'learning session show ' + label });
+    }
+    const workspace = openLearningWorkspace(directory);
+    if (verb === 'list')
+        return emit(workspace.sessions());
+    const view = workspace.session(text(name, 'session name'));
+    if (verb === 'show')
+        return emit(flags.json ? view : formatSession(view));
+    const item = Number(flags.item);
+    if (!Number.isSafeInteger(item) || item < 1 || item > view.sources.length)
+        throw Error('select a listed source with --item N');
+    if (verb === 'source')
+        return emit(new TextDecoder('utf-8', { fatal: true }).decode(readRetainedSessionSource(workspace.configuration().archiveRoot, view.manifestId, item - 1)));
+    const kind = text(flags.kind, '--kind'), note = text(flags.note, '--note'), line = Number(flags.line);
+    if (!['finding', 'proposal', 'acceptance', 'context'].includes(kind) || note.length > 4000 || !Number.isSafeInteger(line) || line < 1)
+        throw Error('bounded annotation and evidence line required');
+    if (flags.confirm !== true)
+        return emit({ state: 'confirmation-required', name, item, line, kind, note, meaning: 'operator annotation only; no trust/adoption authority' });
+    return emit(workspace.noteSession(name, { kind: kind, note, item, line }));
+}
+export async function reviewSessionLearning(directory, ui, display) {
+    const w = openLearningWorkspace(directory), name = await ui.select('Retained sessions', w.sessions().map(s => s.name));
+    if (!name)
+        return;
+    const view = w.session(name);
+    await ui.editor('Session assessment — display only', display(formatSession(view)));
+    for (;;) {
+        const choices = view.sources.map((s, i) => (i + 1) + '. ' + s.kind + ': ' + s.path), selected = await ui.select('Complete retained evidence (may contain sensitive text)', [...choices, 'Done']);
+        if (!selected || selected === 'Done')
+            return;
+        const index = choices.indexOf(selected);
+        if (index < 0)
+            throw Error('select a listed retained source');
+        await ui.editor('Exact source — changes discarded', display(new TextDecoder('utf-8', { fatal: true }).decode(readRetainedSessionSource(w.configuration().archiveRoot, view.manifestId, index))));
+    }
+}
+//# sourceMappingURL=session-learning.js.map

package/docs/PRODUCT-GUIDE.md

@@ -1,15 +1,14 @@
 # Factory: work, review, learn
 
-**Product guide for the 0.16.0 release candidate**, paired with pi-daddy **0.27.0**;
-Principal **3.2.0** is unchanged. The prior audited baseline was harness 0.15.0 /
-producer 0.26.1. Harness PR80 is merged and independently approved with green CI;
-source/built cross-package checks passed with synthetic fixtures, not human evidence.
-Canonical release packaging, publication and final installed-flow verification remain
-separate pending gates. After installation, expect `skill-harness --version` **0.16.0**
-and producer package **0.27.0**; check `skill-harness learning help` and loaded Pi resources.
-Do not assume an existing session reloaded because a package was updated. Use a **fresh
-Pi session** when upgrading an already-published immutable dashboard bridge: `/reload`
-cannot replace the old global API. No other running session needs to be stopped.
+**Release candidate: skill-harness 0.17.0**, paired with **pi-daddy 0.27.3**.
+Principal 3.2.0 is unchanged. The session retrospective feature is merged in PR82
+with independent Sol review and green CI. This release adds explicit local session
+import, timeline/usage coverage and evidence-linked notes. The producer adds a
+visible count and toggle for completed ledger history.
+
+Canonical packaging, installed verification and publication are recorded separately
+in the release PR. Use a fresh Pi session after updating the harness: an existing
+immutable dashboard bridge survives reload. Other running sessions need not stop.
 
 ## Who does what?
 
@@ -131,3 +130,61 @@ All learning commands are offline/no-model. Command completion is never a qualit
 Local author attribution and content hashes are not authentication or hostile-owner attestation.
 
 Current requirements and remaining evidence: [STATUS.md](STATUS.md).
+
+## Whole-session retrospective (0.17.0)
+
+Use this after a real task to inspect the conversation, model/thinking settings,
+tool use, individual delegation attempts and provider-reported usage. The importer
+reads only explicitly selected files and never contacts or interrupts an agent.
+
+Start with the terminal CLI (or prefix these arguments with
+"/skill-harness learning" in Pi instead of "skill-harness learning"):
+
+    skill-harness learning session preview --session /absolute/parent.jsonl --ledger /absolute/grants.jsonl
+    skill-harness learning session import --session /absolute/parent.jsonl --ledger /absolute/grants.jsonl --name task --title "Task retrospective" --expected DIGEST_FROM_PREVIEW --confirm --state /private/learning/workspace --archive /private/learning/archive --author operator
+    skill-harness learning session show task --state /private/learning/workspace
+    skill-harness learning session source task --item 1 --state /private/learning/workspace
+
+The first import can create a workspace. For an existing workspace omit --archive
+and --author. Optional --feedback FILE and --artifact FILE retain selected external
+feedback and artifact/source evidence. Use --sources FILE for a JSON array of
+additional selections, for example:
+
+    [{"kind":"child","path":"/absolute/child.jsonl","executionId":"exec:10000000-0000-4000-8000-000000000001"}]
+
+Every source must be a regular, unlinked file: at most 16 files, 8 MiB each,
+32 MiB total; Pi/ledger JSONL is bounded to 4096 records with complete final lines.
+Pi session format v3 and the existing frozen pi-daddy v3 ledger contract are
+supported. Re-preview if any selected bytes change. The ledger association and
+child execution mapping are operator declarations, not authenticated parentage.
+
+**Privacy:** import retains exact original bytes locally, potentially including
+credentials, reasoning, tool arguments or private text present in the source.
+Preview prints paths, hashes and coverage, not a redacted copy. Inspect selected
+inputs before confirming; no scanning, automatic redaction or publication occurs.
+Full-source readback deliberately displays the selected source; terminal control
+characters are escaped for display without altering archived bytes.
+
+Open the existing learning wizard with the same --state path to choose **Import
+session** or **Review sessions**. Editors display evidence; edits are discarded.
+The ordinary producer "/grants learning" bridge also reaches those menu items
+when its current host workspace is already connected. Reading does not reserve
+attention, run a model or change a next-order policy.
+
+Record a finding, proposal, acceptance observation or context note against a
+specific retained source line:
+
+    skill-harness learning session note task --kind proposal --note "Ask for the capability map before implementation; compare this on a later task." --item 1 --line 2 --confirm --state /private/learning/workspace
+
+Notes identify the configured local author. An acceptance note is an operator
+annotation, not an authenticated user approval or qualified comparison.
+The timeline is chronological and may include abandoned branches; excerpts are
+labelled. It does not reconstruct the active branch or verify a test claimed in prose.
+Child usage and missing evidence are reported separately; totals are provider
+observations, not billing or a complete parent-plus-child cost.
+
+This slice makes sessions reviewable. It does **not** automatically generate or
+measure skill/tool/instruction improvements. A later experiment still needs a
+frozen task and candidate, appropriate independent assessment and actual retained
+measurements before claiming faster or equally good output. Existing adoption
+supports its documented model/effort policy scope only; annotations do not expand it.

package/docs/STATUS.md

@@ -1,10 +1,21 @@
-# Factory requirement register — 0.16.0 release preparation
+# Factory requirement register
 
 Current entry point: [PRODUCT-GUIDE.md](PRODUCT-GUIDE.md). The dated
 [CURRENT.md](CURRENT.md), build reports and transport decisions are retained history,
 not current instructions to supply manifests or judge engineering repairs.
 
-## Baseline and candidate
+## 0.17.0 release candidate — session learning
+
+Adds explicit Pi-session import, exact private retention, chronological evidence,
+per-execution delegation history, parent/child usage coverage, and line-bound
+operator annotations through the existing CLI/Pi learning workspace. No model
+calls, automatic acceptance, calibrated improvement or expanded adoption authority.
+See the whole-session section of PRODUCT-GUIDE.md. Feature PR82 is merged with independent review and green CI. Release metadata
+pairs harness 0.17.0 with producer 0.27.3; canonical publication and installed user
+testing remain separate. Entire-session optimization and measured skill/tool variants remain
+follow-up work.
+
+## Historical 0.16.0 release preparation
 
 Release pair: **skill-harness 0.16.0 / pi-daddy 0.27.0**; Principal 3.2.0 is unchanged.
 The prior audited baseline was harness 0.15.0 (`a725579`) / producer 0.26.1 (`93a9b01`).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@skill-harness/cli",
-    "version": "0.16.0",
+    "version": "0.17.0",
     "description": "skill-harness CLI — run, grade, review, and lint agent-skill scenarios on the pi harness",
     "type": "module",
     "license": "MIT",
@@ -46,7 +46,7 @@
         "prepack": "node ../../scripts/release-pack.mjs --guard"
     },
     "dependencies": {
-        "@skill-harness/core": "0.16.0",
-        "@skill-harness/adapters": "0.16.0"
+        "@skill-harness/core": "0.17.0",
+        "@skill-harness/adapters": "0.17.0"
     }
 }