chore: add ASF source headers and a release header audit gate

.coderabbit.yaml

@@ -1,3 +1,20 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
 # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
 
 language: "en-US"

.git-blame-ignore-revs

@@ -11,3 +11,6 @@
 
 # style: apply Biome format baseline outside the UI surface (#415)
 # -> squash-commit hash added in a follow-up immediately after this PR lands.
+
+# chore: apply the ASF source header sweep (#3271)
+# -> squash-commit hash added in a follow-up immediately after this PR lands.

.github/ASF_SOURCE_HEADERS.md

@@ -0,0 +1,112 @@
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# ASF source header policy
+
+Apache Maka (Incubating) applies the [ASF source header policy](https://www.apache.org/legal/src-headers.html) to its source release and enforces it with an automated audit.
+
+`scripts/asf-license-headers.mjs` is the policy. This document explains it; the script decides it. Where the two disagree, the script is authoritative and this document is the bug.
+
+## What the audit asserts
+
+The audit states two properties of the tree it is pointed at, and nothing else:
+
+1. **Every entry is classified exactly once** — covered, excluded with a recorded reason, or an audit failure.
+2. **In every covered file the ASF license text occurs exactly once**, and that occurrence is the canonical rendering at the top of the file.
+
+Both are properties of the artifact. Neither is stated in terms of what `npm run write:asf-headers` produces, and that separation is deliberate: an audit defined as "the file starts with the bytes the writer emits" can only ever confirm its own writer. Such an audit accepts a second license block stacked on top of a first one it failed to recognize, because the block it just wrote is sitting at the top of the file.
+
+```sh
+npm run check:asf-headers          # audit; fails on anything unresolved
+npm run check:asf-headers -- --report
+npm run write:asf-headers          # insert the header where there is none
+```
+
+## Detection is loose, acceptance is strict
+
+Finding the license text and accepting it are different questions, so they use different tests.
+
+- **Detection** flattens comment punctuation and line wrapping away, then looks for the text. It finds a header written with `//`, in a JSDoc block, with `#`, inside an HTML comment, at any indentation, with an `https` license URL, or rewrapped into one paragraph.
+- **Acceptance** is byte-exact: the canonical rendering, first in the file apart from a shebang, an HTML doctype, or Markdown front matter.
+
+A covered file is therefore in one of four states, and only the first is one a program may act on:
+
+| State | Meaning | What happens |
+| --- | --- | --- |
+| `absent` | no license text anywhere | `write` inserts the header |
+| `canonical` | exactly one occurrence, canonical, at the top | passes |
+| `unrecognized` | one occurrence, but not the canonical rendering at the top | audit fails; `write` refuses |
+| `duplicated` | more than one occurrence | audit fails; `write` refuses |
+
+`write` only ever inserts. Reconciling an existing header written in another form means deciding what someone else's rendering meant, and that is not a decision to make in a mechanical sweep.
+
+## Where the audit runs
+
+- **Every pull request**, over the checkout. This keeps new files from landing without a header.
+- **`Prepare ASF source candidate`**, over the extracted `apache-maka-<version>-incubating-src.tar.gz`, before anything is installed or built into that tree. The release gate therefore reads the exact bytes a voter downloads.
+
+In a checkout the audit reads tracked files plus untracked files Git would not ignore, so a new file is audited before it is ever staged while ignored local scratch files stay out of the gate. An extracted archive has no index, so **every entry on disk is audited and none is skipped by name**. A file inside a `dist/` or `release/` directory in a source candidate is not something to audit around — it is unclassified, and the gate says so. An entry that is neither a directory nor a regular file is reported rather than passed over.
+
+## Covered file types
+
+| Comment syntax | Extensions |
+| --- | --- |
+| `/* … */` | `.cjs`, `.css`, `.js`, `.mjs`, `.mts`, `.rs`, `.swift`, `.ts`, `.tsx` |
+| `//` | `.jsonc` |
+| `#` | `.ps1`, `.py`, `.sh`, `.toml`, `.yaml`, `.yml`, `Dockerfile`, `network-policy` |
+| `<!-- … -->` | `.html`, `.md` |
+
+## Reviewed exclusions
+
+Each rule is a category with a justification. A rule **names the files it excludes, or states a structural property** that holds for anything it matches. A bare directory prefix does neither: it lends its justification to whatever is added to that directory next, which is the failure this audit exists to prevent. `npm run check:asf-headers -- --report` prints the resolved file list for every rule.
+
+| Rule | Why the header does not belong |
+| --- | --- |
+| `not-in-source-release` | `export-ignore` in `.gitattributes` keeps these out of the archive: repository-local agent configuration, visual review evidence, and incubation working notes. |
+| `asf-release-documents` | `LICENSE`, `NOTICE`, and `DISCLAIMER-WIP` are the license and notice themselves. |
+| `third-party-license-texts` | Verbatim upstream license and notice texts. They must stay byte-identical to what upstream published, and the executor preparation scripts verify their digests. |
+| `maka-authored-legal-notices` | Notices Maka publishes about a bundled third-party runtime, addressed to the recipient of a binary rather than to a reader of source. |
+| `third-party-source` | Third-party work under its own license, including mixed-origin files Maka adapted from upstream. See below. |
+| `generated-files` | Mechanically derived and byte-compared against a fresh generator run, so a hand-written header would be reverted by the next regeneration. The generators carry the header. |
+| `verbatim-runtime-payloads` | Bundled skill payloads are embedded in the generated catalog verbatim, pinned by content digest, and delivered to the model as instructions. Each payload is listed by name. |
+| `verbatim-github-templates` | GitHub copies the pull request template into every new pull request description. |
+| `byte-significant-fixtures` | Recorded inputs and captured historical state, asserted on byte-for-byte or parsed by a strict reader. |
+| `no-comment-syntax` | JSON and CSV have no comment syntax; a header could only be added by corrupting the file for its parser. |
+| `binary-files` | Binary content cannot carry a text header. |
+| `no-creative-content` | Version-control metadata and platform manifests whose content is a list of names or required platform keys. Apache RAT excludes the same kind of file by default. |
+
+## Third-party and mixed-origin source
+
+[ASF policy](https://www.apache.org/legal/src-headers.html#3party) treats the portion of a file that was not contributed by the copyright owner as third-party work. A file Maka adapted from an upstream project is therefore not Maka's to license wholly, and a mechanical sweep may not assert a whole-file ASF header over one. Whether a heavily modified file should instead carry a combined header is a PPMC decision, taken case by case.
+
+Such files are excluded here and their attribution belongs to `LICENSE` and the `NOTICE` audit, not to this gate.
+
+## Unreviewed provenance
+
+This gate cannot determine provenance — that is a fact about people, not a property of a path — but it can refuse to let an unreviewed claim of it through. A covered file that carries an SPDX identifier, an explicit copyright line, or an adaptation notice fails the audit unless it appears in `reviewedProvenance` with the decision that nonetheless put an ASF header on it.
+
+The markers are deliberately narrow, chosen by measuring them against the whole tree. Those three hit three files between them. `derived from` hits seventy, and an upstream project name such as `opencode` hits forty-five, because Maka supports it as a provider; a net that noisy gets answered with a list of paths added to quiet it, which is the outcome this rule exists to avoid.
+
+This is a net, not a proof. It catches a file that states its origin. It cannot catch prose that merely alludes to one.
+
+## Changing the policy
+
+Adding a file type means adding it to `coveredExtensions` or `coveredNames` and running `npm run write:asf-headers`.
+
+Adding an exclusion means adding a rule with an `id` and a `justification` that a mentor can evaluate without reading the code around it. "The audit failed on it" is not a justification. If a file is source that Maka wrote, it gets the header.

.github/ASF_SOURCE_RELEASE.md

@@ -1,3 +1,22 @@
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
 # Apache Maka source release runbook
 
 This runbook prepares the official Apache Incubator source-release component.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,3 +1,20 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
 name: Bug report
 description: Report a defect in Maka (Desktop, TUI/CLI, Runtime Host, or Eval)
 labels: ["bug"]

.github/ISSUE_TEMPLATE/config.yml

@@ -1,3 +1,20 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
 blank_issues_enabled: true
 contact_links:
   - name: Report a security vulnerability

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,3 +1,20 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
 name: Feature request
 description: Propose an improvement or new capability for Maka
 labels: ["enhancement"]

.github/RELEASE_CHECKLIST.md

@@ -1,3 +1,22 @@
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
 # Product release checklist
 
 The `Release` workflow is Maka's convenience-artifact release entry point. Desktop, CLI/TUI, and

.github/copilot-instructions.md

@@ -1,3 +1,22 @@
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
 # Code Review
 
 When reviewing a pull request, always apply

.github/dependabot.yml

@@ -1,3 +1,20 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
 version: 2
 updates:
   - package-ecosystem: npm

.github/skills/code-review/SKILL.md

@@ -2,6 +2,24 @@
 name: code-review
 description: Adversarially review pull requests and code changes against the actual problem. Use for GitHub Copilot code review to assess correctness, root cause, simplicity, deletions, test quality, maintainability, and merge readiness.
 ---
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
 
 # Adversarial Code Review
 

.github/workflows/asf-source-candidate.yml

@@ -1,3 +1,20 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
 name: Prepare ASF source candidate
 
 on:
@@ -73,6 +90,13 @@ jobs:
             --strip-components=1 \
             -C candidate-source
 
+      # Runs before anything installs or builds into the extracted tree, so the
+      # audit classifies the exact bytes a voter downloads. It fails on a file
+      # that carries no header and matches no reviewed exclusion.
+      - name: Audit source headers in the extracted candidate
+        working-directory: candidate-source
+        run: npm run check:asf-headers -- --report
+
       - name: Install from the committed lockfile
         working-directory: candidate-source
         run: npm ci