harnessed 4.4.0 → 4.5.1

package/README.md

@@ -11,12 +11,31 @@
 
 > Not affiliated with, endorsed by, or sponsored by Harness Inc. (see [NOTICE](./NOTICE))
 
+> **How it compares** to [comet](https://github.com/rpamis/comet) and [Trellis](https://github.com/mindfold-ai/Trellis) — an honest, snapshot-dated comparison (including where harnessed lags): [`docs/comparison.md`](./docs/comparison.md).
+
 ---
 
 ## ✨ TL;DR
 
 **Best-practice orchestration for Harness Engineering on Claude Code** — assembles the best open-source Claude Code ecosystem components, weaving them into a unified workflow via opinionated composition skills; does not vendor upstream code — manifests describe install/check, and composition skills orchestrate multi-upstream collaboration.
 
+### 🔁 The operating loop
+
+> **Discuss → Plan → Build → Verify → Ship**, closed by a **Learn** loop — machine-executed across the three-layer stack (gstack governance · GSD orchestration · superpowers TDD · checkpoint evidence). Raw agent work drifts; harnessed turns it into a source-of-truth path where progress and evidence persist instead of living in chat. **Learning is automatic**: every completed workflow appends its failure/loop/reject signals to `.planning/LEARNINGS.md`, which are injected into the next cycle — this is always-on, **not** gated on the optional Retro. Retro (`/retro`) is a separate, optional milestone summary.
+
+```mermaid
+flowchart LR
+  R(["⓪ Research<br/>multi-source investigate<br/>(optional)"]):::opt --> D
+  D(["① Discuss<br/>3-layer clarify"]) --> P(["② Plan<br/>persist spec + tasks"])
+  P --> T(["③ Task<br/>TDD build + checkpoint"])
+  T --> V(["④ Verify<br/>independent review + evidence gate"])
+  V --> S(["⑤ Ship<br/>release-preflight → tag-ready (publish via CI)"])
+  S -. "milestone summary" .-> RT(["Retro<br/>(optional)"]):::opt
+  V -. "fail / gap" .-> T
+  S == "🔁 Learn — learnings captured on every workflow completion → injected next cycle" ==> D
+  classDef opt stroke-dasharray:5,opacity:0.8
+```
+
 ---
 
 > Wait — can harnessed really go toe-to-toe with upstream giants like superpowers / gstack / GSD?
@@ -30,10 +49,10 @@
 
 - **Three-layer stack machine-executed** — `gstack governance` + `GSD project manager` + `superpowers senior engineer` + `karpathy 4 principles` + `mattpocock 23 moves`, 5 pillars at 100% capture
 - **No vendoring of upstream** — manifests describe install/check; on upstream upgrade users just re-install to get the latest version
-- **Composition Skill** — in-house workflow skills act as the conductor's baton, orchestrating multiple upstreams in concert. **1 super-master `/auto` + 4 stage masters + 18 sub-workflows + 2 standalones = 25 namespace-layered workflows**, full 4-stage machine-execution (`/auto` one-shot across stages / `/discuss /plan /task /verify` single stage / 18 three-layer-stack subs / `/research /retro` 2 standalones)
+- **Composition Skill** — in-house workflow skills act as the conductor's baton, orchestrating multiple upstreams in concert. **1 super-master `/auto` + 5 stage masters + 19 sub-workflows + 2 standalones = 27 namespace-layered workflows**, full 5-stage machine-execution (`/auto` one-shot across stages / `/discuss /plan /task /verify /ship` single stage / 19 three-layer-stack subs / `/research /retro` 2 standalones)
 - **L0 Discipline Substrate** — global cross-stage behavior baseline (karpathy principles + output-style + language + operational + priority + protocols), applied universally
 - **Package manager mindset** — install dependency graph auto-resolves, doctor health check, install-base one-shot full install
-- **Unified entry point** — users face `/discuss /plan /task /verify` master slash commands without learning each upstream's terminology; sub commands explicitly invoke a single stage (e.g. `/discuss-strategic` runs only the strategic-layer clarification)
+- **Unified entry point** — users face `/discuss /plan /task /verify /ship` master slash commands without learning each upstream's terminology; sub commands explicitly invoke a single stage (e.g. `/discuss-strategic` runs only the strategic-layer clarification)
 
 ---
 
@@ -90,14 +109,14 @@ In order of increasing user intervention:
 /discuss-phase "..."        # Run only Phase-layer clarification
 /plan-architecture "..."    # Run only architecture review
 /verify-paranoid "..."      # Run only the Paranoid Staff Engineer review
-# ... pick any of the other 18 sub-workflows
+# ... pick any of the other 19 sub-workflows
 ```
 
 > "I'm an expert, I'll decide myself" — skip the master, invoke a sub-workflow directly. Suits advanced users who know exactly which sub they need, or reuse of a single step.
 
 ---
 
-## 📐 4-Stage Flow Diagram
+## 📐 5-Stage Flow Diagram
 
 ```mermaid
 graph TD
@@ -135,16 +154,21 @@ graph TD
     VM[verify-multispec]
     VMs --> VP & VC & VPa & VQ & VS & VD & VSi & VM
   end
-  RT([⑤ /retro — milestone summary, optional]):::optional
+  subgraph Ship[⑤ Ship — Release]
+    SMs[/ship master/]
+    SP[ship-preflight]
+    SMs --> SP
+  end
+  RT([⑥ /retro — milestone summary, optional]):::optional
   RS --> Discuss
-  Discuss --> Plan --> Task --> Verify
-  Verify --> RT
+  Discuss --> Plan --> Task --> Verify --> Ship
+  Ship --> RT
   classDef optional stroke-dasharray:5 5,fill:#f5f5f5,color:#666
 ```
 
-> Dashed boxes = optional standalones (`/research` pre-strategic investigation / `/retro` post-milestone summary); solid boxes = main 4-stage cadence.
+> Dashed boxes = optional standalones (`/research` pre-strategic investigation / `/retro` post-milestone summary); solid boxes = main 5-stage cadence (Ship stops at tag-ready; `publish.yml` CI does the actual publish).
 
-### 25-Workflow Overview Table
+### 27-Workflow Overview Table
 
 | Slash cmd | Stage | Type | Capability / Upstream | Brief |
 |-----------|-------|------|----------------------|-------|
@@ -170,6 +194,8 @@ graph TD
 | `/verify-design` | ④ Verify | Sub | gstack `/design-review` + ui-ux-pro-max + frontend-design | Design system consistency (has_design_changes conditional) |
 | `/verify-simplify` | ④ Verify | Sub | `code-simplifier` | Final serial simplification |
 | `/verify-multispec` | ④ Verify | Sub | 4-specialist Agent Team Pattern C | Critical release / large refactor PR escalation (mutual SendMessage cross-examination) |
+| `/ship` | ⑤ Ship | Master | masterOrchestrator | Release stage after Verify — preflight → delegate PR/deploy to gstack `/ship` → publish via CI (tag-ready boundary) |
+| `/ship-preflight` | ⑤ Ship | Sub | `harnessed release-preflight` | Read-only release-readiness gate (CHANGELOG `[Unreleased]` / version / git-clean / tag-absent); blocks on failure |
 | `/research` | Standalone | Standalone | Tavily / Exa MCP + ctx7 + GSD `/gsd-discuss-phase` | Multi-source investigation (Stage ① alternate) |
 | `/retro` | Standalone | Standalone | gstack `/retro` + planning-with-files RETROSPECTIVE.md | Project / milestone close-out summary |
 
@@ -180,11 +206,11 @@ graph TD
 
 ## ⚡ Usage Flow
 
-4-stage three-layer-stack methodology — recommended driving via the 4 master orchestrators in series:
+5-stage three-layer-stack methodology — recommended driving via the 5 master orchestrators in series:
 
 ```
-/discuss  →  /plan  →  /task  →  /verify
-   ①         ②        ③         ④
+/discuss  →  /plan  →  /task  →  /verify  →  /ship
+   ①         ②        ③         ④           ⑤
 ```
 
 | Stage | Master | Main sub-workflows | Upstream collaboration |
@@ -193,6 +219,7 @@ graph TD
 | ② **Plan** | `/plan` | architecture (conditional) → phase | gstack `/plan-eng-review` + GSD `/gsd-plan-phase` + planning-with-files |
 | ③ **Task** | `/task` | clarify → code → test → deliver (4 serial per subtask) | karpathy principles + mattpocock moves + superpowers TDD + `ralph-loop` |
 | ④ **Verify** | `/verify` | progress → 5 parallel conditional → simplify (+ multispec critical) | GSD `/gsd-verify-work` + code-review + gstack `/review` / `/qa` / `/cso` / `/design-review` + code-simplifier |
+| ⑤ **Ship** | `/ship` | preflight (release-readiness gate) → delegate PR/deploy | `harnessed release-preflight` + gstack `/ship` + `publish.yml` CI (tag-ready boundary) |
 
 Practical example:
 
@@ -200,11 +227,12 @@ Practical example:
 # 1. Install workflow upstreams (one line installs gstack + GSD + superpowers + planning-with-files)
 harnessed setup
 
-# 2. Run the 4-stage cadence inside Claude Code
+# 2. Run the 5-stage cadence inside Claude Code
 /discuss "new feature X"          # Strategic + Phase + Subtask 3-layer clarification
 /plan "new feature X"             # Architecture (conditional) + plan (task graph persisted)
 /task "subtask-1: API contract"   # 4 subs serial per subtask
 /verify "phase-1"                 # 7 subs conditional
+/ship                             # release-preflight gate → PR/deploy (tag-ready; publish via CI)
 
 # 3. Resume after interruption (any time)
 harnessed resume
@@ -216,14 +244,14 @@ harnessed resume
 
 ---
 
-## 🗂️ Architecture (4-stage namespace-layered)
+## 🗂️ Architecture (5-stage namespace-layered)
 
 ### 1. Directory Structure
 
 ```
 harnessed/
 ├── manifests/                  # L1: upstream description layer (NOT vendored)
-├── workflows/                  # L6: composition skills (4-stage conductor's baton)
+├── workflows/                  # L6: composition skills (5-stage conductor's baton)
 │   ├── discuss/                # Stage ① 3 layers (strategic + phase + subtask)
 │   │   ├── auto/               # /discuss master gate-route
 │   │   ├── strategic/          # /discuss-strategic (gstack /office-hours + /plan-ceo-review)
@@ -232,8 +260,9 @@ harnessed/
 │   ├── plan/                   # Stage ② (architecture + phase task graph)
 │   ├── task/                   # Stage ③ (clarify + code + test + deliver)
 │   ├── verify/                 # Stage ④ (progress + code-review + paranoid + qa + cso + design + simplify + multispec)
+│   ├── ship/                   # Stage ⑤ (preflight release-readiness gate → delegate PR/deploy to gstack /ship; tag-ready)
 │   ├── research/               # standalone Stage ① alternate
-│   ├── retro/                  # standalone post-④ milestone close
+│   ├── retro/                  # standalone post-⑤ milestone close
 │   ├── capabilities.yaml       # L5a: ~100 entries, 7 categories SoT
 │   ├── defaults.yaml           # ralph_max_iterations per workflow phase
 │   ├── judgments/              # L5a: three-layer-stack criteria + parallelism + tdd + fallback + rules-routing
@@ -268,7 +297,7 @@ harnessed/
 ```
 ┌────────────────────────────────────────────────────────────┐
 │ L7 User-facing slash cmd + harnessed CLI                    │
-│   /discuss /plan /task /verify (master) + 18 sub + /research /retro + /auto super-master
+│   /discuss /plan /task /verify /ship (master) + 19 sub + /research /retro + /auto super-master
 │   + direct gstack invoke (30+ optional): /office-hours /review /qa /...
 ├────────────────────────────────────────────────────────────┤
 │ L6 Workflow orchestration (workflows/<stage>/<sub>/)         │
@@ -376,10 +405,17 @@ planning-with-files /plan (cross-cutting tool) → write artifacts to .planning/
 | `harnessed gates <master>` | Evaluate which sub-workflows fire for a master stage (JSON: fire/skip/parallelism). Used by slash commands to orchestrate native spawns. |
 | `harnessed prompt <sub>` | Output a spawn-ready prompt (role + checklist + disciplines + completion/clarification protocols) for a sub-workflow. |
 | `harnessed checkpoint <action> <sub>` | Record sub-workflow start/complete/fail to `~/.claude/harnessed/checkpoints/`. |
+| `harnessed next` | Deterministic next-step contract (`NEXT: auto\|manual\|done`) for the active workflow. |
+| `harnessed reject <sub>` | Mark a sub as user-rejected (terminal, distinct from `failed`). |
+| `harnessed compact [--tokens <n>]` | Summarize+evict resolved ledger entries (G6-safe: `fail_count>0` never evicted); auto-triggers on `checkpoint complete --tokens`. |
+| `harnessed workflows` | List in-flight workflows (one per repo). |
+| `harnessed learn "<lesson>"` | Append a prose learning to this repo's `.planning/LEARNINGS.md`. |
 | `harnessed run <name>` | Run a workflow via in-process SDK spawn (CI/headless mode). Slash commands use CC-native spawn instead. |
 | `harnessed resume` | Resume from the most recent checkpoint after a session interruption |
 | `harnessed status` | Current phase + lock holder |
-| `harnessed doctor` | 8-check health check (Node / MCP / jq / Win bash / routing / token budget, etc.) |
+| `harnessed doctor` | 14-check health check (Node / MCP / jq / Win bash / routing / token budget / mattpocock / CodeGraph / update-available, etc.) |
+| `harnessed update [--check\|--upstreams\|--migration-report]` | Self-update (`npm i -g harnessed@latest`); `--check` reports the latest version; `--upstreams` re-runs the base manifests; `--migration-report` is a read-only stale-state inventory |
+| `harnessed release-preflight` | Read-only release-readiness gate (CHANGELOG `[Unreleased]` / version / git-clean / tag-absent); exits 1 if not ready. The Ship-stage gate. |
 | `harnessed install <name>` | Install an upstream manifest |
 | `harnessed uninstall [name]` | Reverse uninstall |
 | `harnessed backup` | Snapshot backup management |
@@ -450,7 +486,7 @@ Think `brew install <formula>` pulling the full dependency set — you don't nee
 | Orchestration | GSD | High-level phase task graph + dependency analysis |
 | Persistence | planning-with-files | Persists `task_plan.md` / `progress.md` / `findings.md` |
 
-`/discuss /plan /task /verify` — the 4 masters string the 4 stages together; each master internally delegates to its sub. Each stage does a different thing and feeds the next. **No merging**.
+`/discuss /plan /task /verify /ship` — the 5 masters string the 5 stages together; each master internally delegates to its sub. Each stage does a different thing and feeds the next. **No merging**.
 
 </details>
 

package/bin/harnessed-inject-state.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// G4 UserPromptSubmit hook — print the per-turn injection for the active harnessed
+// workflow: a <workflow-state> breadcrumb + (Phase 17) a relevance-filtered
+// <project-context> block (recent, phase/sub-relevant learnings from the repo's
+// .planning/LEARNINGS.md + the current phase's CONTEXT.md excerpt). Silent exit 0
+// on any error (fail-soft — a hook must never block the prompt).
+//
+// Self-contained plain JS (no project imports, no subprocess, no LLM) for hot-path
+// speed. This MUST stay equivalent to src/checkpoint/injectState.ts `buildInjection`
+// — the parity test in tests/checkpoint/injectState.test.ts runs this file and
+// compares its stdout to the TS builder.
+//
+// Phase 15 repo-aware: resolves the active repo's slot from
+// workflows.json[repoKey(cwd)] (legacy current-workflow.json as a fallback).
+// Root: HARNESSED_ROOT_OVERRIDE if set, else <homedir>/.claude/harnessed.
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+
+const DEFAULT_INJECT_BUDGET = 1500
+const tok = (s) => Math.ceil(Buffer.byteLength(s, 'utf8') / 4)
+
+function repoKey(cwd) {
+  let dir = resolve(cwd)
+  for (;;) {
+    if (existsSync(join(dir, '.git'))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return resolve(cwd)
+}
+
+function harnessedRoot() {
+  const override = process.env.HARNESSED_ROOT_OVERRIDE
+  return override !== undefined && override !== ''
+    ? override
+    : join(homedir(), '.claude', 'harnessed')
+}
+
+// workflows.json[repoKey] first, then the legacy singleton (dual-write anchor).
+function readWorkflow(root, key) {
+  try {
+    const store = JSON.parse(readFileSync(join(root, 'workflows.json'), 'utf8'))
+    if (store && store.workflows && store.workflows[key]) return store.workflows[key]
+  } catch {}
+  try {
+    return JSON.parse(readFileSync(join(root, 'current-workflow.json'), 'utf8'))
+  } catch {}
+  return null
+}
+
+function workflowStateBlock(wf) {
+  const ledger = wf.sub_progress ?? []
+  const next = ledger.find((e) => e.status === 'pending')?.sub ?? null
+  const lines = [
+    '<workflow-state>',
+    `phase: ${wf.phase}`,
+    `status: ${wf.status}`,
+    next ? `next: ${next}` : 'next: (none — all subs resolved)',
+  ]
+  for (const e of ledger) {
+    if ((e.fail_count ?? 0) >= 3)
+      lines.push(
+        `BREAK-LOOP: sub '${e.sub}' failed ${e.fail_count}x — stop retrying, run break-loop skill`,
+      )
+  }
+  lines.push('</workflow-state>')
+  return lines.join('\n')
+}
+
+function parseLearnings(md) {
+  const blocks = md.split(/^### /m).slice(1)
+  return blocks.map((b) => {
+    const raw = `### ${b}`.trimEnd()
+    const phase = /phase (\S+)/.exec(b)?.[1] ?? ''
+    const subs = []
+    for (const m of b.matchAll(/^- (?:looped|rejected|failed): (\S+)/gm)) subs.push(m[1])
+    return { raw, phase, subs }
+  })
+}
+
+function filterRelevant(entries, phase, ledgerSubs) {
+  const rel = entries.filter((e) => e.phase === phase || e.subs.some((s) => ledgerSubs.includes(s)))
+  const ordered = [...rel].reverse()
+  if (ordered.length === 0 && entries.length > 0) return [entries[entries.length - 1]]
+  return ordered
+}
+
+function selectWithinBudget(entries, budget) {
+  const out = []
+  let acc = 0
+  for (const e of entries) {
+    const cost = tok(e.raw)
+    if (acc + cost > budget) break
+    acc += cost
+    out.push(e)
+  }
+  return out
+}
+
+function findPhaseContextExcerpt(repoRoot, phase, budget) {
+  try {
+    const phasesDir = join(repoRoot, '.planning', 'phases')
+    if (!existsSync(phasesDir)) return null
+    for (const dir of readdirSync(phasesDir)) {
+      const num = /^(\d+)/.exec(dir)?.[1]
+      if (!num || !phase.includes(num)) continue
+      const ctxFile = join(phasesDir, dir, `${num}-CONTEXT.md`)
+      if (!existsSync(ctxFile)) continue
+      const body = readFileSync(ctxFile, 'utf8')
+      const goalIdx = body.indexOf('## Goal')
+      const slice = goalIdx >= 0 ? body.slice(goalIdx) : body
+      const nextH = slice.indexOf('\n## ', 1)
+      const excerpt = (nextH > 0 ? slice.slice(0, nextH) : slice).trim()
+      return excerpt.length > budget * 4 ? excerpt.slice(0, budget * 4) : excerpt
+    }
+  } catch {}
+  return null
+}
+
+function projectContextBlock(learnings, contextExcerpt) {
+  const parts = []
+  for (const l of learnings) parts.push(l.raw.trim())
+  if (contextExcerpt) parts.push(contextExcerpt.trim())
+  if (parts.length === 0) return ''
+  return ['<project-context>', ...parts, '</project-context>'].join('\n')
+}
+
+try {
+  const root = harnessedRoot()
+  const key = repoKey(process.cwd())
+  const wf = readWorkflow(root, key)
+  if (!wf) process.exit(0)
+
+  const budget = Number(process.env.HARNESSED_INJECT_BUDGET) || DEFAULT_INJECT_BUDGET
+  const ws = workflowStateBlock(wf)
+
+  let learningsMd = ''
+  try {
+    learningsMd = readFileSync(join(key, '.planning', 'LEARNINGS.md'), 'utf8')
+  } catch {}
+
+  const ledgerSubs = (wf.sub_progress ?? []).map((e) => e.sub)
+  const rel = selectWithinBudget(
+    filterRelevant(parseLearnings(learningsMd), wf.phase, ledgerSubs),
+    budget,
+  )
+  const used = rel.reduce((a, e) => a + tok(e.raw), 0)
+  const ctx = findPhaseContextExcerpt(key, wf.phase, Math.max(0, budget - used))
+  const pc = projectContextBlock(rel, ctx ?? undefined)
+
+  process.stdout.write(`${pc ? `${ws}\n${pc}` : ws}\n`)
+} catch {
+  // no state / corrupt / not a harnessed session -> inject nothing
+}
+process.exit(0)