@spences10/pi-harness 0.0.2

package/dist/schema.d.ts

@@ -0,0 +1,105 @@
+import { Type, type Static } from 'typebox';
+export declare const HARNESS_VERSION = 1;
+export declare const HARNESS_CUSTOM_TYPE = "pi-harness-state";
+export declare const DEFAULT_FORBIDDEN_COMMANDS: string[];
+export declare const thinking_levels_schema: Type.TUnion<[Type.TLiteral<"off">, Type.TLiteral<"minimal">, Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">, Type.TLiteral<"xhigh">]>;
+export declare const harness_create_params_schema: Type.TObject<{
+    task: Type.TString;
+    slug: Type.TOptional<Type.TString>;
+    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>>;
+    forbidden_commands: Type.TOptional<Type.TArray<Type.TString>>;
+    allow_test_changes: Type.TOptional<Type.TBoolean>;
+    planner_model: Type.TOptional<Type.TString>;
+    planner_thinking: Type.TOptional<Type.TUnion<[Type.TLiteral<"off">, Type.TLiteral<"minimal">, Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">, Type.TLiteral<"xhigh">]>>;
+    executor_model: Type.TOptional<Type.TString>;
+    executor_thinking: Type.TOptional<Type.TUnion<[Type.TLiteral<"off">, Type.TLiteral<"minimal">, Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">, Type.TLiteral<"xhigh">]>>;
+    reviewer_model: Type.TOptional<Type.TString>;
+    reviewer_thinking: Type.TOptional<Type.TUnion<[Type.TLiteral<"off">, Type.TLiteral<"minimal">, Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">, Type.TLiteral<"xhigh">]>>;
+}>;
+export type HarnessCreateParams = Static<typeof harness_create_params_schema>;
+export declare const harness_update_params_schema: Type.TObject<{
+    harness_dir: Type.TString;
+    status: Type.TOptional<Type.TUnion<[Type.TLiteral<"created">, Type.TLiteral<"running">, Type.TLiteral<"reviewing">, Type.TLiteral<"completed">, Type.TLiteral<"failed">]>>;
+    phase: Type.TOptional<Type.TString>;
+    note: Type.TOptional<Type.TString>;
+    evidence: Type.TOptional<Type.TString>;
+    team_status: Type.TOptional<Type.TString>;
+    remaining_risks: Type.TOptional<Type.TArray<Type.TString>>;
+    changed_files: Type.TOptional<Type.TArray<Type.TString>>;
+}>;
+export type HarnessUpdateParams = Static<typeof harness_update_params_schema>;
+export declare const harness_read_params_schema: Type.TObject<{
+    harness_dir: Type.TString;
+}>;
+export type HarnessReadParams = Static<typeof harness_read_params_schema>;
+export type HarnessStatus = 'created' | 'running' | 'reviewing' | 'completed' | 'failed';
+export type HarnessThinking = Static<typeof thinking_levels_schema>;
+export interface HarnessContract {
+    version: typeof HARNESS_VERSION;
+    id: string;
+    task: string;
+    cwd: string;
+    created_at: string;
+    status: HarnessStatus;
+    planner: {
+        model?: string;
+        thinking?: HarnessThinking;
+    };
+    executor: {
+        model?: string;
+        thinking?: HarnessThinking;
+    };
+    reviewer: {
+        model?: string;
+        thinking?: HarnessThinking;
+    };
+    allowed_paths: string[];
+    forbidden_paths: string[];
+    allowed_tools: string[];
+    validation_commands: string[];
+    forbidden_commands: string[];
+    allow_test_changes: boolean;
+    escalation_rules: string[];
+    baseline_changed_files: string[];
+}
+export interface HarnessLogEntry {
+    timestamp: string;
+    status?: HarnessStatus;
+    phase?: string;
+    note?: string;
+    evidence?: string;
+    team_status?: string;
+    remaining_risks?: string[];
+    changed_files?: string[];
+}
+export interface HarnessOutcome {
+    id: string;
+    status: HarnessStatus;
+    phase?: string;
+    task: string;
+    cwd: string;
+    generated_at: string;
+    execution_cwd: string;
+    changed_files: string[];
+    baseline_changed_files: string[];
+    validation: {
+        commands: string[];
+        evidence: Array<{
+            timestamp: string;
+            phase?: string;
+            evidence: string;
+        }>;
+    };
+    team_status: string;
+    remaining_risks: string[];
+    log: HarnessLogEntry[];
+}
+export interface HarnessStatusFile {
+    id: string;
+    status: HarnessStatus;
+    phase?: string;
+    log: HarnessLogEntry[];
+}

package/dist/schema.js

@@ -0,0 +1,62 @@
+import { Type } from 'typebox';
+export const HARNESS_VERSION = 1;
+export const HARNESS_CUSTOM_TYPE = 'pi-harness-state';
+export const DEFAULT_FORBIDDEN_COMMANDS = [
+    'rm -rf .git',
+    'git reset --hard',
+    'git clean -fd',
+    '--updateSnapshot',
+    ' -u ',
+];
+export const thinking_levels_schema = Type.Union([
+    Type.Literal('off'),
+    Type.Literal('minimal'),
+    Type.Literal('low'),
+    Type.Literal('medium'),
+    Type.Literal('high'),
+    Type.Literal('xhigh'),
+]);
+export const harness_create_params_schema = Type.Object({
+    task: Type.String({ description: 'Task the harness is built for' }),
+    slug: Type.Optional(Type.String({ description: 'Descriptive filesystem-safe name' })),
+    cwd: Type.Optional(Type.String({ description: 'Project working directory' })),
+    allowed_paths: Type.Optional(Type.Array(Type.String({
+        description: 'Path or glob-like path the executor may edit, relative to cwd unless absolute',
+    }))),
+    forbidden_paths: Type.Optional(Type.Array(Type.String({ description: 'Path the executor may not edit' }))),
+    validation_commands: Type.Optional(Type.Array(Type.String({ description: 'Command run from cwd' }))),
+    forbidden_commands: Type.Optional(Type.Array(Type.String({ description: 'Command substring to block' }))),
+    allow_test_changes: Type.Optional(Type.Boolean({
+        description: 'Whether executor may edit test files',
+    })),
+    planner_model: Type.Optional(Type.String()),
+    planner_thinking: Type.Optional(thinking_levels_schema),
+    executor_model: Type.Optional(Type.String()),
+    executor_thinking: Type.Optional(thinking_levels_schema),
+    reviewer_model: Type.Optional(Type.String()),
+    reviewer_thinking: Type.Optional(thinking_levels_schema),
+});
+export const harness_update_params_schema = Type.Object({
+    harness_dir: Type.String({
+        description: 'Harness directory in /tmp',
+    }),
+    status: Type.Optional(Type.Union([
+        Type.Literal('created'),
+        Type.Literal('running'),
+        Type.Literal('reviewing'),
+        Type.Literal('completed'),
+        Type.Literal('failed'),
+    ])),
+    phase: Type.Optional(Type.String()),
+    note: Type.Optional(Type.String()),
+    evidence: Type.Optional(Type.String()),
+    team_status: Type.Optional(Type.String()),
+    remaining_risks: Type.Optional(Type.Array(Type.String())),
+    changed_files: Type.Optional(Type.Array(Type.String())),
+});
+export const harness_read_params_schema = Type.Object({
+    harness_dir: Type.String({
+        description: 'Harness directory in /tmp',
+    }),
+});
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAe,MAAM,SAAS,CAAC;AAE5C,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AACjC,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AACtD,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACzC,aAAa;IACb,kBAAkB;IAClB,eAAe;IACf,kBAAkB;IAClB,MAAM;CACN,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC,KAAK,CAAC;IAChD,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;IACnB,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;IACvB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;IACnB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;IACtB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IACpB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;CACrB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAI,CAAC,MAAM,CAAC;IACvD,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,+BAA+B,EAAE,CAAC;IACnE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAClB,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,kCAAkC,EAAE,CAAC,CAChE;IACD,GAAG,EAAE,IAAI,CAAC,QAAQ,CACjB,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,2BAA2B,EAAE,CAAC,CACzD;IACD,aAAa,EAAE,IAAI,CAAC,QAAQ,CAC3B,IAAI,CAAC,KAAK,CACT,IAAI,CAAC,MAAM,CAAC;QACX,WAAW,EACV,+EAA+E;KAChF,CAAC,CACF,CACD;IACD,eAAe,EAAE,IAAI,CAAC,QAAQ,CAC7B,IAAI,CAAC,KAAK,CACT,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,gCAAgC,EAAE,CAAC,CAC9D,CACD;IACD,mBAAmB,EAAE,IAAI,CAAC,QAAQ,CACjC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,sBAAsB,EAAE,CAAC,CAAC,CAChE;IACD,kBAAkB,EAAE,IAAI,CAAC,QAAQ,CAChC,IAAI,CAAC,KAAK,CACT,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,4BAA4B,EAAE,CAAC,CAC1D,CACD;IACD,kBAAkB,EAAE,IAAI,CAAC,QAAQ,CAChC,IAAI,CAAC,OAAO,CAAC;QACZ,WAAW,EAAE,sCAAsC;KACnD,CAAC,CACF;IACD,aAAa,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IAC3C,gBAAgB,EAAE,IAAI,CAAC,QAAQ,CAAC,sBAAsB,CAAC;IACvD,cAAc,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5C,iBAAiB,EAAE,IAAI,CAAC,QAAQ,CAAC,sBAAsB,CAAC;IACxD,cAAc,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5C,iBAAiB,EAAE,IAAI,CAAC,QAAQ,CAAC,sBAAsB,CAAC;CACxD,CAAC,CAAC;AAMH,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAI,CAAC,MAAM,CAAC;IACvD,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC;QACxB,WAAW,EAAE,2BAA2B;KACxC,CAAC;IACF,MAAM,EAAE,IAAI,CAAC,QAAQ,CACpB,IAAI,CAAC,KAAK,CAAC;QACV,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC;QACzB,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC;QACzB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;KACtB,CAAC,CACF;IACD,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IACnC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IAClC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IACtC,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IACzC,eAAe,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,aAAa,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;CACvD,CAAC,CAAC;AAMH,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC,MAAM,CAAC;IACrD,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC;QACxB,WAAW,EAAE,2BAA2B;KACxC,CAAC;CACF,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@spences10/pi-harness",
+  "version": "0.0.2",
+  "description": "Ephemeral task harness runtime for my-pi agent workflows",
+  "keywords": [
+    "agent",
+    "coding",
+    "harness",
+    "pi",
+    "pi-package",
+    "skills"
+  ],
+  "homepage": "https://github.com/spences10/my-pi/tree/main/packages/pi-harness#readme",
+  "license": "MIT",
+  "author": "Scott Spence <me@scottspence.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spences10/my-pi.git",
+    "directory": "packages/pi-harness"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.80.2",
+    "@types/node": "^25.8.0",
+    "typebox": "^1.1.38",
+    "typescript": "^6.0.3",
+    "vitest": "4.1.9"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "image": "https://raw.githubusercontent.com/spences10/my-pi/main/assets/pi-package-preview.png"
+  },
+  "scripts": {
+    "build": "pnpm --filter \"$npm_package_name^...\" run build:self && pnpm run build:self",
+    "build:self": "vp exec tsc -p tsconfig.build.json",
+    "check": "pnpm --filter \"$npm_package_name^...\" run build:self && pnpm run check:self",
+    "check:self": "vp exec tsc --noEmit -p tsconfig.json",
+    "test": "pnpm --filter \"$npm_package_name^...\" run build:self && pnpm run test:self",
+    "test:self": "vp exec vitest run",
+    "coverage:self": "vp exec vitest run --coverage",
+    "coverage": "pnpm --filter \"$npm_package_name^...\" run build:self && pnpm run coverage:self"
+  }
+}

package/skills/create-harness/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: create-harness
+# prettier-ignore
+description: Use when creating executable /tmp Pi task harnesses for ambiguous or high-risk coding work. Builds contract, prompts, validation, logs, and enforcement rules.
+compatibility:
+  Requires my-pi or Pi with the pi-harness extension tools enabled.
+---
+
+# Create Harness
+
+Create a real my-pi task harness, not a prose-only plan. The harness
+must live in `/tmp` and be created with the `harness_create` tool
+after context gathering.
+
+## Workflow
+
+1. Recover context with read-only tools first: docs, package READMEs,
+   source, tests, git, LSP, recall, browser, or MCP as relevant.
+2. Establish source of truth: list the concrete files, commands, docs,
+   or evidence the harness is grounded in.
+3. Challenge assumptions: identify uncertainties and whether the
+   executor may decide or must escalate.
+4. Define the execution contract: allowed paths, forbidden paths,
+   validation commands, test-change policy, and forbidden shortcuts.
+5. Call `harness_create` with the task and contract fields.
+6. If the `team` tool is available, create or reuse a team and call
+   `task_create` with the harness directory in the description.
+7. Read back the created harness path and report how to run it with
+   `/harness run <dir>`.
+
+## Contract Guidance
+
+- Keep `allowed_paths` narrow. Use `.` only when the task genuinely
+  spans the repo.
+- Set `allow_test_changes: false` unless changing tests is explicitly
+  part of the task.
+- Include validation commands whenever the project has a known check
+  path.
+- Add `forbidden_commands` for task-specific hazards.
+- Do not implement the task during harness creation unless the user
+  explicitly asks for combined create/run.
+- Do not spawn a teammate during creation; save spawning for the run
+  phase.
+
+## Output
+
+Report only:
+
+- harness directory
+- source-of-truth inputs used
+- allowed scope
+- validation commands
+- team task id if one was created
+- open decisions or escalation triggers

package/skills/execute-harness/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: execute-harness
+# prettier-ignore
+description: Use when running an existing /tmp Pi task harness. Executes inside the active contract, records status, respects enforcement, and loops through validation.
+compatibility:
+  Requires my-pi or Pi with the pi-harness extension tools enabled.
+---
+
+# Execute Harness
+
+Run the task through an existing my-pi harness. The harness is the
+execution contract.
+
+## Workflow
+
+1. Resolve the harness directory from the user request or active
+   harness context.
+2. Read `harness.json`, `SYSTEM.md`, `TASK.md`, and `status.json`
+   before editing.
+3. Call `harness_update` with `status: running` and the current phase.
+4. If the `team` tool is available and you are the team lead, create
+   or reuse a team, create/claim a task for the harness, and use
+   `member_spawn` with `workspace_mode: worktree` and `mutating: true`
+   to run one executor teammate against the harness.
+5. The teammate prompt must tell it to read `harness.json`,
+   `SYSTEM.md`, `TASK.md`, and `status.json`, execute only inside the
+   contract, run `validate.sh` and `review.sh`, update harness
+   evidence, and report changed files plus risks.
+6. Recover any remaining source-of-truth context needed to act safely.
+7. Execute surgically inside `allowed_paths`; do not fight
+   enforcement.
+8. Record decisions, phase changes, and validation evidence with
+   `harness_update`, including team status and remaining risks when
+   known.
+9. Run `<harness_dir>/validate.sh`.
+10. Run `<harness_dir>/review.sh` from the execution workspace. If
+    using a linked worktree, run it from that worktree or set
+    `HARNESS_CWD` to the worktree path.
+11. Review `<harness_dir>/OUTCOME.md` or `<harness_dir>/outcome.json`
+    for changed files, baseline ignored files, validation evidence,
+    team status, and risks.
+12. Mark `completed` only when validation passes and no escalation
+    rule applies; otherwise mark `failed` with evidence.
+
+## Rules
+
+- Do not edit outside the harness contract.
+- Do not weaken tests, fake outputs, or bypass validation.
+- If enforcement blocks an action, update the harness as failed or ask
+  for a planner/user amendment.
+- If validation fails after one focused fix attempt, escalate.
+- If team mode is unavailable, run the harness directly in the current
+  session and say that no teammate was spawned.
+- Keep the final report to changed files, validation evidence, team
+  status/results, and remaining risks.

package/skills/review-harness/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: review-harness
+# prettier-ignore
+description: Use when reviewing implementation work that ran through a /tmp Pi task harness. Checks contract drift, unsafe shortcuts, validation evidence, and status honesty.
+compatibility:
+  Requires my-pi or Pi with the pi-harness extension tools enabled.
+---
+
+# Review Harness
+
+Review the completed or failed work against the harness contract.
+
+## Workflow
+
+1. Resolve the harness directory and read `harness.json`, `TASK.md`,
+   `status.json`, `OUTCOME.md` or `outcome.json`, and
+   `logs/events.jsonl` if present.
+2. Run or inspect `<harness_dir>/review.sh`.
+3. Inspect git diff and changed files.
+4. Compare changes against `allowed_paths`, `forbidden_paths`,
+   test-change policy, and escalation rules.
+5. Verify validation evidence from `status.json`, logs, and command
+   output.
+6. Decide: pass, needs executor fix, or escalate to planner/user.
+
+## Review Checks
+
+- Did work stay inside allowed paths?
+- Were tests changed when `allow_test_changes` is false?
+- Were validators weakened, deleted, skipped, or bypassed?
+- Were outputs faked or hardcoded to satisfy checks?
+- Are status and evidence entries honest and complete?
+- Does the outcome artifact include changed files, validation
+  evidence, team status, and remaining risks?
+- Did the executor make unapproved architecture decisions?
+
+## Output Shape
+
+```md
+## Verdict
+
+Pass | Needs executor fix | Escalate
+
+## Findings
+
+- P0/P1/P2: <issue> — `<path>` — <required action>
+
+## Validation Evidence
+
+- `<command>` — pass/fail/not run — <evidence>
+
+## Required Next Step
+
+- <one action>
+```