734 lines
21 KiB
Markdown
734 lines
21 KiB
Markdown
# pi-crew Next Upgrade Roadmap
|
|
|
|
Date: 2026-05-05
|
|
Source inputs:
|
|
|
|
- `docs/research-oh-my-pi-distillation.md`
|
|
- `docs/source-runtime-refactor-map.md`
|
|
- Recent runtime hardening commits through `f5d47aa feat: surface run effectiveness evidence`
|
|
|
|
This document tracks the next practical upgrades after the current scaffold/no-op subagent fix, runtime safety classification, cancellation provenance, intent audit trail, prompt pipeline artifacts, capability inventory artifacts, and run effectiveness reporting.
|
|
|
|
## Current Baseline
|
|
|
|
Already implemented and pushed:
|
|
|
|
- Real child worker execution is the default.
|
|
- Implicit scaffold/no-op runs are blocked when worker execution is disabled by config/env.
|
|
- Explicit `runtime.mode=scaffold` remains available for dry-run prompt/artifact generation.
|
|
- Run `summary.md`, `progress.md`, and `status` now expose effectiveness evidence.
|
|
- Structured cancellation reasons flow through retry/cancel/team-runner/run events/metrics/UI snapshot.
|
|
- `cancel`, `cleanup`, `forget`, and `prune` accept audit intent metadata.
|
|
- Live-agent control distinguishes `steer` from `follow-up` at live-control/API level.
|
|
- Retry attempts have `attemptId`; max-retry deadletters link to the final `attemptId`.
|
|
- Worker prompt pipeline and capability inventory metadata artifacts are written per task.
|
|
|
|
## Priority Legend
|
|
|
|
- **P0**: correctness/safety issue; should be addressed before next release if feasible.
|
|
- **P1**: high user-visible value or reliability gain; good patch-release candidates.
|
|
- **P2**: larger subsystem work; should be planned and sequenced.
|
|
- **P3**: polish/UX/longer-term architecture.
|
|
|
|
## P0 — Prevent Ineffective Completed Runs
|
|
|
|
### P0.1 Enforce effectiveness policy for non-scaffold workers
|
|
|
|
**Problem**
|
|
|
|
`summary/status` now surface effectiveness evidence, but non-scaffold `child-process`/`live-session` runs can still end `completed` when task evidence is weak unless the existing mutation guard fires.
|
|
|
|
**Target behavior**
|
|
|
|
- For real workers, a run with completed tasks but no observable worker activity should be `blocked` or `failed`, not silently `completed`.
|
|
- Keep explicit scaffold dry-runs allowed, but label them as dry-runs.
|
|
- Policy should be configurable:
|
|
- `runtime.effectivenessGuard = "off" | "warn" | "block" | "fail"`
|
|
- default candidate: `warn` for read-only roles, `block` for mutating roles.
|
|
|
|
**Suggested files**
|
|
|
|
- `src/runtime/team-runner.ts`
|
|
- `src/runtime/completion-guard.ts`
|
|
- `src/state/types.ts` if storing guard result on manifest/tasks
|
|
- `src/schema/config-schema.ts`
|
|
- `src/config/config.ts`
|
|
- `test/unit/summary.test.ts`
|
|
- `test/unit/team-runner-merge.test.ts` or new `test/unit/effectiveness-guard.test.ts`
|
|
|
|
**Implementation sketch**
|
|
|
|
1. Extract run effectiveness calculation into a reusable exported helper, e.g.:
|
|
|
|
```ts
|
|
export interface RunEffectivenessSummary {
|
|
completed: number;
|
|
observable: number;
|
|
noObservedWorkTaskIds: string[];
|
|
needsAttentionTaskIds: string[];
|
|
workerExecution: "enabled" | "disabled/scaffold";
|
|
severity: "ok" | "warning" | "blocked" | "failed";
|
|
}
|
|
```
|
|
|
|
2. Use this helper for:
|
|
- `progress.md`
|
|
- `summary.md`
|
|
- `status`
|
|
- policy enforcement before `run.completed`.
|
|
|
|
3. For non-scaffold runs, if mutating tasks have no mutation/tool/model/transcript evidence:
|
|
- append `policy.action` with `reason: "ineffective_worker"`;
|
|
- set run `blocked` or `failed` depending config;
|
|
- include task IDs in `data`.
|
|
|
|
**Acceptance criteria**
|
|
|
|
- A mocked child-process run with no tool/model/transcript evidence does not report clean `completed` by default.
|
|
- Scaffold run still completes as explicit dry-run and displays `Worker execution: disabled/scaffold`.
|
|
- `status` clearly lists `noObservedWork` and `needsAttention` task IDs.
|
|
- Unit tests cover warn/block/fail modes.
|
|
|
|
**Verification**
|
|
|
|
```bash
|
|
npx tsc --noEmit
|
|
node --experimental-strip-types --test --test-concurrency=1 --test-timeout=30000 test/unit/effectiveness-guard.test.ts test/unit/summary.test.ts
|
|
npm run test:unit
|
|
```
|
|
|
|
### P0.2 Make runtime safety visible in manifest and run events
|
|
|
|
**Problem**
|
|
|
|
`runtime.safety` exists in runtime resolution, but it is not persisted as first-class run metadata. Debugging currently requires reading events or inferred artifacts.
|
|
|
|
**Target behavior**
|
|
|
|
- Manifest records resolved runtime:
|
|
|
|
```json
|
|
{
|
|
"runtimeResolution": {
|
|
"kind": "child-process",
|
|
"requestedMode": "auto",
|
|
"safety": "trusted",
|
|
"fallback": "child-process",
|
|
"reason": "..."
|
|
}
|
|
}
|
|
```
|
|
|
|
- `run.running` or `run.blocked` event includes the same resolution.
|
|
|
|
**Suggested files**
|
|
|
|
- `src/state/types.ts`
|
|
- `src/extension/team-tool/run.ts`
|
|
- `src/runtime/background-runner.ts`
|
|
- `src/extension/team-tool/status.ts`
|
|
- `test/unit/team-run.test.ts`
|
|
- `test/unit/runtime-resolver.test.ts`
|
|
|
|
**Acceptance criteria**
|
|
|
|
- `status` shows `Runtime safety: trusted|explicit_dry_run|blocked`.
|
|
- Blocked disabled-worker runs persist enough evidence to explain why no subagents spawned.
|
|
- Existing manifest schema remains backward compatible.
|
|
|
|
## P1 — Steering/Follow-up Semantics Beyond Live Control
|
|
|
|
### P1.1 Persist separate steering and follow-up queues in mailbox state
|
|
|
|
**Current state**
|
|
|
|
`follow-up-agent` exists in live-control, but durable mailbox is still generic inbox/outbox and `respond` still has waiting-task semantics.
|
|
|
|
**Target behavior**
|
|
|
|
- Mailbox messages can carry semantic kind:
|
|
|
|
```ts
|
|
kind?: "message" | "steer" | "follow-up" | "response" | "group_join";
|
|
priority?: "urgent" | "normal" | "low";
|
|
deliveryMode?: "interrupt" | "next_turn";
|
|
```
|
|
|
|
- `steer-agent` appends durable steering queue entry when no live session is present.
|
|
- `follow-up-agent` appends durable follow-up queue entry, deliverable after task stop/resume.
|
|
- UI/status separates urgent steering from follow-up backlog.
|
|
|
|
**Suggested files**
|
|
|
|
- `src/state/mailbox.ts`
|
|
- `src/runtime/live-agent-control.ts`
|
|
- `src/runtime/live-agent-manager.ts`
|
|
- `src/extension/team-tool/api.ts`
|
|
- `src/extension/team-tool/respond.ts`
|
|
- `src/ui/dashboard-panes/mailbox-pane.ts`
|
|
- `test/unit/mailbox-api.test.ts`
|
|
- `test/unit/live-agent-control.test.ts`
|
|
- `test/unit/respond-tool.test.ts`
|
|
|
|
**Acceptance criteria**
|
|
|
|
- Steering and follow-up can be inspected separately.
|
|
- Existing inbox/outbox JSONL remains readable.
|
|
- Durable queue survives process/session switch.
|
|
- Realtime live delivery dedupes against durable replay.
|
|
|
|
### P1.2 Clarify `respond` vs `follow-up` UX
|
|
|
|
**Problem**
|
|
|
|
`respond` is currently a waiting-task resume primitive. Users may expect it to send a general follow-up.
|
|
|
|
**Target behavior**
|
|
|
|
- `/team-respond` remains only for `waiting` tasks.
|
|
- `/team-follow-up` or `api operation=follow-up-agent` is documented as continuation prompt.
|
|
- Error messages recommend the correct command.
|
|
|
|
**Suggested files**
|
|
|
|
- `src/extension/registration/commands.ts`
|
|
- `src/extension/help.ts`
|
|
- `docs/usage.md`
|
|
- `test/unit/registration-commands-coverage.test.ts`
|
|
- `test/unit/respond-tool.test.ts`
|
|
|
|
## P1 — Worker Lifecycle and Process Reliability
|
|
|
|
### P1.3 Two-phase child process teardown
|
|
|
|
**Current state**
|
|
|
|
Child workers have improved post-exit stdio guards and bounded drains, but cancellation semantics can be made more deterministic.
|
|
|
|
**Target behavior**
|
|
|
|
Worker process cancellation returns structured status:
|
|
|
|
```ts
|
|
interface WorkerExitStatus {
|
|
exitCode: number | null;
|
|
cancelled: boolean;
|
|
timedOut: boolean;
|
|
killed: boolean;
|
|
signal?: string;
|
|
cleanupErrors: string[];
|
|
finalDrainMs: number;
|
|
}
|
|
```
|
|
|
|
Process lifecycle:
|
|
|
|
1. graceful cancel/TERM;
|
|
2. wait grace window;
|
|
3. hard kill process tree;
|
|
4. bounded stdout/stderr drain;
|
|
5. mark session non-reusable.
|
|
|
|
**Suggested files**
|
|
|
|
- `src/runtime/child-pi.ts`
|
|
- `src/runtime/pi-spawn.ts`
|
|
- `src/runtime/post-exit-stdio-guard.ts`
|
|
- `src/runtime/task-runner.ts`
|
|
- `src/runtime/cancellation.ts`
|
|
- `test/unit/child-pi*.test.ts`
|
|
- `test/integration/mock-child-run.test.ts`
|
|
|
|
**Acceptance criteria**
|
|
|
|
- Cancelled worker always produces terminal task event.
|
|
- Output drains are bounded.
|
|
- Status includes `cancelled/timedOut/killed`.
|
|
- No zombie/stale running task after cancellation.
|
|
|
|
### P1.4 Reserve worker control channel before spawn
|
|
|
|
**Problem**
|
|
|
|
There can be a short window where a task is logically starting but cancel/steer cannot target a controller yet.
|
|
|
|
**Target behavior**
|
|
|
|
- Synchronously create a `WorkerRunCore`/controller before async spawn.
|
|
- Persist controller metadata in agent status.
|
|
- Cancel/steer requests can be queued immediately while startup is in progress.
|
|
- Controller is cleared in `finally`.
|
|
|
|
**Suggested files**
|
|
|
|
- `src/runtime/task-runner.ts`
|
|
- `src/runtime/agent-control.ts`
|
|
- `src/runtime/live-agent-control.ts`
|
|
- `src/runtime/crew-agent-records.ts`
|
|
- `src/extension/team-tool/api.ts`
|
|
|
|
**Acceptance criteria**
|
|
|
|
- Starting worker can be cancelled immediately.
|
|
- Durable control request written during startup is applied or recorded as terminal no-op with reason.
|
|
- Tests simulate control request before child process emits first output.
|
|
|
|
## P1 — Cancellation and Attempt History
|
|
|
|
### P1.5 Add event-tree provenance: `parentEventId`, `attemptId`, `branchId`
|
|
|
|
**Current state**
|
|
|
|
Retry attempts have `attemptId`, and deadletters link to final attempt. Event log has sequence and terminal fingerprints but no general event tree.
|
|
|
|
**Target behavior**
|
|
|
|
- `TeamEvent.metadata` supports:
|
|
|
|
```ts
|
|
parentEventId?: string;
|
|
attemptId?: string;
|
|
branchId?: string;
|
|
causationId?: string;
|
|
correlationId?: string;
|
|
```
|
|
|
|
- Retry events, task started/completed/failed, deadletter, recovery events link by `attemptId`.
|
|
- UI/status can show attempt timeline.
|
|
|
|
**Suggested files**
|
|
|
|
- `src/state/event-log.ts`
|
|
- `src/state/types.ts`
|
|
- `src/runtime/team-runner.ts`
|
|
- `src/runtime/retry-executor.ts`
|
|
- `src/runtime/recovery-recipes.ts`
|
|
- `src/extension/team-tool/status.ts`
|
|
- `test/unit/event-metadata.test.ts`
|
|
- `test/unit/retry-executor.test.ts`
|
|
|
|
**Acceptance criteria**
|
|
|
|
- Retry attempt events and terminal task events share attempt provenance.
|
|
- Deadletter records can be traced back to event sequence.
|
|
- Existing JSONL readers ignore missing provenance fields.
|
|
|
|
### P1.6 Synthetic terminal results for cancelled in-flight operations
|
|
|
|
**Problem**
|
|
|
|
Run/task cancellation events are now structured, but worker/tool sub-operations can still lack synthetic terminal records if cancelled mid-operation.
|
|
|
|
**Target behavior**
|
|
|
|
- If a task started a worker/tool/model call and cancellation occurs, append a synthetic terminal record:
|
|
- `tool.cancelled` or `worker.cancelled`
|
|
- reason code/message
|
|
- startedAt/finishedAt
|
|
- attemptId if available
|
|
|
|
**Suggested files**
|
|
|
|
- `src/runtime/task-runner.ts`
|
|
- `src/runtime/task-runner/progress.ts`
|
|
- `src/runtime/child-pi.ts`
|
|
- `src/runtime/cancellation.ts`
|
|
- `src/state/contracts.ts`
|
|
- `test/unit/cancellation.test.ts`
|
|
|
|
**Acceptance criteria**
|
|
|
|
- No started tool/model operation is left without terminal evidence after cancellation.
|
|
- Status/diagnostics can distinguish user cancel vs timeout vs shutdown.
|
|
|
|
## P1 — Capability Inventory and Control Center
|
|
|
|
### P1.7 Build run/project capability inventory view
|
|
|
|
**Current state**
|
|
|
|
Per-task capability artifacts exist. There is no unified project/run inventory UI/API yet.
|
|
|
|
**Target behavior**
|
|
|
|
`/team-settings` or new `/team-control` shows normalized inventory:
|
|
|
|
```ts
|
|
interface CapabilityItem {
|
|
id: string;
|
|
kind: "team" | "workflow" | "agent" | "skill" | "tool" | "hook" | "runtime" | "provider";
|
|
name: string;
|
|
source: "builtin" | "project" | "user" | "runtime";
|
|
path?: string;
|
|
state: "active" | "disabled" | "shadowed" | "missing";
|
|
disabledReason?: string;
|
|
shadowedBy?: string;
|
|
}
|
|
```
|
|
|
|
**Suggested files**
|
|
|
|
- `src/extension/team-tool/handle-settings.ts`
|
|
- `src/extension/management.ts`
|
|
- `src/agents/discover-agents.ts`
|
|
- `src/teams/discover-teams.ts`
|
|
- `src/workflows/discover-workflows.ts`
|
|
- `src/runtime/skill-instructions.ts`
|
|
- `docs/resource-formats.md`
|
|
- `test/unit/management.test.ts`
|
|
|
|
**Acceptance criteria**
|
|
|
|
- Inventory is stable and sorted.
|
|
- Shadowed project/user/builtin resources are visible.
|
|
- Skill disabled/budget state is visible.
|
|
- No file path is used as the only stable ID.
|
|
|
|
### P1.8 Persist capability disables by stable ID
|
|
|
|
**Target behavior**
|
|
|
|
- Operator can disable a skill/agent/team by capability ID.
|
|
- Disable config survives path relocation when resource identity remains stable.
|
|
- Status explains disabled reason.
|
|
|
|
**Suggested files**
|
|
|
|
- `src/config/config.ts`
|
|
- `src/schema/config-schema.ts`
|
|
- discovery modules
|
|
- `test/unit/config-schema-validation.test.ts`
|
|
|
|
## P2 — Typed Hook Lifecycle
|
|
|
|
### P2.1 Introduce typed hook contract
|
|
|
|
**Target behavior**
|
|
|
|
Define typed lifecycle gates:
|
|
|
|
- `before_run_start`
|
|
- `before_task_start`
|
|
- `task_result`
|
|
- `before_cancel`
|
|
- `before_forget`
|
|
- `before_cleanup`
|
|
- `before_publish`
|
|
- `session_before_switch`
|
|
- `run_recovery`
|
|
|
|
Each hook declares:
|
|
|
|
```ts
|
|
type HookMode = "blocking" | "non_blocking";
|
|
type HookOutcome = "allow" | "block" | "modify" | "diagnostic";
|
|
```
|
|
|
|
Errors are recorded in diagnostics/events, not uncontrolled exceptions.
|
|
|
|
**Suggested files**
|
|
|
|
- new `src/hooks/*`
|
|
- `src/extension/register.ts`
|
|
- `src/runtime/team-runner.ts`
|
|
- `src/extension/team-tool/cancel.ts`
|
|
- `src/extension/team-tool/lifecycle-actions.ts`
|
|
- `docs/resource-formats.md`
|
|
- `test/unit/hooks*.test.ts`
|
|
|
|
**Acceptance criteria**
|
|
|
|
- Blocking hook can stop a run before worker start with clear event and status.
|
|
- Non-blocking hook failure records diagnostic and does not crash run.
|
|
- Hook context is redacted and bounded.
|
|
|
|
### P2.2 Require intent via policy/hook for destructive actions
|
|
|
|
**Current state**
|
|
|
|
Intent is optional for cancel/cleanup/forget/prune.
|
|
|
|
**Target behavior**
|
|
|
|
- Optional config:
|
|
|
|
```json
|
|
{
|
|
"policy": {
|
|
"requireIntentForDestructiveActions": true
|
|
}
|
|
}
|
|
```
|
|
|
|
- Actions requiring intent:
|
|
- cancel
|
|
- forget
|
|
- prune
|
|
- cleanup with force
|
|
- publish/release helpers if added
|
|
- worktree removal
|
|
|
|
**Acceptance criteria**
|
|
|
|
- Missing intent blocks action with actionable error.
|
|
- Existing tests can opt out or provide intent.
|
|
- Audit trail includes intent after approval.
|
|
|
|
## P2 — Durable History vs Prompt Projection
|
|
|
|
### P2.3 Separate durable run history projection from worker prompt text
|
|
|
|
**Current state**
|
|
|
|
Prompt pipeline artifacts exist, but context projection logic is still coupled to prompt construction in multiple places.
|
|
|
|
**Target behavior**
|
|
|
|
Introduce explicit projection functions:
|
|
|
|
```ts
|
|
transformRunContextBeforeWorkerStart(...)
|
|
convertRunHistoryToWorkerPrompt(...)
|
|
```
|
|
|
|
Rules:
|
|
|
|
- Durable history retains events, mailbox, artifacts, UI/runtime metadata.
|
|
- Worker prompt gets a bounded projection.
|
|
- UI/runtime events are not prompt text unless explicitly selected.
|
|
|
|
**Suggested files**
|
|
|
|
- `src/runtime/task-runner/prompt-pipeline.ts`
|
|
- `src/runtime/task-runner/prompt-builder.ts`
|
|
- `src/runtime/task-output-context.ts`
|
|
- `src/runtime/task-runner.ts`
|
|
- `test/unit/task-runner-prompt-pipeline.test.ts`
|
|
|
|
**Acceptance criteria**
|
|
|
|
- Prompt pipeline artifact identifies every projection source.
|
|
- Large event/mailbox history is summarized or referenced, not blindly embedded.
|
|
- Tests verify UI/runtime events are not injected as instructions.
|
|
|
|
## P2 — Cooperative Cancellation for Internal Scans
|
|
|
|
### P2.4 Add internal `CancellationToken`
|
|
|
|
**Target behavior**
|
|
|
|
A utility for long internal loops:
|
|
|
|
```ts
|
|
interface CancellationToken {
|
|
readonly aborted: boolean;
|
|
readonly reason?: CancellationReason;
|
|
heartbeat(stage?: string): void;
|
|
throwIfCancelled(): void;
|
|
wait(ms: number): Promise<void>;
|
|
}
|
|
```
|
|
|
|
Use it in:
|
|
|
|
- run index scans
|
|
- artifact cleanup
|
|
- mailbox validation/replay
|
|
- worktree cleanup
|
|
- diagnostic export
|
|
- large transcript/event reads
|
|
|
|
**Suggested files**
|
|
|
|
- new `src/runtime/cancellation-token.ts`
|
|
- `src/extension/run-index.ts`
|
|
- `src/extension/registration/artifact-cleanup.ts`
|
|
- `src/state/mailbox.ts`
|
|
- `src/ui/run-snapshot-cache.ts`
|
|
- `test/unit/cancellation-token.test.ts`
|
|
|
|
**Acceptance criteria**
|
|
|
|
- Long scan can abort within bounded cadence.
|
|
- Heartbeat stage appears in diagnostics/logs.
|
|
- Existing APIs can pass no token and keep current behavior.
|
|
|
|
## P2 — Artifact Store Improvements
|
|
|
|
### P2.5 Content-addressed blob artifacts
|
|
|
|
**Target behavior**
|
|
|
|
Large logs/transcripts/results are stored as blobs:
|
|
|
|
```text
|
|
artifacts/blobs/sha256/<hash>
|
|
artifacts/blob-metadata/<hash>.json
|
|
```
|
|
|
|
Metadata includes:
|
|
|
|
- runId/taskId
|
|
- MIME/type
|
|
- producer
|
|
- original path/name
|
|
- size/hash
|
|
- redaction status
|
|
- retention policy
|
|
|
|
**Suggested files**
|
|
|
|
- `src/state/artifact-store.ts`
|
|
- `src/runtime/task-runner.ts`
|
|
- `src/ui/transcript-viewer.ts`
|
|
- `src/extension/run-export.ts`
|
|
- `src/extension/run-import.ts`
|
|
- `test/unit/artifact-store*.test.ts`
|
|
|
|
**Acceptance criteria**
|
|
|
|
- Artifacts above threshold are blob-referenced.
|
|
- Run export/import preserves blobs.
|
|
- GC removes unreferenced blobs after retention.
|
|
- Path traversal protections remain intact.
|
|
|
|
## P2 — UI and Dashboard Upgrades
|
|
|
|
### P2.6 Show capability/effectiveness/cancellation panels in dashboard
|
|
|
|
**Target behavior**
|
|
|
|
Dashboard panes expose:
|
|
|
|
- run effectiveness score and no-observed-work tasks;
|
|
- cancellation reason and intent;
|
|
- capability inventory for selected task;
|
|
- attempt/deadletter timeline.
|
|
|
|
**Suggested files**
|
|
|
|
- `src/ui/run-dashboard.ts`
|
|
- `src/ui/dashboard-panes/*`
|
|
- `src/ui/snapshot-types.ts`
|
|
- `src/ui/run-snapshot-cache.ts`
|
|
- `test/unit/run-dashboard.test.ts`
|
|
- new pane tests
|
|
|
|
**Acceptance criteria**
|
|
|
|
- No heavy synchronous scans in render path.
|
|
- Pane output is width-safe.
|
|
- Snapshot cache provides precomputed compact data.
|
|
|
|
### P2.7 Event-first UI stream
|
|
|
|
**Target behavior**
|
|
|
|
Move more live UI updates from file polling to semantic events:
|
|
|
|
- `task_started`
|
|
- `task_completed`
|
|
- `worker_status`
|
|
- `mailbox_updated`
|
|
- `effectiveness_changed`
|
|
|
|
**Acceptance criteria**
|
|
|
|
- Render scheduler remains coalesced and overlap-safe.
|
|
- UI still recovers from durable files after restart.
|
|
- File polling is fallback, not the hot path.
|
|
|
|
## P2 — Raw Scan Entry Cache
|
|
|
|
### P2.8 Cache raw entries, not final semantic query results
|
|
|
|
**Target behavior**
|
|
|
|
Shared raw scan cache for:
|
|
|
|
- runs
|
|
- artifacts
|
|
- mailbox files
|
|
- transcript chunks
|
|
- worktree roots
|
|
|
|
Then apply filters/sorts after retrieval.
|
|
|
|
**Suggested files**
|
|
|
|
- `src/runtime/manifest-cache.ts`
|
|
- `src/ui/run-snapshot-cache.ts`
|
|
- `src/extension/run-index.ts`
|
|
- `src/utils/file-coalescer.ts`
|
|
|
|
**Acceptance criteria**
|
|
|
|
- Deterministic sort order.
|
|
- State mutation invalidates relevant raw entries.
|
|
- Large workspaces do not trigger full rescans on every render/status.
|
|
|
|
## P3 — Release/Install Hardening
|
|
|
|
### P3.1 Tarball install smoke before publish
|
|
|
|
**Target behavior**
|
|
|
|
Release workflow requires:
|
|
|
|
```bash
|
|
npm run ci
|
|
npm pack --dry-run
|
|
npm pack
|
|
# install tarball in temp project
|
|
# verify pi extension load smoke
|
|
# verify npm package files and version/tag consistency
|
|
```
|
|
|
|
**Suggested files**
|
|
|
|
- `docs/publishing.md`
|
|
- `package.json` scripts
|
|
- `.github/workflows/*` if CI is added
|
|
- optional `scripts/release-smoke.mjs`
|
|
|
|
**Acceptance criteria**
|
|
|
|
- Packed tarball loads extension in temp Pi home.
|
|
- Version in package, changelog, tag, npm view are consistent.
|
|
- Release instructions include rollback notes.
|
|
|
|
## Suggested Implementation Order
|
|
|
|
1. **P0.1 Effectiveness policy enforcement** — prevents misleading completed runs.
|
|
2. **P0.2 Persist runtime safety** — improves debugging for worker spawn issues.
|
|
3. **P1.3 Two-phase worker teardown** — reduces stale/zombie worker risk.
|
|
4. **P1.1 Durable steering/follow-up queues** — completes semantic split started at live-control level.
|
|
5. **P1.5 Event-tree provenance** — builds on current `attemptId` work.
|
|
6. **P1.7 Capability inventory view** — turns existing per-task artifacts into operator UX.
|
|
7. **P2.3 Durable history projection** — reduces prompt/context risks.
|
|
8. **P2.4 CancellationToken** — improves responsiveness of internal scans.
|
|
9. **P2.5 Blob artifacts** — prevents log/transcript bloat.
|
|
10. **P2.6 Dashboard panels** — surface all new evidence in UI.
|
|
|
|
## Release Guidance
|
|
|
|
Before publishing a patch with these upgrades:
|
|
|
|
```bash
|
|
npx tsc --noEmit
|
|
npm run test:unit
|
|
npm run test:integration
|
|
npm pack --dry-run
|
|
```
|
|
|
|
For runtime/process changes also run targeted child-worker integration tests:
|
|
|
|
```bash
|
|
node --experimental-strip-types --test --test-concurrency=1 --test-timeout=60000 \
|
|
test/integration/mock-child-run.test.ts \
|
|
test/integration/mock-child-json-run.test.ts \
|
|
test/integration/phase6-runtime-hardening.test.ts
|
|
```
|
|
|
|
Do not publish without explicit user confirmation and a green verification pass.
|