@piagent/platform 1.8.0 → 1.9.1

package/packages/piagent-core/README.md

@@ -7,8 +7,8 @@ Shared Pi package for reusable project workflows.
 - `extensions/piagent-guard.ts`: Pi extension composition root and registration order.
 - `runtime/`: Pi-facing session, usage, log-compaction, and workflow input adapters. New command/tool/hook modules belong here.
 - `extensions/*.js|ts`: legacy-location core services for policy, context, task lifecycle, state, and document intake; only `piagent-guard.ts` is loaded as an extension.
-- `prompts/*.md`: workflow aliases that intentionally launch an agent turn.
-- `skills/piagent-ops/SKILL.md`: operator-invoked reference for manual intake, recovery, and high-risk controls; routine runtime-managed tasks do not advertise or load it.
+- `prompts/*.md`: historical workflow prompt templates; Pi no longer loads them (retired in 1.9.0).
+- `skills/piagent-ops/SKILL.md`: operator-invoked reference for permission, risk, and blocked-call controls; ordinary work does not load it.
 - `skills/piagent-source-cache/`: local cache for user-provided external source repositories.
 - `subagents/*.md`: piagent roles for `pi-subagents`.
 - `benchmark/benchmark-core.js`: deterministic suite validation, evidence scoring, and paired usage comparison for `piagent-benchmark`; `benchmark-report.js` renders the human/HTML reports.
@@ -76,13 +76,11 @@ Legacy aliases still work: `/permission-status`, `/read-only`, `/workspace-write
 - `piagent_exec_policy_check`
 - `piagent_context_budget`
 - `piagent_tool_policy_check`
-- `piagent_task_gate_check`
 - `piagent_usage_snapshot`
 - `piagent_context_preflight`
 - `piagent_memory_status`
 - `piagent_memory_note`
 - `piagent_memory_search`
-- `piagent_memory_citation_record`
 - `piagent_context_index_status`
 - `piagent_context_index_record`
 - `piagent_context_index_search`
@@ -92,40 +90,34 @@ Legacy aliases still work: `/permission-status`, `/read-only`, `/workspace-write
 - `piagent_profile_tech_apply`
 - `piagent_profile_tech_context_record`
 - `piagent_project_onboarding_record`
-- `piagent_task_start`
-- `piagent_task_progress`
 - `piagent_source_checkout`
 - `piagent_document_read` — reads `.md`/`.txt`/`.csv`/`.json`/`.yaml`/`.pdf`/`.docx` from the project or a granted `additionalReadRoots` directory; read-only, and `protectedPaths` still wins
-- `piagent_context_record`
-- `piagent_verify_record` — records verify evidence only after matching an observed bash tool result after task start
-- `piagent_trace_record`
+- `piagent_wait`
 
-These tools are registered capabilities, not a per-task call sequence. Runtime
-starts bounded source tasks directly and exposes no Piagent management schema
-to the model. Broad, high-risk, or ambiguous intake activates
-`piagent_task_start`; lifecycle hooks still collect context, changes,
-current-tree verification, trace and final-gate evidence. Diagnostic/recovery
-groups load only when requested.
+These tools are registered capabilities, not a per-task call sequence. Since
+1.9.0 a turn is freeform: no task contract is created and the task, trace,
+verify, gate and memory-citation tools (`piagent_task_start`, `piagent_task_progress`,
+`piagent_task_gate_check`, `piagent_context_record`, `piagent_verify_record`,
+`piagent_trace_record`, `piagent_memory_citation_record`) are no longer published. Diagnostic groups load only
+when requested.
 
-## Runtime commands and workflow recipes
+## Runtime commands
+
+Work is requested in plain language. The commands below run without a model turn.
 
-- `/commands`: runtime menu/help for terminal, Pi, MCP, model, memory, session, context, permission, and subagent commands.
-- `/workflow`: one launcher for task, scout, BE-to-FE, discuss, plan, review, commit, PR, platform-improve, and onboarding workflows.
 - `/usage`: runtime usage namespace for live snapshot, history hint, preflight, compact, compact-log captures, and context efficiency.
 - Pi native `/name`: set the current session name for Agent Watch/report mapping; Piagent observes the native rename event and keeps `/setname` as a compatibility alias.
-- `/fresh`: open a fresh governed session for any canonical `/workflow` option; `/fresh help` lists the current catalog.
 - `/context`: runtime context namespace for index/rebuild/search/pack/test-impact/efficiency, task preflight, and semantic compact.
 - `/permission`: runtime permission namespace for status/read-only/workspace-write/full-access.
-- `/onboard`: runtime onboarding namespace; `run` launches the first-read onboarding workflow.
 - `/context-index`: legacy alias for `/context index/search`.
 - `/profile`: show a short profile status, list options, apply a profile directly, or run select-style profile/tech setup without a model follow-up. Short aliases include `fe`, `be`, `full`, and `be-fe`.
 - `/profile tech`: show/select/apply the project tech stack for the active profile; fullstack setup selects frontend, backend, and database tech.
 - `/memory` or `/memory-policy`: inspect project memory policy and explicit remember workflow.
-- `/model-options`: show model selector, scoped models, thinking levels, and benchmark discipline without a model follow-up.
 - `/logs`: short alias for `/usage logs`.
 - `/task-preflight`: legacy alias for `/context preflight`.
-- `/fresh-task`, `/fresh-scout`, `/fresh-be-to-fe`: legacy aliases for `/fresh ...`.
-- `/task`, `/scout`, `/be-to-fe`, `/platform-improve`, `/commit`, `/pr`, `/plan`, `/discuss`, `/review`: workflow aliases kept for power users; team docs should teach `/workflow ...` first.
+- `/piagent-status`, `/piagent-inspector`, `/piagent-orchestration`, `/piagent-mcp`, `/fast`: status, session inspector, helper policy, MCP governance and Codex Fast tier.
+
+Retired in 1.9.0: `/workflow`, `/fresh` (and `/fresh-*`), `/onboard`, `/commands`, `/model-options` and the prompt-template aliases (`/task`, `/scout`, `/be-to-fe`, `/platform-improve`, `/commit`, `/pr`, `/plan`, `/discuss`, `/review`). Project onboarding is a plain request; the agent records it with `piagent_project_onboarding_record`.
 
 ## Subagents
 

package/packages/piagent-core/docs/context-efficiency-improvement-plan.md

@@ -1,5 +1,7 @@
 # Context Efficiency Improvement Plan
 
+> **Design record from before 1.9.0.** The task contract, workflow commands (`/workflow`, `/task`, `/fresh`, `/onboard`) and task/trace/verify tools described here were retired on 2026-09-30; sessions are freeform and the guard keeps its path, permission, confirmation, context-budget and stale-edit checks. Kept for reference. Current behavior: [README](../../../README.md).
+
 ## Status
 
 - **Scope:** `packages/piagent-core`

package/packages/piagent-core/extensions/experiment-loop-policy.ts

@@ -0,0 +1,75 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+// Experiment-loop tools (an optional Pi package may add them): run_experiment
+// runs `bash -c <command>` itself, so the guard checks that command like any
+// shell command (see SHELL_TOOL_NAMES). log_experiment then commits every
+// change when an idea is kept (`git add -A`, `git commit`) and erases every
+// uncommitted change when it is dropped (`git checkout -- .`, `git clean -fd`),
+// outside the guard. The loop is therefore allowed only where those commands
+// cannot destroy the member's work: in the session folder itself, on an
+// `experiment/` branch or in a linked worktree, starting from a tree with
+// nothing uncommitted.
+export const EXPERIMENT_LOOP_TOOLS = new Set(["init_experiment", "run_experiment", "log_experiment"]);
+
+// The loop's own files live in `.auto/` and survive a discard, so they may be
+// uncommitted. Files of any other layout count as project files: the safe side.
+const EXPERIMENT_FILES = /^\.auto\//;
+const EXPERIMENT_BRANCH = "experiment/";
+const DEDICATED_TREE = "Run the loop on a branch or worktree of its own, with nothing uncommitted: `git switch -c experiment/<goal>`, "
+  + "or `git worktree add ../<repo>-experiment -b experiment/<goal>` and start Pi in that folder. Your other changes stay untouched.";
+
+type Decision = { block: true; reason: string } | undefined;
+
+// Trimmed at the end only: `git status --porcelain` lines start with a space.
+function git(cwd: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", ["-C", cwd, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000 }).trimEnd();
+  } catch { return null; }
+}
+
+// `workingDir` from the loop's config (`.auto/config.json`), resolved the way
+// the loop resolves it.
+function configuredWorkingDir(cwd: string): string | null {
+  const file = path.join(cwd, ".auto", "config.json");
+  if (!fs.existsSync(file)) return null;
+  try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8"))?.workingDir;
+    return typeof value === "string" && value.trim() ? path.resolve(cwd, value) : null;
+  } catch { return null; }
+}
+
+// Files with uncommitted changes, other than the loop's own.
+export function uncommittedProjectFiles(cwd: string): string[] {
+  return (git(cwd, ["status", "--porcelain", "--untracked-files=all"]) ?? "").split("\n").filter(Boolean)
+    .map((line) => line.slice(3)).filter((file) => !EXPERIMENT_FILES.test(file));
+}
+
+export function experimentLoopDecision(cwd: string, toolName: string): Decision {
+  if (!EXPERIMENT_LOOP_TOOLS.has(toolName)) return undefined;
+  const workingDir = configuredWorkingDir(cwd);
+  if (workingDir && path.resolve(workingDir) !== path.resolve(cwd)) {
+    return { block: true, reason: `Blocked ${toolName}: the experiment config moves its commands to ${workingDir}. `
+      + "Start Pi in that folder instead, so the guard checks each command where it runs." };
+  }
+  if (toolName === "run_experiment") return undefined;
+  const gitDir = git(cwd, ["rev-parse", "--absolute-git-dir"]);
+  if (gitDir === null) {
+    return { block: true, reason: `Blocked ${toolName}: the experiment loop commits and reverts with git, and this folder is not a git repository.` };
+  }
+  const commonDir = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+  const branch = git(cwd, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+  const linkedWorktree = commonDir !== null && path.resolve(commonDir) !== path.resolve(gitDir);
+  if (!linkedWorktree && !branch?.startsWith(EXPERIMENT_BRANCH)) {
+    return { block: true, reason: `Blocked ${toolName}: log_experiment commits every change when an idea is kept and erases every uncommitted change when it is discarded, and this is ${branch ? `branch ${branch}` : "a detached checkout"}. ${DEDICATED_TREE}` };
+  }
+  if (toolName === "init_experiment") {
+    const dirty = uncommittedProjectFiles(cwd);
+    if (dirty.length > 0) {
+      return { block: true, reason: `Blocked init_experiment: ${dirty.length} uncommitted change(s) (${dirty.slice(0, 3).join(", ")}${dirty.length > 3 ? ", …" : ""}) `
+        + "would be erased by the first discarded experiment. Commit or stash them first, then start the loop." };
+    }
+  }
+  return undefined;
+}

package/packages/piagent-core/extensions/local-state-path.js

@@ -46,9 +46,24 @@ export function resolveLocalStatePath(projectRoot, target, options = {}) {
   return path.join(canonicalRoot, ...segments);
 }
 
+// Runtime state is local evidence, never source. A project that never ran
+// setup has no `.pi/.gitignore`, so `git status` listed the state and
+// `git add -A` swept it into commits. The state root ignores itself instead.
+const STATE_ROOT_IGNORE = "# Piagent runtime state: local only, never committed.\n*\n";
+export function ensureStateRootIgnored(projectRoot) {
+  try {
+    const root = resolveLocalStatePath(projectRoot, path.join(projectRoot, ".pi", "piagent-state"), { label: "Piagent state root" });
+    fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(path.join(root, ".gitignore"), STATE_ROOT_IGNORE, { flag: "wx", mode: 0o600 });
+  } catch {
+    // Already present, or the project refuses state (symlinked or read-only); either way nothing to add.
+  }
+}
+
 export function ensurePrivateStateDirectory(projectRoot, directory, label = "Local state directory") {
   const target = resolveLocalStatePath(projectRoot, directory, { label });
   fs.mkdirSync(target, { recursive: true, mode: 0o700 });
+  if (path.relative(path.join(fs.realpathSync.native(path.resolve(projectRoot)), ".pi", "piagent-state"), target).split(path.sep)[0] !== "..") ensureStateRootIgnored(projectRoot);
   const verified = resolveLocalStatePath(projectRoot, directory, { label, kind: "directory" });
   try {
     fs.chmodSync(verified, 0o700);