harness-everything 0.40.0 → 0.41.0

package/harness-everything/references/doc-check.md

@@ -0,0 +1,186 @@
+# Doc Check (editorial lane)
+
+One command for an edited governed document: lifecycle lint plus local Markdown link targets. Use it to find and fix defects, then record the real output.
+
+## When to run
+
+| Trigger | Run |
+|---|---|
+| Active `doc-change` step (instruction-led: no step binding exists; `SKILL.md` deep dive → `triage-and-tiers.md` leads here) | Yes, after each edit and before claiming the doc is done |
+| Any edit to a file governed by `.agents/harness-everything/project-docs.json` | Yes |
+| Ungoverned file | No. It appears in `coverage.unsupported`; this is not a doc check |
+
+## Command
+
+Replace `<this-skill-dir>` with the directory of the loaded skill. Use an absolute workspace path.
+
+```text
+node "<this-skill-dir>/scripts/doc-check.js" check \
+  --workspace "<absolute-project-root>" \
+  --config .agents/harness-everything/project-docs.json \
+  --changed-path "docs/document-lifecycle.md" \
+  --base <recorded-base-commit>
+```
+
+- `--changed-path` is repeatable. Quote paths with spaces. Pass deleted and old rename paths too.
+- `--base` is the commit the change is measured against. Omit it and the output shows `evidence.immutability: not-observed`.
+
+## Hook invocation grammar
+
+Only a direct `node <installed-doc-check.js> check` command earns credit. The installed script path must resolve through native `realpath` to this plugin's runtime, and its CRLF-normalized SHA-256 must match the shipped pin. Case variants are accepted when the host filesystem resolves them to that same file.
+
+Candidate detection follows command roles across unquoted newline-separated command segments. A direct `doc-check`/`doc-check.js` target, a checker script operand to a recognized runtime, or a checker command inside a recognized shell `-c` string is a candidate even if its launcher, subcommand, flags or shell composition are unsupported. A command segment that explicitly targets the checker followed by unsupported operators, expansion or malformed trailing quoting remains a candidate and is refused by the strict grammar below; candidate status never authorizes a wrapper. A workflow command whose JSON acceptance text merely mentions `doc-check`, or an unrelated command that prints the name, is not a candidate.
+
+The bounded candidate scan treats quoted or escaped newlines as text. Simple here-docs with a same-line delimiter after `<<` or `<<-` are also recognized: their body through the exact closing-delimiter line is data, with leading tabs ignored for `<<-`. Dynamic or continued delimiters and shell-dialect extensions are outside this scan; they do not establish an accepted invocation.
+
+- `--workspace`, `--config`, and at least one `--changed-path` are required. `--workspace`, `--config`, and optional `--base` occur once; `--changed-path` may repeat. Every flag takes one value.
+- The strict invocation tokenizer supports single and double quotes, adjacent quoted/unquoted text, and backslash escapes. This lets quoted or escaped paths contain spaces.
+- An explicit checker target using a wrapper such as `sh -c`, `env`, or `npx` is refused. The tokenizer rejects unquoted shell operators and line breaks, escaped line continuations, comment markers at a word boundary, active `$`/backtick substitution syntax (including inside double quotes), and unquoted glob, brace, or tilde expansion. Quoting or escaping makes supported metacharacters literal.
+- A refused explicit candidate gets a reason and cannot fall through to generic shell verification or set `lastVerifyAt`.
+- The hook sees the command text supplied by the host. An opaque alias such as `dc` cannot be resolved as doc-check without host-provided argv or alias expansion, so it remains unrecognized.
+
+| Layout | `<this-skill-dir>` |
+|---|---|
+| Source checkout | `<checkout>/harness-everything` |
+| Packaged plugin | `<plugin-root>/skills/harness-everything` |
+
+Run it from any cwd. The script finds its sibling `doc-lifecycle.js` from its own location.
+
+## Output and exit codes
+
+Stdout is always one JSON object. Successful checks use this shape:
+
+```text
+{ lint: {exit, evidence, diagnostics}, links: {checked, broken: [{path, line, target}]}, coverage: {unsupported: [...]} }
+```
+
+Usage or config errors use this reduced shape:
+
+```text
+{ lint: {exit: 2, error}, links: {checked: 0, broken: [], skipped: "lint-usage-error"}, coverage: {unsupported: []} }
+```
+
+| Exit | Meaning |
+|---|---|
+| 0 | Lint passed and every checked link resolves |
+| 1 | A defect: a lint error, a broken link, or an unreadable changed path (`links.broken` with `reason: "unreadable"`). Fix it and rerun |
+| 2 | Usage or config error. Nothing was checked; `links.skipped` says so |
+
+A top-level `reminders` array carries advisory prose-share items, `strength: "SHOULD"`. One item is emitted for each changed, readable, non-legacy governed `reference` doc whose body has more than 50% prose lines (`2 * proseLines > eligibleLines`). Reminders never change an exit code and are never diagnostics. The array is absent on the exit-2 lanes. A doc with malformed frontmatter gets no reminder, because lint already reports the frontmatter error.
+
+## Shared craft and maintenance
+
+Read these before drafting or editing a governed document:
+
+- [writing-craft.md](documentation/_shared/writing-craft.md): writing principles and the prose-share reminder rules (D6.7)
+- [maintenance.md](documentation/_shared/maintenance.md): the event table for D6.5 and D6.6
+
+These links resolve from this `references/` directory. A copy of the skill without `references/documentation/` must report the shared reference as unavailable.
+
+## Derived views
+
+**Applicability** (`conservative-all-governed`, not exact dependency inference):
+
+| Change | Affected views |
+|---|---|
+| Any governed or legacy source path | Every declared `derived` view |
+| A declared derived output | Every declared view (the check does not narrow to the changed output) |
+| The config (candidate declarations) | Every candidate declaration; removed or changed declarations are reported, never taken as proof of completion |
+
+- Include deleted and old rename paths.
+- If the baseline is unavailable, applicability stays unknown and pending.
+- `check` lists each affected view in `coverage.unsupported` as unverified (`applicability: conservative-all-governed`). It never runs a generator. Partial coverage is still exit 0 when lint and links pass.
+- With `--base <rev>`, `check` reads the base config through `git show` and names each declaration that is gone or changed: `applicability: declaration-removed` or `declaration-changed`, still unverified. A base revision that cannot be read is reported, not skipped.
+- Without `--base`, a changed config adds a warning: removed or renamed declarations cannot be detected.
+- A declared glob is reported as `applicability: glob-unsupported`, not as a concrete unverified view.
+- A declared view that also matches a `governed` or `legacy` pattern is reported as `applicability: self-governed`. A derived view must not be governed or indexed by its own generator.
+
+**Authorized generation** (host-run, per view):
+
+1. Show the complete command, the working directory, and the expected writes.
+2. Get authorization from current host policy. A non-empty `generator` string in config is not authorization.
+3. Run it through the host tool. Do not wrap it to hide expansion from permission review.
+4. Capture stdout bytes to a scratch file outside the source globs. stdout must hold only the artifact; logs go to stderr. Prefer `process.execPath` with an argument array over shell splitting.
+
+**`compare-derived`** (pure; executes nothing):
+
+```text
+node "<this-skill-dir>/scripts/doc-check.js" compare-derived \
+  --workspace "<project-root>" --config .agents/harness-everything/project-docs.json \
+  --view docs/governed-index.md --candidate "<scratch-file>" --generation-status ok
+```
+
+| Case | Exit | Result |
+|---|---|---|
+| Fresh stdout, target bytes equal | 0 | `equal` |
+| Target differs, or declared target missing | 1 | `stale` or `missing-view`; keep the target intact |
+| Generator exit non-zero (caller-reported) | 1 | `generator-failed`; no equality claim, even on partial stdout |
+| Host timeout or termination | 2 | `generation-timeout`; partial stdout is not compared |
+| Executable missing or permission unavailable | 2 | `generator-unavailable`; no fallback command |
+| Candidate missing or unreadable; config invalid; absent or invalid status; undeclared or ambiguous view; candidate aliases the target | 2 | `comparison-unavailable`; never PASS |
+| Generator reported `unsupported` (write-in-place or glob output), or a glob or traversal or absolute `--view` | 2 | `unsupported`; the JSON result names the case |
+| Missing required flag, `--flag=value` form, repeated flag, or odd argument count | 2 | `usage-error`; the JSON result names the problem |
+
+- `--generation-status` is required: `ok`, `failed`, `timeout`, `unavailable` or `unsupported`. It is caller-reported ordinary evidence, not host attestation. For any non-`ok` value, the candidate is not read.
+- `--view` must match exactly one literal declared `derived.path`. Wildcards are reported as unsupported. Traversal, absolute targets and symlink escape are rejected. A near-miss (leading `./`, a trailing `/`, a case-only difference, or backslashes) is rejected with exit 2, and the reason names the closest declared path.
+- The candidate must be a regular file. A FIFO, a device or a directory gives exit 2 `comparison-unavailable`, and the call never blocks.
+- The declared generator runs from the project root (cwd = the workspace). A relative path such as `node harness-everything/scripts/...` is project-relative. In an installed plugin, name the installed skill path instead.
+- Byte equality only. No trimming, line-ending conversion, encoding repair, or hash-only comparison. CRLF output is stale until regenerated with the project's output convention.
+- Stdout-only generators are supported. Write-in-place and glob outputs are unsupported.
+- Freshness: regenerate after any source or config edit, and compare before further source edits.
+- Record one comparison per affected view in the task report: the command, cwd, exit, the stdout artifact, stderr, and the `compare-derived` result.
+
+**Windows:** use host-appropriate `npm.cmd` or PowerShell execution for authorized npm commands. Harness adds no cross-platform shell runner.
+
+**Boundary:** generators run with the user's privileges. Neither sandboxing nor trusted provenance is provided. If the host cannot bound or terminate a run, report it unavailable instead of inventing a completed run.
+
+## What it does not prove
+
+- No normative review, quality review or conflict review. Normative changes still need their own review.
+- No trusted reconciliation credit. Exit 0 is ordinary command evidence, not a documentation-obligation PASS.
+- Link checks cover inline `[text](target)` links to local files, including nested or escaped brackets in labels and balanced parentheses in destinations. Any inline-link form the scanner cannot parse appears in `coverage.unsupported`:
+
+| Syntax | Result |
+|---|---|
+| `http:`, `https:`, `mailto:`, `#fragment` | Skipped on purpose |
+| `<angle>` destinations, `?query` suffixes, nested/escaped label brackets, balanced destination parentheses | Checked as their plain target |
+| Other schemes, root-relative `/path`, scheme-less `www.` targets, reference-style links | Listed as unsupported, not checked |
+| Malformed inline-link syntax | Listed as `inline-link-unparsed` in `coverage.unsupported` |
+| Changed path not on disk (`reason: "not on disk"`) | Listed as unsupported, not checked |
+| Changed path not governed (`reason: "not governed"`) | Listed as unsupported, not checked |
+| Changed path on disk but unreadable | `links.broken` with `reason: "unreadable"`; exit 1 |
+
+A non-empty `coverage.unsupported` means the check is partial. Say so when you report.
+
+Bare `<DOMAIN>-NNN` tokens (no `REQ-`, `PRD-` or `legacy:` prefix) are references only for a declared domain or an exact known ID, alias or legacy ID. When no `domains` are declared, `coverage.unsupported` says so once per run.
+
+## Repair a config error
+
+| Symptom | Repair |
+|---|---|
+| `cannot read config` (exit 2) | Create `.agents/harness-everything/project-docs.json` with `governed` entries such as `{"path": "docs/x.md", "role": "reference"}` |
+| `invalid project-docs config` (exit 2) | Fix the reported key. Roles: `prd`, `adr`, `ticket`, `reference`, `log`, `report` |
+| Host `projectDocs` differs | A project file wholly overrides differing host values. Keep the fields you still need |
+| `no domains declared; bare <DOMAIN>-NNN references are not checked` in `coverage.unsupported` | Declare `domains` to have bare ADR-style refs checked. An undeclared-domain token is never a valid ADR ID (contract D6.8) |
+
+Do not silence a missing config. A missing config is a visible gap.
+
+## Credit (F4)
+
+The JSON carries a logical command ID (`harness.doc-check.check.v1` or `harness.doc-check.compare-derived.v1`) and per-capability `capabilities` with checked paths, coverage and skipped reasons. Credit is granted only for a registered run of this install's own script, identified by its resolved path and digest.
+
+- This JSON is **never self-credited**. Stdout that repeats an ID or a status is not evidence of credit.
+- Credit needs the host-captured raw output, checked against the producer's independently derived expected set. See `docs/doc-workflow-reconciliation.md`, section "F4: credited reconciliation".
+- Reminders never earn credit.
+- Trust is conservative. A compound shell command (newline, heredoc, `$()`, operators, malformed quoting) or any command that names doc-check gets no generic verification and does not make a reviewer independent. Run the checker as a plain command. A benign compound such as `npm test && echo ok` must run as its own command to count as generic verification.
+
+For an independent review in the L3 path, the parent computes the post-edit candidate digest with the one read-only command `shasum -a 256 docs/a.md`, then gives the reviewer the relative path and actual digest. The reviewer reads the file and returns a plain `Review verdict: approve` or `Review verdict: reject` line, `Reviewed artifact: docs/a.md sha256:<digest>`, and a non-empty `Summary:` line. Do not edit between hashing and review or pre-fill the verdict. Assessment still checks the correlated host review and the candidate digest; supplying a digest is not proof of reading.
+
+## Record evidence
+
+Keep these in the task's verification record:
+
+- The full command, the workspace, the `--base` SHA and the changed paths
+- Exit code and the single JSON object on stdout (`lint.error` explains exit 2)
+- Whether `coverage.unsupported` is empty
+- Label the claim as command evidence, not as document-obligation credit

package/harness-everything/references/documentation/_shared/maintenance.md

@@ -0,0 +1,41 @@
+# Shared Maintenance (D6.5, D6.6)
+
+Shared by the doc-producing skills and the editorial doc check. Read this when a change touches a governed document, a requirement, a ticket or an ADR. The command for the mechanical checks is in [doc-check.md](../../doc-check.md).
+
+## Event table
+
+Origins cite D-numbers and section names in `docs/document-lifecycle.md` (the repository source; it is not in the packaged skill). Strength and Enforced by are copied from that source. `—` means the source gives no strength or enforcement for the row. It does not mean the row is optional.
+
+| Origin | Event | Obligation | Strength | Enforced by |
+|---|---|---|---|---|
+| D6.5 — `doc-change` applicability by diff facts | Any governed file touched | Lint (role, status, ID, alias) and in-repo link check (`doc-check.md`) | — | — |
+| D6.5 — `doc-change` applicability by diff facts | New governed file | Update-over-create check | — | — |
+| D6.5 — `doc-change` applicability by diff facts | New PRD or ADR outline | Outline confirmation | MUST | — |
+| D6.5 — `doc-change` applicability by diff facts | New other governed outline | Outline confirmation | SHOULD | — |
+| D6.5 — `doc-change` applicability by diff facts | Declared derived source affected | Regenerate and regenerate-equals (generators are not automated; see below); the command-lane procedure is in `doc-check.md` § Derived views | — | — |
+| D6.5 — `doc-change` applicability by diff facts | Normative field: frontmatter `status` or `supersedes`, PRD REQ block or acceptance, ADR *Decision* section | Quality review; D6.4 conflict check | MUST | — |
+| D6.5 — `doc-change` applicability by diff facts | Governed reference or guide content | Prose > 50% reminder (see `writing-craft.md`) | SHOULD | — |
+| D6.6 — Event-driven maintenance | A test citing `REQ-X` is added or its assertions change | Update or supersede `REQ-X` in the same change, or record `no-req-change` with reason and cited evidence | MUST | New rule |
+| D6.6 — Event-driven maintenance | An existing test's cited REQ identity set is added, removed, or retargeted, or the changed call cannot be associated with its prior identity | Applicability/scope `unknown`, never N/A; retain candidate REQ identities and the test path. If removal leaves no candidate identity, retain the prior REQ ID as a removed identity. A citation-only change is not by itself a `new-test` or `assertion-change` trigger | — | — |
+| D6.6 — Event-driven maintenance | A legacy file-level REQ tag is added, removed, or retargeted on a modified test file | Applicability/scope `unknown`, never N/A; retain the changed identity and test path, even when stripped comments leave assertion tokens unchanged | — | — |
+| D6.6 — Event-driven maintenance | `no-req-change` without adequate evidence | Recorded as `not-observed`; never an automatic pass | — | — |
+| D6.6 — Event-driven maintenance | Code changed, no REQ-citing test touched | `not-observed`, not a failure; a diff alone does not prove behaviour unchanged | — | — |
+| D6.6 — Event-driven maintenance | Agent claims `REQ-X` affected, no supporting evidence | Claim and evidence contradict; reminder, no lock | — | — |
+| D6.6 — Event-driven maintenance | `describes:` fingerprint drift | Reminder | SHOULD | D5 #4 |
+| D6.6 — Event-driven maintenance | Ticket closed | In-repo tickets: `status: done`; regenerate index. `tickets: "tracker"`: no in-repo ticket status is generated or inferred offline | MUST | D5 #1 + D6.3 lint |
+| D6.6 — Event-driven maintenance | ADR superseded | Old ADR `status: superseded` | MUST | D6.3 lint |
+| D6.6 — Event-driven maintenance | New defect | Goes to tracker or the declared `tickets` path | MUST | Lint reminder when a ticket is added under a `done` phase |
+| D6.6 — Event-driven maintenance | Report finished | `final`; `archived` once its work closes | SHOULD | Reminder |
+
+For PRDs (D6.9, “Contract-style PRD revisions”), the update-over-create check applies when adding a governed file. An existing draft revision can be edited in place and is never authoritative. An approved revision may only be activated (`status` and `effective_at`, at the same path); any other edit requires returning it to `draft` and re-approving. An effective revision is frozen; a change creates a new complete revision copied from the current effective revision.
+
+## Not automated
+
+- Derived-view generator execution. It stays host-authorized: discovery of affected views and the `compare-derived` comparison execute nothing. See `doc-check.md` § Derived views.
+- Trusted reconciliation credit. The lint and link check is ordinary command evidence only.
+- Code-to-doc dependency edges (#350).
+- Forcing or selecting a provider. Advisory provider suggestions do exist (`doc-providers.js`, `suggestDocProviders`, S3); they are never forced or auto-selected.
+- Auto-publish, auto-commit, or automatic locks.
+- Changes to the S1 default-OFF pilot.
+
+Each skill's own approval and authority contract still applies. This table adds obligations; it does not replace them.

package/harness-everything/references/documentation/_shared/writing-craft.md

@@ -0,0 +1,59 @@
+# Shared Writing Craft (D6.7)
+
+Shared by the doc-producing skills (`to-spec`, `to-tickets`, `repo-docs`, `grill-with-docs`) and by the editorial doc check. Read this before drafting a governed or shared Markdown document.
+
+Attribution: ideas adapted from mattpocock-skills and ECC (both MIT-licensed). The wording here is original; no code is imported.
+
+## Principles
+
+| Content | Form |
+|---|---|
+| Flow or relations | Mermaid, ideally ≤ ~15 nodes per diagram |
+| Comparisons or fields | Tables, one fact per cell |
+| Ordered steps or rules | Bullets |
+| Rationale | Prose, normally ≤ 3 sentences per paragraph, one idea per sentence |
+| Long elaboration | Outside tables, in prose or a linked section |
+
+These are not a claim that brevity proves quality.
+
+## Prose-share SHOULD reminder
+
+- Threshold: a non-blank, non-code prose-line share above 50% triggers a reminder.
+- Strength: **SHOULD**. It is advisory, never a quality gate, a lock, or a cognitive lock (#190).
+- It does not change exit codes, lint, links, or coverage. Dismiss a reminder by reading it; no waiver or exemption exists.
+
+## Line classification
+
+Counted on the body only, after removing leading frontmatter and splitting CRLF and LF.
+
+| Physical line | Denominator | Prose numerator |
+|---|---|---|
+| Blank or whitespace only | Exclude | Exclude |
+| Fenced code, including the fence markers | Exclude | Exclude |
+| Four-space or tab-indented line outside fences | Exclude | Exclude |
+| ATX heading; `-`, `+` or `*` bullet; ordered marker (digits, then `.` or `)`); pipe-leading table row | Include | Exclude |
+| Thematic separator (three or more identical `-`, `*` or `_`) | Include | Exclude |
+| Everything else (blockquotes, `**Label:** text`, CJK, inline-code sentences, HTML or comments, unmarked continuations) | Include | Include |
+
+- Fence rules: an opening fence is 0–3 spaces, then three or more backticks or tildes. The closing fence is the same character, at least the opening length, with trailing whitespace only. An unclosed fence runs to end of file. Mermaid counts as code.
+- Trigger: zero eligible lines gives `share = 0`, no reminder. Otherwise `share = proseLines / eligibleLines`, and the reminder fires when `2 × proseLines > eligibleLines` (strictly greater, so exactly 50% does not fire).
+
+## Limitations (documented false positives and negatives)
+
+- Counts quoted prose, generated text and continuation lines as prose.
+- Treats deeply indented list content as code.
+- Recognises only pipe-leading tables and ATX headings.
+- A UTF-8 BOM before the opening `---` stops frontmatter detection (the parser needs the exact first line `---`), so frontmatter lines are then counted. No code change; the case is documented here.
+- No reflow normalisation, NLP, label exemption or quality score. Do not grow a Markdown parser to tune one result.
+
+## Example fixtures
+
+These are the expected counts for the classifier above. They are design expectations, pinned by tests in a later packet.
+
+| Body | Prose / eligible | Reminder |
+|---|---|---|
+| Heading, then one prose line | 1 / 2 | No (exactly 50%) |
+| Heading, prose line, `**Problem:** More` | 2 / 3 | Yes (label line counts) |
+| Heading, blank line, fenced code | 0 / 1 | No |
+| Blockquote CJK line, CJK prose line, pipe-table row | 2 / 3 | Yes |
+| Code fence only | 0 / 0 | No |

package/harness-everything/references/triage-and-tiers.md

@@ -56,6 +56,10 @@ The model remains free to choose tools, implementation technique, decomposition
 
 Keyword/domain matches are normalized planning signals, not document selectors. Each ordered step declares its required and optional skill/reference bindings; only the active step or dependency-ready Fable stage exposes those paths. Read a required skill's complete entry and follow its applicable core contract before the step passes. Required bindings without a known path remain visible and unresolved. Optional bindings resolve as loaded or not-needed. Hooks may remind, but missing bindings do not hard-block ordinary tools or Stop.
 
+### Governed-doc check
+
+An active `doc-change` step, or any edit to a file governed by `.agents/harness-everything/project-docs.json`, runs the editorial check in [doc-check.md](doc-check.md): lifecycle lint plus local link targets. Its exit code is ordinary command evidence, not trusted document credit.
+
 ## 2. Routing Mechanism
 
 Use the public kernel entry point: