pi-background-tasks 0.9.0 → 1.0.4

package/BACKGROUND-TASKS-INSTRUCTIONS.md

@@ -0,0 +1,63 @@
+# pi-background-tasks — Mandatory Agent Gateway
+
+**Read this before you read code, edit docs, edit code, or run anything in this package.**
+This gateway is for AI agents maintaining `pi-background-tasks`. It is package-local, deterministic, and intentionally stricter than generic repo instructions.
+
+**Logo reference:** use the package-local docs logo when present: [`docs/assets/logo.svg`](docs/assets/logo.svg). Do not invent remote logos; asset files remain asset-owner territory and must be verified in the docs/assets payload check.
+
+---
+
+## Required read-before-edit order
+
+1. [`docs/INDEX.md`](docs/INDEX.md) — generated package navigation index. If it is absent, stale, or not generated yet, stop relying on memory and report that the docs-engine lane must create/update it.
+2. [`docs/read-before-edit.md`](docs/read-before-edit.md) — generated source-path to owning-doc read gate. If absent or stale, run/ask for the docs-engine gate before editing production sources.
+3. The owning authored doc for the surface you are touching.
+
+Current authored ownership map:
+
+| Surface/source area | Owning doc |
+|---|---|
+| EventBus API; `src/core/extension-api.ts` | `docs/api/eventbus-v1.md` |
+| Shared context projection and estimator; `src/core/context/**` | `docs/concepts/context-projection-and-budgeting.md` |
+| Pi child launch resolution and durable file primitives; `src/core/pi-launch.ts`, `src/core/durable-fs.ts` | `docs/subsystems/child-launch-durability-and-safety.md` |
+| Paths, artifacts, config, env, defaults, schema registry | `docs/reference/runtime-contracts.md` |
+| Symptom triage | `docs/operations/troubleshooting.md` |
+| QA/test operations | `docs/operations/testing.md`, then `TESTING.md`, then `TEST_PLAN.md` |
+| Release/package maintenance | `docs/operations/releasing.md`, then `PUBLISHING.md` |
+
+---
+
+## Hard rules
+
+- **Code is authority for runtime facts; docs describe code.** Do not change code to satisfy prose. When code and docs disagree, update docs or file a code-owner blocker.
+- **Generated regions are not hand-edited.** Regions named `<!-- pi-docs:begin ... -->` / `<!-- pi-docs:end ... -->`, `docs/INDEX.md`, `docs/read-before-edit.md`, README generated facts, and `docs/manifest.json` belong to the docs engine.
+- **No silent truncation, fallback, or route substitution.** Oversized data must be persisted with hashes or rejected loudly. Unavailable model routes, missing context windows, stale config, malformed frames, missing artifacts, and unknown schemas are hard errors.
+- **Parent and child tools are distinct.** Parent tools include `bg_run`, `bg_delegate`, `bg_result`, `bg_status`, `bg_logs`, `bg_kill`, `bg_run_pi_attested`, and the public Fusion tools. Delegate children are inspect-only (`read`, `grep`, `find`, `ls`, `delegate_read_artifact`). Fusion children receive only the workflow-specific candidate tools; evaluator/merger are no-tools.
+- **Frontier routing is subscription-only.** GPT/Codex and Claude-class work must use Pi subscription/OAuth channels. Never route them through metered OpenAI, Anthropic API, OpenRouter, Azure, or other paid API channels.
+- **Durability and integrity are contract surfaces.** Terminal task truth is published only after output/metadata durability. Delegate/Fusion artifacts and attested Pi sidecars carry hashes and schema versions; do not replace these with best-effort writes.
+- **No self-certification.** If a doc freshness or attestation mechanism exists, do not stamp the same change as verified without the required independent check. If the mechanism is absent, say so plainly.
+- **Do not use Fusion tools or commands for package maintenance.** Read files and run focused local checks only.
+
+---
+
+## Runtime roots
+
+- Task runtime: `.pi/tasks/<session-id>-<pid>/` under the active project cwd.
+- Fusion runtime: `.pi/fusion/<session-id>-<pid>/<run-id>/` under the active project cwd.
+- Delegate artifacts: task-owned artifact directories referenced from task metadata/result packages.
+- Fusion model config: `fusion-models.json` under Pi's agent directory (`getAgentDir()`), not the project `.pi/tasks` tree.
+- Package entrypoint: `extensions/background-tasks.ts` via `package.json.pi.extensions`.
+
+---
+
+## Docs generate/verify/attestation workflow
+
+Current `package.json` exposes the docs-engine lane:
+
+```bash
+npm run docs:generate
+npm run docs:verify
+npm run docs:attest/record -- <doc_id> --reviewer <identity-after-semantic-review> --verdict PASS --notes <review-notes>
+```
+
+`npm run docs:attest` is an alias for the attestation recorder and still requires a doc id, reviewer, verdict, and notes after semantic review. Do not self-award PASS. For docs-only maintenance under a constrained operator request, use the requested focused subset (frontmatter, package-local links, targeted source/doc grep) and report that full docs verification/attestation was not run.

package/PUBLISHING.md

@@ -1,67 +1,81 @@
 # Publishing pi-background-tasks
 
-Release checklist for npm publishing and standalone git publishing. The current release candidate is 0.9.0, which adds the `fusion_validate` validation workflow and Anthropic child sanitization; 0.7.0 introduced the Fusion public surfaces (`/fusion`, `/fusion-models`, `fusion_brainstorm`) in addition to the background-task surfaces. Do not advertise the GitHub install target until the standalone repository has the exact release commit and tag.
+Release checklist for npm publishing and standalone git publishing.
+
+The release version is always read from `package.json`:
+
+```bash
+# From the pi-background-tasks package root:
+VERSION=$(node -p "require('./package.json').version")
+printf 'pi-background-tasks@%s\n' "$VERSION"
+```
+
+Observed standalone git tags currently stop at `v0.6.0`; do **not** advertise a `v$VERSION` git install target until that tag exists in the standalone package repository.
 
 ## Preconditions
 
 - npm account with publish rights for `pi-background-tasks`.
-- Standalone GitHub repository, expected: `github.com/ismailsaleekh/pi-background-tasks`.
-- Clean worktree.
-- Final repair commit present in the standalone package repository; do not push from automated repair runs unless the operator explicitly requests it.
+- Standalone GitHub repository: `github.com/ismailsaleekh/pi-background-tasks`.
+- Clean worktree and final release commit in the standalone package repository.
+- Frontier model evidence, if any, uses Pi subscription/OAuth channels only; never metered APIs.
+- No automated publish, push, or tag from repair runs unless the operator explicitly requests it.
 
-## Verify
+## Ordinary release checks
 
 ```bash
-cd packages/pi-background-tasks
-npm run test
-npm run test:full
+npm run typecheck
+npm run test:type-safety
+npm run test:unit
+npm run test:sdk
+npm run test:rpc
+npm run test:component
+npm run test:package
+npm run test:hook-contract
 npm run smoke
 npm run smoke:large-context
+npm run docs:verify
+npm run payload:check
+# On a tag ref only: GITHUB_REF_TYPE=tag GITHUB_REF_NAME=v$VERSION npm run release:check-version
 npm run pack:dry-run
 npm run test:compat
 npm view pi-background-tasks name version --json
 ```
 
-`npm run test:compat` covers exact Pi `0.75.5`, `0.81.1`, `0.82.1`, and `0.83.0`. For each version it verifies the resolved `typebox` is Pi's bundled peer (not a private or nested copy) and scans the installed package bytes for TypeBox APIs removed in the 1.3.x line.
+`npm run test:full` is the full interactive gate (default gate plus PTY and agent-loop). Run it when certifying full TUI/agent-loop behavior, not for docs-only maintenance.
 
-`pi-background-tasks` is already published; bump `package.json` before each npm publish.
+## Payload verification
+
+Use `npm pack --dry-run --json --ignore-scripts` output as the payload source of truth for payload inspection. Verify that `extensions/`, `src/`, `docs/`, `README.md`, `TESTING.md`, `TEST_PLAN.md`, `PUBLISHING.md`, `BACKGROUND-TASKS-INSTRUCTIONS.md`, root `logo.png`, and `LICENSE` match current `package.json.files`, and that tests/scripts/local `.pi` artifacts/node_modules/nested tarballs are excluded.
 
 ## Publish to npm
 
+Only after operator approval:
+
 ```bash
-cd packages/pi-background-tasks
 npm login
 npm publish --access public
 ```
 
-Pi install smoke after publish:
+Post-publish smoke with isolated Pi state:
 
 ```bash
-PI_CODING_AGENT_DIR=$(mktemp -d) pi -e npm:pi-background-tasks@0.9.0 --offline --no-tools --no-session -p "/jobs"
-pi install npm:pi-background-tasks@0.9.0
+PI_CODING_AGENT_DIR=$(mktemp -d) pi -e npm:pi-background-tasks@$VERSION --offline --no-tools --no-session -p "/jobs"
+pi install npm:pi-background-tasks@$VERSION
 ```
 
-## Publish to git
+## Standalone git tag certification
 
-Because Pi git package installs treat the repository root as the package root, do not point Pi at the `ai-pipeline` monorepo root for this package. Push the contents of `packages/pi-background-tasks/` to a standalone repository.
+Pi git package installs treat the repository root as the package root. Do not point Pi at the `ai-pipeline` monorepo root for this package.
 
-```bash
-cd packages/pi-background-tasks
-git status --short --branch
-git log --oneline -3
-git remote -v
-git push origin main
-git tag v0.9.0
-git push origin v0.9.0
-```
+Before any git install instructions are published, verify in the standalone repo that tag `v$VERSION` exists and points at the release commit. `npm run release:check-version` requires an explicit tag ref (`GITHUB_REF_TYPE=tag`, `GITHUB_REF_NAME=v$VERSION`) and never publishes. If the tag does not exist, the git channel is not certified for this release.
 
-Pi install smoke after git tag, using an isolated Pi agent directory so no local checkout or user `~/.pi` state is involved:
+Git install smoke only after the tag exists:
 
 ```bash
-PI_CODING_AGENT_DIR=$(mktemp -d) pi -e git:github.com/ismailsaleekh/pi-background-tasks@v0.9.0 --offline --no-tools --no-session -p "/jobs"
-pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.9.0
+PI_CODING_AGENT_DIR=$(mktemp -d) pi -e git:github.com/ismailsaleekh/pi-background-tasks@v$VERSION --offline --no-tools --no-session -p "/jobs"
+pi install git:github.com/ismailsaleekh/pi-background-tasks@v$VERSION
 ```
 
 ## pi.dev/packages
 
-The package includes the `pi-package` keyword and a `pi.extensions` manifest. After npm publish, it should be discoverable by pi.dev package indexing. If it does not appear automatically, submit/refresh the package according to the pi.dev package-gallery process.
+The package includes the `pi-package` keyword and a `pi.extensions` manifest. After npm publish, it should be discoverable by pi.dev package indexing. If it does not appear automatically, refresh according to the package-gallery process.