summary: "Overview and quickstart for monorepo package @tryinget/pi-context-packer." read_when:

• "Starting work in this package workspace." system4d: container: "Monorepo package scaffold for pi extension delivery." compass: "Ship safe package-level iterations inside a shared workspace." engine: "Plan -> implement -> validate -> coordinate with monorepo release flow." fog: "Drift risk if package scripts diverge from monorepo root conventions."

@tryinget/pi-context-packer

Read-only context-window packet planning for Pi coding sessions.

This package is the proposed implementation seam for FCOS item context-window-packer: it plans how to assemble useful next-turn context from source-owned providers without turning any provider into a monolithic all-context authority.

• Workspace path: packages/pi-context-packer
• Release component key: pi-context-packer
• Release config mode: component (default: component)

Current surface

• /context-pack — preview the package's read-only planning posture.
• context_plan — model-callable tool that returns a provider plan, budget, file-type readability/retrieval risks, non-authorizations, and a capability-derived selected-provider execution summary that separates providers context_pack can execute now from runtime-conditional, safety-gated, and owner-routed/unwired providers.
• context_pack — model-callable packet assembler for currently wired read-only providers.
• context_dogfood_evaluate — model-callable, non-persistent evaluator for filled redacted dogfood observation templates.
• context_dogfood_summarize — model-callable, non-persistent aggregate summary for multiple redacted dogfood observations/evaluations.

context_pack is the first bounded retrieval slice: it reads only repo-bounded AGENTS/CLAUDE instruction files, caller-seeded or docs-list-ranked Markdown docs, trusted-system-git status, current Pi session/environment metadata, and SCI code context for caller-seeded code paths/symbols only when SCI read-only safety is explicitly confirmed. It returns a curated Markdown packet as primary tool content and keeps structured details compact by default, omitting duplicated raw item content, raw selected item paths, raw omission details, raw next-tool suggestion reasons, raw objective text, and absolute workspace paths from details. It records omissions, owner-surface routes, and a measurement receipt with estimated tool calls avoided, packet fill ratio, wired providers, already-loaded prompt dedupe, provider gaps, a packet-local utility recommendation that can say to use the packet, skip duplicate content, or review omissions, and a redacted copy-ready dogfood observation template for externally comparing actual low-level probes against estimates without persisting evidence, duplicating raw packet content, or leaking selected item paths / raw omission details. The observation template includes optional actualLowLevelCallsAvoided for cases with a known baseline, validationCommandsRun to keep validation activity separate from low-level context probes, activityType to distinguish implementation/review/validation/planning dogfood, observer-supplied runtimeContext to distinguish source_local, installed_artifact, live_pi_reloaded, and unknown calibration without treating it as reload proof, and optional structured omission follow-ups with classifications such as useful_omission, residual_probe, validation_activity, legacy_missingness, provenance_source_owner_followup, true_missing_capability, or other without treating labels as completion proof; legacy string-only follow-ups are summarized with the system-assigned legacy_unspecified class. context_dogfood_evaluate consumes that redacted template after observation fields are filled and returns a packet-local calibration summary (matched, overestimated, underestimated, needs_review, or observation_incomplete) plus redacted runtime context and omission-follow-up class counts without reading files, calling providers, writing evidence, updating AK/FCOS, or creating session memory. context_dogfood_summarize aggregates multiple redacted observations/evaluations into status counts, activity-type counts, core implementation/review/validation coverage, runtime-context counts/live-reloaded coverage, provider omission counts, omission follow-up counts/class counts/truncation totals, validation-command recorded/missing counts, invalid-receipt counts, and cautious next actions under the same non-persistent boundary; stored evaluation inputs are normalized by recomputing calibration status from stored fields rather than trusting a caller-supplied status string, and stable aggregate status requires both core activity coverage and at least one observer-supplied live_pi_reloaded receipt. Provider failure omissions use stable public failure classes; raw subprocess stderr/stdout/error text is omitted from Markdown packet output, compact details, and next-tool suggestions. Session awareness emits compact numeric context-usage metadata only; raw session/context-usage objects and system prompt content are not packetized. Markdown structural labels such as objectives, item IDs, paths, and rationales are rendered as bounded one-line display text so caller-controlled labels cannot forge packet sections. Plan intake also enforces compact hard caps for objective length, seed count, seed values, seed notes, and workspace path strings before provider routing so raw caller input cannot become the packet payload. Owner-surface routes are advisory only: when an objective needs self, subagent execution, peer messaging/launch, orchestrator gates, AK/FCOS authority, Prompt Vault governance, or ROCS semantics, the packet names the owning surface and states that context-packer did not call, spawn, supervise, persist, or authorize it. It enforces the global packet budget across providers while preserving the configured reasoning reserve, enforces cumulative provider-local caps, preserves Pi loader-style per-directory instruction-file priority inside the accepted repoRoot (AGENTS.md, AGENTS.MD, CLAUDE.md, CLAUDE.MD) from repo root/ancestor files to deepest package files, and treats Markdown extensions case-insensitively. It does not mutate source state. Caller-controlled path seeds and provider-discovered Markdown paths are screened before packet reads; URI/drive-letter, absolute, parent-traversing, current-directory, hidden/internal, generated/vendor, or malformed path seeds are omitted from provider queries and surfaced as blocked path risks. Caller-controlled cwd/repoRoot values are also screened before they are echoed as workspace posture: when repoRoot is omitted, package cwd can infer the nearest ancestor git root only when that ancestor has a plausible .git marker, and package cwd can also name an ancestor monorepo repoRoot only with the same marker, while unrelated roots, fake .git marker files, and broad non-repo ancestors fail closed. Safe caller path seeds that exist relative to package cwd are normalized to repo-root-relative paths after root inference, so package-local seeds and monorepo-root seeds share one provider path basis. Retrieval repeats workspace containment plus descriptor/TOCTOU checks before file content enters a packet. When no explicit safe Markdown seed is supplied, the docs provider may use trusted docs-list.mjs read-only ranking to discover repo-relative Markdown candidates by objective, requiring structured JSON rankedItems / repoPath output because --json provider output is a strict contract, even if unrelated unsafe caller seeds were omitted. Docs-list subprocess capture remains bounded at 4 MiB so real monorepo inventories larger than the former 512 KB limit can be parsed without making provider output unbounded. Empty docs-list results are recorded as explicit docs/no_results omissions rather than silent clean packets, while invalid JSON, ok:false, unsupported JSON schema, unsupported JSON item shapes, or JSON repoRoot values outside the caller repoRoot become provider/schema omissions rather than false no-results. Process-level PI_CONTEXT_PACKER_DOCS_LIST / DOCS_LIST_SCRIPT overrides are treated as trusted executable code and ignored unless PI_CONTEXT_PACKER_TRUST_CUSTOM_DOCS_LIST=1 is explicitly set; ambient HOME is not used to derive executable identity, and built-in discovery uses fixed default script candidates; package-local test/dogfood harnesses may still inject an internal docsListScript. From package subdirectories, docs-list discovery climbs to the nearest package/documentation root before scanning so source-file work still gets package-local docs rather than an empty subdirectory scan or the entire monorepo; package-root markers win over nested README.md / docs markers, nested package.json ambiguity is surfaced, package roots under fixture/sample container directories broaden to the outer package ancestor, legitimate nested package roots and packages merely named sample/fixture stay nearest-package scoped, JSON repoPath stays in the caller repo-root basis unless the payload declares a safe inner repoRoot, package-scoped repoPath values that are not already in the caller repo-root package path require explicit JSON repoRoot or a safe item.path fallback, and package-local JSON path fallback values are rebased to POSIX repo-relative packet paths before repo-root packet reads. If SCI read-only safety is not confirmed, context-packer refuses to run SCI workflows rather than risk creating or mutating .ontology artifacts; live Pi hosts opt into the sandboxed SCI seam only with PI_CONTEXT_PACKER_SCI_READ_ONLY_SAFE=true. Process-level PI_CONTEXT_PACKER_SCI_CLI / SCI_CLI executable overrides are treated as trusted executable code and ignored unless PI_CONTEXT_PACKER_TRUST_CUSTOM_SCI_CLI=1 is explicitly set; default SCI discovery uses fixed absolute system candidates rather than ambient PATH, and SCI subprocesses receive a minimal allowlisted environment with a fixed tool path rather than raw host environment variables. Artifact-creation bypass flags are not accepted as context-packer authorization, existing .ontology state under cwd, repoRoot, or any ancestor between them fails closed (including symlinks), SCI path seeds are copied from the normalized repo-root source through a realpath-checked temporary sandbox before workflow execution, symbol seeds with control characters or more than 240 characters are omitted before subprocess queries, and broad symbol-only SCI searches are omitted unless at least one safe code path seed can bound the sandbox. When the active Pi system prompt already contains a selected AGENTS/CLAUDE instruction file or doc file, the packet emits metadata instead of duplicating the whole content.

Initial live and package-local receipts are recorded in Dogfood measurement receipts — 2026-05-22, including useful-packet, no_packet_needed, provider-route, and structured docs-list JSON smoke cases.

Provider boundary

context_plan may select or mark optional providers for intent, but selection is not a claim that context_pack has an unconditional adapter. Every provider plan reports adapterStatus and executionStatus; conditional providers also report an executionCondition. For selected providers, the plan-level executionSummary gives action-complete nextActions plus a summary next step. Mixed selected plans retain packet, runtime-condition, safety-gate, and owner-surface actions instead of collapsing them into one lossy recommendation. Optional providers retain their per-provider capability fields but do not appear in execution actions until selected. A runtime-eligibility provider may intentionally emit no section; retrieval failures still fail closed as explicit omissions.

Providers:

• SCI code context (sci)
• repo docs / docs-list (docs)
• repo-bounded AGENTS/CLAUDE instruction projection (agents)
• git posture (git)
• current session context pressure (session)
• Prompt Vault read-only procedures (prompt_vault)
• AK read-only task/decision/evidence orientation (ak)
• FCOS read-only control-board orientation (fcos)

See the root source-owner docs:

• Context-window packer FCOS slice
• Context packer provider contract

Current MVP omissions

context_pack records explicit omissions instead of pretending full integration exists. Prompt Vault, AK, and FCOS are reported as planned_unwired / owner_routed, not executable packet providers. Repo-bounded instructions, docs/docs-list, and git are wired. Session is guarded by caller_required_or_high_context_pressure, so an auto-selected low-pressure session may intentionally emit no section. SCI is guarded and reports either blocked_by_safety_gate or runtime_preflight_required before packet assembly. The current MVP assembles repo-bounded instruction/docs-list/git/session sections plus SCI code context for safe path seeds, and for symbol seeds only inside a temporary sandbox bounded by at least one safe code path seed, when all SCI preflights pass.

Runtime dependencies

This package expects pi host runtime APIs and declares them as peerDependencies:

• @earendil-works/pi-coding-agent
• @earendil-works/pi-ai

When using UI APIs (ctx.ui), guard interactive-only behavior with ctx.hasUI so pi -p non-interactive runs stay stable.

Package checks

Run from package directory:

npm install
npm run check

npm run check includes structure validation, Biome, real TypeScript checking for the extension entrypoint, tests, and a quick package artifact check. For package-local production dogfood of real structured docs-list JSON intake, run npm run dogfood:docs-list-json; it assembles docs packets from package-root and package-subdirectory cwd values using real rankedItems[].repoPath, checks compact details redaction, carries provider-route telemetry, tracks validation separately from context probes, labels the activity type and source-local runtime context, and evaluates a non-persistent dogfood receipt.

For dependency-audit and full release-readiness checks:

npm audit --omit=dev --audit-level=moderate
npm run release:check

npm run release:check includes isolated Pi tarball install plus runtime registration smoke for /context-pack and the four model-callable tools, then executes installed artifact code for context_plan, seeded context_pack, docs-list-discovered context_pack, dogfood evaluation, and aggregate dogfood validation-count observability against a temporary read-only fixture. The smoke verifies registered tool metadata through Pi runtime; executable behavior is tested through installed package modules because pi.getAllTools() exposes metadata, not tool handler functions.

npm run check uses the quick artifact release check and intentionally skips the Pi smoke; use npm run release:check before claiming live package activation readiness.

Run from monorepo root through the canonical package gate:

bash ./scripts/package-quality-gate.sh ci packages/pi-context-packer

The generated package-local scripts/quality-gate.sh is a thin wrapper that searches upward for the canonical monorepo root gate. If you validate the package outside the monorepo tree, set PACKAGE_QUALITY_GATE_SCRIPT to the canonical pi-extensions root gate path.

AK task/work-item operations

This package is a monorepo member, not a git root. Use the monorepo-root AK wrapper for task/work-item operations:

# from the monorepo root
./scripts/ak.sh --doctor
./scripts/ak.sh task ready

# from this package directory
../../scripts/ak.sh --doctor
../../scripts/ak.sh task show <id> -F json

Documentation placement

Use:

• docs/project/ for dated RFCs, runbooks, and evidence/progress notes
• docs/adr/ for adopted architecture decisions

Avoid creating new package-local docs/dev/ trees.

Live package activation

Install the package into Pi from the package directory containing this package's package.json:

pi install /absolute/path/to/your/monorepo/packages/pi-context-packer

Then in Pi:

1. run /reload
2. verify with a real command or tool call from this package

The current context_plan build prints context_pack executable now: and recommended next step:. If those lines are absent after /reload, treat the in-session tool closure as stale rather than claiming activation; start a fresh Pi process/session and verify again. Installed-artifact smoke or a fresh process can prove package loading, but neither retroactively refreshes a stale closure in an already-running session.

Release metadata

This scaffold keeps npm identity separate from release component identity:

• npm package name: @tryinget/pi-context-packer
• release component/tag stem: pi-context-packer (for example pi-context-packer-vX.Y.Z)

The npm package name must stay scoped. The release component should usually stay unscoped so root release-please component tags remain readable and stable.

This scaffold writes component metadata in package.json under x-pi-template:

• workspacePath
• releaseComponent
• releaseConfigMode

Default releaseConfigMode is component, meaning the package expects root-managed component release metadata such as a monorepo release-please component map. Use none only as an explicit opt-out when the monorepo root deliberately manages releases another way.

Use these values when wiring monorepo-level release-please component maps.

Docs discovery

npm run docs:list
npm run docs:list:workspace
npm run docs:list:json
npm run dogfood:docs-list-json

Stack lane companions

This package follows the shared pi-ts lane. Add companions only when they materially improve clarity or reuse:

• fast-check for parser/rendering/selection invariants
• @cucumber/cucumber for executable Gherkin/operator workflows
• nunjucks for reusable text/config/prompt/file templates
• engineering-pi-ts.ts-quality.md when the package explicitly adopts deterministic screening with ts-quality

If this package adopts ts-quality, prefer repo-local rollout truth in docs/project/ts-quality-current-vs-target.md and keep the detailed adoption doctrine upstream in ~/ai-society/softwareco/owned/ts-quality/docs/adoption/.

Copier lifecycle policy

• Keep .copier-answers.yml committed.
• Do not edit .copier-answers.yml manually.
• Run update/recopy from a clean destination repo (commit or stash pending changes first).
• Use copier update --trust when .copier-answers.yml includes _commit and update is supported.
• In non-interactive shells/CI, append --defaults to update/recopy.
• Use copier recopy --trust when update is unavailable (for example local non-VCS source) or cannot reconcile cleanly.
• After recopy, re-apply local deltas intentionally and run npm run check.