@vaubaan/harness 0.0.0-stage → 1.3.0

package/dist/templates/coding-workflow.md.tmpl

@@ -0,0 +1,88 @@
+---
+tracks:
+  - .github/workflows/*
+  - vercel.json
+  - package.json
+last_reviewed: <DATE>
+---
+
+# Coding workflow
+
+This document describes *how we work* on this project: the CI
+pipeline, the environments, the PR (or direct-push) process, the
+branch model, the commit conventions, and the release
+process.
+
+## 1. CI pipeline
+
+| Trigger                      | Jobs triggered                           | Typical duration |
+|------------------------------|------------------------------------------|------------------|
+| push to `<MAIN_BRANCH>`      | <JOBS_ON_MAIN_PUSH>                      | <DURATION>       |
+| pull_request                 | <JOBS_ON_PR>                             | <DURATION>       |
+| tag `v*`                     | <JOBS_ON_TAG>                            | <DURATION>       |
+| schedule                     | <JOBS_ON_SCHEDULE>                       | <DURATION>       |
+
+**Jobs required to merge a PR:** <REQUIRED_JOBS>.
+
+**How to force a re-run:** <RERUN_INSTRUCTIONS>.
+
+## 2. Environments
+
+| Env            | URL                          | Source branch      | Data                     | Access            |
+|----------------|------------------------------|--------------------|--------------------------|-------------------|
+| `prod`         | <PROD_URL>                   | <PROD_BRANCH>      | <PROD_DATA>              | <PROD_ACCESS>     |
+| `staging`      | <STAGING_URL>                | <STAGING_BRANCH>   | <STAGING_DATA>           | <STAGING_ACCESS>  |
+| `preview`      | <PREVIEW_URL_PATTERN>        | feature branches   | <PREVIEW_DATA>           | <PREVIEW_ACCESS>  |
+| `local`        | <LOCAL_URL>                  | n/a                | <LOCAL_DATA>             | dev               |
+
+Each environment has its own set of variables — see
+<ENV_VARS_REFERENCE>.
+
+## 3. Process: PR or direct-push
+
+<PR_OR_DIRECT_PUSH_DECLARATION>
+
+### If PR
+
+- Creation: <PR_CREATION_RULES>
+- Review: <REVIEW_RULES>
+- Merge: <MERGE_RULES>
+
+### If direct-push
+
+- Branches allowed for direct-push: <DIRECT_PUSH_BRANCHES>
+- Safeguards: <DIRECT_PUSH_GUARDS>
+
+## 4. Branch model
+
+- **Model:** <TRUNK_BASED | GITFLOW | GITHUB_FLOW | OTHER>
+- **Main branch:** `<MAIN_BRANCH>`
+- **Staging branch (if distinct):** `<STAGING_BRANCH>`
+- **Feature naming convention:** `<FEATURE_BRANCH_PATTERN>`
+- **Max lifetime of a feature branch:** <MAX_LIFETIME>
+
+## 5. Commit / merge conventions
+
+- **Message format:** <COMMIT_MESSAGE_FORMAT>
+- **Conventional commits?** <YES_NO_DETAILS>
+- **Squash, rebase or merge?** <MERGE_STRATEGY>
+- **Signing required?** <SIGNING_POLICY>
+
+## 6. Release
+
+- **Who can trigger a release:** <RELEASE_AUTHORITY>
+- **How we tag:** <TAGGING_PROCESS>
+- **Versioning:** <VERSIONING_SCHEME>
+- **Rollback:** <ROLLBACK_PROCESS>
+- **Freeze windows:** <FREEZE_WINDOWS>
+- **Communication:** <RELEASE_NOTES_CHANNEL>
+
+### Minimal release runbook
+
+1. <RELEASE_STEP_1>
+2. <RELEASE_STEP_2>
+3. <RELEASE_STEP_N>
+
+### Post-release incident
+
+See <INCIDENT_RUNBOOK_REF>.

package/dist/templates/decision.md.tmpl

@@ -0,0 +1,60 @@
+# <DECISION_TITLE>
+
+- **Date:** <DATE>
+- **Author:** <AUTHOR>
+- **Status:** <PROPOSED | ACCEPTED | SUPERSEDED | DEPRECATED>
+- **Supersedes:** <PREVIOUS_ADR_SLUG | none>
+
+## Context
+
+Describe the situation that makes this decision necessary. What problem
+are we solving? What constraints apply (technical, organizational,
+time-related)? What signals triggered the discussion?
+
+This section must be readable on its own: a reader discovering the
+ADR six months later must understand why the question came up.
+
+## Decision
+
+State the chosen decision in one to three clear sentences. No
+"we will probably" — it is settled.
+
+Then detail the conditions of application: scope, exceptions,
+thresholds, effective dates.
+
+## Consequences
+
+List the expected effects of the decision, positive **and** negative.
+
+**Positive:**
+
+- <POSITIVE_CONSEQUENCE_1>
+- <POSITIVE_CONSEQUENCE_N>
+
+**Negative:**
+
+- <NEGATIVE_CONSEQUENCE_1>
+- <NEGATIVE_CONSEQUENCE_N>
+
+**Neutral / to watch:**
+
+- <NEUTRAL_CONSEQUENCE_1>
+
+## Rejected alternatives
+
+List the options seriously considered that were not chosen,
+with the reason for rejecting each one. This section is as important
+as the decision itself — it avoids re-debating the same
+alternatives later.
+
+### Alternative A — <ALTERNATIVE_A_NAME>
+
+<DESCRIPTION_A>
+
+Rejected because: <REJECTION_REASON_A>.
+
+### Alternative B — <ALTERNATIVE_B_NAME>
+
+<DESCRIPTION_B>
+
+Rejected because: <REJECTION_REASON_B>.

package/dist/templates/e2e-tests.md.tmpl

@@ -0,0 +1,62 @@
+---
+tracks:
+  - <E2E_TEST_DIR_OR_FILE_1>
+  - <E2E_TEST_DIR_OR_FILE_2>
+last_reviewed: <DATE>
+---
+
+# E2E test plan
+
+## Scope
+
+E2E tests verify the **complete** system against real dependencies
+(or a staging environment faithful to prod). We distinguish:
+
+- **Golden paths**: the main user journeys that must
+  pass on every release. Exhaustive coverage required.
+- **Edge cases**: less frequent but high-value scenarios
+  (errors, permissions, boundary states). Selective coverage.
+
+Anything that can be validated in local integration (see
+[integration-tests.md](./integration-tests.md)) **must** be —
+E2E tests are expensive, we reserve them for journeys that cannot
+be validated otherwise.
+
+## Stack
+
+- **E2E runner:** <E2E_RUNNER>
+- **Drivers:** <BROWSER_OR_API_DRIVER>
+- **Target environment:** <ENV_TARGET>
+- **Reporting:** <REPORT_TOOL>
+
+## Fixture conventions
+
+- **E2E organization:** each scenario runs in an isolated
+  fixture (`<E2E_ORG_NAMING_CONVENTION>`) to avoid
+  interference between parallel runs.
+- **Naming:** <FIXTURE_NAMING_RULE>
+- **Seed data:** <SEED_STRATEGY>
+- **Authentication:** <AUTH_STRATEGY>
+
+## Sweeper / cleanup
+
+E2E fixtures inevitably leave artifacts behind (created orgs,
+uploaded files, in-flight jobs). The sweeper:
+
+- **Cadence:** <SWEEPER_FREQUENCY>
+- **Purge criterion:** <PURGE_CRITERIA>
+- **Logs:** <SWEEPER_LOG_LOCATION>
+- **Dry-run mode:** <DRY_RUN_SWITCH>
+
+## Covered scenarios
+
+| ID     | Scenario                          | Category        | Linked spec          | Test file                  |
+|--------|-----------------------------------|-----------------|----------------------|----------------------------|
+| E2E-01 | <SCENARIO_1_NAME>                 | golden          | [[<SPEC_NAME_1>]]    | <TEST_FILE_PATH_1>         |
+| E2E-02 | <SCENARIO_2_NAME>                 | edge            | [[<SPEC_NAME_2>]]    | <TEST_FILE_PATH_2>         |
+| E2E-NN | <SCENARIO_N_NAME>                 | golden | edge   | [[<SPEC_NAME_N>]]    | <TEST_FILE_PATH_N>         |
+
+## Known gaps
+
+- <GAP_1> — <REASON> — <TRACKING_REF>
+- <GAP_N> — ...

package/dist/templates/handbook.md.tmpl

@@ -0,0 +1,58 @@
+---
+tracks:
+  - <RELEVANT_CODE_PATH_1>
+  - <RELEVANT_CODE_PATH_2>
+last_reviewed: <DATE>
+---
+
+# <FEATURE_NAME> — handbook
+
+## Overview
+
+Describe in one paragraph what this feature / module *actually* does
+in the code, as opposed to the spec, which describes *what we
+want*. Explicitly mention the files or directories involved.
+
+The `tracks:` frontmatter above lists the code files this
+handbook depends on. The `frontmatter-tracks` linter and the
+`drift-detector` skill rely on it to flag drifts.
+
+## How it works
+
+Explain the internals, cross-linking to the code
+files (`[<path/to/file.ext>](../../<path/to/file.ext>)`). Cover:
+
+- The main entry point and its contract.
+- The control or data flow through the modules listed
+  in `tracks:`.
+- The data structures / entities handled.
+- The implicit assumptions that are not visible in the spec.
+
+### <SUB_TOPIC_1>
+
+<DESCRIPTION_1>
+
+### <SUB_TOPIC_2>
+
+<DESCRIPTION_2>
+
+## How to use it
+
+If the feature exposes an API (function, endpoint, CLI), give a
+minimal invocation example. Mention the prerequisites (env
+variables, initial state, dependencies).
+
+```
+<USAGE_EXAMPLE>
+```
+
+## How to debug
+
+List the typical failures and their diagnosis.
+
+- **Symptom:** <SYMPTOM_1> — **Likely cause:** <CAUSE_1> —
+  **Fix:** <FIX_1>.
+- **Symptom:** <SYMPTOM_2> — ...
+
+Also mention: where to look at the logs, which flags to enable for
+verbose output, which tests reproduce the bug fastest.

package/dist/templates/integration-tests.md.tmpl

@@ -0,0 +1,50 @@
+---
+tracks:
+  - <TEST_DIR_OR_FILE_1>
+  - <TEST_DIR_OR_FILE_2>
+last_reviewed: <DATE>
+---
+
+# Integration test plan
+
+## Scope
+
+Define what is tested in integration **vs** unit **vs** e2e:
+
+- **Unit**: isolated, no real I/O, next to the code (`*.test.<ext>`).
+  Not documented here.
+- **Integration**: several modules assembled, real I/O against
+  local dependencies (ephemeral DB, service mocked at the network
+  level, temporary filesystem). This is the scope of this document.
+- **E2E**: complete system against real or staging dependencies,
+  walking through a user journey. Documented in
+  [e2e-tests.md](./e2e-tests.md).
+
+Specify here the boundaries specific to the current project.
+
+## Test stack
+
+- **Runner:** <TEST_RUNNER>
+- **Assertions:** <ASSERTION_LIB>
+- **Fixtures:** <FIXTURE_STRATEGY>
+- **Setup / teardown:** <SETUP_TEARDOWN>
+- **Data:** <DATA_STRATEGY>
+
+## Covered scenarios
+
+| ID    | Scenario                            | Linked spec             | Test file                          |
+|-------|-------------------------------------|-------------------------|------------------------------------|
+| IT-01 | <SCENARIO_1_NAME>                   | [[<SPEC_NAME_1>]]       | <TEST_FILE_PATH_1>                 |
+| IT-02 | <SCENARIO_2_NAME>                   | [[<SPEC_NAME_2>]]       | <TEST_FILE_PATH_2>                 |
+| IT-NN | <SCENARIO_N_NAME>                   | [[<SPEC_NAME_N>]]       | <TEST_FILE_PATH_N>                 |
+
+Each scenario must cross-link the spec it verifies (syntax
+`[[spec-name]]`) — the `cross-link` linter uses it.
+
+## Known gaps
+
+Explicitly list the areas not covered in integration, with a
+risk estimate and a pointer to the tracking ticket, if any.
+
+- <GAP_1> — risk <LOW | MEDIUM | HIGH> — <TRACKING_REF>
+- <GAP_N> — ...

package/dist/templates/readme.md.tmpl

@@ -0,0 +1,51 @@
+# <PROJECT_NAME>
+
+> <ONE_LINE_PITCH>
+
+## What is this
+
+<ONE_PARAGRAPH_DESCRIPTION>
+
+Describe in one paragraph what the project does, who it is for, and
+what its value proposition is. Stay factual; no marketing.
+
+## Quick start
+
+### Install
+
+```
+<INSTALL_COMMAND>
+```
+
+### Run
+
+```
+<RUN_COMMAND>
+```
+
+<OPTIONAL_FIRST_USE_EXAMPLE>
+
+## Documentation
+
+The project maintains six documentation pillars:
+
+- [Spec](docs/spec/) — theoretical vision: what we want.
+- [Decisions](docs/decisions/) — ADRs: what we decided and why.
+- [Handbook](docs/handbook/) — implementation docs: how it actually
+  works.
+- [Tests](docs/tests/) — test plans (integration + e2e).
+- [Workflow](docs/workflow/coding-workflow.md) — CI, env variants, PR
+  process, branches, release.
+- This README — entry point.
+
+## Contributing
+
+<CONTRIBUTING_POINTER>
+
+See [docs/workflow/coding-workflow.md](docs/workflow/coding-workflow.md)
+for the commit conventions, the branch model, and the release
+process.
+
+## License
+
+<LICENSE_NAME> — see [LICENSE](./LICENSE).

package/dist/templates/spec.md.tmpl

@@ -0,0 +1,64 @@
+# <SUBSYSTEM_NAME> — spec
+
+> **Status:** <DRAFT | REVIEW | STABLE>
+>
+> <ONE_PARAGRAPH_FRAMING>
+>
+> Describe in a few lines what this subsystem covers, why
+> it exists, and how it fits with the other pieces of the project.
+
+## 0. Vocabulary
+
+List the <N> keywords this subsystem reasons about. Define
+each one in one to three lines, without reference to any specific technology.
+
+| Term            | Definition                                                          |
+|-----------------|---------------------------------------------------------------------|
+| <TERM_1>        | <DEFINITION_1>                                                      |
+| <TERM_2>        | <DEFINITION_2>                                                      |
+| <TERM_N>        | <DEFINITION_N>                                                      |
+
+## 1. Vision
+
+Articulate in 3 to 7 points what this subsystem **must** be. Stay
+abstract — this is the "what", not the "how".
+
+1. <VISION_POINT_1>
+2. <VISION_POINT_2>
+3. <VISION_POINT_N>
+
+## 2. Out of scope
+
+Explicitly list what the subsystem does **not** do. This
+section is as important as the vision: it closes doors.
+
+- <NON_GOAL_1>
+- <NON_GOAL_2>
+- <NON_GOAL_N>
+
+## 3. Domain
+
+### 3.1 Entities
+
+List the main entities and their relationships. Stay at the
+conceptual level — no table schema, no function signature.
+
+### 3.2 Invariants
+
+List the properties that must hold true at all times.
+
+- <INVARIANT_1>
+- <INVARIANT_N>
+
+## 4. <FREE_SECTION_TITLE>
+
+Free sections for the rest of the spec: usage flows, conceptual
+interface contracts, acceptance criteria, etc.
+
+## N. Open decisions
+
+List the questions not yet settled, with a pointer to the ADR
+that will close them once they are.
+
+- <OPEN_QUESTION_1>
+- <OPEN_QUESTION_N>

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@vaubaan/harness",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.3.0",
+  "description": "Coding Agent Harness (CAH) — multi-engine skills + commands + linters for Vaubaan sandboxes",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "Vaubaan",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vaubaan/harness.git"
+  },
+  "homepage": "https://github.com/vaubaan/harness#readme",
+  "bugs": "https://github.com/vaubaan/harness/issues",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "vaubaan-harness": "./dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./render": {
+      "types": "./dist/render.d.ts",
+      "import": "./dist/render.js"
+    },
+    "./linters": {
+      "types": "./dist/linters/index.d.ts",
+      "import": "./dist/linters/index.js"
+    },
+    "./parser": {
+      "types": "./dist/parser/index.d.ts",
+      "import": "./dist/parser/index.js"
+    },
+    "./init": {
+      "types": "./dist/init.d.ts",
+      "import": "./dist/init.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"],
+  "scripts": {
+    "build": "tsup && node scripts/copy-content.mjs",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint:harness": "node dist/cli/index.js lint --cwd .",
+    "ci": "npm run typecheck && npm run lint && npm run test && npm run build && npm run lint:harness",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "cosmiconfig": "^9.0.2",
+    "fast-glob": "^3.3.2",
+    "gray-matter": "^4.0.3",
+    "yaml": "^2.5.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^22.7.5",
+    "@vitest/coverage-v8": "^2.1.2",
+    "execa": "^9.4.0",
+    "husky": "^9.1.7",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.2"
+  }
+}