@tryinget/pi-agent-vent 0.1.0

package/docs/project/2026-05-21-agent-vent-implementation-plan.md

@@ -0,0 +1,66 @@
+---
+summary: "Implementation plan for the first pi-agent-vent package slice."
+read_when:
+  - "Continuing or reviewing the initial agent vent implementation."
+system4d:
+  container: "Implementation slice for local agent vent capture."
+  compass: "Ship a minimal, tested, local-first tool without authority drift."
+  engine: "Scaffold -> domain/store core -> Pi extension surface -> docs -> validation."
+  fog: "Overbuilding escalation workflows before local records prove useful."
+---
+
+# Implementation plan — pi-agent-vent v0.1
+
+## Scope
+
+Create a new simple-package monorepo package from `pi-extensions-template` and replace scaffold placeholders with a real local agent vent tool.
+
+## Acceptance criteria
+
+- Package exists at `packages/pi-agent-vent` with tracked `.copier-answers.yml` and template-aligned metadata.
+- `agent_vent` custom tool supports `record`, `summary`, `list`, and `path` actions.
+- `/agent_vent` command supports human-readable `help`, `summary`, `list`, and `path` inspection, with `/agent-vent` retained as a compatibility alias.
+- Durable data is append-only JSONL at `~/.pi/agent/agent-vent/vents.jsonl` or `PI_AGENT_VENT_DIR`.
+- Records are minimized, schema-versioned, and redacted for common secret patterns.
+- Recurrence grouping and candidate-incident heuristics are implemented in testable core code.
+- Package README, engineering override, vision/foundation docs, and root package maps describe the real behavior.
+- Root release-please component config is synchronized from package metadata.
+- `pi-toolbox-discovery` catalog exposes an `agent_vent` diagnostic bundle without moving vent ownership into ASC/self.
+- `npm run check` passes for `packages/pi-agent-vent`.
+
+## Implementation steps
+
+1. Generate package scaffold with `copier copy --trust --vcs-ref HEAD` from `~/ai-society/softwareco/owned/pi-extensions-template` in `simple-package` mode.
+2. Add core module `src/vent-store.js`:
+   - category/severity vocabularies;
+   - redaction and recurrence-key normalization;
+   - append/read JSONL store helpers;
+   - grouping, candidate-incident, and formatting helpers.
+3. Replace `extensions/agent-vent.ts` scaffold command:
+   - register `agent_vent` custom tool with clear prompt guidelines;
+   - register `/agent_vent` inspection command plus `/agent-vent` compatibility alias;
+   - keep all storage local; avoid network and owner-surface writes.
+4. Add `tests/vent-store.test.js` for redaction, record creation, JSONL round-trip, and summary grouping.
+5. Update package metadata and docs:
+   - `package.json` description/keywords/files;
+   - `README.md` quickstart and data/privacy contract;
+   - `docs/engineering.local.md` selected disciplines and package-specific deltas;
+   - `docs/project/vision.md`, `foundation.md`, and `extension-sop.md`;
+   - `next_session_prompt.md` if needed.
+6. Update root and cross-package discovery docs:
+   - `README.md` package list and routing;
+   - `README.terse.md` package map;
+   - `pi-toolbox-discovery` catalog/docs/tests for the `agent_vent` bundle;
+   - ASC/self capability docs to point at `agent_vent` as a separate companion when relevant;
+   - root release-please config/manifest via `node ./scripts/release-components.mjs sync`.
+7. Validate:
+   - `npm install` in the package;
+   - `npm run check` in the package;
+   - optionally `node ./scripts/release-components.mjs validate` at root.
+
+## Deferred work
+
+- Confirmation-gated delete/export commands.
+- Rich TUI summary view.
+- Optional AK/GitHub escalation helpers that create draft text only, never silent mutations.
+- Team-shared sink after consent, retention, identity, and sync semantics are designed.

package/docs/project/extension-sop.md

@@ -0,0 +1,52 @@
+---
+summary: "Lifecycle SOP for extension delivery and maintenance."
+read_when:
+  - "Planning, implementing, verifying, releasing, or maintaining extension work."
+system4d:
+  container: "End-to-end extension operating procedure."
+  compass: "Consistent quality from idea to maintenance."
+  engine: "plan -> implement -> verify -> release -> maintain."
+  fog: "Unknowns resolved through incremental validation loops."
+---
+
+# Extension SOP
+
+## 1) Plan
+
+- Define scope and acceptance criteria.
+- Read [Agent vent design](2026-05-21-agent-vent-design.md) before changing tool behavior or storage.
+- Run `npm run docs:list` and read docs matching your task domain.
+- Capture dated RFCs, runbooks, and evidence/progress notes in `docs/project/`.
+- Capture adopted architecture decisions in `docs/adr/`.
+- Confirm privacy, authority-boundary, storage, and dependency risks.
+
+## 2) Implement
+
+- Build in small commits.
+- Keep command/tool behavior explicit.
+- Keep pure recurrence/redaction/store behavior in `src/vent-store.js` with `node:test` coverage.
+- Do not add network calls, telemetry, AK mutations, GitHub mutations, or incident creation without a new design.
+- Update docs as behavior changes.
+
+## 3) Verify
+
+- Run `npm run check`.
+- Confirm tests cover changed redaction, recurrence, JSONL, and candidate-incident behavior.
+- Validate prompt templates if changed.
+- For live behavior, install the package into Pi, `/reload`, then verify `/agent_vent help` or a safe `agent_vent` call.
+
+## 4) Release
+
+- Run `npm run release:check` (or `npm run release:check:quick` for artifact-only CI mode).
+- Confirm GitHub Actions settings allow marketplace actions and PR creation by workflows.
+- Use release-please PR flow for versioning/changelog updates.
+- For first-time npm packages, follow [trusted-publishing.md](./trusted-publishing.md); if npm requires bootstrap before trusted publishing can be bound, perform that one-time operator step outside CI before returning to OIDC-only publishing.
+- Publish from GitHub release after publish workflow checks pass.
+- Sync extension to live pi when needed.
+
+## 5) Maintain
+
+- Monitor regressions and user feedback.
+- Review whether candidate-incident heuristics are noisy or too quiet.
+- Re-run validation after dependency/script changes.
+- Keep `README.md` and `next_session_prompt.md` current.

package/docs/project/product-posture.md

@@ -0,0 +1,191 @@
+---
+summary: "Product posture for pi-agent-vent: promise, maturity, trust gates, boundaries, and next bets."
+read_when:
+  - "Before choosing the next pi-agent-vent product or implementation slice."
+  - "When deciding whether vent review, escalation drafting, retention, or routing belongs in pi-agent-vent."
+  - "When aligning pi-agent-vent with ASC/self, toolbox, AK, GitHub, incidents, or evidence surfaces."
+type: "reference"
+system4d:
+  container: "Package-local product posture for agent frustration diagnostics and operator review."
+  compass: "Make recurring agent pain actionable without turning local diagnostics into authority."
+  engine:
+    invariants:
+      - "Capture minimized local vents before they disappear."
+      - "Group recurrence and route review without automatic escalation."
+      - "Keep tasks, issues, incidents, evidence, and publication with their owner surfaces."
+  fog:
+    risks:
+      - "A convenient vent log can become hidden incident/task/evidence authority."
+      - "Raw logs or private payloads can leak into diagnostic records."
+      - "Noisy one-off complaints can bury recurring maintenance signal."
+---
+
+# Product posture — `@tryinget/pi-agent-vent`
+
+## Vision relation
+
+The package north star lives in [vision.md](./vision.md). This posture file is the current bridge from that vision into promise, maturity, trust gates, boundaries, strategic line, and next product bets.
+
+## Product promise
+
+`pi-agent-vent` turns repeated agent frustration into a local, reviewable maintenance inbox.
+
+Short form:
+
+```text
+surface pain; review before authority
+```
+
+## Primary users
+
+- Pi operators who want recurring agent friction surfaced instead of lost in chat history.
+- Controller agents that need a safe place to record repeated tool/runtime/workflow pain.
+- Package/runtime maintainers reviewing patterns before deciding whether to file issues or tasks.
+- Future adapter authors that may generate human-approved owner-surface draft text.
+
+## Job to be done
+
+When an agent keeps hitting the same bug, missing affordance, brittle workflow, context-loss pattern, or tool failure, I want it captured locally, grouped with similar observations, and presented for operator review without silently creating incidents, tasks, issues, evidence, or telemetry.
+
+## Current product maturity
+
+- maturity: `local diagnostic alpha, review-and-retention safety hardened; privacy, review-command, outcome-follow-up, review-filter, review-compare, follow-up-scope, export-scope, export-follow-up, review-decision-legibility, destructive-selection, retention-history, public-contract parity, unpacked-artifact contract, installed-command smoke, installed shadow registered-tool smoke, and release-metadata alignment membranes verified`
+- current capability baseline: local append-only vent capture with optional local tool/package facets, recurrence grouping, local facet summary, local operator review queue with fail-closed-before-store-read command syntax and read-only category/tag/tool/package facet filters, read-only per-state review outcome follow-up buckets, read-only cross-state review comparison without archive/restore tokens, explicit derived local decision-posture projections, curation-aware recurrence resolution for review-state commands and record feedback, filter-preserving supported follow-up commands including record/state-scoped facet export, export-local-follow-up guidance without archive/restore tokens, read-only reviewed-group retention candidate planning without archive tokens, read-only retention receipt history with rollback-candidate restore command reconstruction, advisory human-review hints, quoted state-aware local next-action guidance that round-trips legacy recurrence keys, bounded representative-sample detail, review-state events, append-only recurrence curation projections with remove/undo events, diagnostic-state load membrane with privacy metadata recomputation, facet-aware draft-only owner-surface text generation, lifecycle stats/export projections, lock/hash-guarded confirmation-gated retention archive/restore with duplicate-id-safe record selection, local backup receipts, and rollback safeguards, advisory candidate-incident heuristic, redaction/minimization, `/agent_vent` inspection command, toolbox discovery, ASC/self companion routing, self-contained public-artifact validation for advertised package scripts/docs, no-auth installed-artifact shadow registered-tool `agent_vent path` release smoke with isolated npm prefix/cache and vent storage, installed-tarball local-path package-discovery `/agent_vent path` release smoke with isolated Pi settings, npm prefix/cache, and vent store, explicit local `npm:<tarball>` install-source validation, and package-local release metadata alignment checks for `repository.directory`, `x-pi-template.workspacePath`, and `x-pi-template.releaseComponent`
+- release posture: first publishable package release at `0.1.0`; npm package not yet published at time of first release checks; unpacked tarball contract has artifact-local `npm install && npm run check` proof, artifact-only quick release checks now install the packed tarball into an isolated npm prefix and execute the installed artifact's registered `agent_vent` tool `action=path` through a shadow import against isolated vent storage without Pi auth, full release checks additionally validate local `npm:<tarball>` as the install source and smoke the installed packed artifact through local-path Pi package discovery by running `/agent_vent path` with isolated Pi settings, isolated npm prefix/cache, and isolated vent storage, and package-local structure validation now fails closed on release metadata drift against `.copier-answers.yml`; the remaining release gap is real npm/GitHub provenance publication, not local artifact/package-loading confidence
+- current strategic line: harden the local review workflow before adding owner-surface escalation adapters
+
+## Product success criteria
+
+The package is product-healthy when:
+
+1. an agent can record a minimal vent without leaking secrets or raw user payloads;
+2. an operator can see the top recurring pain points quickly;
+3. recurrence groups separate repeated maintenance signal from one-off complaints;
+4. candidate-incident language remains advisory and never implies an incident was declared;
+5. review state, retention, export, and deletion behavior are explicit before data volume grows;
+6. escalation surfaces generate drafts only and require human approval before owner-system mutation;
+7. ASC/self, toolbox, AK, GitHub, incident, and evidence boundaries remain explicit.
+
+## Current landed capability baseline
+
+The package currently owns:
+
+- `agent_vent` tool with `record`, `summary`, `list`, `path`, `facets`, `review`, `outcomes`, `compare`, `set_review`, `curate`, `draft`, `stats`, `export`, and `retention` actions, including read-only local facet filters for review queues, outcome follow-up, cross-state comparison, retention-candidate planning, and read-only retention receipt history;
+- `/agent_vent` command for local inspection and recurrence review, with `/agent-vent` retained as a compatibility alias;
+- schema-versioned local JSONL storage at `~/.pi/agent/agent-vent/vents.jsonl`, local review events at `~/.pi/agent/agent-vent/review-events.jsonl`, local curation events at `~/.pi/agent/agent-vent/curation-events.jsonl`, local retention receipts at `~/.pi/agent/agent-vent/retention-events.jsonl`, and retention backups under `~/.pi/agent/agent-vent/backups/`, overridable via `PI_AGENT_VENT_DIR`;
+- conservative redaction for common secret/token/password shapes;
+- recurrence key derivation and grouping;
+- advisory candidate-incident heuristic based on repetition/severity;
+- malformed JSONL line tolerance, oversized-line/file guards, read-time schema normalization/redaction with privacy metadata recomputation, and semantic curation quarantine during reads;
+- package-local tests for redaction, privacy metadata recomputation, record creation, JSONL round trip, recurrence summaries, local facet summaries, review filtering/detail/hints/next-action guidance, review decision-posture projection, curation-aware recurrence resolution for review state and record feedback, outcome follow-up buckets, explicit per-state outcome/compare limits, read-only cross-state comparison without archive/restore tokens, filter-preserving compare follow-ups and record/state-scoped facet export, export follow-up command quoting without archive/restore tokens or owner-routing claims, read-only retention-candidate planning without archive tokens, read-only retention-history restore-candidate reconstruction without active-store reads, fail-closed review/outcome/compare/export/retention-candidate/history command syntax before store reads (including empty filters), quoted legacy recurrence-key command round trips, review/curation/draft/retention projections, hostile legacy JSONL redaction, curation-cycle quarantine, file/line-size guards, confirmation-gated archive/restore, duplicate-id retention selection, complete token-input requirements, stale token/restore failures, path-escape/symlink backup failures, receipt-failure rollback, stale lock cleanup, quoted rollback commands, and extension registration;
+- `pi-toolbox-discovery` integration through the same-named `agent_vent` bundle;
+- ASC/self capability-routing text that points frustration diagnostics to `agent_vent` instead of self/ASC state.
+
+## Product non-goals
+
+`pi-agent-vent` must not become:
+
+- an automatic incident declaration system;
+- a direct AK task/evidence writer;
+- a GitHub issue creator without explicit human approval;
+- a telemetry collector or team sync daemon by default;
+- a replacement for ASC/self operational introspection;
+- a canonical evidence, publication, KES, Prompt Vault, or ROCS owner;
+- a dumping ground for ordinary progress updates or emotional noise with no maintenance signal.
+
+## Trust gates
+
+A vent-derived recommendation is trustworthy only when:
+
+1. **Minimization** — summary/evidence are short and avoid raw logs or private payloads.
+2. **Privacy** — known secret shapes are redacted and the operator still treats records as local diagnostic user data.
+3. **Recurrence** — repeated groups are visible by stable recurrence key rather than just timestamp order.
+4. **Review state** — operator review status is explicit before escalation.
+5. **Owner seam** — draft escalation names the target owner surface but does not mutate it automatically.
+6. **Boundary report** — output says what was not done: no task, issue, incident, evidence, telemetry, or ASC/self state mutation.
+
+## Current strategic line
+
+Prioritize review quality over escalation power.
+
+The highest-leverage product line is:
+
+```text
+local vent capture -> operator review queue -> draft-only owner routing -> human-approved escalation
+```
+
+Do not add automatic GitHub/AK/incident writers. The local facet summary, fail-closed facet-filtered local review queue, per-state review outcome follow-up, read-only cross-state review comparison, explicit local decision posture, filter-preserving supported follow-up commands, record/state-scoped facet export, export-local-follow-up guidance, read-only retention-candidate planning, read-only retention-history receipt projection, advisory human-review hints, quoted state-aware next-action guidance, bounded review-detail samples, curation-aware recurrence resolution, facet-aware draft-only routing, retention archive/restore, and privacy membrane now have package validation; remaining product depth should refine operator comprehension only where it does not broaden authority. Hard-delete beyond backup-backed archive is decided out of v0.1: permanent removal remains operator-owned filesystem/data-lifecycle control unless a future decision accepts a narrower purge design.
+
+Current proof: `npm run check` passes with 80 package tests plus release dry-run, packaged Markdown link checks, an unpacked-tarball `npm install && npm run check` contract smoke that runs the packaged fallback gate from inside the artifact, an artifact-only no-auth installed shadow registered-tool `agent_vent path` no-store-read smoke, and a full installed-tarball local-path package-discovery `/agent_vent path` smoke using isolated `PI_CODING_AGENT_DIR`, isolated npm prefix/cache, and `PI_AGENT_VENT_DIR`; docs strict check passes, `git diff --check` passes, and historical dogfood covered curation resolution, export posture, and live `pi install` reload behavior. Validation now covers quoted rollback commands, complete retention token inputs, stale-token/stale-restore failures, path-escape/symlink backup failures, receipt-failure rollback, retention-history restore-candidate reconstruction without active-store reads, export follow-up command quoting without archive/restore tokens or owner-routing claims, review decision-posture projection without resolution/assignment/evidence/incident claims, curation-aware recurrence resolution for review state and record feedback, stale lock cleanup, backup restore, duplicate-id-safe retention archive selection, retention-candidate planning without archive tokens, retention-candidate and compare tool-schema/command-contract parity, filter-preserving supported compare follow-ups, record/state-scoped facet export without owner-routing claims, mixed-group export non-broadening, empty export filters failing closed before store reads, tag/facet privacy metadata recomputation, hostile legacy JSONL privacy recomputation, fail-closed review/outcome/compare/export/retention-candidate/history syntax before store reads including empty filters, invalid review category/state handling, explicit per-state outcome/compare limits, quoted legacy recurrence-key command round trips, tool-only maintainer-note hints, reference-style packaged Markdown links, fail-closed `files[]` wildcard handling, public artifact script viability, release metadata alignment with `.copier-answers.yml`, local `npm:<tarball>` install-source validation, isolated installed-command smoke output, local-path package-discovery loading from the installed artifact, shadow registered-tool execution from the installed artifact, and registered-tool `path` no-store-read/no-store-write behavior with symlinked active stores.
+
+## Next product bets
+
+### Bet 1 — Operator review queue — landed baseline
+
+The local review surface turns recurrence groups into an inbox:
+
+```text
+new -> acknowledged | dismissed | escalation_drafted
+```
+
+The landed baseline lists groups by recurrence priority, supports fail-closed read-only category/tag/tool/package facet filters, shows advisory human-review hints, shows explicit local decision posture, shows quoted state-aware local next-action guidance that remains safe for legacy recurrence keys, shows representative summaries/sample ids through recurrence projections, offers bounded read-only representative-sample expansion for a single group, records append-only local review-state events without mutating owner systems, provides read-only outcome follow-up buckets for `new`, `acknowledged`, `dismissed`, and `escalation_drafted` groups, compares review-state buckets with filter-preserving supported follow-up commands, exports filtered local diagnostic projections with safe local follow-up guidance, and supports retention receipt history. Remaining product depth is contract-parity polish only unless fresh discovery shows a concrete gap; owner-system mutation stays human-approved and external.
+
+### Bet 2 — Retention, export, and deletion controls — non-destructive baseline landed
+
+Make local data lifecycle explicit before records accumulate:
+
+- show store size/count — landed via `stats`;
+- export JSON or markdown diagnostic projections — landed via `export`;
+- list reviewed groups for archive planning — landed through read-only `retention candidates` with state/facet filters, exact preview commands, and no archive confirmation tokens;
+- archive reviewed groups with confirmation — landed through `retention preview|archive` with exact store/review/curation-hash tokens, local lock coordination with vent appends, duplicate-id-safe selected-record removal, local backups, append-only receipts, and receipt-failure rollback;
+- rediscover archive/restore receipts — landed through read-only `retention history`, which reconstructs rollback-candidate restore commands from archive receipts without reading active vents/backups and without implying rollback already happened;
+- restore archived groups from package backups — landed through `retention restore` with derived exact tokens, real backup-directory containment, current-store hash checks, and quoted rollback command support;
+- delete reviewed groups without backup — decided out of the v0.1 package surface by [ADR 2026-05-22](../adr/2026-05-22-agent-vent-retention-delete-policy.md); archive remains the destructive package lifecycle baseline;
+- document backup/restore posture — covered by explicit paths, lifecycle stats, and retention command output;
+- keep corruption behavior fail-soft and visible — landed for malformed lines, oversized lines, invalid entries, semantic curation quarantine, and fail-closed symlink/oversized-file checks.
+
+### Bet 3 — Recurrence curation — merge/rename baseline landed
+
+Improve signal quality without over-modeling:
+
+- merge recurrence groups — landed as append-only local curation projection events;
+- rename recurrence keys — landed as append-only local curation projection events;
+- undo local curation aliases — landed as append-only `remove` curation events;
+- dismiss noisy groups — already covered by local review state;
+- show top categories/tags/tools/packages — landed as read-only local facet summaries; owner hints are intentionally local diagnostic/draft hints only, not package-owned routing truth;
+- preserve append-only source records while treating curated summaries as local projections — landed; raw vents are not rewritten.
+
+### Bet 4 — Draft-only owner escalation — landed baseline
+
+Generate human-reviewable drafts for likely owner surfaces:
+
+- GitHub issue draft — landed;
+- AK task draft — landed;
+- incident review draft — landed;
+- package maintainer note — landed.
+
+These drafts do not submit automatically. The package prepares local text, local diagnostic facet hints, and exact next-step guidance; the owner system performs any mutation only after explicit human/operator action. Producing a draft does not automatically mark review state; operators can set `escalation_drafted` explicitly when useful. This clarified the provenance seam: draft text is a local diagnostic projection, not evidence, task truth, issue truth, incident truth, or owner-routing truth.
+
+## Next frontier guidance
+
+The next highest-leverage slice should assume the facets/review/outcomes/compare/filter/hint/detail/draft/curation/retention-candidate/retention-history/retention-archive/export/export-follow-up/review-decision-posture and public-runtime-artifact smoke membranes are the baseline and should not broaden authority. Retention now has transaction-oriented safeguards (store/review/curation-hash tokens, append/archive locking, duplicate-id-safe selected-record removal, stale-lock cleanup, receipt-failure rollback, derived restore tokens, realpath backup containment, quoted rollback commands, retention-history receipt rediscovery, and stale-restore checks) plus read-only reviewed-candidate, receipt-history, export follow-up, decision-posture, and cross-state comparison surfaces that preserve supported follow-up scope without owner-surface mutation. Local facet labels, filters, curation aliases, outcome states, comparison buckets, hints, generated commands, export snapshots, history receipts, decision posture, and draft text are diagnostic projections only; filtered export is record/state-scoped and is not evidence, publication, owner routing, or owner assignment. The clarified source-owner seam is that export/history/review scope may focus local diagnostic data but cannot make that data canonical evidence or publication, and curation-aware recurrence keys are local projection identity rather than owner-system identity; local release smoke and release metadata checks may prove package-loading and repo-local metadata alignment but cannot prove npm publication/provenance; Prompt Vault, AK, GitHub, incident, evidence, ROCS, ASC/self, toolbox surfaces, and npm publication/provenance remain separate owners. The latest contract-parity frontier is maintaining source checkout versus public runtime artifact proof together: `npm pack` contents, README/package scripts, packaged docs, release checks, installed package settings, isolated npm installation state, no-auth installed shadow registered-tool smoke, installed command smoke, local tarball install-source validation, local-path Pi package-discovery smoke, and release metadata alignment must be validated as consumed, not only from the monorepo checkout. Discovery showed local `npm:<tarball>` is useful as a Pi install input but is not a documented runtime package-discovery source like `npm:@scope/pkg@1.2.3`; the package now fails closed against falsely claiming that proof. The remaining release frontier is the external publish/provenance workflow, not more unlabeled local package smoke. npm publish, AK/GitHub/incident/evidence creation, and hard-delete remain out of scope unless explicitly authorized. Preserve the contract-parity lesson from this iteration: command grammar, LLM tool schema, README examples, posture docs, package `files[]`, release checks, artifact-local scripts, smoke scripts, and tests must change together; unknown syntax must fail closed before store reads even when values are empty. Do not spend the next slice on hard-delete unless a new decision explicitly supersedes [ADR 2026-05-22](../adr/2026-05-22-agent-vent-retention-delete-policy.md).
+
+## Ownership map
+
+| Concern | Owner |
+|---|---|
+| Local vent records, recurrence grouping, review queue/outcome projections, local curation events, retention receipts/backups, draft text projections, diagnostic-state membrane | `packages/pi-agent-vent` |
+| Tool discovery/activation | `packages/pi-toolbox-discovery` |
+| Operational self mirror and subagent runtime | `packages/pi-autonomous-session-control` |
+| Durable task/evidence/direction truth | AK / society authority surfaces |
+| GitHub issues and repo issue policy | Target repo / GitHub owner workflow |
+| Real incident declaration | Incident owner surface / human operator |
+| Prompt/procedure reuse | Prompt Vault |
+| Shared ontology/controlled semantics | ROCS / ontology owner repos |
+
+## Read map
+
+- Vision / north star: [vision.md](./vision.md)
+- Design: [2026-05-21-agent-vent-design.md](./2026-05-21-agent-vent-design.md)
+- Implementation plan: [2026-05-21-agent-vent-implementation-plan.md](./2026-05-21-agent-vent-implementation-plan.md)
+- Extension SOP: [extension-sop.md](./extension-sop.md)

package/docs/project/trusted-publishing.md

@@ -0,0 +1,53 @@
+---
+summary: "Trusted publishing notes for monorepo package components."
+read_when:
+  - "Configuring npm OIDC trusted publishing for monorepo package releases."
+  - "Debugging release-please or publish workflow failures in monorepo CI."
+system4d:
+  container: "Monorepo release automation reliability notes."
+  compass: "Use OIDC safely with component-aware release behavior."
+  engine: "Configure root workflows -> validate package metadata -> release -> verify."
+  fog: "Most failures come from root workflow policy mismatch or component map drift."
+---
+
+# Trusted publishing runbook (monorepo package mode)
+
+## Baseline assumptions
+
+- Release automation lives at monorepo root.
+- Package release is component-scoped (release-please component mode or equivalent).
+- Publish workflow uses npm OIDC trusted publishing (no long-lived npm token in CI).
+- If npm registry policy requires first-package bootstrap before trusted publishing can be bound, perform that one-time operator step outside CI, then return CI to OIDC-only publishing.
+
+## Package-level requirements
+
+- `package.json.repository.url` must point to monorepo git URL.
+- `package.json.repository.directory` must match package workspace path.
+- `x-pi-template` metadata should align with root component mapping:
+  - `workspacePath`
+  - `releaseComponent`
+  - `releaseConfigMode` (default/root-managed baseline: `component`; `none` is an explicit opt-out only)
+
+## Root workflow expectations
+
+- Root `release-please` workflow must keep component map aligned with package metadata when `releaseConfigMode` is `component`.
+- Publish workflow should run npm >= 11.5.1 for trusted publishing compatibility.
+- Actions policy + permissions at repo level must allow release/publish workflows.
+
+## Common failure modes
+
+1. Component key drift between package metadata and root release config.
+2. Wrong `repository.directory` causing provenance verification failures.
+3. Workflow permissions set to read-only in monorepo settings.
+4. Missing npm trusted publisher binding for monorepo repository/workflow.
+
+## Verification checklist
+
+- Package passes `npm run release:check:quick` in workspace.
+  - Quick checks are artifact-only and require no Pi auth: they verify `npm pack`, packaged Markdown links, artifact-local `npm install && npm run check`, isolated npm installation of the packed tarball, and installed shadow registered-tool `agent_vent path` execution against isolated vent storage.
+- Package passes `npm run release:check` where live Pi smoke is available.
+  - Full checks additionally install the tarball through isolated Pi package settings, validate local `npm:<tarball>` as the install source, and smoke `/agent_vent path` through local-path package discovery of the installed artifact. Pi package docs define npm settings sources as package specs such as `npm:@scope/pkg@1.2.3`; local tarball paths are validated here as install inputs, not claimed as a runtime package-discovery source.
+- Root release workflow can produce/update component release PR.
+- Publish workflow completes with `npm publish --provenance --access public` for package.
+
+Local release checks prove artifact/package-loading behavior only. npm trusted publisher binding, GitHub release execution, and provenance publication remain external owner-surface facts.

package/docs/project/vision.md

@@ -0,0 +1,70 @@
+---
+summary: "Product and technical vision for pi-agent-vent."
+read_when:
+  - "Defining or revisiting project direction."
+  - "Deciding whether a venting/review/escalation feature belongs in pi-agent-vent."
+system4d:
+  container: "Project north-star statement for local agent frustration capture and operator review."
+  compass: "Turn recurring agent pain into reviewable maintenance signal without authority drift."
+  engine: "Capture minimized vent -> group recurrence -> review in an operator inbox -> draft owner-surface escalation only after human choice."
+  fog: "The package fails if vents become noisy, privacy-risky, silently escalated, or mistaken for real incidents/tasks/evidence."
+---
+
+# Vision
+
+`pi-agent-vent` turns repeated agent frustration into a small, local maintenance inbox.
+
+Agents regularly encounter the same brittle workflows, missing affordances, tool/runtime failures, context-loss patterns, and long-lived bugs. Those observations usually disappear into chat history or final-answer omissions. This package gives them a safe local place to say “this keeps hurting,” then helps an operator review the pattern before deciding whether any owner surface should act.
+
+The product promise is:
+
+```text
+capture local pain -> make recurrence visible -> let a human decide escalation
+```
+
+## Product principles
+
+- **Local first:** records stay on the operator machine by default.
+- **Minimal by default:** summarize friction; do not copy secrets, private user payloads, or long logs.
+- **Review before escalation:** vent records become an operator-reviewable inbox, not automatic tasks or incidents.
+- **Advisory, not authoritative:** candidate incidents are review prompts, not incident declarations.
+- **Human-owned escalation:** AK tasks, GitHub issues, evidence, incidents, and publication belong to their owner surfaces.
+- **Cheap to inspect:** `/agent_vent summary`, `/agent_vent list`, and `/agent_vent path` should explain the state quickly.
+- **Coherent naming:** user-facing runtime surfaces should prefer `agent_vent`; package/release filesystem names may remain `pi-agent-vent` where ecosystem conventions require kebab-case.
+
+## Product shape
+
+A healthy workflow looks like:
+
+```text
+agent notices recurring friction
+-> agent_vent records a minimized local vent
+-> recurrence groups reveal repeated pain
+-> operator reviews, acknowledges, dismisses, merges, or drafts escalation
+-> owner system receives a human-approved draft only when appropriate
+```
+
+Near-term product work should make the review step better rather than broadening authority. Useful next surfaces include:
+
+- `/agent_vent review` for an operator-facing review queue;
+- explicit local review states such as `new`, `acknowledged`, `dismissed`, and `escalation_drafted`;
+- recurrence-group merge/dedupe flows;
+- export/delete/retention controls;
+- package/tool owner routing hints;
+- draft-only GitHub/AK/incident text generation that never submits automatically.
+
+## Technical principles
+
+- Use the `engineering-core` `pi-ts` lane.
+- Keep runtime dependencies minimal; prefer Node built-ins and Pi host APIs.
+- Keep durable state schema-versioned, local-first, append-friendly, and privacy-reviewed.
+- Put pure recurrence/redaction/store/review behavior in testable JS modules.
+- Keep the extension entrypoint small and explicit.
+- Preserve template-aligned package metadata and root release automation compatibility.
+- Integrate with `pi-toolbox-discovery` for discovery/activation and with ASC/`self` only as a companion boundary, not by storing vent state in ASC.
+
+## Enduring invariant
+
+```text
+agent_vent surfaces pain; humans and owner systems decide authority.
+```