agy-context-saver 1.5.0 → 1.6.0

package/skills/context-governance/SKILL.md

@@ -43,11 +43,13 @@ Performs streaming inspection of `transcript.jsonl` to calculate turn budgets, s
   - `transcriptPath` (string, required): Absolute path to `transcript.jsonl`.
 
 ### 2. `subagent_brief`
-Generates a strictly formatted, scope-isolated prompt for delegating research or debugging to a subagent (`invoke_subagent`).
+Generates a strictly formatted, scope-isolated prompt for delegating research or debugging to a subagent (`invoke_subagent`). Enforces the **Pointer-Over-Wire (POW)** protocol: deliverables exceeding 1 KB must be written to workspace scratch files (e.g. `scratch/<task>_findings.md`), transmitting only an executive summary, scoreboard, and clickable `file:///` link in-band.
 - **Parameters**:
   - `objective` (string, required): Core investigative or implementation goal.
+  - `role` (string, optional): Subagent role / title.
   - `scopeFiles` (array of strings, optional): Specific file targets.
   - `expectedDeliverable` (string, optional): Expected concise synthesis format.
+  - `subagents` (array, optional): Batch of subagent objects for multi-role delegation.
 
 ### 3. `read_transcript`
 Quickly reads recent conversation turns from an Antigravity transcript in clean Markdown format with zero JSON noise.
@@ -57,11 +59,13 @@ Quickly reads recent conversation turns from an Antigravity transcript in clean
   - `lastTurns` (number, default: 3): Number of turns to display.
 
 ### 4. `query_transcript`
-Granular query and forensic filtering engine for transcripts with keyword/regex search and role filtering.
+Granular query and forensic filtering engine for transcripts with keyword/regex search, auto-dereferencing of truncated payloads, and surgical step projection.
 - **Parameters**:
   - `conversationId` (string, required): Conversation UUID or path.
   - `query` (string, optional): Search keyword or regex.
   - `roles` (array, default: ["user", "assistant"]): Filter by role.
+  - `stepIndex` (number, optional): Specific step to dereference from `transcript_full.jsonl`.
+  - `field` (string, optional): Field projection (`"content"`, `"thinking"`, `"tool_calls"`).
 
 ### 5. `get_installation_status`
 Audits the Antigravity integration layers (Native Plugin Link, Lifecycle Hook in `hooks.json`, MCP Server in `mcp_config.json`, Tool Schemas, and RTK binary/hook).
@@ -73,58 +77,30 @@ Re-verifies, repairs, and synchronizes the installation and tool schemas in ~25m
 
 ---
 
-## Core Governance Rules
+## 3-Layer Governance Invariants
 
-1. **Reactive Wakeup First**:
-   - Never busy-wait on `manage_task(Action='status')` or `schedule` polling timers.
+1. **Layer 1: Reactive Lifecycle & Polling Immunity**:
+   - Never busy-wait on `manage_task(Action='status')` or rapid polling timers.
    - Stop calling tools and yield the turn for native Reactive Wakeup (`<SYSTEM_MESSAGE>`).
-   - Polling calls across tasks are tracked in a session ledger. 5 cumulative denials trigger `force_ask` autonomous freeze.
+   - Diagnostic status inspections follow exponential backoff: $\min(600, \text{round}(30 \times 2.5^{\text{pollCount}-1}))$.
+   - 5 cumulative denials trigger the `force_ask` circuit breaker.
+   - For operations $>15\text{s}$, schedule coordinated watchdog timers: `schedule(DurationSeconds=45, TimerCondition="task-X")` and output a structured Pre-Yield Status Card.
 
-2. **Fast Synchronous Execution**:
-   - Commands default to `WaitMsBeforeAsync: 10000` to complete synchronously without background detachment.
+2. **Layer 2: Transparent CLI & Codebase Streamlining**:
+   - Shell commands transparently rewrite via RTK (`rtk git`, `rtk pytest`, `rtk cargo`, etc.).
+   - Codebase inspection is hard-routed to `rtk read`, `rtk find`, and `rtk rg "<pattern>" .`.
+   - Direct access to `.system_generated/` is strictly denied; use `read_transcript` and `query_transcript`.
 
-3. **Protected Antigravity State**:
-   - Direct access to `.system_generated/` (transcripts, task logs, scheduler state) is strictly denied. Use Agy MCP transcript tools.
-
-4. **Benchmark Integrity**:
-   - Mutating benchmark definitions, prompt templates, or evaluators requires explicit user confirmation.
+3. **Layer 3: Orchestration, Delegation & Pointer-Over-Wire (POW)**:
+   - Synchronous wait window expands to 10,000ms to eliminate unnecessary detachment.
+   - Heavy exploratory work is delegated to subagents (`invoke_subagent`).
+   - Subagents strictly follow Pointer-Over-Wire: write reports $>1\text{ KB}$ to disk; transmit only summary, scoreboard, and clickable file link.
 
 ---
 
-## Zero-Guesswork Testing & Verification Playbook
-
-When validating this framework or reproducing tests, execute these exact steps:
-
-1. **Check Live Registration**:
-   ```bash
-   npm run status
-   # or
-   node mcp/index.js status
-   ```
-   *Expected*: Reports `HEALTHY & ACTIVE 🛡️` across plugin link, hook, MCP server, schemas, and RTK.
-
-2. **Run Full Test Suite**:
-   ```bash
-   npm test
-   ```
-   *Expected*: All 5 suites pass (Unit hook tests, MCP protocol tests, E2E probes, live system validation, lifecycle rollback).
-
-3. **Run Targeted Suite Tests**:
-   - Governance Hook: `node tests/test-hook.mjs`
-   - MCP Protocol & JSON-RPC: `node tests/test-mcp.mjs`
-   - E2E Probes: `node tests/test-e2e-probes.mjs`
-   - Live System Checks: `node tests/test-installed-verification.mjs`
-   - Lifecycle & Rollback: `node tests/test-lifecycle-rollback.mjs`
-
-4. **Verify MCP Tools Inside Antigravity**:
-   - `get_installation_status`: Call with `{}` to audit all 4 layers + RTK.
-   - `check_context_health`: Call with `{ "transcriptPath": "<path-to-transcript.jsonl>" }`.
-   - `read_transcript`: Call with `{ "conversationId": "<uuid>", "lastTurns": 3, "mode": "compact" }`.
-   - `query_transcript`: Call with `{ "conversationId": "<uuid>", "query": "<term>", "summaryOnly": true }`.
-   - `subagent_brief`: Call with `{ "objective": "<goal>", "scopeFiles": ["..."] }`.
-
-5. **Operational Guardrails**:
-   - ❌ Never launch `npm start` or `node mcp/index.js` interactively without stdin redirection (it is a stdio JSON-RPC daemon).
-   - ❌ Never loop on `manage_task(Action='status')` or use task watchdog timers (circuit breaker freezes at 5 denials).
-   - ❌ Never run `npm run uninstall` as an isolated test (always follow immediately with `npm run setup`).
-   - ❌ On Windows, never run `rtk rg` without an explicit directory (e.g. use `rtk rg "pattern" .`).
+## Quick Verification & Health Check
+
+To verify installation health and run test validation:
+- **Health Check**: `npm run status` (verifies plugin link, hook, MCP config, schemas, RTK).
+- **Test Suite**: `npm test` (runs all 8 test suites).
+- Detailed verification playbooks and release steps reside in `docs/publishing.md`.