@raquezha/notrace 0.0.4 → 0.0.5

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @raquezha/notrace
 
+## 0.0.5
+
+### Patch Changes
+
+- 6eac69d: Relocate core configuration files (`mindsets.json`, `settings.json`, `AGENTS.md`) to a dedicated `config/` directory for better maintainability and a cleaner repository root. Updated `bootstrap.sh` and shell integration to support the new layout.
+- c19a93a: Add a machine-readable `notrace.json` run record alongside the existing HTML report to normalize captured session/task metadata, activity metrics, and evidence for future retrospective and comparison workflows.
+
 ## 0.0.4
 
 ### Patch Changes

package/README.md

@@ -1,23 +1,36 @@
 # notrace
 
-Phase 0 / POC local-first interactive HTML Trace Viewer for the Pi Coding Agent. It captures execution traces for workflow debugging — LLM calls, tool executions, token usage, costs — and writes an interactive HTML report to your active task workspace at session end.
+Phase 0 / POC local-first trace capture for the Pi Coding Agent. It captures execution traces for workflow debugging — LLM calls, tool executions, token usage, costs — and writes both an interactive HTML report and a machine-readable `notrace.json` run record to your active task workspace at session end.
 
 > **Security warning:** notrace is local-first and now redacts common secrets by default, escapes report rendering, blocks network access in generated reports, and writes private report files. Reports can still contain sensitive prompts, tool payloads, outputs, and local paths. Do not publish generated reports.
 
+## Boundary with RPIV
+
+The relationship is intentionally optional both ways:
+
+- **notrace without RPIV**: should work; notrace-owned artifacts belong under `.notrace/`
+- **RPIV without notrace**: should work; `WORK.md` remains the source of truth without any notrace dependency
+- **together**: RPIV `WORK.md [LOG]` may reference notrace artifacts, but `.workflow/` should not own them
+
+Neither package should require the other to function.
+
 ## Features
 
 - **Session timeline**: Every turn, tool call, and LLM completion rendered as an expandable card
 - **Metrics dashboard**: Total tokens, input/output split, cache reads, cost (USD), duration
-- **Clickable `file://` link**: Report path printed to console at session end for instant browser access
-- **Active task aware**: Writes the report into `.workflow/tasks/<task>/notrace.html` when a task is active
+- **Machine-readable run record**: Normalized `notrace.json` sidecar for future retrospective/compare flows
+- **Clickable `file://` links**: Artifact paths printed to console at session end for instant browser access
+- **Workdir aware**: notrace-owned artifacts are planned to live under `.notrace/` for the root execution directory
+- **RPIV attachment**: When a task has a `WORK.md`, notrace appends artifact/review references into `[LOG]`
 - **HTML report**: Self-contained/offline report with a restrictive CSP and no remote font/network loads
-- **Safer defaults**: Secret-key/value redaction, bounded payload sizes, metadata-only mode, private file permissions, and `.workflow`-confined report writes
+- **Safer defaults**: Secret-key/value redaction, bounded payload sizes, metadata-only mode, private file permissions, and `.workflow`-confined artifact writes
 
 ## Output
 
 ```
-🔍 [notrace] Observability report generated:
-📂 file:///path/to/.workflow/tasks/my-task/notrace.html
+🔍 [notrace] Observability artifacts generated:
+📂 file:///path/to/.notrace/sessions/<session-id>/notrace.html
+📂 file:///path/to/.notrace/sessions/<session-id>/notrace.json
 ```
 
 ## Usage
@@ -36,6 +49,46 @@ pi --dev
 npm install -g @raquezha/notrace
 ```
 
+## Add a human review
+
+```bash
+npm run review:notrace -- path/to/notrace.json \
+  --outcome partial \
+  --friction high \
+  --lesson "Headroom reduced tokens but needed manual steering." \
+  --next-change "Try same task with RepoScry enabled."
+```
+
+This writes an adjacent review sidecar. For normal runs that means `notrace.review.json` next to `notrace.json`.
+
+If the run is attached to an RPIV task folder with `WORK.md`, the review is also logged into that task's `[LOG]` section as a reference to the notrace artifact.
+
+Review fields:
+
+- `outcome`: `success`, `partial`, `failed`, `abandoned`, `inconclusive`
+- `friction`: `low`, `medium`, `high`
+- `lesson`: short human conclusion
+- `nextChange`: what to try next run
+
+## Compare two runs
+
+```bash
+npm run compare:notrace -- \
+  path/to/baseline/notrace.json \
+  path/to/candidate/notrace.json
+```
+
+This prints a small retrospective diff for:
+
+- total/input/output tokens
+- duration
+- LLM calls
+- tool calls
+- tool errors
+- total cost
+- model/provider mix
+- review sidecar outcome/friction/lesson when present
+
 ## Capture controls
 
 By default, notrace uses `NOTRACE_CAPTURE=redacted`: it captures useful payloads but redacts common secret keys/values and truncates very large values.