Harness Release Readiness

# Harness Release Readiness

> Audit, fix, and track your project's path to a publishable release. No release without a passing report.

## When to Use

- Before publishing packages to npm — audit readiness and fix gaps
- At milestone boundaries — check progress toward release (fires on `on_milestone` trigger)
- When resuming release prep after a previous session — loads state and shows what changed
- NOT for actually performing the release (that is CI/CD — Changesets, GitHub Actions, etc.)
- NOT for non-npm targets (Docker, PyPI, etc.) — this skill is npm-focused
- NOT when the project has no packages to publish (use harness-verification for general health)

## Arguments

- **`--comprehensive`** — Run additional checks beyond the standard set: API doc coverage, example project validation, dependency health audit, and git hygiene scan. These checks are slower and may require network access (e.g., `npm audit`). Omit for a fast standard audit.

## Process

### Iron Law

**No release may be performed without a passing release readiness report.**

If the report shows failures, the project is not ready. Fix the failures first. A "mostly passing" report is not a passing report — every failure is a risk that lands on your users.

---

### Phase 1: AUDIT — Release-Specific Checks

#### Session Resumption

Before running checks, look for existing state:

1. Read `.harness/release-readiness.json`. If it exists, this is a resumption.
2. Display a delta summary:

   ```
   Release Readiness — resuming from <timestamp>

   Since last run:
     ✓ N items fixed (<list>)
     → N items remaining (<list>)

   Re-running full audit...
   ```

3. If no state file exists, this is a fresh run. Proceed directly to checks.

#### Project Type Detection

Before running any checks, verify this is an npm project:

1. Check whether `package.json` exists at the project root.
2. If `package.json` does **not** exist, exit immediately with:

   ```
   This project does not appear to be an npm project (no package.json found).
   /harness:release-readiness is npm-focused and cannot audit this project type.

   For general project health, use: /harness:verification
   ```

3. If `package.json` exists, continue to Monorepo Detection.

#### Monorepo Detection

Detect whether the project is a monorepo:

1. Check for `packages/*/package.json` or a `workspaces` field in root `package.json`.
2. If monorepo: collect all non-private packages. Run packaging checks against each independently. Run shared checks (docs, repo hygiene, CI/CD) once at the root.
3. If single package: run all checks against the root `package.json`.

#### Standard Checks (always run)

Run every check below. Record each as **pass**, **warn**, or **fail**:

- **pass** — check satisfied, no action needed
- **warn** — not blocking but should be addressed before release (e.g., missing optional field)
- **fail** — must be fixed before release

##### Packaging (per package)

| Check                                                                                | Severity if missing |
| ------------------------------------------------------------------------------------ | ------------------- |
| `name` field exists and is scoped (`@org/name`) or valid unscoped name               | fail                |
| `version` field exists and is valid semver                                           | fail                |
| `license` field exists                                                               | fail                |
| `exports` or `main` field exists (entry point is defined)                            | fail                |
| `files` field exists (controls what gets published)                                  | fail                |
| `publishConfig` field exists with `access: "public"` (for scoped packages)           | warn                |
| `repository` field exists with valid URL                                             | warn                |
| `bugs` field exists                                                                  | warn                |
| `homepage` field exists                                                              | warn                |
| `description` field exists                                                           | warn                |
| Build succeeds: run the project's build command                                      | fail                |
| Typecheck passes: run the project's typecheck command (e.g., `pnpm typecheck`)       | fail                |
| Tests pass: run the project's test command (e.g., `pnpm test`)                       | fail                |
| `pnpm pack --dry-run` produces expected files (no test files, no src if dist exists) | warn                |

##### Documentation (root level)

| Check                                                                                                             | Severity if missing |
| ----------------------------------------------------------------------------------------------------------------- | ------------------- |
| `README.md` exists                                                                                                | fail                |
| README contains an install/quickstart section (search for `install`, `getting started`, `quickstart`, or `npm i`) | warn                |
| README contains a usage or API section                                                                            | warn                |
| `CHANGELOG.md` exists                                                                                             | fail                |
| CHANGELOG has at least one entry (not empty or template-only)                                                     | warn                |
| `LICENSE` file exists                                                                                             | fail                |

##### Repo Hygiene (root level)

| Check                                                                                       | Severity if missing |
| ------------------------------------------------------------------------------------------- | ------------------- |
| `CONTRIBUTING.md` exists                                                                    | warn                |
| `CODE_OF_CONDUCT.md` exists                                                                 | warn                |
| `SECURITY.md` exists                                                                        | warn                |
| `.gitignore` exists and covers `node_modules`, `dist`, `.env`                               | fail                |
| No `TODO` or `FIXME` in published source files (files matching each package's `files` glob) | warn                |

##### CI/CD (root level)

| Check                                                           | Severity if missing |
| --------------------------------------------------------------- | ------------------- |
| CI workflow file exists (`.github/workflows/ci.yml` or similar) | fail                |
| Release/publish workflow file exists                            | warn                |
| `test` script exists in root `package.json`                     | fail                |
| `lint` script exists in root `package.json`                     | fail                |
| `typecheck` or `tsc` script exists in root `package.json`       | fail                |
| `assess_project` passes (full harness CI gate)                  | fail                |

For the `assess_project` check, run it with all harness-specific checks including lint:

```json
assess_project({
  path: "<project-root>",
  checks: ["validate", "deps", "docs", "lint", "perf", "security", "entropy", "arch"],
  mode: "detailed"
})
```

If `healthy: false`, each failing check in the `checks` array maps to a separate finding with its `topIssue`. This replaces running `harness validate`, `harness check-deps`, and lint as separate commands.

##### i18n Coverage (conditional)

When `i18n.enabled: true` in `harness.config.json`, run these checks:

| Check                                                                                          | Severity if failing             |
| ---------------------------------------------------------------------------------------------- | ------------------------------- |
| Translation coverage meets `i18n.coverage.minimumPercent` for all target locales               | fail (strict) / warn (standard) |
| No untranslated values (source text in target locale files) when `coverage.detectUntranslated` | warn                            |
| All CLDR plural forms present for target locales when `coverage.requirePlurals`                | warn                            |
| No stale translations (source changed since last translation timestamp)                        | warn                            |
| `harness-i18n` scan passes with zero errors                                                    | fail (strict) / warn (standard) |

If `i18n.enabled` is false or the `i18n` config block is absent, skip this section entirely and report it as "N/A" in the audit output.

#### Comprehensive Checks (only with `--comprehensive`)

These checks run only when `--comprehensive` is passed. They are slower and may require network access.

##### API Documentation

| Check                                                         | Severity if missing |
| ------------------------------------------------------------- | ------------------- |
| Exported functions/classes/types have JSDoc or TSDoc comments | warn                |
| Coverage threshold: >80% of exports documented                | warn                |

To check: for each package, read the main entry point (`exports` or `main`), find all `export` statements, and verify each has a preceding doc comment (`/** ... */`).

##### Examples

| Check                                                                                  | Severity if missing |
| -------------------------------------------------------------------------------------- | ------------------- |
| Example projects exist (in `examples/` directory)                                      | warn                |
| Each example's `package.json` references workspace packages at current versions        | warn                |
| Each example builds successfully: `cd examples/<name> && npm install && npm run build` | fail                |

##### Dependency Health

| Check                                                                  | Severity if missing |
| ---------------------------------------------------------------------- | ------------------- |
| `npm audit` reports no high or critical vulnerabilities                | fail                |
| No deprecated dependencies (check `npm outdated` for deprecated flags) | warn                |

##### Git Hygiene

| Check                                                                                                               | Severity if missing |
| ------------------------------------------------------------------------------------------------------------------- | ------------------- |
| No binary files >1MB tracked in git (check with `git ls-files`)                                                     | warn                |
| `.gitignore` covers common artifacts: `.env`, `.DS_Store`, `*.log`, `coverage/`                                     | warn                |
| No secrets detected in tracked files (search for patterns: `API_KEY=`, `SECRET=`, `PASSWORD=`, private key headers) | fail                |

#### Output

After all checks complete, produce a structured summary for the next phases:

```
AUDIT COMPLETE

Packaging:  8/12 passed, 2 warnings, 2 failures
Docs:       5/6 passed, 1 warning, 0 failures
Hygiene:    3/5 passed, 2 warnings, 0 failures
CI/CD:      4/5 passed, 1 warning, 0 failures
i18n:       N/N passed, N warnings, N failures (or: skipped — i18n not enabled)
[comprehensive] API Docs:  skipped (use --comprehensive)
[comprehensive] Examples:  skipped (use --comprehensive)
[comprehensive] Dep Health: skipped (use --comprehensive)
[comprehensive] Git Hygiene: skipped (use --comprehensive)

Total: 20/28 passed, 6 warnings, 2 failures
```

Proceed to Phase 2: MAINTAIN.

---

### Phase 2: MAINTAIN — Parallel Maintenance Skill Dispatch

Run existing maintenance skills to catch issues that release-specific checks do not cover. These skills are independent of each other and should be dispatched in parallel.

#### Dispatch

Launch 4 agents concurrently using the Agent tool. Each agent runs one maintenance skill against the project root:

| Agent | Skill                           | Purpose                                                         |
| ----- | ------------------------------- | --------------------------------------------------------------- |
| 1     | `/harness:detect-doc-drift`     | Find documentation that has fallen out of sync with code        |
| 2     | `/harness:cleanup-dead-code`    | Find unused exports, imports, and files                         |
| 3     | `/harness:enforce-architecture` | Validate layer boundaries and dependency rules                  |
| 4     | `/harness:diagnostics`          | Classify any existing errors and route to resolution strategies |

Example dispatch (Claude Code):

```
Use the Agent tool to launch 4 agents in parallel:

Agent 1: "Run /harness:detect-doc-drift on this project and return findings as a structured list"
Agent 2: "Run /harness:cleanup-dead-code on this project and return findings as a structured list"
Agent 3: "Run /harness:enforce-architecture on this project and return findings as a structured list"
Agent 4: "Run /harness:diagnostics on this project and return findings as a structured list"
```

#### Result Collection

Wait for all agents to complete. Set a 2-minute timeout per agent — if an agent exceeds this, treat it as failed. For each agent:

1. If the agent succeeded: extract its findings as a list of issues with file paths and descriptions.
2. If the agent failed (error, timeout, or exceeded 2-minute limit): log the failure reason and continue. A failed maintenance check does not block the release readiness report — it is reported as "unavailable" in the final report.

#### Merge

Combine findings from all maintenance skills into a unified structure:

```
MAINTENANCE RESULTS

Doc Drift:     2 issues found
  - docs/api/index.md references removed function `parseConfig`
  - docs/guides/getting-started.md version number outdated (0.7.0 → 0.8.0)

Dead Code:     0 issues found (clean)

Architecture:  0 violations found (clean)

Diagnostics:   1 warning
  - TypeScript strict mode warning in packages/cli/src/init.ts:42
```

Carry these results forward to Phase 3 (FIX) and Phase 4 (REPORT).

---

### Phase 3: FIX — Auto-Remediation

Review all findings from Phase 1 (AUDIT) and Phase 2 (MAINTAIN). For each fixable finding, offer to apply a fix. Non-fixable findings are listed with remediation guidance for the human.

#### Fixable Findings

| Finding                                      | Auto-Fix                                                                                         |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Missing `publishConfig` in package.json      | Add `"publishConfig": { "access": "public" }`                                                    |
| Missing `repository` field in package.json   | Add `"repository": { "type": "git", "url": "<detected from git remote>" }`                       |
| Missing `bugs` field in package.json         | Add `"bugs": { "url": "<repository>/issues" }`                                                   |
| Missing `homepage` field in package.json     | Add `"homepage": "<repository>#readme"`                                                          |
| Missing `description` field in package.json  | Add `"description": ""` with a TODO comment for the human to fill in                             |
| Missing `files` field in package.json        | Add `"files": ["dist"]` (or `["dist", "src"]` if no build step)                                  |
| Missing `CONTRIBUTING.md`                    | Generate from template with standard sections (how to contribute, development setup, PR process) |
| Missing `CODE_OF_CONDUCT.md`                 | Generate Contributor Covenant v2.1                                                               |
| Missing `SECURITY.md`                        | Generate template with vulnerability reporting instructions                                      |
| Missing `CHANGELOG.md` (file does not exist) | Generate skeleton with `# Changelog` header and initial entry from git log since last tag        |
| Doc drift detected                           | Delegate to `/harness:align-documentation`                                                       |
| Dead code found                              | Delegate to `/harness:cleanup-dead-code` (with `--fix` intent)                                   |

#### Prompting

Present each fix individually:

```
[1/6] Fix: Add "repository" field to packages/core/package.json
      Value: { "type": "git", "url": "https://github.com/org/repo.git" }
      [y]es / [n]o / [a]ll remaining
```

- **y** — Apply this fix and show the next one.
- **n** — Skip this fix. Record it as "skipped" in state.
- **a** — Apply this fix and all remaining fixes without prompting.

After each batch of fixes (or after each individual fix if not batching), run `harness validate` to ensure the fixes did not introduce new issues.

#### Non-Fixable Findings

These require human judgment and cannot be auto-fixed. List them with guidance:

| Finding                                                      | Guidance                                                                                                                                                                                                                      |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TODO`/`FIXME` in published source                           | List each location with file:line. Human must resolve or move to a tracked issue.                                                                                                                                             |
| README missing usage/API sections                            | Suggest section structure but do not generate content — only the author knows the API.                                                                                                                                        |
| CHANGELOG exists but has no entries (empty or template-only) | Suggest running `git log --oneline <last-tag>..HEAD` to generate entries. Unlike a missing file (auto-fixable above), an empty CHANGELOG needs human-authored content.                                                        |
| CI workflow missing                                          | Provide a starter template but flag for human review before committing.                                                                                                                                                       |
| Build failure                                                | Show the error output. Do not attempt to fix build issues automatically.                                                                                                                                                      |
| Typecheck failure                                            | Show the error output with file:line. Common causes: orphaned files with stale imports, missing type declarations, `exactOptionalPropertyTypes` violations. Do not auto-fix — type errors often indicate structural problems. |
| Test failure                                                 | Show the error output with failing test names. Do not attempt to fix test failures automatically — they may indicate real bugs.                                                                                               |

#### Output

```
FIX COMPLETE

Applied:  4 fixes
Skipped:  1 fix (README usage section — requires human)
Failed:   0 fixes

Remaining manual items:
  - [ ] Write usage section in README.md
  - [ ] Resolve TODO in packages/cli/src/init.ts:42
```

Proceed to Phase 4: REPORT.

---

### Phase 4: REPORT — Final Output

Write two artifacts: a human-readable report and a machine-readable state file.

#### 1. Release Readiness Report (`release-readiness-report.md`)

Write to the project root by default. If the project uses `.harness/reports/` for generated reports, write there instead. Use this template:

```markdown
# Release Readiness Report

**Date:** YYYY-MM-DD
**Project:** <project name>
**Flags:** standard | comprehensive

## Summary

**Result: PASS / FAIL**

| Category                   | Passed       | Warnings | Failures |
| -------------------------- | ------------ | -------- | -------- |
| Packaging                  | N/N          | N        | N        |
| Documentation              | N/N          | N        | N        |
| Repo Hygiene               | N/N          | N        | N        |
| CI/CD                      | N/N          | N        | N        |
| Maintenance — Doc Drift    | N issues     | —        | —        |
| Maintenance — Dead Code    | N issues     | —        | —        |
| Maintenance — Architecture | N violations | —        | —        |
| Maintenance — Diagnostics  | N warnings   | —        | —        |

## Packaging

### <package-name> [pass/warn/fail per check]

- [x] name: `@org/package`
- [x] version: `1.0.0`
- [ ] missing `files` field

(Repeat for each package in monorepo)

## Documentation

- [x] README.md exists
- [x] README has install section
- [ ] README missing usage section

## Repo Hygiene

- [x] CONTRIBUTING.md exists
- [ ] SECURITY.md missing

## CI/CD

- [x] CI workflow exists
- [x] Release workflow exists

## Maintenance Results

### Doc Drift

(findings from detect-doc-drift, or "clean")

### Dead Code

(findings from cleanup-dead-code, or "clean")

### Architecture

(findings from enforce-architecture, or "clean")

### Diagnostics

(findings from diagnostics, or "clean")

## Fixes Applied

- Added `repository` field to packages/core/package.json
- Generated SECURITY.md from template

## Remaining Items

- [ ] Write usage section in README.md
- [ ] Resolve TODO in packages/cli/src/init.ts:42
- [ ] Add `files` field to packages/types/package.json
```

**Result** is **PASS** only when: zero failures across all categories AND zero maintenance issues with "fail" severity. Warnings alone do not block a PASS.

#### 2. State File (`.harness/release-readiness.json`)

Write to `.harness/release-readiness.json`. This file enables session resumption.

```json
{
  "schemaVersion": 1,
  "timestamp": "YYYY-MM-DDTHH:MM:SSZ",
  "flags": {
    "comprehensive": false
  },
  "summary": {
    "result": "FAIL",
    "passed": 14,
    "warned": 2,
    "failed": 2,
    "total": 18
  },
  "categories": {
    "packaging": {
      "passed": 5,
      "warned": 1,
      "failed": 1,
      "findings": [
        {
          "package": "packages/types",
          "check": "files field exists",
          "severity": "fail",
          "fixable": true,
          "fixed": false
        }
      ]
    },
    "documentation": {
      "passed": 5,
      "warned": 1,
      "failed": 0,
      "findings": []
    },
    "repo-hygiene": {
      "passed": 3,
      "warned": 2,
      "failed": 0,
      "findings": []
    },
    "ci-cd": {
      "passed": 4,
      "warned": 1,
      "failed": 0,
      "findings": []
    },
    "maintenance": {
      "doc-drift": { "issues": 2, "findings": [] },
      "dead-code": { "issues": 0, "findings": [] },
      "architecture": { "issues": 0, "findings": [] },
      "diagnostics": { "issues": 1, "findings": [] }
    }
  },
  "fixes": {
    "applied": ["added-repository-field-core", "generated-security-md"],
    "pending": ["add-files-field-types", "doc-drift-api-index"],
    "skipped": ["readme-usage-section"]
  }
}
```

#### Session Resumption Behavior

When the skill is invoked and `.harness/release-readiness.json` exists:

1. Load the previous state.
2. Re-run all checks (do not trust cached results — code may have changed).
3. Compare new results against previous state.
4. Display a delta:

```
Release Readiness — resuming from 2026-03-19T10:30:00Z

Since last run:
  ✓ 2 items fixed (added "files" field to types, resolved doc drift in api/index.md)
  ↑ 1 new issue (CONTRIBUTING.md was deleted)
  → 1 item remaining (TODO in cli/init.ts:42)

Previous: 14/18 passed (FAIL)
Current:  16/19 passed (FAIL)
```

#### Milestone Trigger Variant

When the skill fires via `on_milestone` trigger, use progress framing instead of pass/fail:

```
Release Readiness Progress — Milestone: <milestone name>

  16/18 checks passing (up from 12/18 last run)
  1 item auto-fixable
  1 item requires manual attention

  Trend: ↑ improving (4 items resolved since last milestone)
```

This framing is informational — it does not block anything. It gives the team a sense of trajectory.

---

## Harness Integration

- **`assess_project`** — Used in AUDIT Phase 1 (CI/CD section) to run the full harness CI gate (validation, dependencies, docs, lint, performance/complexity, security, entropy, and architecture) in a single parallel call. Also run after auto-fixes in Phase 3 to verify project health. Automatically inherits new checks added to `assess_project`.
- **Sub-skill invocations** — Phase 2 dispatches `detect-doc-drift`, `cleanup-dead-code`, `enforce-architecture`, and `diagnostics` as parallel agents. Phase 3 delegates fixes to `align-documentation` and `cleanup-dead-code`.
- **State file** — `.harness/release-readiness.json` enables session resumption and progress tracking. This file is read at the start of each invocation and written at the end.
- **Report file** — `release-readiness-report.md` is written to the project root. It is a snapshot, not a tracked artifact — regenerate it on each run.
- **i18n coverage** — When `i18n.enabled: true`, Phase 1 checks translation coverage against configured thresholds. Uses `harness-i18n` scan results and `harness-i18n-workflow` coverage tracking. Blocks release in strict mode if coverage is below `i18n.coverage.minimumPercent`.

## Success Criteria

1. Running `/harness:release-readiness` on a project with known gaps produces a report that identifies all of them — no false negatives on standard checks
2. Running it on a clean project produces an all-pass report with no false positives
3. Maintenance skills are dispatched in parallel and their results appear in the unified report
4. Auto-fix applies correct changes — package.json modifications are valid JSON, generated files match project conventions
5. State file persists across sessions and subsequent runs show accurate deltas
6. `--comprehensive` flag activates additional checks without affecting standard check behavior
7. `on_milestone` trigger fires and produces a progress-style report (not just pass/fail)
8. Monorepo support: each package is audited independently with per-package results in the report
9. `harness validate` passes after the skill's SKILL.md and skill.yaml are written

## Rationalizations to Reject

These are common rationalizations that sound reasonable but lead to incorrect results. When you catch yourself thinking any of these, stop and follow the documented process instead.

| Rationalization                                                                           | Why It Is Wrong                                                                                                            |
| ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| "The MAINTAIN phase takes too long, so I will skip dispatching the 4 maintenance agents"  | No skipping the MAINTAIN phase. Maintenance checks catch issues that release-specific checks miss.                         |
| "This auto-fix is obviously correct, so I can apply it without prompting the user"        | No auto-fix without prompting. Every fix must be presented to the human before being applied.                              |
| "Most checks pass and only a few warnings remain, so the release is ready"                | A "mostly passing" report is not a passing report. The result is PASS only when zero failures exist across all categories. |
| "The previous run found these issues and I fixed them, so I can trust the cached results" | Session resumption requires re-running all checks. Code may have changed since the last run.                               |

## Examples

### Example: First Run on a Monorepo with Gaps

**Context:** A TypeScript monorepo with 3 packages. Two packages are missing `files` fields, README lacks a usage section, and SECURITY.md does not exist.

**Phase 1: AUDIT**

```
No existing state found. Running fresh audit.

Checking packages/core...
  ✓ name: @myorg/core
  ✓ version: 1.2.0
  ✓ license: MIT
  ✓ exports defined
  ✗ files field missing (fail)
  ✗ publishConfig missing (warn)

Checking packages/utils...
  ✓ name: @myorg/utils
  ✓ version: 0.3.0
  ✓ license: MIT
  ✓ exports defined
  ✗ files field missing (fail)

Checking packages/cli...
  ✓ name: @myorg/cli (all fields present)

Documentation:
  ✓ README.md exists
  ✗ README missing usage section (warn)
  ✓ CHANGELOG.md exists with entries
  ✓ LICENSE exists

Repo Hygiene:
  ✓ CONTRIBUTING.md exists
  ✓ CODE_OF_CONDUCT.md exists
  ✗ SECURITY.md missing (warn)
  ✓ .gitignore covers node_modules, dist, .env

CI/CD:
  ✓ CI workflow: .github/workflows/ci.yml
  ✓ Release workflow: .github/workflows/release.yml
  ✓ test, lint, typecheck scripts present

AUDIT COMPLETE
Packaging:  9/12 passed, 1 warning, 2 failures
Docs:       5/6 passed, 1 warning, 0 failures
Hygiene:    4/5 passed, 1 warning, 0 failures
CI/CD:      5/5 passed, 0 warnings, 0 failures
Total: 23/28 passed, 3 warnings, 2 failures
```

**Phase 2: MAINTAIN**

```
Dispatching 4 maintenance agents in parallel...

Doc Drift:     1 issue — docs/api/core.md references removed function `legacyParse`
Dead Code:     0 issues (clean)
Architecture:  0 violations (clean)
Diagnostics:   0 warnings (clean)

MAINTENANCE COMPLETE — 1 issue found
```

**Phase 3: FIX**

```
5 fixable findings:

[1/5] Fix: Add "files": ["dist"] to packages/core/package.json
      [y]es / [n]o / [a]ll remaining
> y
      ✓ Applied

[2/5] Fix: Add "files": ["dist"] to packages/utils/package.json
      [y]es / [n]o / [a]ll remaining
> y
      ✓ Applied

[3/5] Fix: Add "publishConfig": { "access": "public" } to packages/core/package.json
      [y]es / [n]o / [a]ll remaining
> a
      ✓ Applied (and all remaining)

[4/5] Fix: Generate SECURITY.md from template
      ✓ Applied (batch)

[5/5] Fix: Delegate doc drift to /harness:align-documentation
      ✓ Applied (batch) — docs/api/core.md updated

Running harness validate... ✓ passes

FIX COMPLETE — 5 applied, 0 skipped, 0 failed
```

**Phase 4: REPORT**

```
Writing release-readiness-report.md...
Writing .harness/release-readiness.json...

# Release Readiness Report
Date: 2026-03-19
Result: PASS (after fixes)

28/28 checks passed, 0 warnings, 0 failures
Maintenance: all clean

Fixes applied this session: 5
Remaining manual items:
  - [ ] Write usage section in README.md (optional — warning only)
```

### Example: Resuming After Partial Fixes

```
Release Readiness — resuming from 2026-03-18T14:20:00Z

Since last run:
  ✓ 3 items fixed (added files fields, generated SECURITY.md)
  → 2 items remaining (doc drift in api/core.md, README usage section)

Re-running full audit...

Previous: 23/28 passed (FAIL)
Current:  27/28 passed (PASS — 1 warning remaining)

The project is release-ready. The remaining warning (README usage section) is not blocking.
```

## Gates

These are hard stops. Violating any gate means the process has broken down.

- **No release without a passing report.** If the report result is FAIL, the project must not be released. Fix all failures first.
- **No skipping the MAINTAIN phase.** Maintenance checks catch issues that release-specific checks miss (dead code, architecture drift, doc drift). They must run every time.
- **No auto-fix without prompting.** Every fix must be presented to the human before being applied (unless the human chose `all` to batch-approve remaining fixes). Silent fixes are not allowed.
- **All findings must have evidence.** Do not report a check as failed without showing the specific file, line, or field that caused the failure. "Packaging looks incomplete" is not a finding — "packages/core/package.json is missing the `files` field" is.
- **State must be written.** After every run, `.harness/release-readiness.json` must be updated. Without state, session resumption is impossible and progress is lost.

## Escalation

- **When there are too many failures to fix in one session:** Present the full report, highlight the most impactful fixes (failures before warnings, blocking before non-blocking), and suggest a prioritized fix order. Save state so the next session can pick up where this one left off.
- **When a maintenance skill is unavailable or errors out:** Report it as "unavailable" in the maintenance section. Do not block the rest of the report. Suggest running the failed skill manually: "Doc drift check failed — run `/harness:detect-doc-drift` separately to investigate."
- **When monorepo packages have inconsistent configurations:** Flag the inconsistency explicitly: "packages/core has `publishConfig` but packages/utils does not. Should all packages use the same publishing configuration?" Ask the human before applying a uniform fix.
- **When the project has no build command:** Some packages are types-only and have no build step. Skip the build check for packages without a `build` script and note it as "N/A" rather than a failure.
- **When fixes conflict with each other:** Present both findings and let the human choose. Example: dead code cleanup wants to remove a function, but doc drift fix references that function in updated docs. Human must decide which takes priority.