pi-harness-runtime 0.10.12 → 0.10.13

package/IMPLEMENTATION/RFC-0099/TESTS.md

@@ -0,0 +1,3 @@
+- Happy path
+- Invalid input
+- Deterministic output

package/IMPLEMENTATION/RFC-0100/ACCEPTANCE_CRITERIA.md

@@ -0,0 +1,2 @@
+- Tests pass
+- API documented

package/IMPLEMENTATION/RFC-0100/AI_BRIEF.md

@@ -0,0 +1,2 @@
+# AI Brief
+Implement self developing runtime.

package/IMPLEMENTATION/RFC-0100/FILES.md

@@ -0,0 +1,2 @@
+packages/<module>/src/
+packages/<module>/test/

package/IMPLEMENTATION/RFC-0100/TASKS.md

@@ -0,0 +1,4 @@
+1. Define types
+2. Implement core logic
+3. Add tests
+4. Integrate runtime events

package/IMPLEMENTATION/RFC-0100/TESTS.md

@@ -0,0 +1,3 @@
+- Happy path
+- Invalid input
+- Deterministic output

package/IMPLEMENTATION/RFC-0101/ACCEPTANCE_CRITERIA.md

@@ -0,0 +1,74 @@
+# Acceptance Criteria — RFC-0101
+
+## Implementation
+
+- Implementation follows the RFC.
+- State is durable and runtime-owned.
+- Human is not required as message bus.
+- Failures produce explicit records.
+- Tests cover happy path and failure path.
+
+## Functional
+
+- A task can be submitted during a chat session and complete after the session closes.
+- A scheduled task fires its cron / timer schedule with no active session.
+- Two workers cannot claim the same task concurrently.
+- A killed worker is replaced by another worker resuming from the last checkpoint within `leaseTTL + grace`.
+- Privilege broker refuses any capability not in `config/privileges.yaml`.
+- Privilege broker refuses any `argv` mismatch on a registered capability.
+- `human_approval_required` tasks block at `waiting_approval` and resume on `approved`.
+- `forbidden` capabilities fail the task immediately with a clear reason.
+- Quota exhaustion transitions the task to `waiting_quota` and resumes on reset.
+- Notifications comply with RFC-0022 rules — no secrets, no tokens, no full source.
+
+## Operational
+
+- The runtime runs under `systemd`, `launchd`, or Docker with restart policy verified.
+- Heartbeats are written to `worker-registry.json` every 30 seconds.
+- The reaper script releases expired leases correctly under a chaos test.
+- The audit log accumulates one entry per broker call and rotates daily.
+
+## Recovery
+
+- Worker killed mid-task -> recovered within `leaseTTL + grace` from the last checkpoint.
+- Host reboot -> worker restarts and in-flight tasks recover automatically.
+- Filesystem full -> worker pauses new claims without corrupting checkpoints.
+- Notification channel outage -> events buffer; flush on reconnect; no event loss after the outage clears.
+
+## Integration
+
+- Successful tasks with deliverables promote an OKF pattern bundle.
+- Failed tasks after retries promote an OKF lesson bundle readable by the Master Planner.
+- The Master Planner references pattern and lesson bundles during decomposition.
+
+## Security
+
+- No capability is a wildcard, a shell, or arbitrary `argv`.
+- The agent cannot mutate `privileges.yaml` at runtime.
+- The audit log cannot be rewritten by the worker — filesystem permissions enforced.
+- All approval requests are signed via the operator's SSH key fingerprint.
+
+## Performance / Cost
+
+- Worker steady-state CPU < 1 % on idle.
+- Heartbeat write rate < 1 KB / 30 s.
+- Inbox append throughput ≥ 1 000 tasks / s on local SSD.
+
+## Sanitization
+
+- No client company names appear in the implementation files.
+- No real IPs, hostnames, domains (other than the approved `bunchee.online`, `moo-ai.online`, `moocoding.com`).
+- No API keys, tokens, passwords, or secrets.
+- All placeholder names follow the convention `your_app`, `your-app.service`, `your-project`, `/opt/your_app`.
+
+## Documentation
+
+- `packages/autonomous-runtime/README.md` covers install, supervisor selection, and lifecycle.
+- `packages/privilege-broker/README.md` covers capability registration.
+- `packages/scheduler-adapter/README.md` covers each adapter's install + test path.
+- Root `README.md` references RFC-0101 and lists the new packages.
+- Bundled skill `harness-runtime/SKILL.md` documents the `/runtime` command surface.
+
+## Done When
+
+All of the above are demonstrated and recorded in `test/reports/RFC-0101-<date>.md`.

package/IMPLEMENTATION/RFC-0101/AI_BRIEF.md

@@ -0,0 +1,80 @@
+# AI Brief — Autonomous Operations Runtime (RFC-0101)
+
+## Status
+
+🟡 Proposed — awaiting implementation kickoff
+
+## Goal
+
+Implement the Autonomous Operations Runtime subsystem of `pi-harness-runtime` so that:
+
+- Queued work runs without an active `pi` session.
+- The runtime survives worker crashes, host reboots, quota exhaustion, and SSH / browser disconnect.
+- Privileged operations are gated by a capability-based broker, never by raw `sudo`.
+- Recovery, lease, and approval semantics are durable and observable.
+
+## Implemented (when done)
+
+- `packages/autonomous-runtime/` — Task Inbox, Lease, Worker, Recovery, Supervisor templates.
+- `packages/privilege-broker/` — capability registry + executor + audit log.
+- `packages/scheduler-adapter/` — `systemd` / `launchd` / `cron` / internal.
+- `config/privileges.yaml` — versioned capability registry (closed enum).
+- `units/systemd/pi-runtime.service`, `units/launchd/*.plist`, `units/cron/*.cron.example`.
+- OKF promotion rules in `packages/okf-kb/` (reuses existing engine).
+
+## Features
+
+- Structured durable Task Inbox (`tasks.jsonl` + `claimed/` + `completed/` + `failed/` + `dead-letter/`).
+- Single-execution guarantee via Task Lease (TTL 5 min, heartbeat 30 s, grace 30 s).
+- Capability-based privilege broker with append-only audit log.
+- Approval classes (`automatic_read_only`, `automatic_reversible`, `human_approval_required`, `forbidden`).
+- Scheduler abstraction compiling to `systemd`, `launchd`, `cron`, or internal timer.
+- Notification fan-out extended with autonomous-ops events (`task.recovered`, `audit.privileged_called`, etc.).
+- Recovery from worker crash, host reboot, quota exhaustion, task timeout.
+- OKF lesson / pattern promotion rules.
+
+## Non-Goals
+
+- Multi-host distributed lease coordination (deferred to future RFC).
+- Multi-tenant isolation (deferred to future RFC).
+- Replacing RFC-0015 (Job State Machine) or RFC-0011 (Shared Blackboard).
+
+## Integration Points
+
+| Existing | Reused As |
+|---|---|
+| RFC-0001 Loop Runtime | Inner execution loop |
+| RFC-0003 Quota Manager | `waiting_quota` transitions |
+| RFC-0006 Checkpoint Manager | Task-level checkpoint storage |
+| RFC-0011 Shared Blackboard | Operator-visible progress events |
+| RFC-0017 Master Planner | Task generation |
+| RFC-0018 Repair Engine | Failure -> repair task generation |
+| RFC-0022 Notification Center | Channel adapters |
+| RFC-0028 Policy Engine | Approval class resolution |
+
+## Constraints
+
+- **Public repository.** Sanitize client / server / product names. Use generic placeholders: `your_app`, `your-app.service`, `your-project`, `/opt/your_app`.
+- **No wide-open `NOPASSWD`.** Sudoers is not acceptable as a privilege mechanism.
+- **No `shell.root` capability.** The capability registry is closed and versioned.
+- **Local-first.** No mandatory cloud dependency.
+- **Recoverable.** Every transition is checkpointed; every lease has a TTL.
+
+## Tests
+
+Subagent-implemented:
+
+- Unit: inbox append/read, lease atomic claim, heartbeat extension, broker execution, policy class resolution.
+- Integration: parallel-worker claim races, lease reaper recovery, broker denial paths, scheduler materialisation for each adapter.
+- Failure-mode: killed worker, full disk, quota reset, expired approval, repeated failures -> dead letter.
+- Security: capability enumeration refuses unknown names; argv-tampering rejected; audit log rotation works.
+
+## Risks
+
+- **Risk:** OS-specific supervisor templates break on non-target platforms. *Mitigation:* Adapter abstraction + matrix tests per adapter.
+- **Risk:** Audit log grows unbounded. *Mitigation:* Daily rotation via `logrotate` + monthly archive.
+- **Risk:** Operator forgets to wire scheduler adapter. *Mitigation:* Installer detects host OS and writes the correct unit; warns if multiple supervisors detected.
+
+## Definition of Done
+
+RFC-0101 implementation is considered done when all 25 acceptance criteria in the RFC are demonstrably met (manual or automated test) and the README + skill docs reference the new packages.

package/IMPLEMENTATION/RFC-0101/FILES.md

@@ -0,0 +1,82 @@
+# Suggested Files — RFC-0101
+
+```text
+packages/
++-- autonomous-runtime/
+|   +-- src/
+|   |   +-- inbox.ts
+|   |   +-- lease.ts
+|   |   +-- recovery.ts
+|   |   +-- worker.ts
+|   |   +-- supervisor.ts          # unit installation (systemd/launchd/cron)
+|   |   +-- types.ts
+|   +-- scripts/
+|   |   +-- reap-leases.ts         # standalone reaper for cron / external trigger
+|   +-- units/                     # supervisor drop-ins
+|   |   +-- systemd/
+|   |   |   +-- pi-runtime.service
+|   |   |   +-- pi-runtime.timer.example
+|   |   +-- launchd/
+|   |   |   +-- ai.moocoding.runtime.plist
+|   |   +-- cron/
+|   |       +-- pi-runtime.cron.example
+|   +-- test/
+|   |   +-- inbox.test.ts
+|   |   +-- lease.test.ts
+|   |   +-- worker.test.ts
+|   |   +-- recovery.test.ts
+|   +-- package.json
+|   +-- tsconfig.json
+|   +-- README.md
+|
++-- privilege-broker/
+|   +-- src/
+|   |   +-- registry.ts            # loads config/privileges.yaml
+|   |   +-- executor.ts            # execve wrapper
+|   |   +-- audit.ts               # append-only audit log writer
+|   +-- config/
+|   |   +-- privileges.yaml        # versioned, reviewed capability registry
+|   +-- logrotate.d/
+|   |   +-- pi-runtime-audit       # daily rotation
+|   +-- test/
+|   |   +-- registry.test.ts
+|   |   +-- executor.test.ts
+|   |   +-- audit.test.ts
+|   +-- package.json
+|   +-- tsconfig.json
+|   +-- README.md
+|
++-- scheduler-adapter/
+|   +-- src/
+|   |   +-- interface.ts           # SchedulerAdapter contract
+|   |   +-- systemd.ts             # compiles ScheduledTask to .service/.timer
+|   |   +-- launchd.ts             # compiles to .plist
+|   |   +-- cron.ts                # writes crontab fragments
+|   |   +-- internal.ts            # in-process timer (dev/test only)
+|   +-- test/
+|   |   +-- systemd.test.ts
+|   |   +-- launchd.test.ts
+|   |   +-- cron.test.ts
+|   |   +-- internal.test.ts
+|   +-- package.json
+|   +-- tsconfig.json
+|   +-- README.md
+|
++-- okf-kb/                        # OKF lesson / pattern promotion (extends existing)
+|   +-- (existing — append promote-pattern.ts + promote-lesson.ts)
+|
++-- config/
+    +-- privileges.yaml            # initial capability registry
+```
+
+## Files Modified (out-of-tree)
+
+```text
+skills/harness-runtime/SKILL.md    # add /runtime command, link RFC-0101
+README.md                          # reference RFC-0101 + new packages
+MANIFEST.json                      # include autonomous-runtime, privilege-broker, scheduler-adapter
+```
+
+## Files NOT Modified
+
+- RFC-0001, RFC-0003, RFC-0006, RFC-0011, RFC-0015, RFC-0017, RFC-0018, RFC-0022, RFC-0028 — referenced as integration points only.

package/IMPLEMENTATION/RFC-0101/TASKS.md

@@ -0,0 +1,92 @@
+# Tasks — RFC-0101 Autonomous Operations Runtime
+
+> Track per-package work. Sub-tasks may reference each other.
+
+## Phase 1 — Foundations
+
+- [x] Read RFC-0101 and confirm scope.
+- [x] Define `TaskRecord`, `TaskLease`, `TaskEvent`, `CapabilityName`, `ApprovalClass`, `TaskStatus` types in `packages/autonomous-runtime/src/types.ts`.
+- [x] Define JSON schemas for inbox and lease files (as JSDoc comments in types.ts).
+- [x] Implement `TaskInbox.append`, `TaskInbox.list`, `TaskInbox.transition` against `tasks.jsonl`.
+- [x] Implement atomic claim via `open(O_EXCL) + rename` to `claimed/<task>.lease.json`.
+  - **Fix applied:** `rename(2)` atomically overwrites — switched to `open(O_CREAT|O_EXCL)` + `rename` so second worker gets `EEXIST`.
+  - **Tests:** 23/23 pass including race condition test.
+
+## Phase 2 — Lease and Worker
+
+- [ ] Implement `Lease.claim(taskId, workerId)` — atomic, single-execution.
+- [ ] Implement `Lease.heartbeat(leaseId)` — extends `expiresAt`.
+- [ ] Implement `Lease.reap()` — releases expired leases back to `queued`.
+- [ ] Implement `Worker.loop()` — claim -> execute -> checkpoint -> finalize.
+- [ ] Implement `Worker.recoverOnStartup()` — reaps orphan leases.
+- [ ] Implement `Worker.emitHeartbeat()` — every 30 s.
+- [ ] Add `worker-registry.json` rotation.
+
+## Phase 3 — Privilege Broker
+
+- [ ] Load `config/privileges.yaml` at worker startup; reject unknown capabilities.
+- [ ] Implement `Broker.request(capabilityName, args)` — resolves to registered `argv`.
+- [ ] Implement `Broker.execute(grant)` — uses `execve` (no shell) with service account.
+- [ ] Implement `Broker.deny(unknown)` — explicit failure with reason.
+- [ ] Append every call to `audit.log` with `{ts, workerId, taskId, capability, argv, exitCode}`.
+- [ ] Add `logrotate` config for `audit.log`.
+
+## Phase 4 — Policy + Approval
+
+- [ ] Resolve `approvalClass(capability)` via RFC-0028 lookup.
+- [ ] Implement `Approval.request(capability, rationale)` — write approval request.
+- [ ] Implement `Approval.decide(id, decision, signedBy)` — updates request, audits.
+- [ ] Implement `Approval.timeout()` — sweep expired approvals, fail tasks.
+- [ ] Implement `Approval.notify()` via RFC-0022 channel adapters.
+
+## Phase 5 — Scheduler Adapter
+
+- [ ] Implement `SchedulerAdapter.interface.ts` — common API.
+- [ ] Implement `systemd` adapter — write `.service` + `.timer` units from templates.
+- [ ] Implement `launchd` adapter — write `plist` with `StartCalendarInterval`.
+- [ ] Implement `cron` adapter — write crontab fragment.
+- [ ] Implement `internal` adapter — for dev/test only, marks not-for-production.
+- [ ] Make install-time selection idempotent — re-running install does not duplicate units.
+
+## Phase 6 — Recovery
+
+- [ ] Wire `worker-crash -> reaper -> resume from last checkpoint`.
+- [ ] Wire `host-reboot -> supervisor restart -> worker startup recovery`.
+- [ ] Wire `quota-exhausted -> waiting_quota -> resume on reset`.
+- [ ] Wire `task-timeout -> checkpoint preserved -> reaped and resumed`.
+- [ ] Wire `filesystem-full -> worker paused claims -> operator alert`.
+
+## Phase 7 — OKF Integration
+
+- [ ] Implement `OKF.promotePattern(task)` — only on `TaskResult.kind === "deliverable"`.
+- [ ] Implement `OKF.promoteLesson(task)` — only on classified failure.
+- [ ] Wire planner (RFC-0017) to read lesson / pattern bundles during decomposition.
+- [ ] Document OKF promotion rules in `packages/okf-kb/`.
+
+## Phase 8 — Tests
+
+- [ ] Unit: inbox append/read, lease claim/heartbeat/reap.
+- [ ] Unit: broker lookup, argv resolution, denial paths.
+- [ ] Unit: policy class resolution per capability.
+- [ ] Integration: parallel worker claim race.
+- [ ] Integration: lease reaper recovery.
+- [ ] Integration: broker denial paths.
+- [ ] Integration: scheduler materialisation for each adapter.
+- [ ] Failure-mode: killed worker, full disk, quota reset, expired approval, repeated failures.
+- [ ] Security: argv tampering rejected; audit log rotation works; broker refuses unknown names.
+
+## Phase 9 — Documentation
+
+- [ ] Write `packages/autonomous-runtime/README.md`.
+- [ ] Write `packages/privilege-broker/README.md` (incl. how to add a new capability).
+- [ ] Write `packages/scheduler-adapter/README.md` (per-adapter install guide).
+- [ ] Update root `README.md` with reference to RFC-0101.
+- [ ] Update bundled `skills/harness-runtime/SKILL.md` with `/runtime` slash-command doc.
+
+## Phase 10 — Acceptance
+
+- [ ] All 25 acceptance criteria from RFC-0101 §20 demonstrated.
+- [ ] Skill registry exposes `autonomous-runtime` skill on agent startup.
+- [ ] Systemd unit survives `systemctl restart` chaos test.
+- [ ] Audit log present after one broker call; rotated after 24 h.
+- [ ] OKF pattern bundle produced by at least one happy-path task.

package/IMPLEMENTATION/RFC-0101/TESTS.md

@@ -0,0 +1,127 @@
+# Test Plan — RFC-0101
+
+## Unit Tests
+
+### Inbox
+
+- `inbox.append` writes one JSON line per call to `tasks.jsonl`.
+- `inbox.list` returns queued tasks in stable order (priority -> createdAt).
+- `inbox.transition` updates status atomically with history append.
+- `inbox.archive` moves completed records after the retention window.
+
+### Lease
+
+- `lease.claim` returns a lease and writes the lease file atomically.
+- Two parallel `claim` calls on the same task — exactly one wins.
+- `lease.heartbeat` extends `expiresAt`; cross-worker heartbeat aborts safely.
+- `lease.reap` releases leases past `expiresAt + grace` and writes a `recovered` history entry.
+- Lease file with corrupt JSON is quarantined, not silently reaped.
+
+### Worker
+
+- `worker.loop` claims the next ready task and runs it through the inner loop.
+- `worker.recoverOnStartup` calls `lease.reap` once before the main loop.
+- `worker.heartbeat` writes to `worker-registry.json` at the configured cadence.
+- Worker `SIGTERM` handler runs graceful shutdown and exits 0.
+
+### Privilege Broker
+
+- `registry.load` reads `config/privileges.yaml` and rejects unknown capabilities.
+- `executor.execve` runs an exact `argv` with no shell.
+- `executor.argvTampering` — passing extra args that do not match the registered `argv` is rejected.
+- `executor.unknownCapability` fails with a structured `BrokerDeniedError`.
+- `audit.append` writes one line per broker call; rotation reads `logrotate` config and works under simulated 24 h clock.
+
+### Policy Engine Integration
+
+- `policy.class(capability)` resolves from `config/privileges.yaml`.
+- Each capability in the initial registry is mapped to the class declared in RFC-0101 §9.
+- `Approval.request` creates an approval request with `expiresAt`.
+- `Approval.timeout` sweeps expired requests and fails the task.
+
+### Scheduler Adapter
+
+- `systemd.compile(task)` produces a `.service` + `.timer` pair matching the template.
+- `launchd.compile(task)` produces a `plist` with `StartCalendarInterval`.
+- `cron.compile(task)` produces a crontab fragment.
+- `internal.compile(task)` registers an in-process timer (and is marked not-for-production).
+- Re-running install does not duplicate units (idempotency test).
+
+## Integration Tests
+
+### Happy Path
+
+- Submit a task while a chat session is open; close the chat; worker still completes the task.
+- Schedule a recurring task; verify it fires every N minutes under `cron` and `systemd` adapters.
+- OKF pattern bundle is produced on a successful task with deliverable.
+- OKF lesson bundle is produced on a classified failure.
+
+### Concurrency
+
+- Spin up two workers on the same host; submit 100 tasks; verify each is executed exactly once.
+- Spin up a reaper script in parallel with the workers; verify no lease is reaped while still heartbeating.
+
+### Recovery
+
+- Kill a worker mid-task with `SIGKILL`; another worker resumes the task from its last checkpoint.
+- Reboot the host (or simulate via `systemctl restart`); worker restarts; in-flight tasks recovered.
+- Fill the disk to 99 %; worker pauses new claims; verify no checkpoint corruption.
+- Block the notification channel for 1 hour; verify events buffer and flush on reconnect.
+
+### Approval Flow
+
+- Submit a `human_approval_required` task; verify the task pauses at `waiting_approval`.
+- Approve the task via operator; verify the task resumes and completes.
+- Deny the task; verify it transitions to `failed` with reason "approval denied".
+- Let an approval expire (24 h); verify it transitions to `failed` with reason "approval timeout".
+
+### Privilege Broker
+
+- Request a registered capability -> succeeds.
+- Request an unknown capability -> fails with `BrokerDeniedError`.
+- Request a registered capability with mismatched args -> fails.
+- Verify audit log contains one entry per call with the correct shape.
+
+## Failure-Mode Tests
+
+| Scenario | Expected Outcome |
+|---|---|
+| Worker killed mid-task | Lease reaper releases; next worker resumes from checkpoint. |
+| Host reboot | Supervisor restarts worker; leases reaped; checkpoints restored. |
+| Filesystem full during checkpoint | Worker pauses new claims; operator notified; no half-written checkpoint. |
+| Quota exhausted | Task transitions to `waiting_quota`; resumes after reset. |
+| Provider returns 5xx for 30 min | Tasks wait in `waiting_quota`; resume on green health probe. |
+| Clock skew between two workers | Atomic rename protects; only one heartbeat wins. |
+| Privilege registry file corrupted | Worker refuses to start; clear error pointing at schema validator. |
+| Approval request lost in transit | Task expires after 24 h; broker logs lost request. |
+| Repeated identical failure | After `maxAttempts` the task moves to `dead_letter`; operator notified. |
+| Recursive task creation (cycle) | DAG cycle detection rejects; task fails. |
+
+## Security Tests
+
+- Capability enumeration refuses unknown names.
+- Argv tampering rejected at broker.
+- Audit log cannot be rewritten by the worker (`chmod 0640`, owner `root`, group `your_app`).
+- No `shell.root`, `sudo.any`, or wildcard capabilities are reachable via the registry.
+- Agent cannot mutate `privileges.yaml` at runtime (no API exposed).
+
+## Performance / Cost
+
+- Worker steady-state CPU < 1 % on idle (verify with `pidstat -u -p <pid> 60`).
+- Heartbeat write rate < 1 KB / 30 s.
+- Inbox append throughput ≥ 1 000 tasks / s on local SSD.
+- Lease claim latency < 5 ms on local filesystem.
+
+## Acceptance Run
+
+- All 25 criteria in RFC-0101 §20 must be demonstrated.
+- Run the integration suite end-to-end against a clean `~/.pi/harness/` directory.
+- Capture the test report under `test/reports/RFC-0101-<date>.md`.
+
+## Required Tooling
+
+- `bun test` (or `node --test`) for unit + integration.
+- `tmux` or `setsid` for parallel-worker chaos.
+- `systemd-run --scope` for supervised-worker tests on Linux.
+- `logrotate --debug` for audit-log rotation tests.
+- `faketime` (or equivalent) for approval-timeout and clock-skew tests.

package/IMPLEMENTATION/RFC-0102/ACCEPTANCE_CRITERIA.md

@@ -0,0 +1,33 @@
+# Acceptance Criteria — RFC-0102 Context Engineering Pipeline
+
+## Functional
+
+- [ ] IntentAnalyzer classifies "fix the login bug" as `bug_fix`
+- [ ] IntentAnalyzer classifies "add dark mode support" as `feature`
+- [ ] IntentAnalyzer classifies "deploy to production" as `deployment`
+- [ ] IntentAnalyzer falls back to `general` for unknown input
+- [ ] WorkspaceScanner detects git branch, dirty state, modified files
+- [ ] WorkspaceScanner detects project type from package.json, go.mod, Cargo.toml
+- [ ] WorkspaceScanner detects framework from vite.config.ts, next.config.js, nuxt.config.ts
+- [ ] DependencyAnalyzer parses ESM imports: `import X from './y'`, `import { a } from 'pkg'`
+- [ ] DependencyAnalyzer parses CommonJS: `const X = require('./y')`
+- [ ] DependencyAnalyzer parses Python: `from module import x`
+- [ ] ContextDiscovery collects candidates from workspace + git diff + OKF
+- [ ] ContextEngineeringPipeline returns a valid ContextPackage
+- [ ] Policy filter denies `**/.env`, `**/*.pem`, `**/credentials/**`
+- [ ] Cache key invalidates when git branch changes
+- [ ] Cache key invalidates when AGENTS.md changes
+
+## Non-Functional
+
+- [ ] Each package compiles with `npx tsc --skipLibCheck` zero errors
+- [ ] All tests pass: `bun test packages/*/test/*.test.ts`
+- [ ] No hardcoded paths — uses configurable root
+- [ ] No secret leakage — .env files never included
+- [ ] Pipeline processes known workspace in < 2 seconds
+
+## Integration
+
+- [ ] Pipeline integrates with `@pi/context-compiler` (compileContext, loadOkfConcepts)
+- [ ] Pipeline integrates with `@pi/session-api` for historical context
+- [ ] Pipeline output compatible with provider router input format

package/IMPLEMENTATION/RFC-0102/AI_BRIEF.md

@@ -0,0 +1,34 @@
+# AI Brief — RFC-0102 Context Engineering Pipeline
+
+## What is being built
+
+An 5-package pipeline that transforms user intent into an optimal LLM input:
+
+1. **intent-analyzer** — keyword-based intent classification
+2. **workspace-scanner** — git state + project type detection
+3. **dependency-analyzer** — import/export graph builder
+4. **context-discovery** — orchestrates all stages to collect relevant files
+5. **context-engineering** — wires pipeline, builds ContextPackage, manages cache
+
+Existing `packages/context-compiler/` covers: ranking, compression, compilation, OKF loading.
+
+## Key interfaces
+
+- `Intent` — kind (bug_fix/feature/etc.), confidence, signals, originalText
+- `WorkspaceSnapshot` — root, git state, project config, env files, config files
+- `DependencyGraph` — Map<filePath, DependencyNode> + edges[]
+- `DiscoveredContext` — intent + workspace + dependencies + knowledge + files
+- `ContextPackage` — structured output sent to LLM
+
+## Integration
+
+- Pipeline reads from: filesystem, git, OKF
+- Output feeds: `compileContext()` from `@pi/context-compiler`, then to provider router
+- No new schema — uses existing context-compiler types for candidates
+- Session API (RFC-0103) provides historical context
+
+## Testing strategy
+
+- Unit: intent detection keywords, workspace detection patterns, import parsing
+- Integration: full pipeline on known workspaces
+- Mock workspace fixture for CI

package/IMPLEMENTATION/RFC-0102/FILES.md

@@ -0,0 +1,73 @@
+# Files — RFC-0102 Context Engineering Pipeline
+
+## New Packages
+
+```
+packages/
++-- intent-analyzer/
+|   +-- src/
+|   |   +-- types.ts          # Intent, IntentKind, IntentConfidence, IntentSignal, IntentRule
+|   |   +-- analyzer.ts       # IntentAnalyzer class — keyword scoring, analyze(text): Intent
+|   |   +-- index.ts         # Public barrel
+|   +-- test/
+|   |   +-- analyzer.test.ts  # bun test — all intent kinds
+|   +-- package.json
+|   +-- tsconfig.json
+|
++-- workspace-scanner/
+|   +-- src/
+|   |   +-- types.ts         # WorkspaceSnapshot, GitState, ProjectConfig, ScannerOptions
+|   |   +-- git.ts           # getGitState(rootPath): GitState | null via git CLI
+|   |   +-- detect.ts        # detectProject(rootPath): ProjectConfig — file-based detection
+|   |   +-- scanner.ts       # WorkspaceScanner class — orchestrates git + detect
+|   |   +-- index.ts         # Public barrel
+|   +-- test/
+|   |   +-- scanner.test.ts  # bun test — mock workspace
+|   +-- package.json
+|   +-- tsconfig.json
+|
++-- dependency-analyzer/
+|   +-- src/
+|   |   +-- types.ts         # DependencyNode, DependencyGraph, DependencyEdge, DependencyKind
+|   |   +-- analyzer.ts       # DependencyAnalyzer class — scan + graph build
+|   |   +-- imports.ts       # parseImports(content, filePath): string[] — regex for TS/JS/Python
+|   |   +-- index.ts         # Public barrel
+|   +-- test/
+|   |   +-- analyzer.test.ts # bun test — import patterns
+|   +-- package.json
+|   +-- tsconfig.json
+|
++-- context-discovery/
+|   +-- src/
+|   |   +-- types.ts         # DiscoveredContext, DiscoveryOptions, DiscoveryResult
+|   |   +-- discovery.ts     # ContextDiscovery class — orchestrates all stages
+|   |   +-- index.ts         # Public barrel
+|   +-- test/
+|   |   +-- discovery.test.ts # bun test — mock dependencies
+|   +-- package.json
+|   +-- tsconfig.json
+|
++-- context-engineering/
+    +-- src/
+    |   +-- types.ts         # ContextPackage, PipelineOptions, PipelineStats
+    |   +-- pipeline.ts       # ContextEngineeringPipeline — orchestrates all 5 packages
+    |   +-- cache.ts          # ContextCache — wraps @pi/context-compiler cache
+    |   +-- index.ts          # Public barrel
+    +-- test/
+    |   +-- pipeline.test.ts  # bun test — full pipeline
+    +-- package.json
+    +-- tsconfig.json
+```
+
+## Integration (do not create new files)
+
+| Source | Import from |
+|---|---|
+| Context Compiler | `@pi/context-compiler` — compileContext, ContextCandidate, ContextPolicy |
+| OKF Loader | `@pi/context-compiler/src/okf-loader.js` — loadOkfConcepts |
+| Session API | `@pi/session-api` — getRecentFailures, getArchitectureHistory |
+
+## Files NOT Created
+
+- `packages/context-compiler/` — already exists, do not modify
+- `packages/okf-kb/` — already exists, do not modify