docs: rework README around the product story + add community files - #3
Merged
Conversation
Reframe the README from workflow reference documentation into a conversion-focused product story: - Lead with a one-sentence value proposition and three concrete, evidence-backed proof points (correctness gate, statistical verdict, auditable proof/ trail) instead of an implementation walkthrough. - Add an "in action" first screen: minimal config + single dispatch, and the five terminal verdict states. - Add vision, jobs-to-be-done use cases, a shortest-path quickstart with an explicit "aha" moment, outcome-oriented capabilities, a simplified how-it-works with Mermaid diagrams, and a fair comparison table. - Separate working / experimental / planned functionality and add a maturity warning. - Mark unverified facts with explicit placeholders (benchmarks, demo, portability, community files) rather than inventing them. Preserves the prior reference material in docs/ and executive-summary.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add the community and trust files the README references, grounded in the actual pipeline rather than boilerplate: - CONTRIBUTING.md: how to exercise a workflows-only project (dry-run first), what a good proof/-backed report contains, and the core invariant contributors must preserve (generators propose, the independent pipeline disposes; no self-certification). - SECURITY.md: private vulnerability reporting, plus concrete credential handling for COPILOT_TOKEN / PUSH_TOKEN and the self-hosted runner that holds them. - ROADMAP.md: now/next/later framed around publishing a real run, portability via the harness-manifest seam, and making energy a gating signal. Placeholders remain only for facts that require a human decision (security contact, response SLA, code of conduct). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace the [ADD ...] placeholders in the README community section with links to CONTRIBUTING.md, SECURITY.md, ROADMAP.md, and the issues tab. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
ab_compare.py writes markdown containing non-ASCII (the Delta and CO2 symbols) via open(path, 'w') with no explicit encoding. That works on the Linux runner (UTF-8 locale) but crashes under any default codec that isn't UTF-8 (e.g. cp1252 on Windows) with UnicodeEncodeError — a latent portability defect in the code that produces every verdict. Surfaced by the new verdict-engine test suite. Make all file I/O in ab_compare.py, op_microbench.py, and diff_fuzz.py explicitly encoding='utf-8' for reads and writes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
ab_compare.py is the single source of truth for every KEEP / INVESTIGATE / REVERT verdict, and had no tests. Add tests/tools/test_ab_compare.py covering: - compute_stats (empty, single, known-value, zero-mean guard) - the directional decision table for both measurement paths, incl. the noise-floor gate (significant-but-sub-MDE must not KEEP), micro corroboration, regression priority, and the microbench 'no primary signal -> REVERT' rule - Holm-Bonferroni step-down (known thresholds, monotone failure, input-order preservation) - micro_comparison significance (raw-sample t-test, unknown-without-samples, sub-floor delta) - baseline / compare / family CLI modes end to end on synthetic records, incl. stale-format rejection and a KEEP demoted by the family-wise correction Add pytest.ini (scopes CI to repo tooling, not the generated target harness) and requirements-dev.txt (pinned pytest/numpy/scipy). All 31 pass locally on Python 3.12. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add .github/workflows/ci.yml (hosted-runner CI, separate from the CodeWeave pipeline and touching no secrets/target/Copilot): runs the verdict-engine tests on every push and PR, and lints the pipeline's own workflow YAML (actionlint) and shell scripts (shellcheck). Add .gitattributes to LF-normalize repo text — the pipeline runs on Linux and its shell scripts must stay LF — which also silences the CRLF churn on Windows checkouts. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add a truthful 'Tested' line to the project status: the verdict engine is now covered by a unit + integration suite run in CI. Does not change the overall experimental status — the remaining blockers (a published run, second-target portability) are empirical. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The first CI run flagged 23 shellcheck findings in the existing pipeline workflows: 21 info/style advisories + 2 warning-level unused variables. - Remove the two genuinely dead variables (real fixes, no behavior change): BOOK_INDEX_BUILT in phase-2-adr.yml (its sibling ADR_INDEX_BUILT is the one echoed to GITHUB_OUTPUT) and the shadowed VENV_PY assignment in the Phase 5 block of phase-5-6-build-baseline.yml (the used copy is re-declared in the Phase 6 block). - Gate shellcheck at severity>=warning (SHELLCHECK_OPTS) so info/style hints on the already-in-production pipeline shell don't block, while real defects still fail CI. Rewriting the 21 advisories belongs in a dedicated shell-hardening pass, not a docs PR. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…e design pillars Reframe the documentation around what CodeWeave is actually for: finding energy and CO2 hotspots and shipping proven-real efficiency fixes. - Lead with the energy/carbon objective; keep the honest note that energy is the target and per-iteration latency is the resolvable lever. - Present CodeWeave as language- and stack-agnostic (toolchain read from a manifest); remove target-specific framing and examples from the docs. The config defaults and constraints still describe a concrete target and are left to a separate change. - Add a 'What CodeWeave takes seriously' section making three deliberate design pillars explicit: statistical proof embedded in the acceptance path, the quality of the context built before any change, and integration tests reverse-engineered from the real system. - Convert the docs to flowing prose and remove em-dashes throughout. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The context CodeWeave builds to optimize a system safely (the architecture book, the committed ADRs, the grounded harness) is a durable artifact that outlives the run. Frame this as a second goal in the vision and reframe the 'inherited codebase' use case around recovering effectively-unmaintainable software and paying down technical debt. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Reworks the README from workflow-reference documentation into a conversion-focused product story, and adds the community/trust files it references.
Commits
proof/trail); adds an "in action" first screen, vision, jobs-to-be-done use cases, a shortest-path quickstart with an explicit "aha" moment, outcome-oriented capabilities, Mermaid how-it-works diagrams, a fair comparison table, and a status/maturity section. Unverifiable facts are marked with explicit[ADD ...]/[VERIFY ...]placeholders rather than invented.proof/-backed reports, PAT scoping and self-hosted-runner trust, a now/next/later roadmap around publishing a real run and portability via theharness-manifest.jsonseam).The prior per-phase reference material is preserved in
docs/andexecutive-summary.md, which the README now links to.Remaining placeholders (need a human)
proof/trail + Phase 8 report with a realKEEPverdict) and a demo asset — the two biggest credibility gaps.SECURITY.md.Testing
Docs-only change; no workflow logic touched.
🤖 Generated with Claude Code