@hallucination-studio/harness-engine 1.0.0-beta.9.bb2cd30 → 1.0.0-nightly.20260613.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hallucination Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,26 +1,38 @@
 # Harness Engine
 
+[![npm version](https://img.shields.io/npm/v/%40hallucination-studio%2Fharness-engine?color=cb3837&logo=npm)](https://www.npmjs.com/package/@hallucination-studio/harness-engine)
+[![npm downloads](https://img.shields.io/npm/dm/%40hallucination-studio%2Fharness-engine?logo=npm)](https://www.npmjs.com/package/@hallucination-studio/harness-engine)
+[![CI](https://github.com/hallucination-studio/harness-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/hallucination-studio/harness-engine/actions/workflows/ci.yml)
+[![Publish Release](https://github.com/hallucination-studio/harness-engine/actions/workflows/publish-release.yml/badge.svg)](https://github.com/hallucination-studio/harness-engine/actions/workflows/publish-release.yml)
+[![Publish Nightly](https://github.com/hallucination-studio/harness-engine/actions/workflows/publish-nightly.yml/badge.svg)](https://github.com/hallucination-studio/harness-engine/actions/workflows/publish-nightly.yml)
+[![license](https://img.shields.io/npm/l/%40hallucination-studio%2Fharness-engine)](https://github.com/hallucination-studio/harness-engine/blob/main/LICENSE)
+
 Harness Engine packages a Codex skill that bootstraps an agent-first repository harness.
 It turns the repository-shaping ideas from OpenAI's
 ["Harness engineering: leveraging Codex in an agent-first world"](https://openai.com/index/harness-engineering/)
 into an installable `npx` workflow.
 
 The package does not install a harness into this repository. This repository builds and publishes
-the installer. Users install the bundled `harness-repo-bootstrap` skill into their own project or
+the installer. Users install the bundled `harness-engine` skill into their own project or
 global Codex skill directory, then ask Codex to use that skill to analyze the target repository,
 ask for missing high-impact facts, create the harness files, and keep future work closed-loop.
 
 ## What This Project Does
 
-- Installs the `harness-repo-bootstrap` Codex skill locally, globally, or into a custom skills directory.
+- Installs the `harness-engine` Codex skill locally, globally, or into a custom skills directory.
 - Provides a repository analyzer that detects language, package manager, frontend signals, existing harness files, missing execution-plan state, and missing SOPs.
-- Generates a short routing-style `AGENTS.md` plus durable system-of-record docs such as `ARCHITECTURE.md`, `docs/RELIABILITY.md`, `docs/SECURITY.md`, `docs/QUALITY_SCORE.md`, and `docs/FRONTEND.md`.
-- Creates execution-plan folders for active and completed plans.
+- Generates a short routing-style `AGENTS.md` plus durable system-of-record docs such as `ARCHITECTURE.md`, `docs/RELIABILITY.md`, `docs/SECURITY.md`, and `docs/QUALITY_SCORE.md`.
+- Generates `docs/FRONTEND.md`, `docs/DESIGN.md`, and `docs/design-docs/` only when a frontend surface is detected.
+- Creates version-controlled execution-plan folders for active and completed plans.
 - Adds SOPs for architecture setup, knowledge capture, local observability, and UI validation.
+- Reconciles managed harnesses through the same `init` flow, refreshing managed files and backfilling newly introduced managed files while preserving unmanaged docs.
+- Provides `clean` to remove local skill installs and generated evidence, add `.gitignore` entries, and untrack already committed runtime artifacts so a follow-up commit deletes them from the remote.
 - Enforces a local harness check without assuming the user's project has CI.
+- Previews and optionally removes stale unreferenced generated evidence under `docs/generated/`.
 - Supports durable knowledge closure with stable knowledge IDs and evidence text, so permanent docs can use natural wording instead of duplicated checklist strings.
-- Enforces a local quality gate for execution plans; failed scores write `## Rework Required` into the plan and block `plan-close`.
+- Enforces structured execution-plan state: `acceptance-set` creates a pre-implementation Acceptance Contract, `quality-score` records post-implementation evidence against that contract, and stale or failed scores block `plan-close`.
 - Tracks resumable workstreams so interrupted features, refactors, reliability work, and cleanup efforts can be recovered from repo state instead of chat history.
+- For frontend projects, asks for the desired visual style and initializes a repository-owned visual specification based on the local DESIGN.md format pattern: YAML design tokens plus markdown rationale.
 
 ## Why It Exists
 
@@ -74,55 +86,175 @@ Show where the skill would be installed:
 npx @hallucination-studio/harness-engine where --local
 ```
 
+## Frontend Design Docs
+
+Harness Engine has no external design runtime dependency and never calls an external design skill
+during `init`. When a target repository has no frontend, it does not generate `docs/FRONTEND.md`,
+`docs/DESIGN.md`, or `docs/design-docs/`.
+
+When a frontend is detected, Harness Engine creates:
+
+- `docs/FRONTEND.md`: project positioning, requested style direction, existing frontend code signals, frontend scope, stack notes, validation loop, and the read order for UI work.
+- `docs/DESIGN.md`: a project-owned unified visual specification using YAML design tokens plus markdown rationale, seeded from the human-confirmed style direction and existing frontend code signals. It defines semantic colors, a unified typography scale, spacing/radius tokens, component states, and rules for mapping those tokens into the project's shared style layer.
+- `docs/design-docs/`: durable design decisions and style-system notes.
+
+The templates are informed by the local reference checkout at `/Users/murphy/code/github/design.md`
+for document shape only. The target project owns the content and should replace starter tokens and
+prose with its concrete product style before substantial UI work.
+
+## Update An Installed Skill Package
+
+The `npx` installer installs or replaces the `harness-engine` Codex skill.
+To update an already installed skill, rerun `install` with `--force` in the same install location.
+
+Replace the local skill install:
+
+```bash
+npx @hallucination-studio/harness-engine install --local --force
+```
+
+Replace the global skill install:
+
+```bash
+npx @hallucination-studio/harness-engine install --global --force
+```
+
+Replace a custom skill install:
+
+```bash
+npx @hallucination-studio/harness-engine install --path /path/to/skills --force
+```
+
+After the skill package is installed, the target repository workflow happens inside Codex. In the
+target workspace, invoke the skill:
+
+```text
+$harness-engine
+```
+
+The skill should analyze the workspace and run the single workspace entrypoint:
+
+- If the harness is not installed in that repository, `manage_harness.py init` creates it.
+- If a managed harness already exists, `manage_harness.py init` reconciles it by refreshing managed files and backfilling newly introduced managed files.
+- Unmanaged user files are preserved unless `--force` is explicitly used.
+
+Codex runs the underlying manager commands. Users should not need to call the Python script
+directly during normal work.
+
 ## Use The Skill In A Target Repo
 
 After installing, open Codex in the target repository and invoke:
 
 ```text
-$harness-repo-bootstrap
+$harness-engine
 ```
 
 The intended workflow is:
 
 1. Analyze the target repository.
 2. Ask the human only for unresolved, high-impact facts.
-3. Initialize or update the harness files.
-4. Create execution plans for multi-step work.
-5. Log durable knowledge into active plans.
-6. Write the durable facts into permanent docs.
-7. Mark knowledge as written using ID plus evidence text.
-8. Score the finished work across product, UX/operator clarity, architecture, reliability, and security.
-9. If the quality gate fails, implement the generated `## Rework Required` items and score again.
-10. For phased or resumable work, update `Phase Continuity` and `docs/exec-plans/workstreams.md`.
-11. Close the execution plan only after the quality gate passes, phase continuity is recorded, and durable docs are updated.
-12. Run the local harness check before handoff.
+3. Initialize or reconcile the harness files.
+4. Create or reuse execution plans for repository-mutating work, including code, docs, configuration, tests, dependencies, build/release scripts, generated templates, runtime behavior, migrations, cleanup, and review fixes.
+5. Define the Acceptance Contract before implementation with product, UX, architecture, reliability, and security criteria.
+6. Log durable knowledge into active plans.
+7. Write the durable facts into permanent docs.
+8. Mark knowledge as written using ID plus evidence text.
+9. Score the finished work against the Acceptance Contract across product, UX/operator clarity, architecture, reliability, and security.
+10. If the Quality Result fails, implement the generated `## Rework Required` items and score again.
+11. Before closing, record a `Continuation Decision` for the plan.
+12. Close the execution plan only after the Quality Result passes against the current contract fingerprint, the continuation decision is recorded, and durable docs are updated.
+13. Run the local harness check before handoff.
+14. Periodically run `evidence-prune` to preview stale unreferenced generated evidence, and apply it only after reviewing the candidate list.
+
+## User Continuation UX
+
+Users should express the desired continuation state in natural language. Codex then runs the
+required harness commands and repairs any blocked state before handoff.
+
+Useful phrases:
+
+- "这项完成了，没有后续" / "mark this complete"
+- "这项要继续到下一阶段" / "continue this as a follow-up workstream"
+- "先暂停，等 API 定稿后恢复" / "pause until the API contract is approved"
+- "停止这个方向，记录原因" / "stop this work and record why"
+- "这个放到技术债，不进入当前 workstream" / "defer this to tech debt"
+
+When the user says a task should continue or pause, Codex records the workstream, next action,
+resume notes, and goal in `docs/exec-plans/workstreams.md`. When the user says it is complete,
+Codex records a complete decision and closes the plan without creating a workstream entry.
+
+## CLI Reference
 
-The installed skill exposes the underlying script at:
+The installed skill exposes a manager script for Codex and for advanced debugging:
 
 ```bash
-python3 .codex/skills/harness-repo-bootstrap/scripts/manage_harness.py --help
+python3 .codex/skills/harness-engine/scripts/manage_harness.py --help
+```
+
+For frontend or visual-design work, the generated harness uses `docs/FRONTEND.md` to route agents through `docs/DESIGN.md`. `docs/FRONTEND.md` defines which files are controlled by `docs/DESIGN.md`: design notes under `docs/design-docs/`, Tailwind theme files, global CSS variables, component theme modules, Storybook/theme previews, and UI implementation files that consume shared tokens or style rules. Agents should read `docs/FRONTEND.md`, then `docs/DESIGN.md`, then the relevant component, theme, or stylesheet.
+
+These commands are not the primary user interface. They are shown so maintainers can debug or
+inspect what Codex runs:
+
+```bash
+python3 .codex/skills/harness-engine/scripts/manage_harness.py analyze --repo . --output analysis.json
+python3 .codex/skills/harness-engine/scripts/manage_harness.py sample-answers --analysis analysis.json --output answers.json
+python3 .codex/skills/harness-engine/scripts/manage_harness.py init --repo . --answers answers.json
+python3 .codex/skills/harness-engine/scripts/manage_harness.py plan-start --repo . --slug feature-name --goal "Implement the feature"
+python3 .codex/skills/harness-engine/scripts/manage_harness.py acceptance-set --repo . --plan docs/exec-plans/active/2026-06-11-feature-name.md --product "The feature satisfies the named user workflow and expected output." --ux "The user or operator can complete the workflow without ambiguous states." --architecture "The change fits the existing module boundaries and keeps plan state recoverable." --reliability "The validation commands and failure evidence are repeatable from a clean checkout." --security "The change introduces no secrets and preserves sensitive-data handling rules."
+python3 .codex/skills/harness-engine/scripts/manage_harness.py quality-score --repo . --plan docs/exec-plans/active/2026-06-11-feature-name.md --product-correctness 8 --product-note "Product assertions passed" --ux-operator-clarity 8 --ux-note "User workflow evidence passed" --architecture-maintainability 8 --architecture-note "Boundary and maintainability review passed" --reliability-observability 8 --reliability-note "Tests and smoke checks passed" --security-data-handling 8 --security-note "No new sensitive-data paths or secrets"
+python3 .codex/skills/harness-engine/scripts/manage_harness.py continuation-set --repo . --plan docs/exec-plans/active/2026-06-11-feature-name.md --decision complete --closure-reason "Feature is complete with no follow-up."
+python3 .codex/skills/harness-engine/scripts/manage_harness.py continuation-set --repo . --plan docs/exec-plans/active/2026-06-11-feature-name.md --decision continue --workstream feature-name --next-target docs/exec-plans/workstreams.md#feature-name --next-action "Create the next execution plan" --goal "Deliver the feature across follow-up execution plans"
+python3 .codex/skills/harness-engine/scripts/manage_harness.py check --repo .
+python3 .codex/skills/harness-engine/scripts/manage_harness.py evidence-prune --repo . --older-than-days 14
+python3 .codex/skills/harness-engine/scripts/manage_harness.py evidence-prune --repo . --older-than-days 14 --apply
+python3 .codex/skills/harness-engine/scripts/manage_harness.py clean --repo .
+python3 .codex/skills/harness-engine/scripts/manage_harness.py clean --repo . --apply
+```
+
+The quality workflow is intentionally local and repository-owned. It does not require the user's
+project to have CI. Active plans must have a ready Acceptance Contract sidecar so work is
+recoverable before implementation finishes. Completed plans must have a passing Quality Result
+scored against the current Acceptance Contract fingerprint; `plan-close` rejects stale scores,
+open defects, unresolved placeholders, and unresolved durable knowledge. Blocked `plan-close`
+commands return structured JSON with `status: "blocked"`, a stable `reason`, a user-readable
+`message`, and machine-readable `details`.
+
+## Version Control Policy
+
+Commit harness docs that carry durable repository knowledge: `AGENTS.md`, `ARCHITECTURE.md`,
+`docs/PLANS.md`, `docs/QUALITY_SCORE.md`, `docs/RELIABILITY.md`, `docs/SECURITY.md`,
+`docs/FRONTEND.md`, `docs/sops/`, `docs/product-specs/`, `docs/design-docs/`,
+`docs/references/`, and execution-plan state.
+
+Execution plans are project state. Commit active plans, completed plans, JSON sidecars, and `docs/exec-plans/workstreams.md` so another agent can recover the work from the repository.
+
+Do not commit local skill installs or generated evidence by default. `clean --apply` adds these directory-level ignores:
+
+```gitignore
+# harness-engine transient files
+.codex/skills/
+docs/generated/
+# end harness-engine transient files
 ```
 
-Common commands:
+If those files were already committed or pushed, run:
 
 ```bash
-python3 .codex/skills/harness-repo-bootstrap/scripts/manage_harness.py analyze --repo . --output analysis.json
-python3 .codex/skills/harness-repo-bootstrap/scripts/manage_harness.py sample-answers --analysis analysis.json --output answers.json
-python3 .codex/skills/harness-repo-bootstrap/scripts/manage_harness.py init --repo . --answers answers.json
-python3 .codex/skills/harness-repo-bootstrap/scripts/manage_harness.py plan-start --repo . --slug feature-name --goal "Implement the feature"
-python3 .codex/skills/harness-repo-bootstrap/scripts/manage_harness.py quality-score --repo . --plan docs/exec-plans/active/2026-06-11-feature-name.md --product-correctness 8 --ux-operator-clarity 8 --architecture-maintainability 8 --reliability-observability 8 --security-data-handling 8
-python3 .codex/skills/harness-repo-bootstrap/scripts/manage_harness.py phase-set --repo . --plan docs/exec-plans/active/2026-06-11-feature-name.md --mode multi-phase --workstream feature-name --current-phase 1 --next-phase 2 --continuation docs/exec-plans/workstreams.md#feature-name --next-action "Create Phase 2 plan"
-python3 .codex/skills/harness-repo-bootstrap/scripts/manage_harness.py workstream-upsert --repo . --id feature-name --status active --current-plan docs/exec-plans/active/2026-06-11-feature-name.md --next-action "Create Phase 2 plan"
-python3 .codex/skills/harness-repo-bootstrap/scripts/manage_harness.py check --repo .
+python3 .codex/skills/harness-engine/scripts/manage_harness.py clean --repo .
+python3 .codex/skills/harness-engine/scripts/manage_harness.py clean --repo . --apply
+git status --short
+git diff --cached --stat
+git commit -m "Remove harness runtime artifacts from git"
+git push
 ```
 
-The quality gate is intentionally local and repository-owned. It does not require the user's
-project to have CI. `plan-close` refuses to move a plan to `completed` unless `quality-score`
-has passed, and `check` reports active plans whose quality gate is missing or failing.
+`clean --apply` removes local generated evidence, then uses `git rm --cached` to stage removal of tracked local skill installs and generated evidence from git and the remote. It does not remove, ignore, or untrack execution plans, JSON sidecars, or workstreams.
 
-For multi-phase work, `Phase Continuity` and `docs/exec-plans/workstreams.md` form the recovery
-ledger. A plan like `Local Workbench Phase 1` can close only after it records whether the workstream
-continues, pauses, completes, or stops, and where the next agent should resume.
+Every plan closes with a `Continuation Decision`: `complete`, `continue`, `pause`, `stop`, or
+`defer`. Only resumable `continue` and `pause` decisions enter `docs/exec-plans/workstreams.md`;
+one-off completed plans do not need workstream entries. Invalid `continue` or `pause` inputs fail before
+writing workstream state, and workstream goals are taken from `--goal` or the plan goal.
 
 ## Generated Harness Shape
 
@@ -188,6 +320,15 @@ Check npm package contents:
 npm run pack:check
 ```
 
+Before release, run:
+
+```bash
+npm test
+npm run smoke:install
+npm run pack:check
+git diff --check
+```
+
 The publish workflows expect an npm token when trusted publishing is not yet configured:
 
 ```text
@@ -200,15 +341,15 @@ These scores describe the current implementation, not an external guarantee.
 
 | Layer | Score | Notes |
 | --- | ---: | --- |
-| Product fit | 8.5 / 10 | Clear purpose: install a Codex skill that creates and maintains an agent-first repository harness. The main missing piece is broader real-world usage data across more project types. |
-| Skill workflow design | 9 / 10 | Strong progressive workflow: analyze, confirm, initialize/update, plan, capture knowledge, validate, score, rework, record continuity, close. The current skill is opinionated but still adapts to target repositories. |
-| Knowledge, quality, and workstream closure loop | 8.7 / 10 | Stable knowledge IDs plus evidence text reduce noisy doc duplication, `quality-score` blocks closure until failed dimensions are reworked, and workstreams make phased work recoverable. Future work could move plan state into structured sidecar metadata instead of Markdown parsing. |
+| Product fit | 9 / 10 | Clear purpose: install a Codex skill that creates and maintains an agent-first repository harness. Real acceptance against a fresh Go backend plus browser frontend project validated generation and later issue workflows. Broader usage across more project types would still improve confidence. |
+| Skill workflow design | 9.2 / 10 | Strong progressive workflow: analyze, confirm, init/reconcile, plan, capture knowledge, validate, score with evidence notes, rework, record continuity, close. The workflow now explicitly routes repository-mutating feature, bug, refactor, docs, dependency, UI, test, security, performance, and reliability work through the same lifecycle. |
+| Knowledge, quality, and workstream closure loop | 9.3 / 10 | Stable knowledge IDs plus exact destination evidence reduce noisy doc duplication. Execution plans now have JSON sidecars for Acceptance Contracts, Quality Results, defects, and knowledge state; `quality-score` rejects missing evidence notes or missing contracts, defects invalidate stale scores, and workstreams make resumable follow-up work recoverable. |
 | CLI installer | 8 / 10 | Simple local/global/custom install modes, force replacement, and path discovery. It is intentionally minimal and does not manage Codex runtime configuration. |
-| Generated harness docs | 7.5 / 10 | Covers architecture, plans, reliability, security, frontend policy, references, generated artifacts, and SOPs. Templates still require Codex to tighten project-specific language after generation. |
-| Evaluation coverage | 8.2 / 10 | Includes empty-repo init, frontend analysis, quality-gated closed-loop plan behavior, phase continuity, workstream recovery, user-owned doc preservation, and installer smoke tests. More end-to-end Codex acceptance tests would raise confidence. |
+| Generated harness docs | 8.4 / 10 | Covers architecture, plans, reliability, security, frontend policy, broad task intake, issue workflows, references, generated artifacts, and SOPs. The docs now front-load exact knowledge evidence, per-dimension quality notes, default plan lifecycle, and plan placeholder cleanup, but templates still require Codex to tighten project-specific language after generation. |
+| Evaluation coverage | 9.2 / 10 | `npm test` runs 23 structured eval cases covering empty-repo init, frontend analysis, init reconciliation, clean command behavior, broad task intake, closed-loop plan behavior, continuation decisions, path canonicalization, defect recovery, required quality-score notes, exact knowledge evidence, structured sidecars, acceptance readiness, stale score rejection, generated-evidence cleanup, eval report shape, user-owned doc preservation, and frontend design control. A fully automated Codex child-agent E2E would raise this further. |
 | Release automation | 8 / 10 | Supports stable release, beta on every main commit, nightly, manual dry-run, artifacts, provenance, and token fallback. npm first-publish/trusted-publishing setup still requires external configuration. |
-| User-project safety | 8.5 / 10 | The skill avoids adding CI to target projects by default and uses local harness checks instead. It preserves unmanaged files unless forced. |
-| Overall | 8.5 / 10 | Usable and coherent, with the highest leverage still in richer end-to-end evals and more structured plan/knowledge/quality/workstream state. |
+| User-project safety | 8.8 / 10 | The skill avoids adding CI to target projects by default, preserves unmanaged files unless forced, and requires evidence-backed closure for defects and durable knowledge. More destructive-change simulation in evals would improve this score. |
+| Overall | 9.1 / 10 | The skill is now strong enough for regular use: self evals pass across the structured suite, real acceptance covered initial scaffold plus frontend and backend issue workflows, and plan lifecycle state is enforced through JSON sidecars. Remaining leverage is automated child-agent E2E coverage. |
 
 ## Reference
 

package/bin/install.js

@@ -5,8 +5,7 @@ const os = require("os");
 const path = require("path");
 
 const PACKAGE_ROOT = path.resolve(__dirname, "..");
-const SKILL_NAME = "harness-repo-bootstrap";
-const SOURCE_SKILL_DIR = path.join(PACKAGE_ROOT, "skills", SKILL_NAME);
+const SKILL_NAME = "harness-engine";
 
 function printHelp() {
   console.log(`harness-engine
@@ -85,32 +84,45 @@ function copyDir(sourceDir, targetDir) {
   for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
     const sourcePath = path.join(sourceDir, entry.name);
     const targetPath = path.join(targetDir, entry.name);
-    if (entry.isDirectory()) {
+    const stat = fs.statSync(sourcePath);
+    if (stat.isDirectory()) {
       copyDir(sourcePath, targetPath);
+    } else if (entry.isSymbolicLink()) {
+      const linkTarget = fs.readlinkSync(sourcePath);
+      fs.symlinkSync(linkTarget, targetPath);
     } else {
       fs.copyFileSync(sourcePath, targetPath);
-      const stat = fs.statSync(sourcePath);
       fs.chmodSync(targetPath, stat.mode);
     }
   }
 }
 
-function installSkill(destinationDir, force) {
-  const skillTargetDir = path.join(destinationDir, SKILL_NAME);
-  if (!fs.existsSync(SOURCE_SKILL_DIR)) {
-    throw new Error(`Bundled skill not found: ${SOURCE_SKILL_DIR}`);
+function assertSkillSource() {
+  const sourcePath = path.join(PACKAGE_ROOT, "skills", SKILL_NAME);
+  if (!fs.existsSync(sourcePath)) {
+    throw new Error(`Bundled skill not found: ${sourcePath}`);
   }
+}
 
-  if (fs.existsSync(skillTargetDir)) {
-    if (!force) {
-      throw new Error(`Skill already exists at ${skillTargetDir}. Re-run with --force to replace it.`);
-    }
-    fs.rmSync(skillTargetDir, { recursive: true, force: true });
+function removeIfExists(targetPath, force, label) {
+  if (!fs.existsSync(targetPath)) {
+    return;
   }
 
+  if (!force) {
+    throw new Error(`${label} already exists at ${targetPath}. Re-run with --force to replace it.`);
+  }
+
+  fs.rmSync(targetPath, { recursive: true, force: true });
+}
+
+function installSkill(destinationDir, force) {
+  assertSkillSource();
   fs.mkdirSync(destinationDir, { recursive: true });
-  copyDir(SOURCE_SKILL_DIR, skillTargetDir);
-  return skillTargetDir;
+  const skillTarget = path.join(destinationDir, SKILL_NAME);
+  removeIfExists(skillTarget, force, "Skill");
+  copyDir(path.join(PACKAGE_ROOT, "skills", SKILL_NAME), skillTarget);
+  return skillTarget;
 }
 
 function main() {
@@ -143,8 +155,8 @@ function main() {
 
   try {
     const installedPath = installSkill(destinationDir, args.force);
-    console.log(`Installed ${SKILL_NAME} to ${installedPath}`);
-    console.log("Invoke it in Codex with $harness-repo-bootstrap.");
+    console.log(`Installed ${SKILL_NAME} skill to ${installedPath}`);
+    console.log("Invoke it in Codex with $harness-engine.");
   } catch (error) {
     console.error(`Install failed: ${error.message}`);
     process.exit(1);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hallucination-studio/harness-engine",
-  "version": "1.0.0-beta.9.bb2cd30",
-  "description": "Install a Codex skill that bootstraps and updates an advanced harness-engineering repository layout.",
+  "version": "1.0.0-nightly.20260613.2",
+  "description": "Install the harness-engine Codex skill for initializing and reconciling advanced repository harness docs.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/hallucination-studio/harness-engine.git"
@@ -13,7 +13,7 @@
     "access": "public"
   },
   "scripts": {
-    "test": "python3 skills/harness-repo-bootstrap/evals/run_evals.py",
+    "test": "python3 skills/harness-engine/evals/run_evals.py",
     "smoke:install": "node scripts/smoke_install.js",
     "pack:check": "npm pack --dry-run"
   },
@@ -23,9 +23,9 @@
     "skills/**/agents/**",
     "skills/**/assets/**",
     "skills/**/evals/*.json",
-    "skills/**/evals/*.py",
+    "skills/**/evals/**/*.py",
     "skills/**/references/**",
-    "skills/**/scripts/*.py"
+    "skills/**/scripts/**/*.py"
   ],
   "license": "MIT"
 }

package/skills/harness-engine/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: harness-engine
+description: Initialize, refresh, and operate an advanced harness-engineering repository lifecycle for Codex-driven projects. Use when Codex needs to create or reconcile harness docs, or when work inside a harness-managed repository will change code, docs, configuration, tests, dependencies, build/release scripts, generated templates, runtime behavior, migrations, cleanup policy, or other durable repository state.
+---
+
+# Harness Engine
+
+Use the packaged script yourself to inspect the target repository before editing files. Do not ask the user to run the harness Python commands during normal work. Use the generated analysis to decide what to ask the human, what durable knowledge is missing from the repo, and which execution-plan and SOP files must be created or reconciled.
+
+In a harness-managed repository, default every repository-mutating request into the harness lifecycle. Repository-mutating work includes code, docs, configuration, tests, dependencies, build/release scripts, generated templates, runtime behavior, migrations, cleanup, and fixes from review or user feedback. The only no-plan exceptions are pure question answering, read-only investigation, showing command output, and status reporting with no file changes. If an investigation turns into editing files, enter the lifecycle before editing.
+
+The user-facing interface is intent, not CLI. If the user says a task is complete, should continue, should pause, should stop, or should become follow-up debt, translate that into the appropriate manager command yourself and report the outcome. Only show raw commands when the user explicitly asks for implementation details or debugging help.
+
+## Workflow
+
+1. Run `python3 scripts/manage_harness.py analyze --repo <target-repo> --output <analysis.json>`.
+2. Read `analysis.json`.
+3. Ask the human only the unresolved, high-impact questions from `human_confirmations`.
+4. During initialization, create frontend design docs only when the analysis detects a frontend surface. Frontend repos get `docs/FRONTEND.md`, `docs/DESIGN.md`, and `docs/design-docs/`; backend-only repos do not. Ask the human for the desired visual style direction and use existing frontend style files as evidence. The generated `docs/DESIGN.md` is a project-owned visual specification shaped like DESIGN.md: YAML tokens plus markdown rationale. Do not call external design-generation skills or packages during init.
+5. Run `python3 scripts/manage_harness.py sample-answers --analysis <analysis.json> --output <answers.json>`.
+6. Fill the placeholders in `answers.json` from the repository and the human's confirmed answers.
+7. Run `python3 scripts/manage_harness.py init --repo <target-repo> --answers <answers.json>`. This is the single workspace entrypoint: it creates a new harness when none exists, and reconciles a managed or partial harness when managed harness files are already present. Reconcile refreshes managed files, backfills newly introduced managed files, and preserves unmanaged user files. Pass `--force` only with explicit user approval.
+8. For any repository-mutating task, run `python3 scripts/manage_harness.py plan-start --repo <target-repo> --slug <task-name> --goal "<goal>"` unless an active plan already covers the exact work. Small changes may use a lightweight plan, but they still require acceptance, validation, quality scoring, plan close, and check.
+9. Before implementation, run `python3 scripts/manage_harness.py acceptance-set --repo <target-repo> --plan <plan-file> --product "<product criterion>" --ux "<UX criterion>" --architecture "<architecture criterion>" --reliability "<reliability criterion>" --security "<security criterion>"`. Criteria must be concrete to the task; generic templates are rejected.
+10. If you learn durable facts during the work, run `python3 scripts/manage_harness.py knowledge-log --repo <target-repo> --plan <plan-file> --fact "<fact>" --destination <durable-doc>` and keep the returned `id`. Use `--fact-file <file>` when the fact contains shell-sensitive characters.
+11. Before closing the task, write those facts into their durable docs.
+12. Run `python3 scripts/manage_harness.py knowledge-mark-written --repo <target-repo> --plan <plan-file> --id <knowledge-id> --evidence "<verbatim text already in durable doc>"`; prefer `--evidence-file <file>` when evidence contains backticks, globs, quotes, pipes, or other shell-sensitive characters. Evidence must be copied from the destination doc, not summarized. Use `--append` only when the exact fact should be appended mechanically.
+13. If validation, evals, browser checks, or code review reveal a bug, immediately run `python3 scripts/manage_harness.py defect-log --repo <target-repo> --plan <plan-file> --severity <P0|P1|P2|P3> --summary "<bug>" --evidence "<failing check>"`. This invalidates any existing quality result and makes the defect the next rework input.
+14. Fix logged defects, then run `python3 scripts/manage_harness.py defect-resolve --repo <target-repo> --plan <plan-file> --id <bug-id> --fix-evidence "<passing check or code evidence>"`.
+15. Score the finished work with `python3 scripts/manage_harness.py quality-score --repo <target-repo> --plan <plan-file> --product-correctness <0-10> --product-note "<evidence>" --ux-operator-clarity <0-10> --ux-note "<evidence>" --architecture-maintainability <0-10> --architecture-note "<evidence>" --reliability-observability <0-10> --reliability-note "<evidence>" --security-data-handling <0-10> --security-note "<evidence>"`. Every dimension needs an evidence note tied to the ready Acceptance Contract.
+16. If `quality-score` fails, treat `## Rework Required` in the plan as the next implementation input, fix the work, then run `quality-score` again.
+17. Before closing, run `python3 scripts/manage_harness.py continuation-set --repo <target-repo> --plan <plan-file> --decision <complete|continue|pause|stop|defer>`. Use `--workstream`, `--next-target`, `--next-action`, `--closure-reason`, `--resume-notes`, and `--goal` as needed; `continue` and `pause` update `workstreams.md` automatically only after required fields validate.
+18. Before closing, replace generic plan placeholders with task-specific scope, constraints, steps, validation, and completion notes; leave no open durable-knowledge placeholder except the default unused line.
+19. Close the plan with `python3 scripts/manage_harness.py plan-close --repo <target-repo> --plan <plan-file> --summary "<summary>"`.
+20. Before handoff, run `python3 .codex/skills/harness-engine/scripts/manage_harness.py check --repo <target-repo>` from an installed target repository.
+21. To review stale generated evidence, run `python3 scripts/manage_harness.py evidence-prune --repo <target-repo>` first; it is dry-run by default. Add `--apply` only after checking the candidate list.
+22. To clean transient harness runtime files or remove already committed runtime files from the remote, run `python3 scripts/manage_harness.py clean --repo <target-repo>` first; it is dry-run by default. Add `--apply` to clean local runtime state, update `.gitignore`, and stage `git rm --cached` removals, then commit and push. Clean is limited to local skill installs and generated evidence; execution plans, sidecars, and workstreams are durable project state.
+23. After changing this skill, run `python3 evals/run_evals.py` and iterate until it passes.
+
+## Reading Order
+
+- Read [references/workflow.md](references/workflow.md) first for the operating model and question policy.
+- Read [references/file-map.md](references/file-map.md) when deciding which generated file to edit.
+- Read [references/question-catalog.md](references/question-catalog.md) when the analysis surfaces ambiguous product, security, reliability, or frontend facts.
+- Read [references/knowledge-capture.md](references/knowledge-capture.md) when you discover facts that should survive chat history.
+- Read [references/exec-plans.md](references/exec-plans.md) before planning or updating any repository-mutating work.
+- Read [references/sop-index.md](references/sop-index.md) to choose the right SOP for architecture, UI validation, observability, or knowledge capture work.
+- Read [references/template-policy.md](references/template-policy.md) before overwriting existing files.
+- Read [references/evaluation-loop.md](references/evaluation-loop.md) before changing the skill, templates, scripts, or policy references.
+- Read [references/evidence-first-evals.md](references/evidence-first-evals.md) before designing evals for product correctness, frontend validation, or bug-discovery coverage.
+- Read `docs/FRONTEND.md` and `docs/DESIGN.md` when they exist for frontend, UI, product design, visual design, canvas, or interface polish work.
+
+## Command Rules
+
+- Prefer `analyze` before `init`.
+- Prefer the draft, test, evaluate, iterate loop for changes to this skill.
+- Use `init` as the workspace entrypoint for both creation and reconciliation. It refreshes managed harness files when an existing managed harness is detected and preserves unmanaged user files. Use `--force` only when the human accepts overwriting.
+- Do not overwrite existing files unless the human asked for it or you pass `--force`.
+- Treat the generated files as starting points. After generation, tighten them with repository-specific details instead of leaving placeholders behind.
+- Before plan close, replace or remove task placeholders such as "Define in-scope work", "Add the first concrete step", "Describe how the work will be verified", and any ad hoc durable-knowledge TODOs.
+- Treat `docs/exec-plans/` as required durable state for repository-mutating work, not optional notes.
+- Read `docs/exec-plans/workstreams.md` before resuming interrupted feature, refactor, reliability, security, frontend, or cleanup work.
+- Treat `docs/sops/` as mechanical operating procedures, not background reading.
+- When you answer a question using facts that are not yet in the repo but should be reusable, write them into a durable doc before finishing.
+- Prefer `knowledge-mark-written --id ... --evidence-file ...` so durable docs can use natural wording without shell quoting failures or duplicated exact fact strings.
+- The knowledge evidence text must exist verbatim in the destination doc; if it is only a paraphrase, write the durable doc first or use a file containing exact destination text.
+- Use `defect-log` for every bug found by tests, evals, browser validation, or code review; unresolved defects must block handoff.
+- Use `defect-resolve` only after the implementation is fixed and you can cite passing validation or code evidence.
+- Use `acceptance-set` before implementation and `quality-score` before `plan-close`; include `--product-note`, `--ux-note`, `--architecture-note`, `--reliability-note`, and `--security-note`; failed or stale scores must drive rework, not handoff.
+- Use `continuation-set` before every `plan-close`; choose `complete` for one-off plans, and use `continue` or `pause` for resumable multi-plan work. Invalid continuation input must fail before writing a half-valid workstream.
+- Use `plan-close` as the final guardrail so plan state, quality score, and durable docs stay synchronized. When blocked, it returns JSON with `status`, `reason`, `message`, and `details`; use that output as the next repair input.
+- Use `check` as the local handoff guardrail for user repositories. Active plans require ready Acceptance Contracts; completed plans require passing Quality Results scored against the current contract fingerprint.
+- Use `evidence-prune` as a cleanup preview for old unreferenced files under `docs/generated/`; it never deletes unless `--apply` is present.
+- Use `clean` when `.codex/skills/` or `docs/generated/` files need cleanup or were already committed. It never changes files or the git index unless `--apply` is present, and it must not remove execution plans, sidecars, or workstreams.
+- Run `python3 evals/run_evals.py` after skill changes, read the structured report, and treat per-case failures as iteration input.
+- Do not add CI to user repositories unless the human explicitly asks for it.
+
+## Frontend Design Docs
+
+Harness-engine has no external design runtime dependency and must not call an external design skill during init. It uses the local `/Users/murphy/code/github/design.md` checkout only as a reference for document shape.
+
+For frontend repositories, `docs/FRONTEND.md` records product positioning, requested style direction, existing frontend code signals, scope, stack notes, validation expectations, controlled files, and read order. `docs/DESIGN.md` records the unified visual specification with YAML tokens and markdown rationale. For backend-only repositories, these files are not generated.
+
+## Output Rules
+
+- Keep `AGENTS.md` short and routing-oriented.
+- Keep durable knowledge in repo docs, not in chat-only explanations.
+- Keep plans under `docs/exec-plans/active/` and move finished plans to `docs/exec-plans/completed/`; plan Markdown and JSON sidecars are version-controlled project state.
+- Keep resumable workstreams in `docs/exec-plans/workstreams.md`; this is version-controlled project state.
+- Keep generated evidence under `docs/generated/`; it is local runtime output and is ignored by git unless the human intentionally promotes a specific artifact into tracked docs.
+- Keep external, model-friendly references under `docs/references/`.
+- Keep SOPs explicit and task-triggered so the next agent can follow the same path mechanically.
+
+## Assets
+
+- Scaffold templates live under [assets/repo-template](assets/repo-template).
+- SOP starter docs live under [assets/sops](assets/sops).

package/skills/harness-engine/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Harness Engine"
+  short_description: "Scaffold advanced Codex harness docs"
+  default_prompt: "Use $harness-engine to analyze this repository and scaffold or refresh its advanced harness documentation."