docs: rework README around the product story + add community files

.gitattributes

@@ -0,0 +1,17 @@
+# Normalize line endings. The pipeline runs on Linux; shell scripts MUST stay LF
+# or they break on the runner. Keep repo text LF-normalized regardless of the OS
+# a contributor commits from (silences the CRLF warnings on Windows checkouts).
+* text=auto eol=lf
+
+# Explicitly LF for executable/interpreted files that are line-ending sensitive.
+*.sh   text eol=lf
+*.py   text eol=lf
+*.js   text eol=lf
+*.yml  text eol=lf
+*.yaml text eol=lf
+*.md   text eol=lf
+
+# Treat these as binary (no EOL munging, no diffs).
+*.pdf  binary
+*.png  binary
+*.jpg  binary

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+# Repo self-validation, distinct from the CodeWeave pipeline (codeweave.yml).
+# Runs on hosted runners and does NOT touch the target repo, secrets, or Copilot.
+# It exercises the deterministic tooling that decides every verdict, and lints the
+# pipeline's own workflow YAML and shell scripts.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  tools-tests:
+    name: Verdict-engine tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-dev.txt
+      - name: Run tooling tests
+        run: python -m pytest tests -q
+
+  lint-workflows:
+    name: Lint workflows & shell
+    runs-on: ubuntu-latest
+    # The pipeline's workflow shell is authored (and partly Copilot-generated) and
+    # already runs in production. We gate on genuine defects (shellcheck severity
+    # >= warning: unused vars, quoting bugs that change behavior, etc.), not on
+    # info/style advisories (SC2086 word-splitting hints, SC2129 redirect grouping,
+    # ...), which would be high-churn/low-value to rewrite blindly here. Raise the
+    # bar in a dedicated shell-hardening pass, not a docs PR.
+    env:
+      SHELLCHECK_OPTS: --severity=warning
+    steps:
+      - uses: actions/checkout@v4
+      - name: actionlint (GitHub Actions workflow linter, incl. embedded shellcheck)
+        uses: raven-actions/actionlint@v2
+        with:
+          fail-on-error: true
+      - name: shellcheck (standalone .sh scripts)
+        uses: ludeeus/action-shellcheck@master
+        with:
+          scandir: "."
+          severity: warning

.github/workflows/phase-2-adr.yml

@@ -249,7 +249,6 @@ jobs:
       - name: Generate navigation indexes
         id: build-indexes
         run: |
-          BOOK_INDEX_BUILT=0
           ADR_INDEX_BUILT=0
 
           node .github/scripts/generate-indexes.js --generate-adr-index 2>&1 | tee "proof/adr-index.md" || true
@@ -263,7 +262,6 @@ jobs:
             git add book/BOOK-INDEX.md
             if ! git diff --cached --quiet; then
               git commit -m "Phase 2: update BOOK-INDEX.md"
-              BOOK_INDEX_BUILT=1
             fi
           fi
 

.github/workflows/phase-5-6-build-baseline.yml

@@ -145,7 +145,6 @@ jobs:
             # Copilot AUTHORS integration-test/build-source.sh (read/write/edit only —
             # no shell needed); the workflow EXECUTES it directly so build output
             # streams into the job log and no tool permissions can block the build.
-            VENV_PY="$PWD/integration-test/${HARNESS_VENV_PYTHON:-.venv/bin/python}"
             BUILD_OK=false
             for ATTEMPT in $(seq 1 "${PHASE5_MAX_ITERATIONS}"); do
               if [ -f integration-test/build-error.md ]; then MODE=repair; else MODE=author; fi

CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to CodeWeave
+
+Thanks for your interest in CodeWeave. It is an experimental, research-grade
+automation pipeline, so the contributions that help most are the ones that make it
+more portable, more auditable, or more statistically rigorous. Please read this
+guide before opening an issue or a pull request.
+
+## Ways to contribute
+
+The most valuable areas are portability, measurement science, and reporting real
+behavior. On portability, CodeWeave is designed to run against any codebase by
+reading the target's toolchain from a manifest, and driving it end to end against a
+new kind of target (through the `integration-test/harness-manifest.json` seam) is
+the highest-leverage work available. On measurement science, the verdict logic
+lives in `integration-test/_tools/ab_compare.py`, and changes there should arrive
+with a written rationale and, ideally, a worked example. Reporting pipeline
+behavior is also genuinely useful: a phase that stalls, a gate that misfires, or a
+verdict that looks wrong all make good issues, as do clarifications to `docs/`, the
+`README.md`, or the executive summary.
+
+## Before you start
+
+CodeWeave runs as GitHub Actions workflows on a self-hosted runner rather than as a
+local command-line tool. There is no local install-and-test loop; changes are
+exercised by dispatching the workflows, as described in the
+[Quickstart](README.md#quickstart). Smoke-test structural changes cheaply with a
+dry run before a real run, because a dry run skips the Copilot invocations and the
+prerequisite checks:
+
+```bash
+gh workflow run codeweave.yml -f dry_run=true
+```
+
+The deterministic tooling under `integration-test/_tools/` is covered by tests you
+can run locally. Install the development dependencies and run the suite:
+
+```bash
+pip install -r requirements-dev.txt
+python -m pytest
+```
+
+## Reporting an issue
+
+A good report names the phase involved and the workflow that ran it, states what
+you expected against what actually happened, and includes the relevant `proof/`
+artifacts. Those artifacts, the generate and validate logs, the session
+transcripts, the gate diagnostics, and the measurement records, are the primary
+evidence for any pipeline behavior, so please attach or paste the relevant files
+rather than describing them from memory. Include the relevant parts of your
+`.github/codeweave.config` and your `constraints/` files as well, with anything
+sensitive redacted. Never include the values of the `COPILOT_TOKEN` or `PUSH_TOKEN`
+secrets.
+
+## Pull requests
+
+Use a descriptive branch prefix that matches the existing history, such as `docs/`,
+`pipeline/`, `config/`, or `work/`. Follow the repository's commit style: a subject
+line of the form `scope: imperative summary`, then a body that explains why. Keep
+one logical change per commit, and keep pull requests focused, so that a change to
+prompt files under `work/` stays separate from a change to workflow logic under
+`.github/workflows/`.
+
+One invariant matters above the rest. CodeWeave's whole premise is that generators
+propose and an independent, deterministic pipeline disposes, so any change must
+preserve that separation. An agent must never be able to certify its own phase as
+complete, and the pipeline must remain the single owner of commits and verdicts.
+Changes to the verdict logic in `ab_compare.py` or to the correctness gate should
+explain how they affect the trustworthiness of a verdict, in terms of significance,
+the noise floor, drift control, or the family-wise correction.
+
+## Code of conduct
+
+Be respectful and constructive. `[ADD CODE_OF_CONDUCT.md IF ADOPTING ONE]`
+
+## License
+
+By contributing, you agree that your contributions are licensed under the project's
+GNU General Public License v3.0 or later. See [`LICENSE`](LICENSE).