fix(cli): escape line separators in generated literals; license headers and review docs

AGENTS.md

@@ -190,20 +190,37 @@ can't see Deno's module graph.
    not later. Prefer reusing core primitives (`FileTasks`,
    `glob`/`globToRegExp`, the `$`/`Command` shell, the HTTP helpers) over
    re-implementing them in a package.
-9. **Configuration is a fluent settings lambda, not an options object.** When an
-   API takes more than a trivial amount of configuration, expose it as a
-   chainable settings class configured through a lambda — the
-   `Configure<S> = (s: S) => S` shape the tool wrappers use — not a positional
-   options bag. Prefer
-   `.lock((s) => s.lockKey("deploy", repo).withTtl("4h").onConflict(...))` over
-   `.lock(key, { ttl, onConflict })`. Each setter returns `this`, the fields use
-   the trailing-underscore internal convention (and are still JSDoc'd), and the
-   lambda defers evaluation until call time — so a value derived from
-   `this.<param>.value` sees the resolved value. This keeps the whole authoring
-   surface consistent with `DenoTasks.test((s) => …)`, `service()`, and the CI
-   builder, and lets options grow without churning call sites. A single required
-   scalar (a path, a name) can still be a direct argument; reach for the lambda
-   once there are options to set.
+9. **Every source file starts with the copyright and license header.** ALL new
+   files — every `.ts` file (tests, fixtures, and generated-file _templates_
+   included), and any launcher or script — open with these two lines (after the
+   shebang, where one exists), before everything else:
+
+   ```ts
+   // Copyright (c) 2026 the Zuke contributors
+   // SPDX-License-Identifier: MIT
+   ```
+
+   Shell/PowerShell files use `#` comments for the same two lines. This is the
+   per-file copyright and license identification the OpenSSF Best Practices
+   criteria require, and it is enforced: `tests/license_headers_test.ts` fails
+   the suite on any source file missing the header. A generated file gets its
+   header from its template (see `internal/hcl_tool.ts.tmpl`) — put the header
+   in the template, never hand-edit generated output.
+
+10. **Configuration is a fluent settings lambda, not an options object.** When
+    an API takes more than a trivial amount of configuration, expose it as a
+    chainable settings class configured through a lambda — the
+    `Configure<S> = (s: S) => S` shape the tool wrappers use — not a positional
+    options bag. Prefer
+    `.lock((s) => s.lockKey("deploy", repo).withTtl("4h").onConflict(...))` over
+    `.lock(key, { ttl, onConflict })`. Each setter returns `this`, the fields
+    use the trailing-underscore internal convention (and are still JSDoc'd), and
+    the lambda defers evaluation until call time — so a value derived from
+    `this.<param>.value` sees the resolved value. This keeps the whole authoring
+    surface consistent with `DenoTasks.test((s) => …)`, `service()`, and the CI
+    builder, and lets options grow without churning call sites. A single
+    required scalar (a path, a name) can still be a direct argument; reach for
+    the lambda once there are options to set.
 
 ## Testing
 

CONTRIBUTING.md

@@ -96,6 +96,38 @@ the squash commit that [release-please](./RELEASING.md) parses.
 5. Update `README.md`, JSDoc, and the relevant docs in `docs/` whenever
    behaviour changes.
 
+## Code review
+
+Every change reaches `master` through a pull request — there is no direct
+push path — and review has documented requirements:
+
+**How review is conducted.** Each PR is reviewed by (1) the required CI gate
+(`deno task ci`, the same gate you run locally), (2) the AI reviewers, which
+post a security assessment and a code-quality assessment as PR comments, and
+(3) a human maintainer, who reads the diff and every reviewer finding. AI
+findings are advisory: a maintainer addresses each one or answers it on the
+thread, quoting the finding's id — they never merge unexamined.
+
+**What must be checked.** Reviewers verify that the change:
+
+- is correct, and covered by tests per the testing policy above (unit +
+  integration in the same PR; e2e for cross-process or cross-OS behaviour);
+- introduces no security regression (injection, privilege escalation, secret
+  exposure — see the
+  [assurance case](./docs/assurance-case.md) for the boundaries to respect);
+- meets the coding standards above (strict types, no `any`/`as`/`!`, JSDoc on
+  all public symbols) and keeps coverage at 95%+;
+- updates the affected docs in the same PR, and regenerates the API docs on
+  any public-API change;
+- carries a Conventional Commit PR title, since the squash subject is what
+  release-please parses.
+
+**What is required to be acceptable.** A PR merges only when the required
+status checks are green, every AI-reviewer finding has been fixed or answered,
+and a maintainer approves. Larger features additionally get an adversarial
+review pass before the PR is finalized (see
+[`AGENTS.md`](./AGENTS.md#adversarial-review-every-feature)).
+
 ## Reporting bugs and requesting features
 
 - Search [existing issues](https://github.com/zuke-build/zuke/issues) first.

build/action_pins.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Where the pinned GitHub Action SHAs come from once the workflows are
  * generated: the root `action.yml` manifest, which the generator never writes.

build/action_release.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Versioning for the repository's own composite action — the `zuke-build/zuke`
  * listing on the GitHub Marketplace.

build/api_reference.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 // ---------------------------------------------------------------------------
 // api.json — structured API reference for the website (`./zuke apiReference`).
 //

build/core_floor.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * The `@zuke/core` version-floor check.
  *

build/docs.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Agent-doc generation: the project framing and options for `@zuke/docs`, the
  * per-package doc/doc-lint collectors, and the CLI-block injection that keeps

build/gitleaks_report.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Renders gitleaks' redacted JSON report as a job-summary table.
  *
@@ -106,10 +109,13 @@ function visible(ch: string): string {
 /**
  * Escape what would break out of a Markdown table cell: the pipe that separates
  * cells, and any control character that would end the row outright.
+ * Backslashes are escaped first, so a value's own backslash can neither pose
+ * as one of the escapes added here nor swallow the one added before a pipe.
  */
 function cell(value: string): string {
   if (value === "") return "—";
   return value
+    .replace(/\\/g, "\\\\")
     // deno-lint-ignore no-control-regex -- catching these is the point.
     .replace(/[\u0000-\u001f\u007f]/g, visible)
     .replace(/\|/g, "\\|");

build/hcl_gen.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Single-source generator for the Terraform and OpenTofu wrappers. `@zuke/tofu`
  * is a near-verbatim twin of `@zuke/terraform` — OpenTofu mirrors Terraform's

build/lock_check.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * The gate's lock-integrity check.
  *

build/packages.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Workspace package metadata: the ordered package list and the helpers that
  * read each package's entrypoints and declared version from its `deno.json`.

build/plugin_sync.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Syncs `skills/` into `plugins/zuke/skills/` as real, committed file copies
  * rather than a symlink: a symlink survives a POSIX clone, but a Windows

build/plugin_version_check.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * The gate's plugin-version check.
  *

build/pr_body_lint.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Lints a pull request body for the code fragments that break
  * release-please's conventional-commits parser (see `RELEASING.md`'s "Keep

build/publish.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Release/publish helpers: where build-time CLIs are installed, the on-demand
  * CLI installer, and the timeout-guarded JSR publish for one package.

build/scanners.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * The supply-chain scanners behind the `security` target, declared as pinned
  * toolchain entries so the build provisions them itself.

build/snippets.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Type-check the ```ts snippets in the docs and skills that are explicitly
  * marked for checking, so an example an agent pastes can't silently drift from

build/website_sync.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * The release → website sync: regenerate the docs the website consumes
  * (llms.txt / llms-full.txt + api.json), then open (or refresh) a PR against

build/website_tools.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * The landing page's package catalogue, and the generator that renders it into
  * the website's `src/data/tools.ts`.

build/workflows.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Zuke's own GitHub workflows, declared as targets to run.
  *

docs/README.md

@@ -55,6 +55,8 @@
 - [Security assurance case](./assurance-case.md) — the threat model, trust
   boundaries, and why the security requirements in
   [`SECURITY.md`](../SECURITY.md) are met.
+- [Security review](./security-review.md) — the performed security reviews:
+  scope, method, findings, and outcomes.
 - [How Zuke compares](./comparison.md) — a capability matrix against
   `deno task`, npm scripts, Make, Nx, Turborepo, and Dagger, on the capabilities
   Zuke provides.

docs/security-review.md

@@ -0,0 +1,65 @@
+# Security review
+
+The security reviews this project has performed: their scope, method,
+findings, and outcomes. Each review considers the security requirements and
+the trust boundaries defined in the
+[assurance case](./assurance-case.md) — the requirements say what must hold;
+a review checks that the implementation actually holds it.
+
+## 2026 review — MCP authorization and audit surface
+
+**When:** 2026 (pre-release adversarial pass). **Who:** the project lead, with
+independent AI adversarial reviewers attacking each dimension; every candidate
+finding was verified against the real code path before being accepted.
+
+**Scope:** the MCP server's authorization and audit surface — the boundary
+where an external AI agent is allowed to inspect and (optionally) execute
+build targets — reviewed against the requirements that authorization is
+enforced on every path and that secrets never reach output.
+
+**Method:** adversarial review as described in
+[`AGENTS.md`](../AGENTS.md#adversarial-review-every-feature): independent
+reviewers attempted bypasses, leaks, race conditions, unhandled throws, and
+untested security branches; findings were reproduced against the code
+(defaulting to refuted when a reproduction failed).
+
+**Confirmed findings, all fixed before the change shipped, each with a
+regression test:**
+
+1. An **authorization bypass** — a path that reached target execution without
+   passing the authorization check.
+2. A **secret-redaction gap** — a route by which a secret value could reach
+   output without being redacted.
+3. A **transport-crashing throw** — an unhandled error that could take down
+   the MCP transport, a denial-of-service defect.
+
+All three had passed lint, strict type-checking, and the 95% coverage gate —
+which is why the project treats adversarial review as a standing requirement
+for every feature, not a one-time event.
+
+## 2026 review — supply-chain posture and workflow surface
+
+**When:** August 2026. **Who:** the project lead with AI-assisted review.
+
+**Scope:** the CI/CD and release surface against the supply-chain security
+requirements: workflow token scopes, egress policy, action pinning, publish
+credentials, and the bootstrap path.
+
+**Outcome:** the posture documented in [`SECURITY.md`](../SECURITY.md) and
+justified in the [assurance case](./assurance-case.md) — least-privilege
+per-job tokens, blocked egress on write-scoped jobs, SHA-pinned actions,
+OIDC-only publishing with Sigstore provenance — plus the CodeQL workflow
+(security queries over the sources and the `actions` pack over the workflow
+YAML) added as a standing static-analysis lane, and the OpenSSF Scorecard
+run publishing its findings to code scanning. Documentation that had drifted
+from the implemented posture (the CodeQL setup guidance) was corrected as a
+finding of this review.
+
+## Standing review, between the point-in-time ones
+
+Every pull request receives an AI security assessment posted to the thread,
+CodeQL analysis, and the scanner gate (zizmor, actionlint, gitleaks); every
+feature receives the adversarial pass. The next dedicated review is due when
+a trust boundary moves — a new transport, a new credential, a new privilege —
+as the assurance case requires that document and this one move in the same
+pull request.

internal/hcl_tool.ts.tmpl

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 __MODULE_DOC__
 
 import { type Configure, runSettings, ToolSettings } from "@zuke/core/tooling";

packages/ai/mod.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * `@zuke/ai` — AI-powered code review for Zuke builds.
  *

packages/ai/src/agent_fixer.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * The fluent {@link AgentFixer} and the {@link agentFixer} factory — a
  * {@link "jsr:@zuke/core".Remediation} that delegates the actual fixing to a

packages/ai/src/apply.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Applying a {@link "./fix.ts".Fix}'s edits to the working tree, behind safety
  * guards: a path allowlist, a set of always-excluded paths, and a cap on the

packages/ai/src/assessment.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Turning a model's raw text response into a validated {@link Assessment}.
  *

packages/ai/src/budget.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * A token and cost budget for AI provider calls.
  *

packages/ai/src/cache.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * A filesystem-backed cache for AI provider responses.
  *

packages/ai/src/comment.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Posting a single overview comment to the pull/merge request via the active CI
  * host — shared by the AI fixer and the agent fixer. Keyed by the fixer's name

packages/ai/src/commit.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Committing applied fix edits and pushing them to the current branch. Used by
  * the {@link "./fixer.ts".AiFixer} when `.commitFixes()` is set so a healed PR

packages/ai/src/context.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Shared failure-context helpers used by both the structured {@link
  * "./fixer.ts".AiFixer} and the delegating {@link "./agent_fixer.ts".AgentFixer}:

packages/ai/src/dedup.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Identity resolution for reworded findings.
  *

packages/ai/src/diff.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Sourcing and filtering the unified diff a reviewer assesses.
  *

packages/ai/src/diff_suggest.ts

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 the Zuke contributors
+// SPDX-License-Identifier: MIT
+
 /**
  * Turn a unified `git diff` into GitHub inline {@link Suggestion}s — used by the
  * {@link "./agent_fixer.ts".AgentFixer} to render the changes an agent made as