type: meta

slug: harness-engine-foundation

topic: Centrally-install and version the mega-plan-harness engine so it can run against any repo, sub-project 1 of 2 in the run-plan.js -> mega-plan-harness migration

exec_mode: ship

scheduler: dag-parallel

status_enum: BLOCKED PENDING WORKING WRITTEN REVIEWED COMMITTED

truth_rule: this file is ground truth for INTENT (goals/directions/task list); git is ground truth for DONE-NESS — reconcile statuses against git, never trust a COMMITTED line with no commit

refresh_how: native Read of THIS file — NEVER ctx_execute/ctx_search (the point is re-injecting intent into the main thread; a context-mode call keeps bytes OUT and silently kills the feature)

refresh_what: meta + every goal/methodology/intent/direction record + all WORKING and BLOCKED tasks (skip COMMITTED lines)

refresh_when:
wave/phase boundary
any task status change
after a compaction system-reminder
before calling advisor

update_rule: on status change, rewrite that task's single line in place; append new tasks/session_memory as new lines

report_rule: at session end emit brief: done / blocked / deferred / canceled — NO 'next action' (if you know it, do it)


type: goal

text: Migrate off ~/.claude/workflows/run-plan.js (Workflow-tool controller) onto the mega-plan-harness's own engine (src/runner.js / bin/runplan). This is sub-project 1: turn the engine into a centrally-installed, versioned, self-contained-per-version bundle that any repo can launch a plan against, with a --repo flag, a working --preset flag, and a per-run version pin so in-flight runs never see a later release's code underneath them.


text: Sub-project 2 (ship/run-plan skill routing on top of this foundation) is explicitly OUT of scope here — separate spec, gated on this one landing.


type: methodology

text: Contract-level spec authored via brainstorm skill, self-reviewed, advisor()-reviewed twice (two design reversals: shared infra -> self-contained bundle; then presets pulled back into the bundle too). User confirmed: central ~/.harness install (not versioning ~/.claude/workflows/run-plan.js in place), and a single CURRENT pointer file for release (not hand-editing skill files).


type: intent

text: User is retiring the old Workflow-controller engine in favor of their own harness's native orchestration (worktree/journal/gate0 mechanics), generalized so it isn't hardcoded to only work inside the mega-plan-harness repo itself.


type: direction

verbatim: we will keep the old run-plan.js file for reference for now, and later retire it completely. to avodi breaking living sessions, we will start versioning our files. instead of working on running versions of production workflows, bump the version with each version. run-plan-v0.1.0.js -> run-plan-v0.1.1...etc. do not bump to v0.2 or higher without user approval. just bump the 3rd number. then, when we finish a new version and want th "release" it, (for private use, on this machine) you just edit the skills, and move the future runs to the new file. older runs will complete with old working file, nothing broken.


verbatim: i did not mention, the workflow controller and the old run-plan is going to stop being used. we are switching to my own mega-plan-harness workflow


type: deferred

text: ship/SKILL.md and run-plan/SKILL.md routing redesign (sub-project 2): ship as front door routing inline/subagent-orchestrate/delegate-to-run-plan by plan size; run-plan powered by new versioned engine; repo opt-in gate with robust 'never ask again'; preset/runconfig setup interview; web UI run URL surfaced to user.

reason: explicitly gated on sub-project 1 (this plan) landing first


text: run-plan.js is NOT touched or deleted in this sub-project — stays exactly as-is so in-flight runs launched on it complete normally. Retirement is a separate, later, not-yet-authorized action.

reason: user explicit instruction


text: harness-tier-backlog plan (docs/plans/2026-07-01-harness-tier-backlog.jsonl) — separate, unrelated run-plan run, 2/16 tasks done, flagged earlier as possibly needing re-scoping/abandonment. Not auto-resumed.

reason: unrelated to this migration; needs explicit user decision on whether to continue or abandon


type: task

desc: Generalize src/runner.js: --repo flag, --preset/--engine-version in parseArgs, ensureWebUi fixed to resolve via shellPath

status: COMMITTED


desc: Create VERSION (0.1.0) and bin/harness-release.sh (bump: patch-only version bump + self-contained bundle snapshot; release: writes CURRENT pointer)


desc: Create bin/harness-init.sh: per-repo thin wrapper generator materializing <repoRoot>/.claude/scripts/runplan


desc: Extend test/runner-integration.sh with a --repo <tmpdir-not-cwd> case


desc: New test/harness-release.sh covering bump refuses minor/major, release writes CURRENT, old pinned version untouched after later bump+release


desc: New test/ensure-web-central.sh confirming ensureWebUi resolves via shellPath when repoRoot has no bin/ensure-web.sh of its own