@wazir-dev/cli 1.0.0

package/docs/readmes/packages/gray-matter.md

@@ -0,0 +1,116 @@
+# gray-matter
+
+> Parse front-matter from a string or file. Fast, reliable, and lightweight, with zero dependencies.
+
+[![npm version](https://img.shields.io/npm/v/gray-matter)](https://www.npmjs.com/package/gray-matter)
+[![license](https://img.shields.io/npm/l/gray-matter)](https://github.com/jonschlinkert/gray-matter/blob/master/LICENSE)
+[![downloads](https://img.shields.io/npm/dm/gray-matter)](https://www.npmjs.com/package/gray-matter)
+
+## What is gray-matter?
+
+gray-matter parses YAML, TOML, JSON, or custom front-matter from the top of Markdown and text files. Front-matter is the block of structured metadata between `---` delimiters at the start of a file, a convention popularized by static site generators like Jekyll and Hugo and now pervasive across developer tooling, documentation systems, and AI context files.
+
+When you call `matter(string)`, it returns two things: the `data` object (the parsed front-matter block) and the `content` string (everything after the closing delimiter). This clean separation lets consumers treat the same file as both structured configuration and prose documentation without any ambiguity about where one ends and the other begins.
+
+gray-matter handles edge cases that naive split-on-`---` approaches miss: files with no front-matter, files where the front-matter block contains literal `---` inside YAML block scalars, files starting with a BOM, and files using alternative delimiters like `+++` for TOML.
+
+## Why Wazir Uses gray-matter
+
+Wazir's skill files (`skills/*/SKILL.md`) are the canonical mechanism for delivering structured, in-context operating procedures to AI hosts. Each skill file combines two concerns in a single document:
+
+1. A YAML front-matter block declaring the skill's `name` and `description` — structured fields consumed by the skills registry and the `Skill` tool dispatcher.
+2. A Markdown body — the human- and AI-readable procedure that the agent follows when the skill is invoked.
+
+Keeping both in one file is intentional: it eliminates drift between "the metadata that describes the skill" and "the instructions the skill contains." gray-matter is the only reliable way to split those two parts back out programmatically.
+
+Every skill file in `skills/` follows this structure:
+
+```markdown
+---
+name: wz:tdd
+description: Enforces RED -> GREEN -> REFACTOR for implementation work
+---
+
+# TDD
+
+...prose instructions...
+```
+
+gray-matter parses that file and returns `{ data: { name: 'wz:tdd', description: '...' }, content: '# TDD\n\n...' }`.
+
+## How Wazir Uses It
+
+gray-matter is consumed by the skill validation and registry tooling that reads `skills/*/SKILL.md` files. The `data` fields are what the tooling checks against the skills registry — confirming that every declared skill has a matching file with the correct `name` field. The `content` is what gets served to the AI host at invocation time.
+
+A representative usage pattern from the Wazir tooling:
+
+```js
+import matter from 'gray-matter';
+import fs from 'node:fs';
+
+function loadSkill(skillPath) {
+  const raw = fs.readFileSync(skillPath, 'utf8');
+  const { data, content } = matter(raw);
+
+  return {
+    name: data.name,
+    description: data.description,
+    body: content.trim(),
+  };
+}
+```
+
+The `validate.test.js` test suite checks that skill files start with `---` (confirming front-matter presence) and that the `name` and `description` fields are present:
+
+```js
+test('design skill file exists and has frontmatter', () => {
+  const content = fs.readFileSync(skillPath, 'utf8');
+  assert.ok(content.startsWith('---'), 'missing YAML frontmatter');
+  assert.ok(content.includes('name: design'), 'missing name in frontmatter');
+  assert.ok(content.includes('description:'), 'missing description in frontmatter');
+});
+```
+
+## Key Concepts
+
+**Front-matter delimiters**: By default gray-matter expects `---` (YAML), but also supports `+++` (TOML) and `{` (JSON). Wazir uses YAML exclusively for skill front-matter.
+
+**`data` vs `content`**: `data` is the parsed front-matter object; `content` is the raw Markdown body after the closing delimiter. Both are available on every parse result.
+
+**`isEmpty`**: gray-matter returns `isEmpty: true` when no front-matter block is present. This is useful for validating that every skill file actually has metadata.
+
+**`stringify`**: gray-matter can serialize back to a front-matter string with `matter.stringify(content, data)`. This is useful for programmatic generation of skill files.
+
+**Custom engines**: gray-matter accepts a custom engine map so you can replace the default `js-yaml` parser with your own. Wazir does not use this — it relies on the default YAML engine.
+
+## API Reference (Wazir-relevant subset)
+
+| API | Usage in Wazir |
+|-----|---------------------|
+| `matter(string)` | Parse a raw skill file string into `{ data, content }` |
+| `result.data` | The front-matter fields: `name`, `description` |
+| `result.content` | The Markdown body delivered to the AI host |
+| `result.isEmpty` | Check whether a skill file is missing its front-matter block |
+| `matter.stringify(content, data)` | Serialize a skill body + metadata back to a single file |
+
+## Common Patterns
+
+**Single-file skill documents**: Store both skill metadata (for tooling) and skill instructions (for the AI host) in one `.md` file. Parse with gray-matter to separate them without duplicating content across files.
+
+**Front-matter validation gate**: After parsing, immediately validate that `data.name` and `data.description` are present and non-empty before accepting the file as a valid skill. Fail loudly on malformed skills rather than silently serving incomplete ones.
+
+**Round-trip generation**: When programmatically generating or updating skill files, use `matter.stringify` to ensure the front-matter block is always correctly formatted rather than manually constructing `---\nkey: value\n---`.
+
+## Alternatives Considered
+
+| Package | Why not chosen |
+|---------|---------------|
+| `front-matter` | Older, YAML-only, less actively maintained |
+| Manual `split('---')` | Fragile — breaks on `---` inside YAML block scalars, BOMs, and empty files |
+| `vfile` + `remark-frontmatter` | Full remark pipeline is overkill for reading a single structured field |
+| `yaml` alone | Cannot split front-matter from body — requires manual parsing of delimiters |
+
+## Resources
+
+- [GitHub](https://github.com/jonschlinkert/gray-matter)
+- [npm](https://www.npmjs.com/package/gray-matter)

package/docs/readmes/packages/node-test.md

@@ -0,0 +1,137 @@
+# node:test
+
+> The built-in test runner shipped with Node.js since v18, providing `describe`, `test`, and `assert` without any external dependencies.
+
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-green)](https://nodejs.org/api/test.html)
+[![Built-in](https://img.shields.io/badge/built--in-no%20install-blue)]()
+
+## What is node:test?
+
+`node:test` is the test runner built directly into Node.js. It was stabilized in Node.js v18 and provides the same structural primitives that Jest and Mocha users expect — `describe` for grouping, `test` for individual cases, `before`/`after` lifecycle hooks — but ships as part of the Node.js standard library with zero npm dependencies.
+
+Tests are run by invoking `node --test <file>...` directly. Node discovers test files, runs them in parallel by default, and reports results in TAP (Test Anything Protocol) format or as human-readable output depending on the `--reporter` flag. There is no config file, no plugin system to configure, and no babel/esbuild transform pipeline — it runs your files exactly as Node would run any other module.
+
+`node:assert` (also a built-in) provides the assertion library. The key methods are `assert.strictEqual`, `assert.deepStrictEqual`, `assert.match` (regex matching), `assert.ok`, `assert.throws`, and `assert.doesNotMatch`. These cover virtually every assertion Wazir's test suite requires.
+
+## Why Wazir Uses node:test
+
+Wazir is a CLI tooling package with a `"type": "module"` ESM codebase. The team chose `node:test` deliberately rather than defaulting to Jest or Vitest:
+
+1. **Zero dependencies**: Wazir's `package.json` has exactly three runtime dependencies (ajv, gray-matter, yaml). A test runner adds only dev-time weight at best, but `node:test` adds nothing at all — not even a dev dependency. This keeps the package surface minimal and install times fast.
+
+2. **No transform layer**: Jest requires either Babel or `--experimental-vm-modules` to work with ESM. Vitest handles ESM natively but bundles an entire Vite pipeline. `node --test` runs Wazir's ESM source files directly, exactly as `node src/cli.js` would. There is no separate build step, no source map configuration, and no module resolution differences between test and production.
+
+3. **Built-in with the platform**: Wazir targets developers who already have Node.js. There is nothing to install, no version pinning to manage, and no possibility of the test runner becoming incompatible with a future Node.js release while the production code works fine.
+
+4. **Sufficient API surface**: Wazir's tests are integration-style CLI tests and unit tests for pure functions. The `describe`/`test`/`assert` surface is everything needed. Mocking, snapshot testing, and parallel async test suites are not required.
+
+## How Wazir Uses It
+
+Every test file in `tooling/test/` imports from `node:test` and `node:assert`:
+
+```js
+import { describe, test } from 'node:test';
+import assert from 'node:assert';
+```
+
+Tests are organized with `describe` blocks grouping related scenarios, and `test` for individual assertions:
+
+```js
+describe('wazir validate command', () => {
+  test('validates the manifest from a nested working directory', () => {
+    const result = runCli(['validate', 'manifest'], {
+      cwd: path.join(ROOT, 'tooling'),
+    });
+
+    assert.strictEqual(result.exitCode, 0);
+    assert.match(result.stdout, /manifest is valid/i);
+  });
+
+  test('rejects manifest_version 1 with targeted migration guidance', () => {
+    // ...
+    assert.strictEqual(result.exitCode, 1);
+    assert.match(result.stderr, /manifest_version 1 is no longer supported/i);
+    assert.match(result.stderr, /migrate to manifest_version 2/i);
+  });
+});
+```
+
+The `package.json` test script runs all active test files in a single `node --test` invocation:
+
+```json
+"test:active": "node --test tooling/test/cli.test.js tooling/test/validate.test.js tooling/test/index.test.js tooling/test/doctor-status.test.js tooling/test/guard-hooks.test.js tooling/test/export.test.js tooling/test/capture.test.js tooling/test/schema-examples.test.js tooling/test/git-flow-docs.test.js tooling/test/role-contracts.test.js tooling/test/ci-workflow.test.js"
+```
+
+Integration tests use `execFileSync` to spawn the CLI as a child process and verify its stdout, stderr, and exit code — a common pattern across all test files:
+
+```js
+function runCli(args, options = {}) {
+  try {
+    const stdout = execFileSync('node', [CLI_PATH, ...args], {
+      encoding: 'utf8',
+      cwd: options.cwd ?? ROOT,
+    });
+    return { exitCode: 0, stdout, stderr: '' };
+  } catch (error) {
+    return {
+      exitCode: error.status ?? 1,
+      stdout: error.stdout ?? '',
+      stderr: error.stderr ?? '',
+    };
+  }
+}
+```
+
+Fixture setup and teardown use `try/finally` blocks because `node:test` does not have an `afterEach` that runs on failure unless you use the full lifecycle hooks API. The `finally` block ensures `fs.rmSync` always cleans up temp directories even when assertions throw.
+
+## Key Concepts
+
+**`node --test`**: The CLI entry point. Pass one or more file paths explicitly. Node runs each file and aggregates results. Exits with code `0` on all-pass, non-zero on any failure.
+
+**`describe`**: A grouping block. Tests inside a `describe` share a label prefix in the output. Nesting is supported.
+
+**`test`**: An individual test case. Receives a callback. Passes if the callback returns without throwing; fails if an assertion throws an `AssertionError` or any other error is thrown.
+
+**`assert.strictEqual(actual, expected)`**: Uses `===` comparison. This is distinct from `assert.equal`, which uses `==`. Wazir always uses `strictEqual`.
+
+**`assert.match(string, regexp)`**: Passes if the string matches the regex. Used heavily for CLI output assertions where exact text is not required but a pattern must appear.
+
+**`assert.deepStrictEqual(actual, expected)`**: Recursively compares objects and arrays with `===` semantics for primitives. Used for structured output assertions like JSON payloads.
+
+## API Reference (Wazir-relevant subset)
+
+| API | Usage in Wazir |
+|-----|---------------------|
+| `describe(label, fn)` | Groups related tests in every test file |
+| `test(label, fn)` | Every individual test case |
+| `assert.strictEqual(a, b)` | Exit code checks, string equality |
+| `assert.match(str, re)` | CLI stdout/stderr pattern matching |
+| `assert.deepStrictEqual(a, b)` | JSON output structure assertions |
+| `assert.ok(value, msg)` | Boolean truthy assertions with a message |
+| `assert.throws(fn, re)` | Error-throwing assertions in `export.test.js` |
+| `assert.doesNotMatch(str, re)` | Negative pattern assertions |
+
+## Common Patterns
+
+**CLI integration tests via `execFileSync`**: Spawn the real CLI binary, capture stdout/stderr, assert on exit code and output text. This tests the full system including argument parsing, file I/O, and error formatting — not just individual functions.
+
+**Temp fixture directories**: Use `fs.mkdtempSync` to create isolated project roots per test, populate them with the minimal required files, run the CLI against them, and clean up with `fs.rmSync` in a `finally` block.
+
+**`try/finally` cleanup**: Because `node:test` does not run `afterEach` on assertion failures without explicit lifecycle hook usage, wrap each fixture test in `try { ... } finally { fs.rmSync(...) }`.
+
+**`assert.match` for CLI output**: Prefer regex over exact string comparison for CLI messages. Messages evolve; patterns are stable.
+
+## Alternatives Considered
+
+| Package | Why not chosen |
+|---------|---------------|
+| Jest | Requires Babel or `--experimental-vm-modules` for ESM; heavy dependency tree |
+| Vitest | Excellent ESM support but bundles Vite, adding significant install weight |
+| Mocha + Chai | Two packages instead of zero; needs ESM configuration |
+| tap | TAP-native but external; `node:test` outputs TAP natively anyway |
+
+## Resources
+
+- [Node.js test runner documentation](https://nodejs.org/api/test.html)
+- [Node.js assert documentation](https://nodejs.org/api/assert.html)
+- [Node.js blog: built-in test runner](https://nodejs.org/en/blog/announcements/v18-release-announce)

package/docs/readmes/packages/yaml.md

@@ -0,0 +1,112 @@
+# yaml
+
+> A fully-featured YAML 1.2 parser and serializer for JavaScript, with support for all YAML types, custom tags, and streaming.
+
+[![npm version](https://img.shields.io/npm/v/yaml)](https://www.npmjs.com/package/yaml)
+[![license](https://img.shields.io/npm/l/yaml)](https://github.com/eemeli/yaml/blob/main/LICENSE)
+[![downloads](https://img.shields.io/npm/dm/yaml)](https://www.npmjs.com/package/yaml)
+
+## What is yaml?
+
+The `yaml` package (published by Eemeli Aro) is the most complete YAML 1.2 implementation in JavaScript. It goes beyond the YAML 1.1 subset that many older parsers handle and correctly implements the full 1.2 specification — including proper boolean handling (`true`/`false` only, not `yes`/`no`), correct integer/float parsing, null semantics, and multi-document streams.
+
+Unlike `js-yaml`, the `yaml` package provides a full document object model (DOM): you can parse YAML into an AST, inspect and modify nodes, and then serialize back to YAML while preserving comments, formatting hints, and custom tags. For Wazir's use case — reading manifest and hook definition files — only the `YAML.parse()` surface is needed, but the underlying fidelity of the parser matters for correctness.
+
+The package is ESM-native, ships with TypeScript types, and has zero runtime dependencies, making it appropriate for a lean CLI tool like Wazir that must install and run quickly.
+
+## Why Wazir Uses yaml
+
+Wazir's primary configuration artifact is `wazir.manifest.yaml` — a YAML file declaring the project's hosts, workflows, phases, roles, protected paths, and adapter configuration. Every validation, export, and status command starts by reading this file with `YAML.parse()`.
+
+The `yaml` package was chosen over alternatives for these reasons:
+
+1. **YAML 1.2 compliance**: `wazir.manifest.yaml` uses plain YAML 1.2 constructs without `yes`/`no` booleans or YAML 1.1 edge cases, but having a parser that correctly handles the spec avoids subtle future bugs as schemas evolve.
+2. **ESM native**: Wazir's `package.json` declares `"type": "module"`, which means all imports are ESM. The `yaml` package ships a proper ESM entry point (`import YAML from 'yaml'`). `js-yaml` requires an additional import path dance in ESM contexts.
+3. **Clear error messages**: When `YAML.parse()` encounters a malformed file, it throws a `YAMLParseError` with a line/column pointer and an excerpt of the offending content — far more actionable than `js-yaml`'s generic messages.
+4. **Actively maintained**: The package receives regular updates and the maintainer is responsive to spec compliance issues.
+
+## How Wazir Uses It
+
+All YAML file reading is consolidated in a single loader function:
+
+```js
+// tooling/src/loaders.js
+import YAML from 'yaml';
+import fs from 'node:fs';
+
+export function readYamlFile(filePath) {
+  return YAML.parse(fs.readFileSync(filePath, 'utf8'));
+}
+```
+
+This function is imported by every module that needs to read YAML:
+
+- `tooling/src/commands/validate.js` — reads `wazir.manifest.yaml` and all hook definition files in `hooks/definitions/*.yaml`
+- `tooling/src/export/compiler.js` — reads `wazir.manifest.yaml` to drive the host export build
+- `tooling/test/validate.test.js` and `tooling/test/schema-examples.test.js` — read YAML example templates to validate against schemas
+
+The `listYamlFiles` helper in `loaders.js` pairs with `readYamlFile` to enumerate and read entire directories of YAML files:
+
+```js
+export function listYamlFiles(dirPath) {
+  return fs.readdirSync(dirPath)
+    .filter((entry) => entry.endsWith('.yaml') || entry.endsWith('.yml'))
+    .sort()
+    .map((entry) => path.join(dirPath, entry));
+}
+```
+
+Hook definition files (`hooks/definitions/*.yaml`) are loaded this way — the validator enumerates all files, reads each with `readYamlFile`, then validates each against the hook JSON Schema.
+
+In the test suite, the YAML example template for the manifest is read and validated end-to-end:
+
+```js
+// tooling/test/schema-examples.test.js
+['templates/examples/wazir-manifest.example.yaml', 'schemas/wazir-manifest.schema.json', 'yaml'],
+// ...
+function loadExample(examplePath, kind) {
+  return kind === 'yaml' ? readYamlFile(absolutePath) : readJsonFile(absolutePath);
+}
+```
+
+## Key Concepts
+
+**`YAML.parse(string)`**: The primary API. Parses a YAML string and returns a plain JavaScript value (object, array, string, number, boolean, or null). Throws `YAMLParseError` on invalid input.
+
+**`YAML.stringify(value)`**: Serializes a JavaScript value to a YAML string. Wazir does not currently use this, but it is the correct way to write YAML programmatically.
+
+**YAML 1.2 vs 1.1**: The critical difference is boolean parsing. YAML 1.1 treats `yes`, `no`, `on`, `off` as booleans; YAML 1.2 does not. Wazir schemas use explicit `true`/`false` to stay 1.2-safe.
+
+**Document object model**: `YAML.parseDocument()` returns a `Document` node with full AST access, preserving comments. Wazir does not need this — `YAML.parse()` returning a plain object is sufficient.
+
+## API Reference (Wazir-relevant subset)
+
+| API | Usage in Wazir |
+|-----|---------------------|
+| `YAML.parse(string)` | Reads every `.yaml` file in the tooling — manifests, hooks, example templates |
+| `YAML.stringify(value)` | Not currently used; available for future YAML generation |
+| `YAMLParseError` | Thrown on malformed YAML; surfaces file path and line number in error messages |
+
+## Common Patterns
+
+**Centralized loader**: Never call `YAML.parse()` directly in feature modules. Keep it in `loaders.js` so that error handling, encoding, and the import can be changed in one place.
+
+**Parse-then-validate**: Wazir always passes the result of `readYamlFile()` immediately to `validateAgainstSchema()`. YAML parsing catches syntax errors; JSON Schema validation catches semantic errors. These are two distinct failure modes.
+
+**Consistent file sorting**: `listYamlFiles` sorts file names before returning them. This ensures that validation and export produce deterministic results regardless of filesystem ordering, which matters for reproducible builds and test stability.
+
+## Alternatives Considered
+
+| Package | Why not chosen |
+|---------|---------------|
+| `js-yaml` | YAML 1.1 only, requires import path workaround in strict ESM, less clear parse errors |
+| `yamljs` | Abandoned, YAML 1.1, known compliance bugs |
+| `@humanwhocodes/momoa` | JSON/JSONC only, not YAML |
+| Inline `JSON.parse` with `.yaml` extension | Not YAML — Wazir configs use YAML intentionally for readability |
+
+## Resources
+
+- [Official documentation](https://eemeli.org/yaml/)
+- [GitHub](https://github.com/eemeli/yaml)
+- [npm](https://www.npmjs.com/package/yaml)
+- [YAML 1.2 specification](https://yaml.org/spec/1.2.2/)

package/docs/reference/configuration-reference.md

@@ -0,0 +1,159 @@
+# Configuration Reference
+
+Wazir configuration currently starts from the canonical manifest:
+
+- `wazir.manifest.yaml`
+
+That manifest is the source of truth for:
+
+- project identity
+- project description and versioning policy
+- canonical repo paths
+- supported hosts
+- canonical workflows and export targets
+- phase and role rosters
+- required hooks
+- protected paths
+- brand-term enforcement for active surfaces
+- optional adapters
+- validation checks
+
+## Path policy
+
+Repo-managed canonical paths live in the repository:
+
+- `input/`
+- `roles/`
+- `workflows/`
+- `skills/`
+- `hooks/`
+- `templates/`
+- `schemas/`
+- `expertise/`
+- `docs/`
+- `exports/`
+- `tooling/`
+- `memory/`
+- `examples/`
+
+The default external run-state root is declared in the manifest as:
+
+- `~/.wazir/projects/{project_slug}`
+
+That path is intentionally outside the repo so normal runs do not dirty adopters' worktrees.
+
+Indexing and recall commands also accept:
+
+- `--state-root <path>`
+
+Use that override for tests, CI fixtures, or operators who need the index somewhere else.
+
+The status command uses the same state-root resolution rules when reading run-local status files.
+
+## Protected paths
+
+The current protected path roster is declared in `wazir.manifest.yaml`:
+
+- `input`
+- `roles`
+- `workflows`
+- `schemas`
+- `exports/hosts`
+
+These paths are reserved for canonical source material or generated host exports and should not be rewritten by ad hoc task output.
+
+Generated host packages live under:
+
+- `exports/hosts/claude`
+- `exports/hosts/codex`
+- `exports/hosts/gemini`
+- `exports/hosts/cursor`
+
+## Dependency policy
+
+The active CLI keeps runtime dependencies small and explicit:
+
+- `ajv` for JSON Schema enforcement
+- `yaml` for canonical manifest and hook parsing
+- `gray-matter` for frontmatter parsing in library tests
+
+Policy:
+
+- prefer built-in Node APIs unless a library meaningfully reduces correctness risk
+- allow small parsing and schema-validation libraries
+- do not add framework, server, or web-stack dependencies to the product surface
+- keep optional adapter integrations external by default
+
+## Adapter policy
+
+The manifest currently declares one optional adapter:
+
+- `context_mode`
+
+It is:
+
+- disabled by default
+- optional
+- external-install mode
+
+Wazir must remain useful without the adapter present.
+
+## Versioning and naming guardrails
+
+The manifest also records:
+
+- a versioning policy for the active pre-`1.0` line
+- export targets for each supported host
+- brand-term enforcement rules for active surfaces
+- `manifest_version`, currently `2`, for breaking manifest contract changes
+
+Those fields exist to keep the active repo aligned with the Wazir product identity.
+
+The required manifest fields are:
+
+- `project.description`
+- `versioning_policy`
+- `workflows`
+- `export_targets`
+- `prohibited_terms`
+
+Current enforcement scope:
+
+- manifest-declared role files under `roles/`
+- manifest-declared workflow files under `workflows/`
+
+That scope is intentional. The manifest check is a canonical-surface guard for active operating-model content, not a blanket full-repo grep.
+
+Out of scope for this manifest check:
+
+- undeclared helper scripts
+- undeclared config files
+- scratch files
+- generated run artifacts
+
+Maintainers are responsible for policing those surfaces with the separate docs-truth, runtime-surface, and repository review checks.
+
+## Workflows vs phases
+
+- `phases` are the core lifecycle states of the operating model.
+- `workflows` are the canonical callable or review-gated entrypoints that drive those phases.
+
+They overlap heavily, but they are not identical:
+
+- `spec_challenge`, `plan_review`, and `prepare_next` are workflows that sit between or around the core execution phases.
+- Validators and exports should treat manifest-declared workflows as the canonical workflow file roster.
+
+## Current index parser roster
+
+The active manifest currently declares built-in heuristic extractors for:
+
+- JavaScript
+- TypeScript
+- Python
+- Go
+- Rust
+- Java
+- SQL
+- JSON
+- YAML
+- Markdown

package/docs/reference/expertise-index.md

@@ -0,0 +1,52 @@
+# Expertise Index
+
+This reference documents the expertise module system and anti-pattern catalog.
+
+## Metadata
+
+Top-level expertise metadata lives in:
+
+- `expertise/index.yaml`
+
+That index records domain, use cases, review applicability, and freshness date so loading can stay scoped instead of brute-force.
+
+## Module locations
+
+- Domain expertise modules: `expertise/` (organized by domain subdirectory)
+- Anti-pattern modules: `expertise/antipatterns/`
+- Research source material: `docs/research/`
+
+## Loading policy
+
+| Phase | Loads from |
+|-------|-----------|
+| `clarify`, `discover` | `input/`, active docs, `docs/research/` |
+| `specify`, `plan` | Relevant expertise slices based on stack and risks |
+| `review` | `expertise/antipatterns/` first, then broader domain modules |
+| `learn` | Can propose updates to expertise (not silently rewrite) |
+
+## Anti-pattern catalog
+
+The `expertise/antipatterns/` directory contains modules that catch:
+
+- **Fake completion** — claiming done without evidence
+- **Unwired abstractions** — interfaces defined but never connected
+- **Shallow tests** — tests that pass without exercising real behavior
+- **Security theater** — security measures that look good but do not protect
+- **Architecture drift** — implementation diverging from documented architecture
+- **AI-coding failure modes** — patterns specific to LLM-generated code
+
+## Humanize domain
+
+The `expertise/humanize/` domain provides AI text pattern detection and removal. It contains 7 modules: vocabulary blacklist (61 items), sentence patterns (24-pattern taxonomy), domain-specific rules for technical docs, code artifacts, and user-facing content, and a two-pass self-audit checklist.
+
+**Loading policy:** Loads for `specify`, `plan`, `execute`, `author`, `review`, and `learn` phases -- broader than most domains because all text-producing roles generate content that benefits from humanization. Loaded via the `humanize` concern in `expertise/composition-map.yaml` with role-specific module selection.
+
+## Rules
+
+- Expertise modules must be scoped by domain and use case
+- Anti-patterns are always loaded before domain modules during review
+- The composition engine enforces a maximum of 15 modules per dispatch
+- Token budget is enforced per dispatch
+
+For conceptual understanding of how the composition engine works, see [Composition Engine](../concepts/composition-engine.md).

package/docs/reference/git-flow.md

@@ -0,0 +1,43 @@
+# Git-Flow Policy
+
+This document defines the branching model, merge discipline, and changelog rules for the Wazir project.
+
+## Branching Model
+
+| Branch | Pattern | Created From | Merges To | Protected |
+|--------|---------|-------------|-----------|-----------|
+| Main | `main` | — | — | Yes |
+| Develop | `develop` | `main` (once) | — | Yes |
+| Feature | `feat/<slug>` or `feature/<slug>` | `develop` | `develop` | No |
+| Codex | `codex/<slug>` | `develop` | `develop` | No |
+| Release | `release/<version>` | `develop` | `main` + `develop` | No |
+| Hotfix | `hotfix/<slug>` | `main` | `main` + `develop` | No |
+
+## Merge Rules
+
+- All merges to `develop` and `main` use `--no-ff` to preserve merge commits
+- Merges happen only after the full Executor, Verifier, Reviewer gate passes
+- No role performs the merge — it is a post-review integration step
+
+## Conventional Commits
+
+All commit messages must follow the conventional commits specification:
+
+```
+<type>(<optional scope>): <description>
+```
+
+Allowed types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `ci`, `perf`, `build`
+
+## Changelog Rules
+
+- Format: Keep a Changelog (keepachangelog.com)
+- Every user-facing change must have an entry under `[Unreleased]`
+- Valid categories: Added, Changed, Deprecated, Removed, Fixed, Security
+- The executor updates the changelog; the verifier validates it; the reviewer flags quality issues
+
+## Enforcement
+
+- **Tooling:** `wazir validate branches`, `wazir validate commits`, `wazir validate changelog`
+- **CI:** All three validators run on pull requests; `--require-entries` blocks feature/codex/hotfix branches without changelog entries
+- **Roles:** Each role has documented git-flow responsibilities in its contract