@piagent/platform 1.2.5 → 1.2.6

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.2.5",
+  "version": "1.2.6",
   "type": "module",
   "private": true,
   "license": "MIT",

package/packages/piagent-core/policies/base-policy.json

@@ -114,6 +114,8 @@
   "toolRegistry": {
     "defaultMode": "advisory",
     "alwaysAllowedTools": [
+      "piagent_tools",
+      "piagent_context_engine",
       "piagent_context",
       "piagent_permission_status",
       "piagent_exec_policy_check",

package/packages/piagent-core/prompts/scout.md

@@ -11,37 +11,23 @@ $ARGUMENTS
 
 Use this when the user needs evidence before deciding whether to implement. Do not edit source.
 
-Preflight first:
+Lean scouting flow:
 
-1. Call `piagent_context_preflight` with `workflow=scout`.
-2. If it recommends `fresh-session`, stop loading context in this session and tell the user to use `/piagent-session fresh scout <request>` unless this command already runs in a fresh session.
-3. Call `piagent_context` with `detail=full`.
-4. Call `piagent_orchestration_policy`; keep scout solo-first unless independent read-only lanes are useful.
-5. Call `piagent_memory_status`; cite relevant memory or Field Guide only with `piagent_memory_citation_record`, then verify against current repo files.
-6. Read `.pi/project-context.md`; if pending, stop and ask for `/onboard-project run`.
-7. Create a read-only task contract with `piagent_task_start` before broad scouting:
-   - risk lane;
-   - expected output;
-   - scope / out of scope;
-   - protected paths;
-   - required context;
-   - read-only verify command.
-   - review lenses and a compact read-only workPlan.
-8. Read required context and targeted task files. Use `piagent_context_budget` before large files.
-9. Use read-only subagents for independent mapping when useful: `piagent-scout`, builtin `context-builder`, and `piagent-reviewer` for final evidence review. Continue single-agent if unavailable, too small, or likely to burn more context than it saves.
-10. Record context with `piagent_context_record`.
-11. If shell is needed beyond simple read/list/test, call `piagent_exec_policy_check`.
-12. Run the exact verify command from the task contract and record with `piagent_verify_record`.
-13. Record handoff with `piagent_trace_record`.
-14. Call `piagent_task_gate_check`. If the gate fails, report partial/blocked.
-15. Do not paste full tool/test logs into chat or final output. Summarize the signal, quote only relevant lines, and use `/piagent-logs` or a narrower command when oversized output has been compacted.
+1. For a narrow lookup, call `piagent_context` with concise detail, read targeted files, and return cited evidence. Do not create a task contract or load memory/index/orchestration policy automatically.
+2. For a broad, cross-module, or high-risk scout, run `piagent_context_preflight` once. Stop if it recommends a fresh session.
+3. Create a read-only contract with `piagent_task_start` only for a broad governed scout that needs a persisted scope, verification evidence, or handoff.
+4. For an unfamiliar or cross-module area, call `piagent_context_engine` once with `action=pack` before manual search. Use memory, Context7, or a read-only subagent only when the pack is insufficient or the work has independent lanes. Verify every advisory hit against current files.
+5. Call `piagent_context_budget` only for large files and `piagent_exec_policy_check` only for complex or unfamiliar shell commands. Simple read/list commands do not need proactive policy calls.
+6. Record the files that materially support the conclusion. For a governed scout, record verification, trace, and task gate; for a narrow lookup, provide the evidence directly.
+7. A low-confidence pack may trigger one bounded finder pass. Do not loop broad search after the requested evidence is covered.
+8. Do not edit source and do not paste full command output. Summarize relevant evidence and unknowns.
 
 Output:
 
 - Changed files: none.
 - Verify command/result.
 - Context manifest.
-- Subagents used/not used and why.
+- Extra workflow tools or subagents used, if any, and why.
 - Review lenses applied.
 - Memory cited, if any.
 - Evidence matrix.

package/packages/piagent-core/prompts/task.md

@@ -3,56 +3,36 @@ description: Implement a bounded project task using piagent Pi policy
 argument-hint: "<task>"
 ---
 
-Implement this task:
+Implement this bounded project task:
 
 ```text
 $ARGUMENTS
 ```
 
-Mandatory flow:
+Core flow:
 
-0. Call `piagent_context_preflight` with `workflow=task`. If it recommends `fresh-session`, stop loading context in this session and tell the user to use `/piagent-session fresh task <request>` unless this command already runs in a fresh session.
-1. Call `piagent_context` and read the project profile/runtime policy.
-2. Call `piagent_orchestration_policy` and keep the task solo-first unless the policy and task shape make bounded subagents clearly useful.
-3. Call `piagent_memory_status`. If memory or the Field Guide is enabled and relevant to the task, search/read it as advisory context, record citations with `piagent_memory_citation_record`, then verify against current repo files.
-4. Call `piagent_context_index_status` when available, then read `.pi/project-context.md`. If `.pi/project-context.md` is missing or still says `Generated: not yet`, stop and ask the user to run `/onboard-project run` after login/model selection before implementation.
-   - Use `piagent_context_index_search` for navigation hints when the task touches an unfamiliar module/tech/risk area.
-   - Treat context-index hits as advisory; open and verify cited files before editing.
-5. Build a Task Implementation Contract with `piagent_task_start` before editing:
-   - task id or short slug
-   - risk lane
-   - expected output
-   - acceptance criteria
-   - scope / out of scope
-   - protected paths
-   - required context
-   - verify command
-   - review lenses
-   - a compact workPlan/task tree
-6. Read all required context files from the profile before planning, then call `piagent_context_budget` for large or unfamiliar files.
-   - If `piagent_context` reports a configured tech stack, read only the concise `.pi/tech-context/*.json` snapshots relevant to the task.
-   - If a selected tech has pending Context7 status and the task depends on that tech, read current docs through Context7 and record a compact snapshot with `piagent_profile_tech_context_record`.
-   - Do not paste or store large vendor documentation blocks in project files.
-7. Decide whether subagents are worth their extra token/tool cost. If the bundled `pi-subagents` parent skill is available, use it for delegation patterns and safety boundaries. If `pi-subagents`/`subagent(...)` is available, use bounded subagents only for independent read-heavy scout/planning/review work:
-   - use `piagent-scout` for unfamiliar module/spec mapping;
-   - use builtin `context-builder` when a large task needs a handoff context/meta-prompt before planning;
-   - use `piagent-planner` for medium/high-risk implementation planning;
-   - use `piagent-reviewer` for final diff/test/scope review;
-   - use explicit review lenses instead of spawning a broad swarm;
-   - keep implementation single-writer unless the user explicitly asks for parallel writers or worktree isolation is clearly safe;
-   - if subagents are unavailable or not useful, continue single-agent and record why.
-8. Record context manifest with `piagent_context_record`: file + reason.
-9. If the task requires shell commands beyond simple read/list/test, call `piagent_exec_policy_check` first.
-10. If the task requires non-piagent MCP/app tools, call `piagent_tool_policy_check` first.
-11. If the task requires source writes, make a short plan first.
-12. Do not touch protected paths.
-13. Use MCP/tools only when the profile capability allows it.
-14. Before final answer, run the exact verify command from `task.verifyCommands` through Pi bash, then record the observed result with `piagent_verify_record`. Do not use `true`, `echo ok`, or `|| true` as passing evidence unless that exact command is part of the task verify plan.
-15. Record handoff with `piagent_trace_record`. If the task produces durable, non-secret project knowledge and the workflow is approved, record a compact cited node with `piagent_context_index_record`; do not save raw transcript.
-16. Call `piagent_task_gate_check`. If gate fails, final outcome is blocked/partial, not done.
-17. If the user asks about token/context/cost usage, call `piagent_usage_snapshot`; for exact token/cost totals, tell the user to run `/session` or `piagent-usage <project-path>`.
-18. If verify cannot run, stop and report the exact blocker. Do not call it done.
-19. Do not paste full test/build/tool logs into chat or final output. Summarize the signal, quote only the relevant failing lines, and use `/piagent-logs` or a narrower command when oversized output has been compacted.
+1. Run `piagent_context_preflight` once with `workflow=task`, then call `piagent_context` with concise detail. Stop if preflight recommends a fresh session or onboarding context is missing.
+2. Classify the request as `tiny`, `normal`, or `high-risk`, then create the Task Implementation Contract with `piagent_task_start` before source edits. Keep the contract compact and include acceptance criteria, scope, verify command, review lenses, and a short work plan.
+3. Read only files required for the task and record them with `piagent_context_record`. Call `piagent_context_budget` only before reading a large or unfamiliar file; do not call it for ordinary targeted files.
+4. Make a short plan before source writes. Keep one writer unless the user explicitly requests otherwise.
+5. Call `piagent_exec_policy_check` only for complex, generated, unfamiliar, destructive, or externally acting shell commands. Simple read/list and configured test commands do not need a proactive check because runtime guards still apply.
+6. Call `piagent_tool_policy_check` only before a non-piagent MCP/app tool whose capability is not already clear from concise project context.
+7. Run the exact configured verify command through Pi bash, record observed evidence with `piagent_verify_record`, record the final handoff with `piagent_trace_record`, then call `piagent_task_gate_check`.
+
+Risk-adaptive enrichment:
+
+- `tiny`: use only the core flow. Do not call orchestration, memory, context-index, tech-context, or subagent tools unless the task actually depends on them.
+- `normal`: for unfamiliar or cross-module work, call `piagent_context_engine` once with `action=pack`; read the ranked current files and stop broad searching when confidence/evidence is sufficient. Use memory only for a known project decision. Call `piagent_orchestration_policy` only when bounded read-only delegation may save context.
+- `high-risk`: use a bounded Context Engine pack, inspect orchestration policy, relevant memory/context-index evidence, and current vendor documentation when needed. Apply explicit security/data/release review lenses before the final gate.
+
+Always:
+
+- Treat memory, context-index, and generated tech snapshots as advisory; verify against current files.
+- If a Context Engine pack reports low confidence, run at most one bounded read-only finder pass and return paths/symbols/evidence; do not start an open-ended scout loop.
+- Do not touch protected paths or use undeclared capabilities.
+- If verification cannot run or the task gate fails, report `blocked` or `partial`, never done.
+- Do not paste full test/build/tool logs. Summarize the signal and quote only relevant failures.
+- Call `piagent_usage_snapshot` only when the user asks about usage; exact totals remain available through `/usage`.
 
 Do not ask the user to paste this mandatory flow. The platform prompt already contains it. If the user pasted the full flow, treat it as boilerplate and extract only the task request.
 
@@ -61,7 +41,7 @@ Output format:
 - Changed files.
 - Verify command/result.
 - Context manifest.
-- Subagents used/not used and why.
+- Extra workflow tools or subagents used, if any, and why.
 - Review lenses applied.
 - Memory cited, if any.
 - Context index used/updated, if any.

package/scripts/build-docs-site.mjs

@@ -124,6 +124,12 @@ const NAV = [
         title: "Kiến trúc repo",
         lead: "Repo này không nhét business logic vào core. Core chỉ giữ policy, prompts, guard, skills và scripts dùng lại được."
       },
+      {
+        slug: "context-engine",
+        nav: "Context Engine",
+        title: "Ít context hơn, giữ nguyên chất lượng model",
+        lead: "Index local, retrieval có xếp hạng, tool loading theo task, semantic compaction và telemetry minh bạch cho Agent Watch."
+      },
       {
         slug: "runtime",
         nav: "Runtime tools",

package/scripts/context-engine.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  buildContextEfficiencyReport,
+  buildContextIndexV2,
+  buildContextPack,
+  buildTestImpact,
+  contextIndexV2Status,
+  searchContextIndexV2
+} from "../packages/piagent-core/extensions/context-engine.js";
+
+function usage() {
+  return [
+    "Pi Context Engine",
+    "",
+    "Usage:",
+    "  piagent-context status [--project <path>] [--json]",
+    "  piagent-context rebuild [--project <path>] [--json]",
+    "  piagent-context search <query> [--project <path>] [--json]",
+    "  piagent-context pack <task> [--tokens <n>] [--project <path>] [--json]",
+    "  piagent-context impact [file ...] [--project <path>] [--json]",
+    "  piagent-context efficiency [--project <path>] [--json]",
+    "",
+    "All index and telemetry data stays under .pi/piagent-state/context-engine/."
+  ].join("\n");
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  if (args[0] === "--help" || args[0] === "-h") return { help: true };
+  const command = args.shift() ?? "status";
+  let project = process.cwd();
+  let json = false;
+  let tokens = 6_000;
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value === "--project" && args[index + 1]) {
+      project = path.resolve(args[++index]);
+    } else if (value === "--tokens" && args[index + 1]) {
+      tokens = Number(args[++index]);
+    } else if (value === "--json") {
+      json = true;
+    } else if (value === "--help" || value === "-h") {
+      return { help: true };
+    } else {
+      values.push(value);
+    }
+  }
+  return { command, project, json, tokens, values };
+}
+
+function projectExcludes(project) {
+  const target = path.join(project, ".pi", "piagent-profile.json");
+  try {
+    const profile = JSON.parse(fs.readFileSync(target, "utf8"));
+    return [
+      ...(Array.isArray(profile.protectedPaths) ? profile.protectedPaths : []),
+      ...(Array.isArray(profile.shellProtectedPaths) ? profile.shellProtectedPaths : []),
+      ".pi/context-index.json",
+      ".pi/piagent-state/**"
+    ];
+  } catch {
+    return [".pi/context-index.json", ".pi/piagent-state/**"];
+  }
+}
+
+function print(value, json) {
+  if (json || typeof value === "string") {
+    process.stdout.write(`${typeof value === "string" ? value : JSON.stringify(value, null, 2)}\n`);
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+const parsed = parseArgs(process.argv.slice(2));
+if (parsed.help) {
+  process.stdout.write(`${usage()}\n`);
+  process.exit(0);
+}
+
+if (!fs.existsSync(parsed.project) || !fs.statSync(parsed.project).isDirectory()) {
+  process.stderr.write(`Project directory not found: ${parsed.project}\n`);
+  process.exit(1);
+}
+
+try {
+  if (["status", "show"].includes(parsed.command)) {
+    print(await contextIndexV2Status(parsed.project), parsed.json);
+  } else if (["rebuild", "build", "refresh"].includes(parsed.command)) {
+    print(await buildContextIndexV2(parsed.project, { excludePatterns: projectExcludes(parsed.project) }), parsed.json);
+  } else if (parsed.command === "search") {
+    const query = parsed.values.join(" ").trim();
+    if (!query) throw new Error("search requires a query");
+    print(await searchContextIndexV2(parsed.project, query, { limit: 15 }), parsed.json);
+  } else if (parsed.command === "pack") {
+    const query = parsed.values.join(" ").trim();
+    if (!query) throw new Error("pack requires a task or query");
+    const pack = await buildContextPack(parsed.project, query, { budgetTokens: parsed.tokens, includeCode: true });
+    print(parsed.json ? pack : pack.text, parsed.json);
+  } else if (["impact", "tests"].includes(parsed.command)) {
+    print(await buildTestImpact(parsed.project, parsed.values), parsed.json);
+  } else if (["efficiency", "stats", "waste"].includes(parsed.command)) {
+    print(buildContextEfficiencyReport(parsed.project), parsed.json);
+  } else {
+    process.stderr.write(`${usage()}\n`);
+    process.exit(1);
+  }
+} catch (error) {
+  process.stderr.write(`FAIL: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+}

package/scripts/install-global.sh

@@ -203,7 +203,20 @@ is_piagent_platform_source() {
 
   local resolved_source
   resolved_source="$(resolve_user_package_path "$source" 2>/dev/null || true)"
-  [[ "$resolved_source" == "$PLATFORM_ROOT" ]]
+  [[ -n "$resolved_source" ]] || return 1
+  [[ "$resolved_source" == "$PLATFORM_ROOT" ]] && return 0
+
+  node --input-type=module - "$resolved_source" <<'NODE'
+import fs from "node:fs";
+import path from "node:path";
+
+try {
+  const manifest = JSON.parse(fs.readFileSync(path.join(process.argv[2], "package.json"), "utf8"));
+  process.exit(manifest.name === "@piagent/platform" ? 0 : 1);
+} catch {
+  process.exit(1);
+}
+NODE
 }
 
 remove_existing_piagent_platform_sources() {

package/scripts/piagent-cli.mjs

@@ -19,7 +19,8 @@ const scriptByCommand = {
   "piagent-capabilities": "scripts/capability-catalog.mjs",
   "piagent-migrate": "scripts/migrate-project-state.mjs",
   "piagent-import-instructions": "scripts/import-agent-instructions.mjs",
-  "piagent-auto": "scripts/pi-auto.sh"
+  "piagent-auto": "scripts/pi-auto.sh",
+  "piagent-context": "scripts/context-engine.mjs"
 };
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");

package/scripts/quality-benchmark.sh

@@ -11,8 +11,16 @@ Options:
   --task-file <path>      File containing task prompt/spec.
   --verify <command>      Verification command used for the run.
   --tokens <number>       Total tokens reported by the agent/provider.
+  --input-tokens <number> Fresh input tokens reported by the provider.
+  --output-tokens <number>
+                          Output tokens reported by the provider.
+  --cache-read-tokens <number>
+                          Cached input tokens reported by the provider.
   --cost <number>         Cost reported for the run.
   --duration <seconds>    Wall-clock duration.
+  --first-correct-edit <seconds>
+                          Time until the first edit retained in the final fix.
+  --rework <number>       Number of discarded/reworked edit attempts.
   --notes <text>          Short notes or quality observations.
   --agent <name>          Backward-compatible alias for --surface.
 
@@ -42,6 +50,7 @@ fi
 shift || true
 
 PROJECT_PATH="$(cd "$PROJECT_PATH" && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 MODE=""
 SCENARIO=""
 SURFACE=""
@@ -49,8 +58,13 @@ RESULT=""
 TASK_FILE=""
 VERIFY_CMD=""
 TOKENS=""
+INPUT_TOKENS=""
+OUTPUT_TOKENS=""
+CACHE_READ_TOKENS=""
 COST=""
 DURATION=""
+FIRST_CORRECT_EDIT=""
+REWORK=""
 NOTES=""
 
 # A flag left without a value otherwise consumes the next flag as its value, and
@@ -104,6 +118,21 @@ while [[ $# -gt 0 ]]; do
       TOKENS="$2"
       shift 2
       ;;
+    --input-tokens)
+      require_value "$1" "${2:-}"
+      INPUT_TOKENS="$2"
+      shift 2
+      ;;
+    --output-tokens)
+      require_value "$1" "${2:-}"
+      OUTPUT_TOKENS="$2"
+      shift 2
+      ;;
+    --cache-read-tokens)
+      require_value "$1" "${2:-}"
+      CACHE_READ_TOKENS="$2"
+      shift 2
+      ;;
     --cost)
       require_value "$1" "${2:-}"
       COST="$2"
@@ -114,6 +143,16 @@ while [[ $# -gt 0 ]]; do
       DURATION="$2"
       shift 2
       ;;
+    --first-correct-edit)
+      require_value "$1" "${2:-}"
+      FIRST_CORRECT_EDIT="$2"
+      shift 2
+      ;;
+    --rework)
+      require_value "$1" "${2:-}"
+      REWORK="$2"
+      shift 2
+      ;;
     --notes)
       require_value "$1" "${2:-}"
       NOTES="$2"
@@ -173,6 +212,13 @@ case "$RESULT" in
     ;;
 esac
 
+# Keep benchmark evidence and context-efficiency evidence in the same record.
+# Failure here does not invalidate a task result; it leaves the optional
+# contextEfficiency field null for older hosts or telemetry-disabled runs.
+if [[ -f "$SCRIPT_DIR/context-engine.mjs" ]]; then
+  node "$SCRIPT_DIR/context-engine.mjs" efficiency --project "$PROJECT_PATH" --json >/dev/null 2>&1 || true
+fi
+
 export PI_BENCHMARK_PROJECT_PATH="$PROJECT_PATH"
 export PI_BENCHMARK_SCENARIO="$SCENARIO"
 export PI_BENCHMARK_SURFACE="$SURFACE"
@@ -180,8 +226,13 @@ export PI_BENCHMARK_RESULT="$RESULT"
 export PI_BENCHMARK_TASK_FILE="$TASK_FILE"
 export PI_BENCHMARK_VERIFY="$VERIFY_CMD"
 export PI_BENCHMARK_TOKENS="$TOKENS"
+export PI_BENCHMARK_INPUT_TOKENS="$INPUT_TOKENS"
+export PI_BENCHMARK_OUTPUT_TOKENS="$OUTPUT_TOKENS"
+export PI_BENCHMARK_CACHE_READ_TOKENS="$CACHE_READ_TOKENS"
 export PI_BENCHMARK_COST="$COST"
 export PI_BENCHMARK_DURATION="$DURATION"
+export PI_BENCHMARK_FIRST_CORRECT_EDIT="$FIRST_CORRECT_EDIT"
+export PI_BENCHMARK_REWORK="$REWORK"
 export PI_BENCHMARK_NOTES="$NOTES"
 
 node --input-type=module <<'NODE'
@@ -195,8 +246,15 @@ const numberOrNull = (value) => {
   const parsed = Number(value);
   return Number.isFinite(parsed) ? parsed : null;
 };
+const contextReportPath = path.join(root, ".pi", "piagent-state", "context-engine", "efficiency-report.json");
+let contextReport = null;
+try {
+  contextReport = JSON.parse(fs.readFileSync(contextReportPath, "utf8"));
+} catch {
+  // Context telemetry is optional and may be disabled for a baseline run.
+}
 const payload = {
-  schemaVersion: 1,
+  schemaVersion: 2,
   recordedAt: new Date().toISOString(),
   scenario: process.env.PI_BENCHMARK_SCENARIO,
   surface: process.env.PI_BENCHMARK_SURFACE,
@@ -204,8 +262,20 @@ const payload = {
   taskFile: process.env.PI_BENCHMARK_TASK_FILE || null,
   verifyCommand: process.env.PI_BENCHMARK_VERIFY || null,
   tokens: numberOrNull(process.env.PI_BENCHMARK_TOKENS),
+  inputTokens: numberOrNull(process.env.PI_BENCHMARK_INPUT_TOKENS),
+  outputTokens: numberOrNull(process.env.PI_BENCHMARK_OUTPUT_TOKENS),
+  cacheReadTokens: numberOrNull(process.env.PI_BENCHMARK_CACHE_READ_TOKENS),
   cost: numberOrNull(process.env.PI_BENCHMARK_COST),
   durationSeconds: numberOrNull(process.env.PI_BENCHMARK_DURATION),
+  firstCorrectEditSeconds: numberOrNull(process.env.PI_BENCHMARK_FIRST_CORRECT_EDIT),
+  reworkCount: numberOrNull(process.env.PI_BENCHMARK_REWORK),
+  contextEfficiency: contextReport
+    ? {
+        generatedAt: contextReport.generatedAt ?? null,
+        sample: contextReport.sample ?? null,
+        metrics: contextReport.metrics ?? null
+      }
+    : null,
   notes: process.env.PI_BENCHMARK_NOTES || null
 };
 fs.appendFileSync(target, `${JSON.stringify(payload)}\n`);

package/scripts/verify-local.sh

@@ -51,6 +51,7 @@ required_files=(
   "$ROOT/.pi/project-context.md"
   "$ROOT/packages/piagent-core/package.json"
   "$ROOT/packages/piagent-core/extensions/piagent-guard.ts"
+  "$ROOT/packages/piagent-core/extensions/context-engine.js"
   "$ROOT/packages/piagent-core/extensions/policy-core.js"
   "$ROOT/packages/piagent-core/extensions/redaction-core.js"
   "$ROOT/packages/piagent-core/extensions/runtime-evidence.js"
@@ -115,6 +116,7 @@ required_files=(
   "$ROOT/docs/publishing-for-teams.md"
   "$ROOT/docs/herdr-workflow.md"
   "$ROOT/docs/runtime-harness-standard.md"
+  "$ROOT/docs/context-engine.md"
   "$ROOT/docs/task-implementation-contract.md"
   "$ROOT/docs/runtime-quality-baseline.md"
   "$ROOT/docs/quality-benchmark.md"
@@ -128,9 +130,11 @@ required_files=(
   "$ROOT/docs-site/assets/docs.css"
   "$ROOT/docs-site/assets/docs.js"
   "$ROOT/docs-site/content/index.html"
+  "$ROOT/docs-site/content/context-engine.html"
   "$ROOT/docs-site/content/mcp.html"
   "$ROOT/docs-site/vercel.json"
   "$ROOT/scripts/build-docs-site.mjs"
+  "$ROOT/scripts/context-engine.mjs"
   "$ROOT/scripts/preview-docs-site.mjs"
   "$ROOT/schemas/project-profile.schema.json"
   "$ROOT/schemas/task-contract.schema.json"
@@ -171,6 +175,8 @@ required_files=(
   "$ROOT/scripts/import-agent-instructions.mjs"
   "$ROOT/tests/capability-core.test.mjs"
   "$ROOT/tests/piagent-guard-integration.test.mjs"
+  "$ROOT/tests/context-engine.test.mjs"
+  "$ROOT/tests/workflow-prompts.test.mjs"
   "$ROOT/tests/install-global.test.mjs"
   "$ROOT/tests/package-distribution.test.mjs"
   "$ROOT/tests/release-identity.test.mjs"
@@ -538,6 +544,7 @@ if grep -R -E -i \
 fi
 
 node --check "$ROOT/packages/piagent-core/extensions/piagent-guard.ts" >/dev/null
+node --check "$ROOT/packages/piagent-core/extensions/context-engine.js" >/dev/null
 node --check "$ROOT/packages/piagent-core/extensions/policy-core.js" >/dev/null
 node --check "$ROOT/packages/piagent-core/extensions/redaction-core.js" >/dev/null
 node --check "$ROOT/packages/piagent-core/extensions/runtime-evidence.js" >/dev/null
@@ -546,6 +553,7 @@ node --check "$ROOT/packages/piagent-core/capabilities/capability-core.js" >/dev
 node --check "$ROOT/packages/piagent-core/capabilities/capability-sources.js" >/dev/null
 node --check "$ROOT/scripts/capability-catalog.mjs" >/dev/null
 node --check "$ROOT/scripts/piagent-cli.mjs" >/dev/null
+node --check "$ROOT/scripts/context-engine.mjs" >/dev/null
 node --check "$ROOT/scripts/pi-usage-history.mjs" >/dev/null
 node --check "$ROOT/scripts/migrate-project-state.mjs" >/dev/null
 node --check "$ROOT/scripts/import-agent-instructions.mjs" >/dev/null