canary-test-cli 7.0.0 → 7.2.0

package/agents/skills/claude-code/canary-ship/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: canary-ship
+version: '1.0.0'
+description: >-
+  Run the canary ship gate on a finished change: spawn parallel adversarial
+  reviewers on the diff, resolve every confirmed finding with a regression test,
+  then commit, open a PR, and squash-merge while watching CI to green. Use this
+  whenever an implemented, locally-green change on a feature branch should be
+  merged — when the user says ship it, or review resolve commit push pr merge,
+  or get this merged when it is green, or take it the rest of the way, or right
+  after you finish implementing a feature or fix and the next step is
+  integration. It bakes in this repo's conventions (no co-author trailer, squash
+  merge, prettier, exclude local IDE churn, update the roadmap). NOT for writing
+  the implementation itself, and NOT a substitute for finishing the work — the
+  change must already exist and pass tests locally before the gate runs.
+---
+
+# Canary Ship
+
+The last mile of a change is where quality is won or lost: a plausible-looking
+diff merges, and the bug nobody looked for ships with it. This skill is the
+**ship gate** — the disciplined path from "the code is written and tests pass"
+to "it's merged on `main` with CI green." Its spine is a real adversarial review
+_before_ the merge button, not after, because the cheapest place to catch a
+defect is the one before it reaches `main`.
+
+It is not a code generator. It assumes the change already exists on a feature
+branch and passes the suite locally. Its job is to pressure-test that change,
+resolve what the pressure surfaces, and integrate it under this repo's
+conventions without you having to re-remember them each time.
+
+## When this fires vs. when it doesn't
+
+Use it when the work is **done and green** and the remaining verb is "ship",
+"merge", "PR it", "take it home". Do **not** use it to do the implementation, to
+merge something whose tests you haven't run, or to force a merge past a failing
+gate. If the change isn't on a branch yet, make the branch first (see
+[AGENTS.md](../../../../AGENTS.md) branch hygiene) — never ship from `main`.
+
+## Preconditions (verify before starting)
+
+- On a feature branch, not `main` (`git branch --show-current`).
+- The change is implemented and the relevant suite + lint pass locally. If you
+  can't confirm that, stop and run them — the gate reviews a _finished_ change.
+- `git fetch origin` first, then know your diff base (`origin/main...`). Other
+  sessions may be active on this repo; trust the remote, not stale local state.
+
+## The pipeline
+
+Five phases. Do them in order; each depends on the last. Track them as todos so
+none is silently skipped.
+
+### 1 · Review — two independent reviewers, in parallel, on the diff
+
+Spawn **two** review subagents in the _same_ turn so they run concurrently, each
+scoped to the actual change (not the whole repo):
+
+- a **correctness/design** pass — `harness-code-reviewer` — hunting real bugs,
+  broken contracts, and inconsistencies;
+- an **adversarial** pass — `harness-adversarial-reviewer` — constructing
+  failure scenarios: assumption violations, composition failures across _all_
+  callers of anything you changed, and blind spots in new guards or tests.
+
+Give each reviewer the changed-file list, the design intent, and the specific
+risk areas you already suspect (a contract change? a new parser? an import
+cycle?). Ask for **confirmed findings with a concrete failure scenario**
+(specific input/state → bad outcome), ranked by severity — not style nits.
+
+Why two, why adversarial, why before the merge: a single reviewer rubber-stamps;
+two independent ones that disagree surface the real seam. The adversarial lens
+is the one that asks "who _else_ calls this?" — the question that catches the
+regression your own change introduced in a caller you weren't looking at. (This
+is not hypothetical; it is the failure mode this gate exists to catch.)
+
+If the `harness-code-review` pipeline (the `/harness code-review` skill) is
+available and you prefer it, it can stand in for the correctness pass — but keep
+a distinct adversarial pass alongside it. Wait for both to report before editing
+anything, so you resolve in one pass and don't edit files a reviewer is still
+reading.
+
+### 2 · Resolve — fix confirmed findings, each with a regression test
+
+For every **confirmed** finding, fix it and add a test that would have caught
+it. A fix without a regression test is a fix that silently comes back. Rank by
+severity and resolve top-down.
+
+You do not have to accept every finding — but rejecting one is a technical
+judgment you must be able to defend, not a convenience. When you skip a finding,
+say why (e.g. "pre-existing, out of scope"; "the quadrant is empty and pinned by
+an invariant test"). When a reviewer independently confirms another reviewer's
+finding, treat that convergence as strong signal it's real.
+
+Then re-run the affected suite **and** the full suite + lint. Green here is the
+gate for phase 3 — a partial run is not confirmation.
+
+### 3 · Commit — stage the change only, format, no co-author trailer
+
+- **Stage precisely.** Add only the files that belong to this change. This repo
+  often carries local IDE/agent churn (`.claude/settings.json`, `.gitignore`,
+  editor caches) that is _not_ yours to commit — exclude it explicitly and
+  double-check `git status` before committing.
+- **Format first.** Run `npx prettier --write` on any changed `*.md` / `*.yaml`
+  / `*.ts` _before_ committing. Prettier is a **CI** gate here
+  (`npm run format:check` in `harness-quality.yml`), so an unformatted diff
+  commits fine but fails CI _after_ you push — format now to avoid the red
+  round-trip. (The pre-commit hook itself runs the roadmap-comment guard,
+  **markdownlint** on staged `.md`, and the security-ledger refresh — not
+  prettier.) Watch for prettier mangling inline code in prose (e.g. `foo(bar)` →
+  `foo (bar)`); reword to avoid a paren at a wrap boundary if it does.
+- **Doc drift + roadmap.** Before committing, check whether the change made any
+  doc stale, and update `docs/roadmap.md` (mark the item done, with a summary of
+  what shipped and any reviewed-and-resolved findings). Shipping code with a
+  stale roadmap is drift this project specifically tracks.
+- **Commit message:** conventional (`feat(scope): …`), imperative subject, body
+  explaining the _why_ and the review outcome. **No `Co-Authored-By` trailer** —
+  this project's standing preference. Let the pre-commit hooks run.
+
+### 4 · PR — push and open with a structured body
+
+`git push -u origin <branch>`, then `gh pr create --base main` with a body that
+states **What / How / Review (findings resolved) / Tests**. The review section
+is the honest part — name the findings the gate caught and how they were fixed.
+Search for a PR template in `.github/` first and honor it if present.
+
+### 5 · Merge — then watch CI, sync, and prune
+
+`gh pr merge <n> --squash --auto --delete-branch` (this repo squashes).
+Repo-level auto-merge is enabled (`allow_auto_merge: true`) and there are 13
+required status checks, with `strict_required_status_checks_policy: true` on
+ruleset 16189198 — so a PR cannot merge until its branch is up to date with
+`main` and every required check is green. `--auto` is therefore the right
+default: it lands the PR the moment both hold.
+
+Auto-merge **waits**; it does not update the branch. Whenever `main` moves the
+PR goes stale, so run `gh pr update-branch <n>` and let the checks re-run.
+`--delete-branch` is still needed explicitly since the repo does not auto-delete
+on merge.
+
+Merging immediately means CI runs _post-merge_ — so "merge when green" is on
+you: **watch the post-merge CI runs to completion**
+(`gh run watch <id> --exit-status`, or poll `gh run list --branch main`) and
+confirm every check passes. If one fails, that is a real regression on `main` —
+fix it forward immediately, don't leave it red.
+
+Then sync and clean up: `git checkout main && git pull --ff-only`, delete the
+merged local branch, and `git fetch --prune`.
+
+## Conventions this gate enforces (the point of packaging it)
+
+| Convention                                       | Why                                                                                                                                     |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| No `Co-Authored-By` trailer                      | Standing user preference for this repo                                                                                                  |
+| Squash merge (`--squash --auto --delete-branch`) | Repo squashes; auto-merge is on and `strict` is true, so queue it and update the branch when `main` moves; branches aren't auto-deleted |
+| Prettier `--write` before commit                 | Formatting is a CI gate (`format:check`); avoids a red CI round-trip post-push                                                          |
+| Exclude local IDE/agent churn from staging       | `settings.json`/caches aren't part of the change                                                                                        |
+| Update `docs/roadmap.md` + check doc drift       | Drift this project explicitly tracks                                                                                                    |
+| Adversarial review before merge, not after       | Cheapest defect-catch is before `main`                                                                                                  |
+
+## Rationalizations to reject
+
+- _"It's a small change, skip the review."_ Small diffs introduce the caller
+  regressions no one looks for — the review is cheapest exactly when the change
+  looks trivial.
+- _"Tests pass, just merge."_ Passing tests prove the paths you thought of. The
+  adversarial pass is for the paths you didn't.
+- _"CI has no required checks, so I don't need to watch it."_ Then nothing else
+  will — post-merge red on `main` is yours to catch.
+- _"I'll fix the doc/roadmap later."_ Later is how drift accumulates; it's one
+  edit now.
+
+## Stop conditions
+
+Stop and hand back to the human when: a confirmed finding needs a product
+decision you can't make; the review surfaces a design flaw that warrants
+re-scoping rather than patching; a merge conflict needs human judgment; or CI
+fails for a reason you can't safely fix forward. Never force-merge past a red
+gate or an unresolved confirmed finding.

package/agents/skills/claude-code/canary-ship/skill.yaml

@@ -0,0 +1,16 @@
+name: canary-ship
+version: '1.0.0'
+description: >-
+  Run the canary ship gate on a finished, locally-green change - spawn parallel
+  adversarial reviewers on the diff, resolve every confirmed finding with a
+  regression test, then commit, open a PR, and squash-merge while watching
+  CI to green. Bakes in this repo's conventions (no co-author trailer, squash,
+  prettier, exclude local IDE churn, update the roadmap).
+stability: static
+triggers:
+  - manual
+platforms:
+  - claude-code
+type: rigid
+tools: []
+tier: 2

package/agents/skills/claude-code/canary-strix/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: canary-strix
+description: >
+  Keeps company, client and consumer identifiers out of a public repository —
+  scanning both tracked file contents and the AUTHORSHIP of the commits a change
+  adds (author, committer, and `Co-authored-by:` trailers), because a company
+  email never appears in a file, only in commit metadata. Use when the user says
+  "is anything leaking into this public repo", "scan for client names", "did we
+  commit a company email", "open-source hygiene", or before making a repo
+  public. Deterministic — no LLM, no network, no execution. NOT a secret scanner
+  (use gitleaks/trufflehog for credentials); this is about IDENTIFIERS — who you
+  work for and who your customers are.
+cli: scripts/cli.mjs
+requires: [node>=20]
+---
+
+# canary-strix
+
+A public repository leaks who you work for in two places, and only one of them
+is a file.
+
+## The two surfaces
+
+**Tracked file contents** (`STRIX-001`) — the obvious half. A client name in a
+comment, a fixture, a changelog entry.
+
+**Commit authorship** (`STRIX-002`) — the half that gets missed. A company email
+never appears _in_ a tracked file; it lives in the metadata of the commit
+carrying it. A tree can scan perfectly clean while every commit in it is stamped
+with a company address. This is not hypothetical: canary itself accumulated 190
+such commits, every one from a clone that inherited a global `user.email`
+instead of the repo's pin.
+
+The authorship scan reads the author, the committer, **and** `Co-authored-by:`
+style trailers. GitHub renders a co-author as a linked contributor on the public
+commit page, which makes a trailer a _more_ visible identity surface than the
+author field.
+
+## Where terms come from
+
+Three sources, unioned. Which one is right depends on whether the repo is
+public:
+
+| Source                              | Committed? | Use when                                     |
+| ----------------------------------- | ---------- | -------------------------------------------- |
+| `CANARY_PROPRIETARY_DENYLIST` env   | no         | **public repo** — supply it as a CI secret   |
+| `.proprietary-denylist` (gitignore) | no         | **public repo** — the same list, at the desk |
+| `.canary/company.json`              | **yes**    | **private repo only**                        |
+
+`company.json` is the convenient option and the one to be careful with: it is
+committed, so on a public repo it publishes exactly the list of identifiers you
+are trying to hide. The CLI says so out loud when terms come from there.
+
+Prefer **one term per line** in the secret. GitHub masks a multi-line secret
+line by line, so each term is masked individually in a log; a comma-joined value
+is only masked as the whole string, which is never the form that appears in
+output.
+
+## Zero terms is not a clean scan
+
+With no terms configured this cannot match anything, whatever it is pointed at.
+That is an abstention, and it exits **3** under `--strict` rather than reporting
+a pass. The same applies when only half the scan ran — files read but commits
+unreadable is a partial result, not a green one.
+
+Findings never echo the matched value. On a public repo the CI log is
+world-readable, so printing the identifier would publish the thing the scan
+exists to protect, on exactly the lines that trip it. A finding names the file
+and line, or the commit and which field matched, plus a local command to inspect
+it.
+
+## Matching
+
+Terms are authored as prose (`Acme Health`, `Acme Inc.`) and subjects are not:
+an email domain drops or changes the separator. A naive `\b<term>\b` misses
+`dev@acmehealth.example`, misses `dev@acme-health.example`, and — for a term
+ending in punctuation like `Acme Inc.` — matches nothing at all, ever, because
+`\b` after `.` requires a word character. Those failures are silent and they
+fail **open**.
+
+So a term is split into alphanumeric tokens, joined with a separator-tolerant
+gap, and bounded with unicode-aware lookarounds. Boundaries still hold: `Acme`
+does not match `acmecorp`.
+
+## Invocation
+
+```bash
+# Advisory scan of the current repo (exit 0 regardless):
+canary skills run canary-strix
+
+# Gate a CI step — findings or an abstention fail it:
+canary skills run canary-strix -- --strict
+
+# Files only, skipping commit authorship:
+canary skills run canary-strix -- --files-only
+
+# An explicit range instead of the CI event:
+canary skills run canary-strix -- --range origin/main..HEAD
+
+# Machine-readable:
+canary skills run canary-strix -- --json
+
+# Usage and the full flag list (exits 0):
+canary skills run canary-strix -- --help
+```
+
+On CI the commit range is resolved from the event: `GITHUB_BASE_REF` (with
+`GITHUB_PR_HEAD_SHA`) on a pull request, `GITHUB_EVENT_BEFORE` on a push. Pass
+`GITHUB_PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}` — without it the
+range ends at the checked-out `refs/pull/N/merge` commit, which GitHub
+synthesises per event and authors with the PR author's _account_ email. That
+commit is discarded at merge, so scanning it reports a leak that cannot happen.
+
+## Exit codes
+
+| Code | Meaning                                                         |
+| ---- | --------------------------------------------------------------- |
+| 0    | advisory run, or `--strict` with a complete scan and no finding |
+| 1    | `--strict`, findings                                            |
+| 2    | usage error                                                     |
+| 3    | `--strict`, abstained — no terms, or only half the scan ran     |
+
+## Fidelity limits
+
+Literal terms, not inference. It will not catch a client referred to only by a
+nickname, an internal hostname that is not on the list, or a codename nobody
+wrote down. The list is the denominator, and the CLI always prints it.
+
+Secrets and credentials are out of scope — that is a different tool and a
+different failure mode.

package/agents/skills/claude-code/canary-strix/scripts/cli.mjs

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+// canary-strix -- keep company and consumer identifiers out of a public repo.
+//
+//   --root <path>   repository to scan (default: the current directory).
+//   --range <spec>  commit range for the authorship scan; otherwise resolved
+//                   from the CI event (GITHUB_BASE_REF / GITHUB_EVENT_BEFORE).
+//   --files-only    skip the authorship scan.
+//   --json          emit machine-readable findings instead of human text.
+//   --strict        exit 1 when there are findings (default is advisory: 0).
+//
+// Deterministic: no LLM, no network, no execution.
+//
+// Invoked via `canary skills run canary-strix -- [--json] [--strict] ...`.
+
+import {
+  createParser,
+  formatUsageError,
+  EXIT_USAGE,
+} from '../../../lib/parse-args.mjs';
+import {
+  loadTerms,
+  DENYLIST_ENV,
+  DENYLIST_FILE,
+  COMPANY_FILE,
+} from './terms.mjs';
+import {
+  compileTerms,
+  scanFiles,
+  scanAuthorship,
+  resolveRange,
+} from './scanner.mjs';
+
+export const SCHEMA_VERSION = 1;
+
+const PREFIX = 'canary-strix:';
+
+/** Reserved CLI-wide: exit 3 means "abstained -- verified zero items". */
+const EXIT_ABSTAINED = 3;
+
+const ARROW = '\u{2192}';
+
+const USAGE =
+  'usage: canary-strix [-h] [--json] [--strict] [--files-only] [--root PATH]\n' +
+  '                    [--range SPEC]\n' +
+  '\n' +
+  'Keep company and consumer identifiers out of a public repo.\n' +
+  '\n' +
+  'options:\n' +
+  '  -h, --help     show this help message and exit\n' +
+  '  --root PATH    repository to scan (default: the current directory)\n' +
+  '  --range SPEC   commit range for the authorship scan (default: the CI event)\n' +
+  '  --files-only   skip the authorship scan\n' +
+  '  --json         emit machine-readable findings instead of human text\n' +
+  '  --strict       exit 1 when there are findings (default is advisory: exit 0)\n' +
+  '\n' +
+  'rules:\n' +
+  '  STRIX-001  company identifier in a tracked file\n' +
+  '  STRIX-002  company identity on a commit (author, committer or trailer)\n' +
+  '\n' +
+  'terms come from, unioned:\n' +
+  `  ${DENYLIST_ENV}   a CI secret -- the only source safe for a PUBLIC repo\n` +
+  `  ${DENYLIST_FILE}       gitignored, so the desk catches it before a push\n` +
+  `  ${COMPANY_FILE}     committed: PRIVATE repos only\n` +
+  '\n' +
+  'ZERO TERMS IS NOT A CLEAN SCAN. With no terms configured this cannot match\n' +
+  'anything, and it exits 3 under --strict rather than reporting a pass.';
+
+export const CLI_SPEC = {
+  prog: 'canary-strix',
+  booleans: {
+    '--json': 'json',
+    '--strict': 'strict',
+    '--files-only': 'filesOnly',
+  },
+  values: {
+    '--root': { key: 'root' },
+    '--range': { key: 'range' },
+  },
+};
+
+const parseArgs = createParser(CLI_SPEC);
+
+function analyse(opts, env = process.env) {
+  const root = opts.root ?? '.';
+  const { terms, sources, committedSource, implausible } = loadTerms(root, env);
+
+  // A denylist of zero terms matches nothing, whatever it is pointed at. That
+  // is an abstention in every environment -- the single most important line in
+  // this file, because the alternative reads exactly like a clean repo.
+  if (!terms.length) {
+    return {
+      abstained: 'no terms configured',
+      terms,
+      implausible,
+      sources,
+      implausible,
+      findings: [],
+    };
+  }
+
+  const matchers = compileTerms(terms);
+  const files = scanFiles(root, matchers);
+  if (files.unavailable) {
+    return {
+      abstained: files.unavailable,
+      terms,
+      sources,
+      implausible,
+      findings: [],
+    };
+  }
+
+  const findings = [...files.findings];
+  let authorship = { skipped: '--files-only' };
+  if (!opts.filesOnly) {
+    authorship = scanAuthorship(root, matchers, resolveRange(env, opts.range));
+    if (authorship.findings) findings.push(...authorship.findings);
+  }
+
+  return {
+    terms,
+    sources,
+    committedSource,
+    implausible,
+    files,
+    authorship,
+    findings,
+  };
+}
+
+/**
+ * Warns about denylist entries that do not look like identifiers.
+ *
+ * Junk in the denylist inflates the denominator, which is the half of #818
+ * that outlives the parser bug: `15 term(s)` read as fifteen protections when
+ * seven were real, on the last line of defence before a company name reaches a
+ * public repo.
+ *
+ * Reports SHAPE, never the value. The denylist holds exactly the names this
+ * scan exists to keep out of a public repo and this line goes to a CI log, so
+ * printing a term to complain about it would be the leak itself.
+ */
+function reportImplausible(terms) {
+  const odd = terms ?? [];
+  if (odd.length === 0) return;
+  const first = odd[0];
+  console.log(
+    `${PREFIX} WARNING: ${odd.length} denylist term(s) do not look like identifiers ` +
+      `(3+ all-lowercase words, e.g. ${first.split(/\s+/).length} words starting ` +
+      `${JSON.stringify(first.slice(0, 3))}). They are still matched; check the ` +
+      `denylist for stray prose.`,
+  );
+}
+
+function reportJson(result) {
+  console.log(
+    JSON.stringify(
+      {
+        schema_version: SCHEMA_VERSION,
+        skill: 'canary-strix',
+        abstained: result.abstained ?? null,
+        term_count: result.terms.length,
+        sources: result.sources,
+        files_scanned: result.files?.scanned ?? 0,
+        commits_scanned: result.authorship?.scanned ?? 0,
+        findings: result.findings,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+/** Caveats that qualify an otherwise-clean line. Never silent. */
+function reportCaveats(result) {
+  if (result.committedSource) {
+    console.error(
+      `${PREFIX} note: terms were read from ${COMPANY_FILE}, which is ` +
+        'COMMITTED. On a public repo that publishes the list of identifiers ' +
+        `you are hiding -- use ${DENYLIST_ENV} or ${DENYLIST_FILE} instead.`,
+    );
+  }
+  if (result.authorship?.unavailable) {
+    console.error(
+      `${PREFIX} authorship scan could not run: ${result.authorship.unavailable}. ` +
+        'Files were scanned; commits were not.',
+    );
+  }
+}
+
+function report(result, json) {
+  if (json) return reportJson(result);
+
+  if (result.abstained) {
+    console.error(
+      `${PREFIX} ABSTAINED -- ${result.abstained}.\n` +
+        'Nothing was matched, so this is not a clean result. Configure terms in ' +
+        `${DENYLIST_ENV}, ${DENYLIST_FILE}, or ${COMPANY_FILE}.`,
+    );
+    return;
+  }
+
+  for (const f of result.findings) {
+    const where = f.file ? `${f.file}:${f.line}` : f.commit;
+    const what = f.fields ? ` (${f.fields.join('/')})` : '';
+    console.log(`${f.rule}  ${where}${what}\n    ${ARROW} ${f.detail}`);
+  }
+
+  // The denominators, always -- a verdict without them cannot be checked.
+  console.log(
+    `${PREFIX} ${result.findings.length} finding(s) over ` +
+      `${result.files.scanned} file(s) and ` +
+      `${result.authorship?.scanned ?? 0} commit(s), ` +
+      `${result.terms.length} term(s) from ${result.sources.join(' + ')}.`,
+  );
+  reportImplausible(result.implausible);
+  reportCaveats(result);
+}
+
+export function main(argv = [], env = process.env) {
+  const { opts, help, error } = parseArgs(argv);
+
+  if (help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (error) {
+    console.error(formatUsageError(CLI_SPEC.prog, error));
+    return EXIT_USAGE;
+  }
+
+  const result = analyse(opts, env);
+  report(result, opts.json);
+
+  // Advisory by default: findings are loud, the exit is not. Under --strict the
+  // exit-code contract applies, and an abstention takes 3 -- distinct from 1,
+  // "found something real".
+  if (!opts.strict) return 0;
+  if (result.abstained) return EXIT_ABSTAINED;
+  if (result.findings.length) return 1;
+  // Files scanned but commits not: a PARTIAL scan. Zero findings over a half
+  // that never ran is not a pass, and exiting 0 here is precisely the
+  // silently-degraded green this skill exists to make impossible. Findings
+  // still outrank it above — something real is more informative than "one
+  // half was dark".
+  if (result.authorship?.unavailable) return EXIT_ABSTAINED;
+  return 0;
+}
+
+// `process.exitCode`, not `process.exit()`: a large `--json` payload exceeds
+// the pipe buffer and `process.exit` tears the process down mid-write, leaving
+// truncated JSON that still exits 0 (#791).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exitCode = main(process.argv.slice(2));
+}