@spences10/pi-harness 0.1.1 → 0.2.0

package/skills/create-harness/SKILL.md

@@ -1,71 +1,28 @@
 ---
 name: create-harness
 # prettier-ignore
-description: Use when assessing ambiguous or high-risk coding work before creating an approved task harness. Establishes evidence, existing primitives, rejected options, a smallest vertical slice, and an optional execution contract.
-compatibility:
-  Requires my-pi or Pi with the pi-harness extension tools enabled.
+description: Use when the user requests a task harness or a concrete execution contract adds value for risky work. Creates task scaffolding directly; assessment is optional.
+compatibility: Requires Pi with the pi-harness extension enabled.
 ---
 
-# Assess and Create Harness
+# Create a Task Harness
 
-A harness must be earned by an approved assessment. Do not turn
-candidate capabilities directly into an execution contract.
+Use direct work for routine changes. Do not introduce a harness just
+to satisfy process, or expand a candidate idea into a larger project.
 
-## Use threshold
+1. Recover the user's task, repository conventions and acceptance
+   checks.
+2. Call `harness_create` with the task and non-empty validation
+   commands. Add `allowed_paths` when a scope narrower than the
+   project is useful. Normal source and test development are allowed
+   by default.
+3. Read the resulting contract and use the `execute-harness` skill.
 
-Start assessment when work may benefit from an enforceable execution
-contract because it has material risk, unresolved scope, destructive
-effects, or complex coordination. Good candidates include broad
-uncertain refactors, migrations, deployments, risky releases, external
-side effects, and explicit user requests.
+No separate assessment or approval roundtrip is required to create the
+scaffold. If the need or architecture is genuinely uncertain, optional
+`harness_assess` can record investigation and a recommendation without
+locking tools. It is not a read-only security mode.
 
-Use direct work for bounded, low-risk tasks that standard validation
-can verify. A simple ambiguity may need only a clarifying question.
-
-## Workflow
-
-1. Call `harness_assess` before repository mutation. Call it by
-   itself.
-2. Recover context with the remaining read-only tools.
-3. Establish source of truth from concrete source, tests, docs,
-   history, and observed behavior.
-4. Find existing Pi, package, project, or platform primitives before
-   proposing a new capability.
-5. Challenge assumptions. Record rejected options and why the evidence
-   rejects them.
-6. Define the smallest useful vertical slice or falsifiable
-   experiment.
-7. Call `harness_assessment_submit` with one recommendation:
-   - `direct` for bounded work;
-   - `harness` when an execution contract adds value;
-   - `reject` when the work has not earned adoption.
-8. For a harness recommendation, include explicit allowed paths and
-   validation commands in the proposed contract.
-9. Wait for direct user approval. Do not infer approval from agent
-   text or continue implementation while approval is pending.
-10. The extension creates and activates an approved harness
-    atomically. Run it with the `execute-harness` skill. Harness
-    approval does not authorize Factory; use Factory only after a
-    direct user request to evaluate it. Do not call `harness_create`
-    to bypass assessment.
-
-## Scope changes
-
-Use `harness_amend` for bounded changes inside an approved capability.
-A new capability, architecture decision, or outer-policy expansion
-requires another assessment.
-
-## Rules
-
-- Assessment state is session control state, not project source.
-- Read-only mode forbids project edits, writes, commits, package
-  installation, delegation, and other mutating tools.
-- A rejected capability is a valid outcome.
-- Do not create a planner, task graph, or backlog from rejected
-  candidates.
-- Do not implement during assessment.
-
-## Output
-
-Submit only the structured assessment record. The extension presents
-it for user approval and handles the chosen exit.
+Creation does not authorize commits, pushes, releases, destructive
+operations or scope outside the user's request. A broader accepted
+contract needs user authorization, not an executor's self-amendment.

package/skills/execute-harness/SKILL.md

@@ -1,74 +1,35 @@
 ---
 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.
+description: Use when executing an existing Pi task harness. Works inside accepted scope, records progress, and requests evidence-backed completion with normal fix-and-retry loops.
+compatibility: Requires Pi with the pi-harness extension enabled.
 ---
 
-# Execute Harness
+# Execute a Task Harness
 
-Run the task through an existing my-pi harness. Its outer policy is
-the runtime trust boundary; its versioned inner scaffold is an
-amendable execution plan subordinate to system, developer, and current
-user instructions.
+1. Read the harness contract and task. Recover project context.
+2. Record progress with `harness_update`. Work directly unless the
+   user has authorized collaboration with existing Team Mode peers.
+3. Implement inside the accepted maximum scope. Normal project test
+   development is allowed unless explicitly excluded. Do not weaken
+   tests or fake outputs to manufacture success.
+4. Use `harness_amend` for strategy changes. Accepted checks cannot be
+   removed, and scaffold scope never grants a larger accepted
+   boundary.
+5. Inspect and run checks as useful during development. Fix ordinary
+   failures and retry; no arbitrary single-fix escalation applies.
+6. Request `harness_update` with `status: completed`. It reruns
+   accepted checks and drift review through normal tool hooks, stores
+   outputs, and only records completion for a stable passing artifact.
+7. Read `OUTCOME.md` or `outcome.json`, inspect the diff and report
+   actual validation, unresolved risks and any review still needed.
 
-## Workflow
+A failed or interrupted completion attempt is not success. Fix the
+cause or ask for genuinely missing authority. A changed artifact must
+be checked again. Manual evidence strings are notes, not proof.
 
-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 one
-   `member_spawn` executor with `mutating: true` for file-editing
-   work. Default to the contract `cwd`; use `workspace_mode: worktree`
-   only when the user asks for isolation or the plan covers setup,
-   runtime state, merge, and cleanup ownership.
-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. If using a worktree,
-   set `HARNESS_CWD` to that worktree for validation and review.
-6. Recover any remaining source-of-truth context needed to act safely.
-7. Execute surgically inside `scaffold.allowed_paths`. Use
-   `harness_amend` for a bounded change inside the approved
-   capability. If user direction or source evidence introduces a new
-   capability, architecture decision, or outer-policy expansion, stop
-   execution and enter assessment instead of silently expanding the
-   harness. An approved harness recommendation may then amend the
-   active scaffold.
-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. A terminal
-    status seals the run and keeps its guard active for the remainder
-    of the current turn. The extension deactivates it on the next
-    direct user turn or session startup.
-
-## Rules
-
-- Do not bypass the outer policy. Do not edit outside the active
-  scaffold without first recording an authorized amendment.
-- Do not create a replacement harness merely to commit or push
-  already-reviewed changes or to escape a completed run's guard. The
-  harness is control state, not a worktree. Use `/harness clear` only
-  to abandon a non-terminal run.
-- Do not weaken tests, fake outputs, or bypass validation.
-- An enforcement block is a harness mismatch, not a platform-policy
-  refusal. Amend the scaffold when authorized; otherwise ask the user.
-  Mark failed only when the task cannot proceed.
-- 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.
+The harness is temporary workflow state, not an OS sandbox, worktree,
+worker supervisor or a substitute for independent review. Team Mode
+cannot spawn workers. Commits and external effects still require their
+own user authorization. Completed runs are sealed; do not create a new
+harness merely to commit their reviewed changes.

package/skills/review-harness/SKILL.md

@@ -1,59 +1,26 @@
 ---
 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.
+description: Use when reviewing work performed through a Pi task harness. Checks accepted scope, executed validation records, final artifacts and remaining risks without trusting self-reported completion notes.
+compatibility: Requires Pi with the pi-harness extension enabled.
 ---
 
-# Review Harness
-
-Review completed or failed work against the immutable outer policy and
-the complete versioned scaffold/amendment history.
-
-## 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 `policy.forbidden_paths`, the active
-   `scaffold.allowed_paths`, test policy, escalation rules, and all
-   recorded amendments.
-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 the outer policy and active scaffold?
-- Were scaffold changes authorized, versioned, and honestly recorded?
-- Did any amendment attempt to weaken the outer trust boundary?
-- 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>
-```
+# Review Harness Work
+
+1. Read `harness.json`, task, status, amendment history and outcome.
+2. Inspect the actual diff in the execution workspace. Run `review.sh`
+   there or set `HARNESS_CWD` for a linked worktree.
+3. Confirm the final changes respect accepted maximum scope and
+   explicit exclusions. Strategy amendments must not grant wider
+   authority.
+4. Inspect executed validation records and referenced output, not just
+   manual evidence strings. Check that accepted validators were
+   retained, failures were handled honestly, and the reviewed artifact
+   is current.
+5. Check for weakened tests, fake outputs, missed user-facing
+   behaviour, and approvals still required for external effects.
+
+Report pass, needs fix, or needs a user decision, with concrete
+findings, validation run or reused, and remaining risks. A passing
+runtime check is not an independent semantic review or an OS security
+guarantee.