@spences10/pi-harness 0.1.2 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,123 @@
+# @spences10/pi-harness
+
+## 0.2.1
+
+### Patch Changes
+
+- 725454e: Confirm harness selection and clearing with explicit
+  notifications, including repeated clears, and add regression tests.
+- d15e4b8: Ship extension changelogs, announce launcher updates,
+  distinguish cost estimates, and display responding models alongside
+  requests.
+
+## 0.2.0
+
+### Minor Changes
+
+- 20bfa27: Simplify harness creation, fix dirty baselines, and verify
+  completion; breaking APIs now require asynchronous updates.
+
+### Patch Changes
+
+- 720eb07: Restore timers, session autonaming, and portable tool
+  guidance while preserving native Pi prompt configuration
+  compatibility.
+
+## 0.1.2
+
+### Patch Changes
+
+- b07ea54: Remove tool prompt guidelines that repeated the harness and
+  Team Mode system prompt sections, which reduces the default request
+  size.
+
+## 0.1.1
+
+### Patch Changes
+
+- 39fa567: Respect disabled extension defaults and keep harness
+  execution separate from experimental Factory workflows by default.
+
+## 0.1.0
+
+### Minor Changes
+
+- fbf0a07: Add evidence-gated pre-harness assessments requiring
+  read-only investigation and explicit user approval before execution
+  begins safely.
+
+## 0.0.11
+
+### Patch Changes
+
+- c275674: Refine harness guidance to favor direct workflows for
+  bounded work and reserve contracts for risk.
+
+## 0.0.10
+
+### Patch Changes
+
+- f699c9c: Automatically deactivate terminal harnesses on direct user
+  input or session startup, preserving current-turn enforcement
+  guarantees.
+
+## 0.0.9
+
+### Patch Changes
+
+- b2f1fdd: Prevent Codex schema failures by restricting constrained
+  sampling to closed tools with fully required parameters.
+
+## 0.0.8
+
+### Patch Changes
+
+- 5e8460c: Prefer strict JSON Schema sampling for eligible context,
+  LSP, harness, Factory, and Team Mode tools.
+- 5389efc: Refine harness lifecycle and selection to prevent
+  unnecessary commit scaffolds while preserving runtime enforcement
+  boundaries.
+
+## 0.0.7
+
+### Patch Changes
+
+- c425095: Generate shared README maintenance blocks deterministically
+  and validate package documentation links without removing
+  package-specific guidance.
+
+## 0.0.6
+
+### Patch Changes
+
+- df03901: Replace explicit any usages with precise shared, inferred,
+  and fixture types throughout the monorepo safely.
+
+## 0.0.5
+
+### Patch Changes
+
+- 9c8e205: Separate immutable harness policy from amendable scaffolds,
+  adding audited versioning, clearer precedence, and safer
+  enforcement.
+
+## 0.0.4
+
+### Patch Changes
+
+- 7cc67f7: Render active harness state compactly in the TUI without
+  persistent verbose task summary widget.
+
+## 0.0.3
+
+### Patch Changes
+
+- ba4ceed: Update team orchestration guidance to prefer shared cwd
+  mutation and reserve worktrees for explicit isolation.
+
+## 0.0.2
+
+### Patch Changes
+
+- e8c1bfe: Add pi-harness runtime with task contracts, team execution,
+  enforcement, and outcome artifacts.

package/README.md

@@ -11,18 +11,19 @@
 
 <!-- package-readme:header:end -->
 
-Build and run ephemeral task harnesses with my-pi primitives. A
-harness is a `/tmp` runtime containing a machine-readable contract,
-executor prompt, task brief, validation script, review script, logs,
-status, and runtime enforcement. Inspired by Ornith's self-scaffolding
-design, the runtime separates an immutable outer policy from a
-versioned, amendable inner scaffold.
+Prompt guidance uses Pi's named system-prompt sections. It coexists
+with user `SYSTEM.md` and `APPEND_SYSTEM.md` files and other
+extensions without replacing the complete prompt.
 
-The harness tools use normal object-schema tool calling because their
-optional policy fields are not portable across providers'
-strict-schema rules.
+Optional task scaffolding for Pi: a contract, working-state baseline,
+validation scripts, progress log, and reviewable outcome. Pi still
+owns the agent loop, sessions, tools, and permission hooks.
 
-## Installation
+Use direct work for routine changes. Use a harness when the user asks
+for one or a concrete execution contract adds value. Assessment is
+optional advice, not a prerequisite or a read-only security mode.
+
+## Install
 
 <!-- package-readme:install:start -->
 
@@ -32,181 +33,129 @@ pi install npm:@spences10/pi-harness
 
 <!-- package-readme:install:end -->
 
-Local development from this monorepo:
+## Create and execute
 
-```bash
-pnpm --filter @spences10/pi-harness run build
-pi install ./packages/pi-harness
-# or for one run only
-pi -e ./packages/pi-harness
+```text
+/harness create <task>
 ```
 
-## What it does
-
-`pi-harness` adds:
-
-- `/assess` command for evidence-gated capability assessment
-- `/harness` command for assess-before-create, run, review, status,
-  use, and clear
-- `harness_assess` and `harness_assessment_submit` tools for read-only
-  orientation and structured adoption decisions
-- guarded `harness_create` tool that cannot bypass assessment approval
-- `harness_amend` tool for audited, versioned changes to the inner
-  scaffold
-- `harness_update` tool for phase/status/evidence logging
-- generated `OUTCOME.md` and `outcome.json` review artifacts
-- dirty-baseline tracking so pre-existing repo changes are reported
-  but not treated as task drift
-- worktree-aware validate/review scripts for team-mode executors
-- `harness_read` tool for summaries
-- `before_agent_start` context injection for the active harness
-- `tool_call` enforcement for edit/write paths and forbidden commands
-- compact TUI status for the active harness
-- bundled `create-harness`, `execute-harness`, and `review-harness`
-  skills
-
-## Runtime layout
+The agent calls `harness_create` with the task and at least one
+accepted validation command. Scope defaults to the project; provide
+`allowed_paths` to narrow it. Normal project test development is
+allowed by default. Set `allow_test_changes: false` only when the task
+explicitly requires protecting those files.
 
-```text
-/tmp/my-pi-harness-<id>/
-  harness.json      # outer policy, versioned inner scaffold, amendment history
-  SYSTEM.md         # executor system prompt
-  TASK.md           # task brief and required loop
-  status.json       # phase/status/evidence log
-  OUTCOME.md        # reviewable outcome summary
-  outcome.json      # machine-readable outcome summary
-  outcome.mjs       # outcome artifact refresher
-  validate.sh       # validation runner
-  review.sh         # drift/review helper
-  logs/events.jsonl # append-only event log
-```
+Creation does not require a separate assessment or approval roundtrip.
+It does not authorize new capabilities, commits, pushes, releases,
+deployments, destructive operations, or peer collaboration beyond the
+user's request.
+
+The runtime lives under `/tmp/my-pi-harness-<id>/`:
+
+- `harness.json`: accepted maximum scope and checks, plus the
+  execution scaffold and amendment history.
+- `TASK.md` and `SYSTEM.md`: task and workflow guidance.
+- `validate.sh` and `review.sh`: manual validation and drift review.
+- `status.json` and `logs/`: progress, executed checks and output.
+- `OUTCOME.md` and `outcome.json`: review artifacts.
+
+### Completion means checks ran
+
+Request `status: completed` through `harness_update`. The extension
+runs the accepted commands, any additional scaffold checks, and the
+drift guard through Pi's normal nested Bash tool pipeline. Permission
+hooks, cancellation and tool-result handling still apply.
+
+Completion requires successful checks against an unchanged contract
+and Git-visible working state. A failure, denied tool, interruption or
+concurrent change cannot become success merely because an agent writes
+“passed”. Results include executed-check records and output-file
+references. Manual evidence strings are self-reported notes, not
+validation proof.
+
+Failed checks can be fixed and retried; there is no one-attempt
+escalation rule. Completed runs reject further API amendments and
+status mutations. Their active guard clears on the next direct user
+turn or session startup; do not create another harness just to commit
+already-reviewed work.
+
+### Amend strategy, not acceptance
+
+`harness_amend` records a versioned strategy change. It cannot remove
+or replace the accepted validation commands or relax an explicit
+no-test-edit restriction. Additional checks are allowed. Scaffold
+scope always intersects the accepted maximum scope, so broadening a
+strategy does not grant access outside the contract.
+
+A genuinely larger task needs user authorization and a new contract,
+not an executor-authored relaxation of its own acceptance criteria.
+
+### Baseline and worktrees
+
+Dirty files are fingerprinted without changing the working tree, HEAD
+or Git index. Later content, index, mode, symlink, deletion and rename
+changes remain visible, including initially untracked files. Only
+fingerprints are saved, not file contents.
 
-## Commands
+A baseline belongs to the workspace where it was captured. Linked
+worktrees use their own Git state, without another workspace's dirty
+file exemptions. Run manual scripts from the execution worktree or set
+`HARNESS_CWD`. Completion uses the current Pi execution directory and
+rejects unrelated repositories.
+
+### Optional assessment
+
+`/assess <task>`, `harness_assess` and `harness_assessment_submit`
+record evidence, existing primitives and a recommendation. Tools,
+native codemode, discovery and MCP remain available. This is advisory
+investigation: it does not enforce read-only access or add an approval
+queue. Normal user authorization still applies.
+
+## Commands and tools
 
 ```text
-/assess <task>
-/assess status
-/assess approve [harness|direct]
-/assess reject
-/assess clear
 /harness create <task>
-/harness run <dir>
-/harness review <dir>
+/harness run [dir]
+/harness review [dir]
 /harness status [dir]
 /harness use <dir>
 /harness clear
+/assess <task>
+/assess status
+/assess clear
 ```
 
-`/assess` and `/harness create` enter the same read-only assessment.
-The agent records repository evidence, existing primitives, rejected
-options, the smallest useful vertical slice, and one recommendation. A
-harness recommendation must include explicit allowed paths and
-validation commands. Direct user approval then creates and activates
-the harness, restores tools for approved direct work, or rejects the
-candidate without project changes. Approved harnesses run through the
-bundled `execute-harness` skill. Harness approval does not authorize
-Factory; Factory requires a separate direct user request for
-evaluation.
-
-An agent can enter assessment with `harness_assess`. If it calls
-`harness_create` without approval, the extension blocks the call and
-starts assessment. This backstop does not detect an agent that
-misclassifies a task and never asks for harness machinery.
-
-Use assessment when a task may benefit from an enforceable execution
-contract because it has material risk, unresolved scope, destructive
-effects, or complex coordination. Use the normal direct workflow for
-bounded, low-risk changes that standard validation can verify, such as
-documentation and copy edits, focused single-file fixes, configuration
-or metadata updates, test expectation changes, formatting, and
-reviewed commit or push follow-ups. A simple ambiguity may need only a
-clarifying question. Broad uncertain refactors, migrations,
-deployments, risky releases, external side effects, and explicit user
-requests are good assessment candidates.
-
-Assessment snapshots the current tool set, keeps an explicit read-only
-research subset active, and filters Bash through a strict
-single-command allowlist. Unknown and mutating custom tools are
-withheld. This is a workflow guard, not an operating-system sandbox.
-In print and JSON modes, an assessment can be submitted but remains
-waiting because direct approval cannot be inferred. RPC clients can
-answer Pi's extension UI request, or send `/assess approve ...` as an
-explicit command.
-
-`harness.json` contains two deliberately different layers:
-
-- `policy`: runtime-owned workspace and verifier protections such as
-  cwd, forbidden paths/commands, available tools, and the dirty
-  baseline. Executors cannot weaken these through amendments.
-- `scaffold`: the model's task interpretation and execution strategy,
-  including allowed paths, validation, test policy, and model roles.
-  It is subordinate to system, developer, and current user
-  instructions and can be revised with `harness_amend`.
-
-Every scaffold amendment increments its version, records its reason
-and requester, regenerates runtime prompts/scripts, and appends an
-audit event. A harness enforcement block reports a contract mismatch;
-it is not a platform-policy refusal. When a harness is active, the TUI
-shows a compact footer/status indicator; use `/harness status [dir]`
-or `harness_read` for the full contract, task, validation, and outcome
-details.
-
-A terminal `completed` or `failed` status seals the run and keeps
-enforcement active for the remainder of the current turn, so an
-executor cannot escape the outer policy by declaring its own work
-complete. The extension automatically deactivates that terminal
-harness on the next direct user turn or when the session starts again.
-Extension-injected messages do not trigger cleanup. Use
-`/harness clear` only to abandon a non-terminal run. Clearing or
-deleting a harness affects only its `/tmp` control state; repository
-changes remain in the working tree. Do not create a new harness merely
-to commit or push already-reviewed work. A risky release, deployment,
-migration, or destructive operation can still justify a dedicated
-harness when explicitly requested or warranted by its actual risk.
-
-Harnesses snapshot dirty files at creation time. Review and outcome
-artifacts focus on changes after that baseline, while still recording
-baseline files in `outcome.json`. If a team-mode executor runs in a
-linked git worktree, run `review.sh` from that worktree or set
-`HARNESS_CWD` so validation, guard checks, and outcome collection use
-the executor workspace.
-
-## Assessment and harness loops
-
-Assessment happens before harness creation:
-
-1. Read-only context recovery
-2. Source-of-truth and existing-primitive capture
-3. Assumption challenge and rejected options
-4. Smallest vertical slice
-5. Structured recommendation
-6. Direct user adoption decision
-
-An approved harness then runs:
-
-1. Contract recovery
-2. Surgical execution
-3. Validation evidence
-4. Drift review
-5. OUTCOME.md/outcome.json review
-6. Delta/risk report
-
-Use `harness_amend` for bounded inner-scaffold changes. A new
-capability or architecture decision requires assessment; an approved
-harness recommendation can then amend the active scaffold.
-Outer-policy expansion requires a separate execution contract instead
-of silent scope growth.
-
-## Using from a custom harness
-
-```ts
-import harness from '@spences10/pi-harness';
-
-// pass `harness` as an ExtensionFactory to your Pi runtime
-```
+`/harness use <dir>` confirms the selected harness directory.
+`/harness clear` confirms when the active harness is cleared, or
+reports that there is no active harness to clear.
+
+Tools: `harness_create`, `harness_amend`, `harness_update`,
+`harness_read`, `harness_assess`, `harness_assessment_submit`.
+
+Execution is direct by default. Team Mode can coordinate independently
+opened peers only when the user authorizes collaboration. This package
+does not spawn or supervise workers.
+
+## Safety and compatibility
 
-`my-pi` imports this package directly and enables it as the built-in
-harness workflow.
+This is workflow scaffolding, **not an OS sandbox**. Direct edit/write
+hooks and final Git drift checks enforce the accepted paths through
+those interfaces. Shell commands and other tools retain the host
+user's permissions and can modify control files; the runtime is not a
+security boundary against hostile code. Use OS/container isolation for
+that threat model. Explicit `forbidden_commands` are optional
+substring checks, not a general shell parser.
+
+Existing temporary runtimes keep old generated scripts: recreate them
+before relying on these changes. Contracts without accepted checks and
+scope cannot complete or amend through the current API.
+
+For programmatic consumers, `create_harness_runtime` now requires
+`validation_commands`. `update_harness_runtime` is asynchronous;
+completion requires a trusted `HarnessVerificationOptions.run` backend
+that executes the supplied commands in the supplied cwd and respects
+the signal. The extension supplies this through Pi's tool pipeline.
+Removed assessment-locking helpers are no longer exported.
 
 ## Development
 
@@ -215,7 +164,3 @@ pnpm --filter @spences10/pi-harness run check
 pnpm --filter @spences10/pi-harness run test
 pnpm --filter @spences10/pi-harness run build
 ```
-
-## License
-
-MIT

package/dist/assessment.d.ts

@@ -16,7 +16,7 @@ export declare const harness_assessment_submit_params_schema: Type.TObject<{
         cwd: Type.TOptional<Type.TString>;
         allowed_paths: Type.TOptional<Type.TArray<Type.TString>>;
         forbidden_paths: Type.TOptional<Type.TArray<Type.TString>>;
-        validation_commands: Type.TOptional<Type.TArray<Type.TString>>;
+        validation_commands: Type.TArray<Type.TString>;
         forbidden_commands: Type.TOptional<Type.TArray<Type.TString>>;
         allow_test_changes: Type.TOptional<Type.TBoolean>;
         escalation_rules: Type.TOptional<Type.TArray<Type.TString>>;
@@ -32,7 +32,7 @@ export type HarnessAssessParams = Static<typeof harness_assess_params_schema>;
 export type HarnessAssessmentRecord = Static<typeof harness_assessment_submit_params_schema>;
 export type HarnessAssessmentRecommendation = HarnessAssessmentRecord['recommendation'];
 export type HarnessAssessmentSource = 'agent' | 'user' | 'harness-create';
-export type HarnessAssessmentStatus = 'assessing' | 'awaiting_approval' | 'approved' | 'rejected';
+export type HarnessAssessmentStatus = 'assessing' | 'assessed' | 'awaiting_approval' | 'approved' | 'rejected';
 export interface HarnessAssessmentState {
     id: string;
     version: number;
@@ -40,20 +40,12 @@ export interface HarnessAssessmentState {
     task: string;
     source: HarnessAssessmentSource;
     started_at: string;
-    tools_before_assessment: string[];
+    tools_before_assessment?: string[];
     record?: HarnessAssessmentRecord;
     decision?: HarnessAssessmentRecommendation;
 }
-export declare function create_assessment_state(task: string, source: HarnessAssessmentSource, tools_before_assessment: string[], now?: Date): HarnessAssessmentState;
+export declare function create_assessment_state(task: string, source: HarnessAssessmentSource, tools_before_assessment?: string[], now?: Date): HarnessAssessmentState;
 export declare function submit_assessment_record(state: HarnessAssessmentState, record: HarnessAssessmentRecord): HarnessAssessmentState;
 export declare function assessment_active(state: HarnessAssessmentState | undefined): boolean;
-export declare function assessment_tool_names(active_tool_names: string[]): string[];
-export declare function is_assessment_tool_allowed(tool_name: string): boolean;
-export declare function check_assessment_command(command: string): {
-    ok: true;
-} | {
-    ok: false;
-    reason: string;
-};
 export declare function assessment_context(state: HarnessAssessmentState): string;
 export declare function format_assessment_record(state: HarnessAssessmentState): string;