@cardor/agent-harness-kit 1.8.1 → 1.10.0

package/LICENSE

@@ -32,9 +32,10 @@
       not limited to compiled object code, generated documentation,
       and conversions to other media types.
 
-      "Work" shall mean the work of authorship made available under
-      the License, as indicated by a copyright notice that is included in
-      or attached to the work (an example is provided in the Appendix below).
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
 
       "Derivative Works" shall mean any work, whether in Source or Object
       form, that is based on (or derived from) the Work and for which the
@@ -44,21 +45,23 @@
       separable from, or merely link (or bind by name) to the interfaces of,
       the Work and Derivative Works thereof.
 
-      "Contribution" shall mean, as submitted to the Licensor for inclusion
-      in the Work by the copyright owner or by an individual or Legal Entity
-      authorized to submit on behalf of the copyright owner. For the purposes
-      of this definition, "submitted" means any form of electronic, verbal,
-      or written communication sent to the Licensor or its representatives,
-      including but not limited to communication on electronic mailing lists,
-      source code control systems, and issue tracking systems that are managed
-      by, or on behalf of, the Licensor for the purpose of submitting to the
-      Work, but excluding communication that is conspicuously marked or
-      otherwise designated in writing by the copyright owner as "Not a
-      Contribution."
-
-      "Contributor" shall mean Licensor and any Legal Entity on behalf of
-      whom a Contribution has been received by the Licensor and incorporated
-      within the Work.
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
 
    2. Grant of Copyright License. Subject to the terms and conditions of
       this License, each Contributor hereby grants to You a perpetual,
@@ -74,22 +77,22 @@
       use, offer to sell, sell, import, and otherwise transfer the Work,
       where such license applies only to those patent claims licensable
       by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by the combination of their Contribution(s)
+      Contribution(s) alone or by combination of their Contribution(s)
       with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a cross-claim
-      or counterclaim in a lawsuit) alleging that the Work or any
-      Contribution embodied within the Work constitutes direct or contributory
-      patent infringement, then any patent licenses granted to You under
-      this License for that Work shall terminate as of the date such
-      litigation is filed.
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
 
    4. Redistribution. You may reproduce and distribute copies of the
       Work or Derivative Works thereof in any medium, with or without
       modifications, and in Source or Object form, provided that You
       meet the following conditions:
 
-      (a) You must give any other recipients of the Work or Derivative
-          Works a copy of this License; and
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
 
       (b) You must cause any modified files to carry prominent notices
           stating that You changed the files; and
@@ -101,24 +104,28 @@
           the Derivative Works; and
 
       (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, You must include a readable copy of the
-          attribution notices contained within such NOTICE file, in
-          at least one of the following places: within a NOTICE text
-          file distributed as part of the Derivative Works; within
-          the Source form or documentation, if provided along with the
-          Derivative Works; or, within a display generated by the
-          Derivative Works, if and wherever such third-party notices
-          normally appear. The contents of the NOTICE file are for
-          informational purposes only and do not modify the License.
-          You may add Your own attribution notices within Derivative
-          Works that You distribute, alongside or in addition to the
-          NOTICE text from the Work, provided that such additional
-          attribution notices cannot be construed as modifying the License.
-
-      You may add Your own license statement for Your modifications and
-      may provide additional grant of rights to use, copy, modify, merge,
-      publish, distribute, sublicense, and/or sell copies of the Work,
-      and to permit persons to whom the Work is furnished to do so.
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
 
    5. Submission of Contributions. Unless You explicitly state otherwise,
       any Contribution intentionally submitted for inclusion in the Work
@@ -137,10 +144,10 @@
       agreed to in writing, Licensor provides the Work (and each
       Contributor provides its Contributions) on an "AS IS" BASIS,
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any conditions of TITLE,
-      NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR
-      PURPOSE. You are solely responsible for determining the
-      appropriateness of using or reproducing the Work and assume any
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
       risks associated with Your exercise of permissions under this License.
 
    8. Limitation of Liability. In no event and under no legal theory,
@@ -148,23 +155,38 @@
       unless required by applicable law (such as deliberate and grossly
       negligent acts) or agreed to in writing, shall any Contributor be
       liable to You for damages, including any direct, indirect, special,
-      incidental, or exemplary damages of any character arising as a
+      incidental, or consequential damages of any character arising as a
       result of this License or out of the use or inability to use the
-      Work (even if such Contributor has been advised of the possibility
-      of such damages).
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
 
    9. Accepting Warranty or Additional Liability. While redistributing
       the Work or Derivative Works thereof, You may choose to offer,
       and charge a fee for, acceptance of support, warranty, indemnity,
       or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may offer only
-      conditions consistent with this License and indemnify each other
-      Contributor for any liability incurred by such Contributor as a
-      result of your offering any such warranty or additional liability.
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
 
    END OF TERMS AND CONDITIONS
 
-   Copyright 2026 enmanuelmag
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Franklin Enmanuel Magallanes Pinargote
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -176,4 +198,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

package/README.md

@@ -30,6 +30,7 @@ npx ahk init
   - [Features](#features)
   - [Requirements](#requirements)
   - [Installation](#installation)
+  - [MCP command per package manager](#mcp-command-per-package-manager)
   - [Commands](#commands)
     - [`ahk init`](#ahk-init)
     - [`ahk build`](#ahk-build)
@@ -114,7 +115,7 @@ Everything is stored locally in a SQLite database (`.harness/harness.db`). No cl
 - **Health gate** — agents must run `health.sh` and get a green exit before starting or closing any task. You define what "healthy" means.
 - **Markdown fallback** — `current.md` is always regenerated so agents can understand the session state even without the MCP server.
 - **Docs search** — agents can call `docs.search(query)` to find relevant content in your project's docs folder before writing code.
-- **Multi-database support** — SQLite by default (zero native deps, uses `node:sqlite` on Node ≥ 22 or `bun:sqlite` on Bun). Switch to PostgreSQL or MySQL with a single config line — same schema, same MCP tools, same workflow.
+- **Multi-database support** — SQLite by default (uses `better-sqlite3` on Node ≥ 22 or `bun:sqlite` on Bun). Switch to PostgreSQL or MySQL with a single config line — same schema, same MCP tools, same workflow.
 - **Incremental scaffold** — `ahk init` preserves files you've already customized (agent definitions you've edited are kept). `ahk build` always regenerates agent files from the latest templates so they stay up to date.
 - **Global installation** — `ahk init` can scaffold the harness into your home directory (`~/.claude` or `~/.config/opencode`) to share it across all projects.
 - **Input validation** — CLI prompts validate all inputs (name length, path format, task title, etc.) and retry with the error message instead of silently accepting bad values.
@@ -131,35 +132,74 @@ Everything is stored locally in a SQLite database (`.harness/harness.db`). No cl
 ## Installation
 
 ```bash
-# Install in your project as a dev dependency
+# Install in your project as a dev dependency (recommended)
 npm install --save-dev @cardor/agent-harness-kit
-
-# Or globally
-npm install -g @cardor/agent-harness-kit
 ```
 
 Then run the interactive setup inside your project:
 
 ```bash
 npx ahk init
-# or, if installed globally:
-ahk init
 ```
 
+> **Local install required.** `ahk` needs to resolve your project's `agent-harness-kit.config.ts` and its dependencies relative to your project's own `node_modules`. A **global-only** install (`npm install -g @cardor/agent-harness-kit`) cannot do this reliably, so every command except `--version`/`--help` will detect a global-only install and exit with an error telling you to run `npm install --save-dev @cardor/agent-harness-kit` (or the `pnpm`/`yarn`/`bun` equivalent) in your project root.
+>
+> This check also works with **Yarn Berry (PnP)** projects, which never create a `node_modules` folder — `ahk` detects `.pnp.cjs`/`.pnp.loader.mjs` and falls back to checking that the package is declared in `package.json` instead of requiring a `node_modules` entry.
+
+---
+
+## MCP command per package manager
+
+`ahk init` and `ahk build` detect which package manager your project uses and generate the MCP server launch command (`.mcp.json`, `opencode.json`, or `.codex/config.toml`) accordingly, instead of hardcoding `npx`:
+
+| Package manager           | Detected via                                                              | Generated command                             |
+| -------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------- |
+| npm                        | `packageManager` field, `package-lock.json`, or fallback                    | `npx --no ahk serve --port <port>`             |
+| pnpm                       | `packageManager` field or `pnpm-lock.yaml`                                  | `pnpm exec ahk serve --port <port>`            |
+| yarn classic (v1)          | `packageManager` field (major 1) or `yarn.lock` without `.yarnrc.yml`       | `yarn run ahk serve --port <port>`             |
+| yarn berry (v2+, PnP or node-modules) | `packageManager` field (major ≥ 2) or `yarn.lock` + `.yarnrc.yml` | `yarn run ahk serve --port <port>`             |
+| bun                        | `packageManager` field or `bun.lockb`/`bun.lock`                            | `bunx --no-install ahk serve --port <port>`    |
+
+Detection order: the `packageManager` field in your `package.json` (e.g. `"packageManager": "pnpm@8.15.0"`) takes priority when present; otherwise `ahk` falls back to lockfile heuristics; if nothing is detected, it defaults to npm.
+
+**Existing projects:** if you initialized your project before this change, your `.mcp.json`/`opencode.json`/`.codex/config.toml` may still have a hardcoded `npx` command. No migration step is needed — `ahk build` always regenerates (merges) these files from scratch on every run, so the command self-corrects the next time you run `ahk build` (or `ahk build --sync`), including if you've since switched package managers.
+
 ---
 
 ## Commands
 
 ### `ahk init`
 
-Interactive scaffold. Asks for your project name, description, AI provider, docs path, task adapter, and an optional first task. Creates all harness files in the current directory.
+Interactive scaffold. Asks for your project name, description, AI provider, docs path, storage scope, task adapter, and an optional first task. Creates all harness files in the current directory.
+
+For Claude Code and Codex CLI (not OpenCode), you'll also be asked whether to personalize the model per agent (lead/explorer/consultant/builder/reviewer):
+
+- Claude Code: pick from `inherit` (default), `haiku`, `sonnet`, `opus`, `fable` per agent.
+- Codex CLI: free-text model name per agent — Codex does not validate this value; leaving it blank or under 3 characters means no override is written to that agent's TOML file.
+
+**Storage scope** — where the harness DB (and its `current.md` fallback) physically lives:
+
+- `local` (default) — `.harness/harness.db`, inside the project.
+- `global` — `~/.harness/dbs/<projectId>/harness.db`, outside the project tree (useful to keep the DB out of version control entirely, or to centralize storage for many projects). `<projectId>` is a UUID generated once at init and persisted in `agent-harness-kit.config.ts` — it's never regenerated on subsequent runs.
+
+Regardless of scope, `.harness/storage-state.json` is always written to the project — it records the *actual* current storage state (`scope`, `projectId`, `dbType`, `migratedAt`), separate from the *desired* state declared in the config file.
+
+When `--storage-scope global` is chosen, `ahk init` also synchronizes your provider's agent and skill files into your home directory (in addition to the project-local files it always writes), so subsequent `ahk init --storage-scope global` runs in *other* projects on the same machine can reuse them instead of re-scaffolding:
+
+| Provider      | Global agents dir           | Global skills dir            |
+| ------------- | ---------------------------- | ----------------------------- |
+| `claude-code` | `~/.claude/agents/`          | `~/.claude/skills/`           |
+| `codex-cli`   | `~/.codex/agents/`           | `~/.agents/skills/` (separate namespace from `~/.codex/agents`) |
+| `opencode`    | `~/.config/opencode/agents/` | `~/.config/opencode/skills/`  |
+
+This sync is idempotent and non-destructive: it only creates files that are missing. If everything is already present, `ahk init` prints a message and skips; if only some files are missing, it creates just those and reports what was added. Files it detects as already customized/outdated are left untouched (same "preserve, don't overwrite" rule used for project-local agent files).
 
 ```bash
 ahk init
 
 # Skip prompts with flags
-ahk init --name "my-app" --provider claude-code --docs ./docs --tasks local
-ahk init --name "my-app" --provider codex-cli   --docs ./docs --tasks local
+ahk init --name "my-app" --provider claude-code --docs ./docs --tasks local --storage-scope local
+ahk init --name "my-app" --provider codex-cli   --docs ./docs --tasks local --storage-scope global
 ```
 
 Run this once per project. If the project is already initialized, the command prints an 'already initialized' message with suggested next-step commands (`ahk build`, `ahk build --sync`, `ahk reset`, `ahk serve`) and exits without overwriting anything.
@@ -240,7 +280,7 @@ Reports three categories:
 
 - **lib version** — compares installed version against the latest on npm. Shows `[✓]` if up to date, `[!]` if an update is available, or `[~]` if the registry could not be reached.
 - **agent files** — reads each agent file on disk and compares against what `ahk build` would generate. Reports `[!]` with the file name if outdated.
-- **harness skills** — checks that `ahk-ask`, `ahk-consultant`, and `ahk-triage` skills exist and match the bundled source. Reports `[!]` if missing or outdated.
+- **harness skills** — checks that `ahk-ask`, `ahk-consultant`, `ahk-triage`, and `ahk-review` skills exist and match the bundled source. Reports `[!]` if missing or outdated.
 
 Run `ahk build` to fix any reported issues.
 
@@ -331,14 +371,48 @@ After a reset, run `ahk init` to scaffold a fresh harness.
 
 ### `ahk migrate`
 
+`ahk migrate` has two subcommands: `provider` (migrate scaffold files to a different AI provider) and `storage` (migrate the harness database between storage backends). `ahk migrate --to <provider>` (no subcommand) is kept as a backward-compatible alias for `ahk migrate provider --to <provider>` — existing scripts/CI using the old form keep working unchanged.
+
+#### `ahk migrate provider`
+
 Migrates provider-specific files from one AI provider to another. Useful when switching from Claude Code to OpenCode or vice versa.
 
 ```bash
+ahk migrate provider --to opencode
+ahk migrate provider --to claude-code
+ahk migrate provider --to codex-cli
+
+# Backward-compatible alias (identical behavior):
 ahk migrate --to opencode
-ahk migrate --to claude-code
-ahk migrate --to codex-cli
 ```
 
+#### `ahk migrate storage` — ⚠️ sensitive, reads/writes real harness data
+
+Migrates the harness database between storage backends: **local↔global scope** (moving `.harness/harness.db` in/out of `~/.harness/dbs/<projectId>/`) and **sqlite↔postgres/mysql** (dumping and reloading all 6 tables — tasks, task_acceptance, actions, action_sections, action_files, action_tools — inside a single transaction). It is **not interactive** — `agent-harness-kit.config.ts` (`storage.scope`, `database.type`/`path`/`connectionString`) is the only source of truth for the desired target, compared against the real current state recorded in `.harness/storage-state.json`.
+
+```bash
+ahk migrate storage             # migrate to whatever agent-harness-kit.config.ts declares
+ahk migrate storage --dry-run   # preview what would happen, without touching anything
+ahk migrate storage --force     # required whenever the destination already has data
+```
+
+What it does, case by case:
+
+| Situation | Behavior |
+|---|---|
+| Config and real storage state already match | No-op — reports "nothing to migrate" |
+| Only `storage.scope` differs (same DB engine) | Copies the `.db` file (+ WAL/SHM) and `current.md` directly to the new location, verifies the copy, then removes the original |
+| Only `database.type` differs (sqlite → postgres/mysql) | Full export/import of all 6 tables inside one transaction; on failure, the destination is rolled back exactly as it was found |
+| Destination already has data | **Requires `--force`.** Without it, the command aborts and touches nothing. With it, the destination's current content is backed up to `.harness/backups/pre-migrate-<timestamp>.json` **before** anything is overwritten — if the backup can't be written, the whole command aborts |
+| Both source and destination have diverging data (not just empty vs. full) | Same as above (`--force` + backup required) — the command never attempts to auto-merge two independent histories |
+| `.harness/storage-state.json` is missing | Never assumed to mean "safe, empty destination." Both the local and global sqlite candidate locations are inspected for real data first; if both have data, the command refuses to guess and asks for manual resolution |
+
+**Limitations (by design, matches the current scope):**
+- No connection pooling or incremental/partial migrations — always a full dump/load.
+- After inserting rows with their original ids, the destination's internal id sequence is explicitly re-synced (`setval` on Postgres, `sqlite_sequence` update on SQLite; MySQL's `AUTO_INCREMENT` advances on its own) so that the next normal task/action created after migrating never collides with an imported id.
+- Migrating *away from* a previously remote (postgres/mysql) database isn't supported automatically — `storage-state.json` intentionally never stores connection credentials, so there's nothing to reconnect to. Export manually with `ahk export --json` while still connected to the old database first.
+- The original sqlite file is **not** deleted after a sqlite→remote migration — remove it manually once you've verified the migrated data.
+
 ---
 
 ### `ahk export`
@@ -365,8 +439,9 @@ your-project/
 ├── CLAUDE.md
 ├── health.sh
 ├── .harness/
-│   ├── harness.db                 ← gitignored
-│   ├── current.md                 ← gitignored
+│   ├── harness.db                 ← gitignored (local scope only — absent when scope: 'global')
+│   ├── current.md                 ← gitignored (local scope only — absent when scope: 'global')
+│   ├── storage-state.json         ← always present, reflects the REAL current storage scope/projectId
 │   └── feature_list.json
 └── .claude/
     ├── agents/
@@ -421,8 +496,9 @@ your-project/
 | `AGENTS.md`                   | Navigation map agents read first. Regenerated by `ahk build`                          | No — changes will be overwritten                            |
 | `health.sh`                   | Shell script agents run before starting work. Must exit 0                             | **Yes — implement your checks here**                        |
 | `.harness/feature_list.json`  | Task backlog in JSON. Humans edit this, `ahk sync` loads it into SQLite               | Yes — add tasks here                                        |
-| `.harness/harness.db`         | SQLite database. Source of truth for tasks, actions, sections                         | No — managed by the harness                                 |
-| `.harness/current.md`         | Auto-generated session snapshot for agents without MCP access                         | No — regenerated automatically                              |
+| `.harness/harness.db`         | SQLite database (local scope only). Source of truth for tasks, actions, sections      | No — managed by the harness                                 |
+| `.harness/current.md`         | Auto-generated session snapshot for agents without MCP access (local scope only)      | No — regenerated automatically                              |
+| `.harness/storage-state.json` | Always project-local. Records the REAL current storage state (`scope`, `projectId`, `dbType`, `migratedAt`) — used by migration tooling | No — managed by the harness |
 | `.claude/agents/*.md`         | Agent role definitions (Claude Code). Created once, never overwritten                 | **Yes — customize agent behavior**                          |
 | `.claude/mcp.json`            | MCP server registration for Claude Code. Merged by `ahk build`                        | Yes, carefully — don't remove the `agent-harness-kit` entry |
 | `.claude/settings.json`       | Sets `agent: "lead"` so lead runs as the default session agent. Merged by `ahk build` | Yes, carefully                                              |
@@ -458,10 +534,11 @@ export default defineHarness({
   provider: 'claude-code', // 'claude-code' | 'opencode' | 'codex-cli'
 
   agents: {
-    lead: { instructionsPath: null },
-    explorer: { instructionsPath: null, allowedPaths: ['./docs', './src'] },
+    lead: { instructionsPath: null, model: 'sonnet' }, // optional per-agent model override
+    explorer: { instructionsPath: null, allowedPaths: ['./docs', './src'], model: 'haiku' },
     builder: { instructionsPath: null, writablePaths: ['./src', './tests'] },
     reviewer: { instructionsPath: null },
+    consultant: { instructionsPath: null, model: 'haiku' },
     custom: [], // define extra agents here
   },
 
@@ -486,6 +563,10 @@ export default defineHarness({
       nextSteps: false, // optional next steps field
     },
     markdownFallback: { enabled: true, path: '.harness/current.md' },
+    // 'local' (default) — DB lives in .harness/ (project-relative).
+    // 'global' — DB lives under ~/.harness/dbs/<projectId>/, outside the project.
+    scope: 'local', // 'local' | 'global'
+    projectId: '5f2c...', // UUID, generated once at init, never regenerated
   },
 
   health: {
@@ -598,24 +679,24 @@ Good acceptance criteria make the difference — the reviewer agent uses them to
 
 The harness exposes these tools via MCP. Agents use them instead of reading files directly.
 
-| Tool                      | Parameters                                      | Description                                                                                                                                                            |
-| ------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `tasks.get`               | `status?`                                       | List tasks, optionally filtered by `pending \| in_progress \| done \| blocked`                                                                                         |
-| `tasks.claim`             | `id, agent`                                     | Atomically claim a pending task. Returns `task_already_claimed` if another agent got it first                                                                          |
-| `tasks.update`            | `id, status`                                    | Change task status                                                                                                                                                     |
-| `tasks.add`               | `title, slug?, description?, acceptance?`       | Create a new task directly from MCP (agents can queue work on the fly)                                                                                                 |
-| `tasks.acceptance.update` | `criterionId`                                   | Mark an acceptance criterion as met. Criterion IDs come from `tasks.acceptance_get`                                                                                    |
-| `actions.start`           | `taskId, agent`                                 | Start a new action, returns `actionId`                                                                                                                                 |
-| `actions.write`           | `actionId, sectionType, content`                | Record a text section: `result \| tools_used \| blockers \| next_steps`. Does **not** populate the Files dashboard — use `actions.record_file` for that                |
-| `actions.complete`        | `actionId, summary`                             | Close an action with a one-line summary                                                                                                                                |
-| `actions.get`             | `taskId`                                        | Full action history for a task (all agents, all sections)                                                                                                              |
-| `actions.record_file`     | `actionId, filePath, operation, notes?`         | Register a file touch. The **only** way to populate the Files dashboard. `operation`: `read \| created \| modified \| deleted`                                         |
-| `actions.record_tool`     | `actionId, toolName, argsJson?, resultSummary?` | Register a tool call. The **only** way to populate the Tools dashboard                                                                                                 |
-| `docs.search`             | `query`                                         | Search the `docsPath` folder for content matching the query                                                                                                            |
-| `tasks.acceptance_get`    | `taskId`                                        | Returns all acceptance criteria for a task with their `id`, `task_id`, `criterion` text, and `met` status. Use the returned `id` values with `tasks.acceptance.update` |
-| `deps.snapshot`           | _(none)_                                        | Snapshot current `package.json` dependencies to `.harness/deps-lock.json`                                                                                              |
-| `deps.check`              | _(none)_                                        | Compare current `package.json` against `.harness/deps-lock.json`. Returns `{ significant, added, removed, majorBumps, advisory }`                                      |
-| `ahk.doctor`              | _(none)_                                        | Check lib version, agent files, and harness skills sync status. Returns `{ lib: { current, latest, outdated }, agents: { outdated, upToDate }, skills: { missing, outdated, ok } }` |
+| Tool                      | Parameters                                      | Description                                                                                                                                                                         |
+| ------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tasks.get`               | `status?`                                       | List tasks, optionally filtered by `pending \| in_progress \| done \| blocked`                                                                                                      |
+| `tasks.claim`             | `id, agent`                                     | Atomically claim a pending task. Returns `task_already_claimed` if another agent got it first                                                                                       |
+| `tasks.update`            | `id, status`                                    | Change task status                                                                                                                                                                  |
+| `tasks.add`               | `title, slug?, description?, acceptance?`       | Create a new task directly from MCP (agents can queue work on the fly)                                                                                                              |
+| `tasks.acceptance.update` | `criterionId`                                   | Mark an acceptance criterion as met. Criterion IDs come from `tasks.acceptance_get`                                                                                                 |
+| `actions.start`           | `taskId, agent`                                 | Start a new action, returns `actionId`                                                                                                                                              |
+| `actions.write`           | `actionId, sectionType, content`                | Record a text section: `result \| tools_used \| blockers \| next_steps`. Does **not** populate the Files dashboard — use `actions.record_file` for that                             |
+| `actions.complete`        | `actionId, summary`                             | Close an action with a one-line summary                                                                                                                                             |
+| `actions.get`             | `taskId`                                        | Full action history for a task (all agents, all sections)                                                                                                                           |
+| `actions.record_file`     | `actionId, filePath, operation, notes?`         | Register a file touch. The **only** way to populate the Files dashboard. `operation`: `read \| created \| modified \| deleted`                                                      |
+| `actions.record_tool`     | `actionId, toolName, argsJson?, resultSummary?` | Register a tool call. The **only** way to populate the Tools dashboard                                                                                                              |
+| `docs.search`             | `query`                                         | Search the `docsPath` folder for content matching the query                                                                                                                         |
+| `tasks.acceptance_get`    | `taskId`                                        | Returns all acceptance criteria for a task with their `id`, `task_id`, `criterion` text, and `met` status. Use the returned `id` values with `tasks.acceptance.update`              |
+| `deps.snapshot`           | _(none)_                                        | Snapshot current `package.json` dependencies to `.harness/deps-lock.json`                                                                                                           |
+| `deps.check`              | _(none)_                                        | Compare current `package.json` against `.harness/deps-lock.json`. Returns `{ significant, added, removed, majorBumps, advisory }`                                                   |
+| `ahk.doctor`              | _(none)_                                        | Check lib version, agent files, and harness skills sync status. Returns `{ lib: { current, latest, outdated }, agents: { missing, outdated, ok }, skills: { missing, outdated, ok } }`. The `lib` version lookup (npm registry check) is cached in-memory with a 5-minute TTL — repeated calls within that window do not hit the network again. |
 
 ---
 
@@ -675,10 +756,11 @@ Each agent role has a scoped set of MCP tools enforced through the agent definit
 | `opencode.json`               | Yes                 |
 | `.codex/agents/*.toml`        | Yes                 |
 | `.codex/config.toml`          | Yes                 |
-| `.harness/harness.db`         | **No** (gitignored) |
-| `.harness/current.md`         | **No** (gitignored) |
+| `.harness/harness.db`         | **No** (gitignored, local scope only) |
+| `.harness/current.md`         | **No** (gitignored, local scope only) |
+| `.harness/storage-state.json` | Yes (metadata, not gitignored — always present regardless of scope) |
 
-The rule: commit inputs (config, task definitions, agent instructions). Ignore outputs (DB, auto-generated snapshots).
+The rule: commit inputs (config, task definitions, agent instructions). Ignore outputs (DB, auto-generated snapshots). `storage-state.json` is metadata about *where* those outputs live, not an output itself — it's committed so the harness can detect storage drift.
 
 ---
 
@@ -686,11 +768,11 @@ The rule: commit inputs (config, task definitions, agent instructions). Ignore o
 
 | Runtime          | SQLite                         | PostgreSQL                | MySQL                   |
 | ---------------- | ------------------------------ | ------------------------- | ----------------------- |
-| Node.js ≥ 22     | ✅ uses `node:sqlite` built-in | ✅ via `postgres` package | ✅ via `mysql2` package |
-| Bun (any recent) | ✅ uses `bun:sqlite` built-in  | ✅ via `postgres` package | ✅ via `mysql2` package |
-| Node.js < 22     | ❌ `node:sqlite` not available | ✅                        | ✅                      |
+| Node.js ≥ 22     | ✅ uses `better-sqlite3` package | ✅ via `postgres` package | ✅ via `mysql2` package |
+| Bun (any recent) | ✅ uses `bun:sqlite` built-in    | ✅ via `postgres` package | ✅ via `mysql2` package |
+| Node.js < 22     | ❌ blocked by `engines.node` (not by the SQLite driver) | ✅ | ✅ |
 
-SQLite requires no additional packages. For PostgreSQL install `postgres`, for MySQL install `mysql2`:
+SQLite is included via the `better-sqlite3` dependency (installed automatically). For PostgreSQL install `postgres`, for MySQL install `mysql2`:
 
 ```bash
 npm install postgres    # for PostgreSQL

package/dist/agent-templates/builder.md

@@ -152,6 +152,19 @@ Then complete your action with a blocked status — do not guess through ambigui
 actions.complete(actionId, 'Implementation done — N files modified, tests passing')
 ```
 
+## Committing changes with git
+
+Only commit when explicitly asked to.
+
+Before writing a commit message, detect whether the repo already enforces a commit message convention:
+- Look for `commitlint.config.*` or `.commitlintrc*` in the repo root
+- Look for `.husky/commit-msg`
+- Look for `commitlint` or `husky` listed in `package.json` dependencies/devDependencies
+
+**If tooling is detected** — follow the repo's existing convention. Do not invent or override a different format.
+
+**If no tooling is detected** — use the pattern `<action>(<scope>): <message>`, where `<message>` is at most 50 characters. Example: `fix(auth): handle expired refresh tokens`.
+
 ## Hard rules
 
 - **Read the plan and analysis first.** Never implement cold.

package/dist/{chunk-OEPZRC7J.js → chunk-ADV7OPU2.js}

@@ -1,4 +1,5 @@
 // src/core/config.ts
+import { randomUUID } from "crypto";
 import { existsSync } from "fs";
 import { join } from "path";
 import { createJiti } from "jiti";
@@ -61,6 +62,8 @@ function applyDefaults(config) {
         nextSteps: false
       },
       markdownFallback: { enabled: true, path: ".harness/current.md" },
+      scope: "local",
+      projectId: c.storage?.projectId ?? randomUUID(),
       ...c.storage
     },
     health: {
@@ -81,4 +84,4 @@ export {
   loadConfig,
   defineHarness
 };
-//# sourceMappingURL=chunk-OEPZRC7J.js.map
+//# sourceMappingURL=chunk-ADV7OPU2.js.map

package/dist/chunk-ADV7OPU2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/config.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto'\nimport { existsSync } from 'node:fs'\nimport { join } from 'node:path'\nimport { createJiti } from 'jiti'\n\nimport type { HarnessConfig } from '@/types'\n\nconst CONFIG_NAMES = [\n  'agent-harness-kit.config.ts',\n  'agent-harness-kit.config',\n  'agent-harness-kit.config.mjs',\n  'agent-harness-kit.config.cjs',\n]\n\nexport function findConfigFile(cwd: string): string | null {\n  for (const name of CONFIG_NAMES) {\n    const candidate = join(cwd, name)\n    if (existsSync(candidate)) return candidate\n  }\n  return null\n}\n\nexport async function loadConfig(cwd: string): Promise<HarnessConfig> {\n  const configPath = findConfigFile(cwd)\n  if (!configPath) {\n    throw new Error('No agent-harness-kit.config found. Run: ahk init')\n  }\n\n  const jiti = createJiti(import.meta.url)\n  const mod = await jiti.import(configPath) as { default?: HarnessConfig } | HarnessConfig\n  const config = (mod as { default?: HarnessConfig }).default ?? (mod as HarnessConfig)\n\n  if (!config || typeof config !== 'object') {\n    throw new Error(`agent-harness-kit.config must export a default HarnessConfig object.`)\n  }\n\n  return applyDefaults(config as HarnessConfig)\n}\n\nexport function defineHarness(config: HarnessConfig): HarnessConfig {\n  return config\n}\n\nfunction applyDefaults(config: HarnessConfig): HarnessConfig {\n  const c = config as Partial<HarnessConfig>\n  return {\n    ...config,\n    provider: c.provider ?? 'claude-code',\n    project: {\n      docsPath: './docs',\n      agentsMd: './AGENTS.md',\n      ...c.project,\n    } as HarnessConfig['project'],\n    agents: {\n      lead: { instructionsPath: null },\n      explorer: { instructionsPath: null },\n      builder: { instructionsPath: null },\n      reviewer: { instructionsPath: null },\n      custom: [],\n      ...c.agents,\n    } as HarnessConfig['agents'],\n    database: c.database ?? { type: 'sqlite' as const, path: '.harness/harness.db' },\n    storage: {\n      dir: '.harness',\n      tasks: { adapter: 'local' as const },\n      sections: {\n        toolsUsed: true,\n        filesModified: true,\n        result: true,\n        blockers: true,\n        nextSteps: false,\n      },\n      markdownFallback: { enabled: true, path: '.harness/current.md' },\n      scope: 'local' as const,\n      projectId: c.storage?.projectId ?? randomUUID(),\n      ...c.storage,\n    } as HarnessConfig['storage'],\n    health: {\n      scriptPath: './health.sh',\n      required: true,\n      ...c.health,\n    },\n    tools: {\n      mcp: { enabled: true, port: 3742 },\n      scripts: { enabled: true, outputDir: './.harness/scripts' },\n      ...c.tools,\n    } as HarnessConfig['tools'],\n  }\n}\n"],"mappings":";AAAA,SAAS,kBAAkB;AAC3B,SAAS,kBAAkB;AAC3B,SAAS,YAAY;AACrB,SAAS,kBAAkB;AAI3B,IAAM,eAAe;AAAA,EACnB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEO,SAAS,eAAe,KAA4B;AACzD,aAAW,QAAQ,cAAc;AAC/B,UAAM,YAAY,KAAK,KAAK,IAAI;AAChC,QAAI,WAAW,SAAS,EAAG,QAAO;AAAA,EACpC;AACA,SAAO;AACT;AAEA,eAAsB,WAAW,KAAqC;AACpE,QAAM,aAAa,eAAe,GAAG;AACrC,MAAI,CAAC,YAAY;AACf,UAAM,IAAI,MAAM,kDAAkD;AAAA,EACpE;AAEA,QAAM,OAAO,WAAW,YAAY,GAAG;AACvC,QAAM,MAAM,MAAM,KAAK,OAAO,UAAU;AACxC,QAAM,SAAU,IAAoC,WAAY;AAEhE,MAAI,CAAC,UAAU,OAAO,WAAW,UAAU;AACzC,UAAM,IAAI,MAAM,sEAAsE;AAAA,EACxF;AAEA,SAAO,cAAc,MAAuB;AAC9C;AAEO,SAAS,cAAc,QAAsC;AAClE,SAAO;AACT;AAEA,SAAS,cAAc,QAAsC;AAC3D,QAAM,IAAI;AACV,SAAO;AAAA,IACL,GAAG;AAAA,IACH,UAAU,EAAE,YAAY;AAAA,IACxB,SAAS;AAAA,MACP,UAAU;AAAA,MACV,UAAU;AAAA,MACV,GAAG,EAAE;AAAA,IACP;AAAA,IACA,QAAQ;AAAA,MACN,MAAM,EAAE,kBAAkB,KAAK;AAAA,MAC/B,UAAU,EAAE,kBAAkB,KAAK;AAAA,MACnC,SAAS,EAAE,kBAAkB,KAAK;AAAA,MAClC,UAAU,EAAE,kBAAkB,KAAK;AAAA,MACnC,QAAQ,CAAC;AAAA,MACT,GAAG,EAAE;AAAA,IACP;AAAA,IACA,UAAU,EAAE,YAAY,EAAE,MAAM,UAAmB,MAAM,sBAAsB;AAAA,IAC/E,SAAS;AAAA,MACP,KAAK;AAAA,MACL,OAAO,EAAE,SAAS,QAAiB;AAAA,MACnC,UAAU;AAAA,QACR,WAAW;AAAA,QACX,eAAe;AAAA,QACf,QAAQ;AAAA,QACR,UAAU;AAAA,QACV,WAAW;AAAA,MACb;AAAA,MACA,kBAAkB,EAAE,SAAS,MAAM,MAAM,sBAAsB;AAAA,MAC/D,OAAO;AAAA,MACP,WAAW,EAAE,SAAS,aAAa,WAAW;AAAA,MAC9C,GAAG,EAAE;AAAA,IACP;AAAA,IACA,QAAQ;AAAA,MACN,YAAY;AAAA,MACZ,UAAU;AAAA,MACV,GAAG,EAAE;AAAA,IACP;AAAA,IACA,OAAO;AAAA,MACL,KAAK,EAAE,SAAS,MAAM,MAAM,KAAK;AAAA,MACjC,SAAS,EAAE,SAAS,MAAM,WAAW,qBAAqB;AAAA,MAC1D,GAAG,EAAE;AAAA,IACP;AAAA,EACF;AACF;","names":[]}