skill-harness 0.16.0 → 0.17.0

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",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Test/optimize loop for agent skills — run spec'd scenarios on pi, LLM-judge, score, review, re-run",
   "type": "module",
   "keywords": [
@@ -34,7 +34,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@skill-harness/cli": "0.16.0",
+    "@skill-harness/cli": "0.17.0",
     "typebox": "^1.1.38"
   },
   "repository": {