freeharness 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 André Negrelli
+
+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/NOTICE

@@ -0,0 +1,108 @@
+FreeHarness
+Copyright (c) 2026 André Negrelli
+Licensed under the MIT License (see LICENSE).
+
+This distribution contains material derived from third-party projects. Each item below keeps
+its own license; the upstream license text ships next to the vendored tree or under
+packages/cli/vendor-licenses/ where noted, and the exact upstream revision is recorded in the
+PROVENANCE manifests.
+
+1. OpenSpec (vendored engine slice + /opsx skill assets)
+   Upstream:  https://github.com/Fission-AI/OpenSpec  (package @fission-ai/openspec)
+   Copyright: (c) 2024 OpenSpec Contributors
+   License:   MIT — packages/sdd/vendor/openspec/LICENSE.upstream
+   Baseline:  v1.8.0, commit 610b78f  (packages/sdd/PROVENANCE.yaml)
+   Where:     packages/sdd/vendor/openspec/ (bundled in the npm package as
+              node_modules/@freeharness/sdd); canonical/openspec/ (schema override)
+
+2. claude-mem (vendored memory daemon, plugin control plane, and hooks)
+   Upstream:  https://github.com/thedotmack/claude-mem
+   Copyright: Alex Newman (thedotmack)
+   License:   Apache License 2.0 — packages/memory/vendor/claude-mem/LICENSE.upstream
+   Baseline:  v13.24.0, commit be44b6c8  (packages/memory/PROVENANCE.yaml)
+   Where:     packages/memory/vendor/claude-mem/ (repo checkout only; NOT in the npm package —
+              the memory capability builds it from a checkout, or bridges to the upstream
+              installer when the engine is absent). Modifications (memory-slim trim, rewritten
+              hooks.json/.mcp.json) are recorded in FIXUP.md and SLIM-AUDIT.md next to it, as
+              required by Apache-2.0 section 4(b).
+
+3. Claude Code official plugins (harvested concepts; rewritten, never copied)
+   Upstream:  https://github.com/anthropics/claude-code  (plugins/, examples/)
+   Copyright: (c) Anthropic PBC. All rights reserved. Use is subject to Anthropic's Commercial
+              Terms of Service (https://www.anthropic.com/legal/commercial-terms), per the
+              repository's LICENSE.md.
+   Baseline:  commit b3f0e50  (canonical/PROVENANCE.yaml, canonical/HARVEST.yaml)
+   Where:     canonical/PROVENANCE.yaml lists every harvested file (content is folded into
+              existing skills/agents, the spec-driven design artifact, and
+              canonical/hooks/freeharness-security-guidance.mjs). These are original
+              FreeHarness rewrites of the upstream ideas (phase structure, agent roles, hook
+              behavior); canonical/PROVENANCE.yaml records the upstream path, commit, and the
+              upstream file hash, and the test suite asserts no file is byte-identical to its
+              source. No Anthropic file is redistributed.
+
+4. OpenSpec 1.12 ports (v4)
+   Upstream:  https://github.com/Fission-AI/OpenSpec
+   License:   MIT (same text as item 1)
+   Baseline:  v1.12.0, commit e062b957  (packages/sdd/PROVENANCE.yaml; canonical/PROVENANCE.yaml)
+   Where:     engine hunks in packages/sdd/vendor/openspec/{validation,apply,generation/templates/
+              workflows}, packages/sdd/src/shim/{archive,context,new-change}.ts, and the
+              canonical/openspec templates; adopted assets via `freeharness sync adopt sdd`.
+
+5. deepseek-harness (harvested mechanisms; rewritten, never copied)
+   Upstream:  https://github.com/deepseek-ai/deepseek-harness
+   Copyright: (c) 2026 DeepSeek
+   License:   MIT — packages/cli/vendor-licenses/deepseek-harness.LICENSE
+   Baseline:  commit d347e703 (0.1.3-alpha.1)  (canonical/PROVENANCE.yaml, canonical/HARVEST.yaml)
+   Where:     rules/CLAUDE.md (CoT-leakage standard, prose standard, Agent Notes loop),
+              skills (verification grounding, subagent team lessons, description discipline),
+              agents (defensive patterns), openspec templates (Consequences section),
+              hooks/freeharness-repeat-tool.mjs, freeharness-output-pruner.mjs and the
+              SessionStart compaction checkpoint. Each entry records the upstream path,
+              commit and hash; the test suite asserts no file is byte-identical.
+
+6. caveman (MIT skill/agent layer only)
+   Upstream:  https://github.com/JuliusBrussee/caveman
+   Copyright: (c) 2026 Julius Brussee
+   License:   MIT for skills/, agents/, commands/, packages/ — packages/cli/vendor-licenses/
+              caveman.LICENSE (the scope note names the BSL-1.1 engine paths). The BSL-1.1
+              paths (engine/, proxy/, mcp/, shrink/, mem/, browse/, rewriter/) ship nothing
+              here: their items are concepts with an empty target list in HARVEST.yaml.
+   Baseline:  commit 0fca50ac (2.6.0)
+   Where:     rules/CLAUDE.md (output levels, delegation paragraph), the five reviewer
+              agents' output contract, subagent-driven-development stop conditions.
+
+7. pi (pi-mono)
+   Upstream:  https://github.com/badlogic/pi-mono
+   Copyright: (c) 2025 Mario Zechner
+   License:   MIT — packages/cli/vendor-licenses/pi.LICENSE
+   Baseline:  commit 4cc339f5 (0.0.3)
+   Where:     agents/explorer-ai-engineer-analyst.md (scout handoff), rules/CLAUDE.md (two
+              rule lines), skills/git-workflow (worktree safety), hooks/freeharness-output-pruner.mjs
+              (truncation shape).
+
+8. Superpowers
+   Upstream:  https://github.com/obra/superpowers
+   Copyright: (c) 2025 Jesse Vincent
+   License:   MIT — packages/cli/vendor-licenses/superpowers.LICENSE
+   Baseline:  commit b36e0829 (6.3.0)
+   Where:     skills/subagent-driven-development (6.x mechanics, reference/brief.md),
+              skills/test-driven-development/reference/writing-good-tests.md,
+              skills/verification-before-completion, skills/systematic-debugging,
+              skills/git-workflow (worktrees).
+
+9. Everything Claude Code (ECC)
+   Upstream:  https://github.com/affaan-m/ECC
+   Copyright: (c) 2026 Affaan Mustafa
+   License:   MIT — packages/cli/vendor-licenses/ecc.LICENSE
+   Baseline:  commit 68e926bf (harvest); observed 2.2.1 e04ea0b9
+   Where:     rules/safety.md (safety-guard watch list), hooks/freeharness-config-guard.mjs,
+              hooks/freeharness-context-monitor.mjs and their fragments.
+
+10. Concept-only sources (no content shipped; listed in canonical/HARVEST.yaml and sources.yaml)
+   - Ruflo (MIT): PreCompact hook and memory consolidation concepts.
+   - context-mode (ELv2): concepts only; non-permissive, an empty target list is enforced by
+     the harvest test.
+   - ralph-wiggum (official Claude Code plugin, item 3): the converge Stop hook follows its
+     loop shape; no file is copied.
+   - claude-mem 13.15 -> 13.24 delta (item 2): engine hunks ported by hand, listed in
+     packages/memory/vendor/claude-mem/FIXUP.md section 9.

package/README.md

@@ -0,0 +1,134 @@
+# FreeHarness
+
+FreeHarness is an agnostic agentic-engineering harness for AI Engineering, Software Engineering for AI Systems and Data Engineering work.
+A single neutral canonical source (behavior rules, skills, agents, hooks, MCP list, spec-driven schema) is translated by per-harness adapters into each tool's layout:
+Claude Code, OpenCode, or a Claude Code plugin directory. It vendors the engines it depends on (OpenSpec for spec-driven development, the vendored claude-mem engine for memory),
+tracks them against upstream, and harvests ideas from other projects (Superpowers, ECC, Ruflo, the official Claude Code plugins) rewritten in its own style. Goals: efficiency,
+quality, token economy, modular and confirmable install. License: MIT.
+
+
+## Status
+
+v0.4.1 — v1, v2, v3, v4 and v4.1 shipped (v4 sandbox-complete; the [machine] measurements are listed in `Documents/ROADMAP.md`); 19 capability specs published in `openspec/specs/` (the v4 change is archived under `openspec/changes/archive/freeharness-v4`).
+
+- v1: canonical content (rules with the Tool Routing contract, skills, agents, MCP, hooks) and the installer with the claude-code and opencode adapters.
+- v2: hexagonal core with a dependency-rule linter, two-pass confirmable install, `bootstrap`, `doctor --fix`, vendored OpenSpec engine (own `openspec` bin), vendored claude-mem daemon, `sync check`, one-command `install.sh`.
+- v3: memory installed from our build and slimmed (engine trimmed, short hooks, own viewer), node:test suites + CI, npm tarball + hosted `install.sh` + `--target plugin`, `sync adopt`, rich `doctor` / `uninstall` / `update`, content harvest from the official plugins, cost tracker, weekly upstream radar.
+- v4: harness intelligence (rules under 200 lines, language density rule + doctor lint, output contracts, subagent briefs and validated handoffs, verification grounding, CoT-leakage standard), token-economy hooks (output pruner, context monitor, config guard, repeat-tool reminder, post-compaction re-injection, cache-hygiene settings, `cost prefix`, `cost report --sinks`), upstream claude-mem 13.24 ports + PreCompact checkpoint, OpenSpec 1.12 ports + supersession/EARS/task annotations + converge hook, 45 skill eval cases with a runner and `plugin validate` in CI, opt-in local-model and MCP profiles.
+
+Next: the v4 [machine] measurements (compare weeks, recall re-verify, first eval run, GPU
+profiles); v5 moves to an own CLI on the Claude Agent SDK plus OpenCode. Details:
+`Documents/ROADMAP.md`.
+
+## Quickstart
+
+Only Node.js >= 18 and git must be present.
+
+1. Install once per machine (builds, links `freeharness` + the vendored `openspec` into
+   `~/.local/bin`, installs the global set into `~/.claude`, sets up memory, removes leftovers
+   of earlier installs, runs `doctor`):
+
+```bash
+bash install.sh --yes --with-memory
+# or, without a checkout:
+curl -fsSL https://raw.githubusercontent.com/anegrelli/FreeHarness/main/install.sh | bash -s -- --yes --with-memory
+```
+
+2. Activate in each project (writes `CLAUDE.md` from the template, the `/fh-context` command and
+   the SDD set `openspec/` + `/opsx`; skills, agents, hooks, memory and MCP stay global):
+
+```bash
+cd <project> && freeharness bootstrap
+# then, in Claude Code: /fh-context   (fills CLAUDE.md from the codebase; never /init)
+# commit CLAUDE.md + openspec/
+```
+
+Details, reference and troubleshooting: `Documents/INSTALL.md`; manual and advanced paths:
+`Documents/ADVANCED.md`.
+
+## Commands
+
+| Command                                                               | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `freeharness init`                                                    | Install capabilities into the target harness(es).`--target claude-code,opencode,plugin`, `--scope user\|project`, `--only <caps>`, `--project <dir>`, `--dry-run`, `--yes`                                                                                                                                                                                                                                                                                           |
+| `freeharness update [--check]`                                        | Compare the install manifest with the running CLI / repo HEAD; re-emit idempotently                                                                                                                                                                                                                                                                                                                                                                                  |
+| `freeharness bootstrap`                                               | Activate a project:`CLAUDE.md` (template, if absent) + `/fh-context` + SDD (`openspec/`, `/opsx`, `openspec-*` skills). Global-only capabilities are refused at project scope unless `init --allow-project-copies`                                                                                                                                                                                                                                                   |
+| `freeharness cleanup`                                                 | Remove leftovers/duplicates from a fixed list (`--scope user`: parked upstream claude-mem, its backups, upstream claude-mem hook entries in `settings.json` once the plugin is registered, legacy `/openspec` commands, global `@fission-ai/openspec`, a global npm `freeharness` link; `--scope project`: legacy `/openspec` commands, project copies of global agents/skills, duplicate hook entries). Your own skills/agents are never listed. Preview -> confirm |
+| `freeharness doctor [--fix]`                                          | Version and resolved binaries (shadowing, a CLI running from outside`~/.local/bin`), hooks, skills/agents (yours listed as INFO), manifest drift, runtime deps, PROVENANCE baselines, memory verdict (stale worker version), leftovers (user) / duplicates and unresolved placeholders (project)                                                                                                                                                                     |
+| `/fh-context` (in Claude Code)                                        | Project command written by`bootstrap`: fills the `<placeholder>` fields of the project `CLAUDE.md` from the codebase                                                                                                                                                                                                                                                                                                                                                 |
+| `freeharness list`                                                    | Capabilities, required/optional, targets                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `freeharness uninstall`                                               | Remove only what the install manifest lists; never `~/.claude-mem` data or user files                                                                                                                                                                                                                                                                                                                                                                                |
+| `freeharness memory status\|backup\|activate\|restart [--if-running]` | Which memory build is active; copy the data dir; make the FreeHarness build the only active one; restart the worker (`--if-running`: no-op without one)                                                                                                                                                                                                                                                                                                              |
+| `freeharness cost report [--sinks]\|prefix\|prices`                   | Aggregate the cost-tracker log per project and model; rank token sinks per project / task class; estimate the prompt prefix vs budget; print the editable price table path                                                                                                                                                                                                                                                                                           |
+| `freeharness sync check\|adopt <sdd\|memory>`                         | Report drift of the vendored trees vs upstream; adopt tracked paths with preview + confirm + baseline bump                                                                                                                                                                                                                                                                                                                                                           |
+
+## What gets installed (user scope, Claude Code)
+
+- Global behavior rules (`~/.claude/CLAUDE.md`) with a pointer to the Tool Routing table, plus the per-project context template. The table itself lives in `canonical/rules/routing.md`, printed as a `<routing>` block by the SessionStart hook on every source (Claude Code and plugin targets) and appended to `AGENTS.md` for OpenCode.
+- 10 skills: test-driven-development, subagent-driven-development, systematic-debugging, verification-before-completion, code-review, git-workflow, agentic-architecture, agent-evaluation, local-code, report-formatting. report-formatting and agent-evaluation are owner-run: hidden from the model's skill list (`disable-model-invocation: true`) and dispatched by name (`/report-formatting`, `/agent-evaluation`; `/<plugin>:report-formatting` on a plugin install), never selected by the model.
+- 8 agents: python-reviewer, database-reviewer, security-reviewer, pr-reviewer, agentic-architect, report-formatter, explorer-ai-engineer-analyst, test-writer (neutral tiers mapped to opus/sonnet/haiku).
+- 12 hook registrations from 10 scripts: SessionStart pointer (compact/resume re-inject the checkpoint), PreCompact checkpoint, memory guard and config guard (PreToolUse, deny), repeat-tool reminder (PreToolUse + UserPromptSubmit, advisory), security guidance (PreToolUse, advisory), the opt-in converge loop (Stop; armed per project by `.freeharness/converge.json`), and from the `cost` capability (part of the default set) the cost tracker (Stop + SessionEnd), output pruner (PostToolUse Bash) and context monitor (Stop) plus the 1h prompt-cache TTL settings. Details and how to disable each: Documents/ADVANCED.md section 6.
+- SDD: the spec-driven schema override (user-global) and the vendored `openspec` bin; `/opsx` commands, `openspec-*` skills and `/fh-context` per project via `bootstrap`.
+- Memory (optional): the slim free-mem plugin built from the vendored claude-mem engine, installed into the Claude Code plugin cache and registered additively, with the FreeHarness viewer.
+- MCP: servers from `canonical/mcp/servers.json` (context7) via `claude mcp add`.
+
+Capabilities: rules, sdd, skills, agents, safety, mcp, cost (required; the token-economy hooks are core) + memory (optional).
+
+## Structure
+
+```
+FreeHarness/
+├── package.json         npm workspaces root: build (sdd -> core -> cli), verify, test
+├── install.sh           one-command installer (self-bootstrapping)
+├── sources.yaml         upstream watch list + baselines (radar)
+├── canonical/           neutral source of truth
+│   ├── rules/           CLAUDE.md (global rules), safety.md, project-CLAUDE.template.md
+│   ├── commands/        fh-context.md (project slash command written by bootstrap)
+│   ├── skills/          10 skills (SKILL.md, reference/, scripts/)
+│   ├── agents/          8 agents + README (tier map)
+│   ├── hooks/           4 hook scripts + Claude Code fragments + cost-prices.json
+│   ├── mcp/             servers.json
+│   ├── profiles/        opt-in profiles: local-ollama, local-llamacpp, mcp catalog (`init --profile`)
+│   ├── evals/           promptfoo red-team config (on demand); skills carry evals/cases.yaml
+│   ├── openspec/        spec-driven schema override + templates
+│   ├── HARVEST.yaml     classification of the official Claude Code plugins
+│   └── PROVENANCE.yaml  upstream path/commit/hash per harvested file
+├── packages/
+│   ├── core/            @freeharness/core — pure domain, zero deps
+│   ├── cli/             freeharness — CLI, composition root, adapters
+│   ├── sdd/             @freeharness/sdd — vendored OpenSpec slice + openspec bin
+│   └── memory/          vendored claude-mem (slim) + Bun build + viewer
+├── scripts/             check-arch.mjs, upstream-radar.mjs, skill-evals.mjs, simulate-session.mjs
+├── openspec/            FreeHarness's own specs and archived changes
+├── .github/workflows/   ci.yml, upstream-radar.yml
+├── Documents/           project documentation
+├── LICENSE, NOTICE
+└── README.md
+```
+
+## Documents
+
+- `Documents/architecture.md` — as-built architecture: canonical -> adapters -> harness, packages and dependency rule, capabilities per target, memory and SDD stacks, sync/radar, install manifest, cost tracker, harvest, tests and CI, distribution.
+- `Documents/INSTALL.md` — install once per machine, activate per project, short reference.
+- `Documents/ADVANCED.md` — manual build, single capabilities and project copies, memory switch by hand, cost tracking, OpenCode / plugin / npm targets, cleanup details, where things land.
+- `Documents/ROADMAP.md` — v4 and v5 direction; v3 machine-only leftovers.
+- `Documents/TEST-MATRIX.md` — every spec scenario mapped to a test or a machine-only tag.
+- `Documents/INTEGRATION.md` — the Claude Code integration simulation (`npm run simulate`): what it proves, the M-items only a real session proves, the measured hook table.
+- `Documents/RELEASE-CHECKLIST.md` — manual verifications (M1-M9) before a release.
+- `Documents/PUBLISHING.md` — npm tarball contents, pack, publish, tag (owner only).
+- `Documents/UPSTREAM-RADAR.md` — the weekly upstream report: sources, what it reports, from finding to work.
+- `Documents/Prompt_ClaudeCode_Global.md`, `Documents/Prompt_ClaudeCowork.md` — reference copies of the global prompts.
+
+## Principles
+
+- One neutral source; adapters do the translation. Model choice stays a tier, never a model name.
+- Hexagonal-lite: a framework-free core and ports; harness and engine specifics only in adapters (enforced by `check:arch`).
+- Own the engines: OpenSpec and claude-mem are vendored subsets with PROVENANCE, `sync check/adopt`, and a weekly radar; never auto-merged.
+- Every side effect is previewed and confirmed; settings merges are additive; uninstall removes only what was emitted.
+- Spec-first: FreeHarness evolves through its own `openspec/` (`/opsx`). Nothing duplicates OpenSpec's job.
+- Harvest, rewrite, credit: no verbatim third-party content; every derived file has provenance.
+
+## License
+
+MIT (see `LICENSE`). Third-party attributions for the vendored OpenSpec (MIT), claude-mem
+(Apache-2.0) and the harvested Claude Code plugin concepts are in `NOTICE`.