From b0b16d2a25404a843dfef01d0bed6c0e55bf189f Mon Sep 17 00:00:00 2001 From: Randy Northrup Date: Mon, 28 Sep 2026 10:33:33 -0700 Subject: [PATCH 1/6] README: how this extension is built The owner, Claude Code as lead engineer, up to four headless Muse Code builders on the contributor model, Grok Build as the pre-push reviewer and Codex on the pull request, one defect class at a time, and the gates on dedicated test machines and CI. Co-Authored-By: Claude Opus 5.5 (1M context) --- CHANGELOG.md | 4 ++++ README.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index bf6b2fe44..6eed1bb81 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,10 @@ happened, not what was planned; superseded entries are kept. ### Changed +- **README: How this extension is built** (Development): the owner, Claude + Code as lead, up to four headless Muse Code builders on the contributor + model, Grok Build and Codex as reviewers, and the gates on dedicated test + machines and CI. - **Every paid use asks first, in a popup** (M58, PLAN.md D48): **Allow once**, **Allow always in this workspace**, or **Deny**, in every permission mode, Bypass included. It covers each image (on either diff --git a/README.md b/README.md index 5f063373b..878834731 100644 --- a/README.md +++ b/README.md @@ -1728,6 +1728,36 @@ published. - **Webview is blank after a change** — run `npm run build:dev` (F5 does this via the pre-launch task) and reload the window. +### How this extension is built + +The extension is developed by a small team of AI agents under one human +owner, with every change held to the same gates as a human pull request. + +- **The owner** sets the plan (`PLAN.md`), makes the product decisions, and + approves anything that spends money, signs in or publishes. +- **Claude Code** is the lead engineer: it turns the plan into briefs, + builds the harder milestones itself (security-sensitive and stateful + work), verifies every review finding in the code, and merges. +- **Muse Code, the product's own backend, builds too.** Up to four + headless `muse exec` instances build well-scoped milestones in their own + git worktrees, on the Muse Spark contributor model. Their work goes + through exactly the same review and gates. +- **Reviewers.** Each change is reviewed before it is pushed, one defect + class at a time (concurrency and lifecycle; wire evidence, validation and + security; failure paths, honesty and docs). **Grok Build** runs that + review on a test machine, read-only and in plan mode. On the pull + request, **Codex** reviews again. A finding is fixed with every sibling + of its class in one commit, and a change that reaches a third review + round is redesigned instead of patched. +- **Gates.** `npm run quality` runs on dedicated test machines (Linux and + macOS) so builds never compete with the owner's workstation, then CI runs + it again on Ubuntu, Windows and macOS. Every guard added gets a red + drill: it is broken on purpose, its test must fail, and the file is + restored byte for byte (recorded in `docs/certification/`). +- **Evidence.** Anything parsed from Muse Code or the Model API comes from a + live capture (AGENTS.md rule 13), and live checks run on the contributor + model in an empty workspace, with their model calls counted. + ## Support this project If Muse Spark Code saves you time, you can From 0d2889c982c23a07606097af54846f74d86351a7 Mon Sep 17 00:00:00 2001 From: Randy Northrup Date: Mon, 28 Sep 2026 10:50:22 -0700 Subject: [PATCH 2/6] README: say what the gates and drills actually cover Grok Build's review of this PR: CI runs quality:gates (the accessibility gate, gitleaks and semgrep are their own jobs), the full npm run quality runs on the test machine, the third-round redesign rule is new, and the certification records list what was not drilled. Co-Authored-By: Claude Opus 5.5 (1M context) --- README.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 878834731..2827c01d7 100644 --- a/README.md +++ b/README.md @@ -1745,15 +1745,20 @@ owner, with every change held to the same gates as a human pull request. - **Reviewers.** Each change is reviewed before it is pushed, one defect class at a time (concurrency and lifecycle; wire evidence, validation and security; failure paths, honesty and docs). **Grok Build** runs that - review on a test machine, read-only and in plan mode. On the pull - request, **Codex** reviews again. A finding is fixed with every sibling - of its class in one commit, and a change that reaches a third review - round is redesigned instead of patched. -- **Gates.** `npm run quality` runs on dedicated test machines (Linux and - macOS) so builds never compete with the owner's workstation, then CI runs - it again on Ubuntu, Windows and macOS. Every guard added gets a red - drill: it is broken on purpose, its test must fail, and the file is - restored byte for byte (recorded in `docs/certification/`). + review on a test machine, limited to reading files and inspecting git. + On the pull request, **Codex** reviews again. A finding is fixed with + every sibling of its class in one commit. Since September 2026, a change + that reaches a third review round is redesigned instead of patched + (earlier milestones, such as M45, went through more patch rounds). +- **Gates.** The full `npm run quality` (with the accessibility gate, the + secret scan and semgrep) runs on a dedicated test machine, Linux or + macOS, so it never competes with the owner's workstation; the + PowerShell lint runs only on Windows. CI then runs `quality:gates` on + Ubuntu, Windows and macOS, and the other gates as the jobs listed above. + A milestone's guards get red drills: each guard is broken on purpose, its + test must fail, and the file is restored byte for byte. The milestone's + record in `docs/certification/` lists the drills, and anything it did + not drill. - **Evidence.** Anything parsed from Muse Code or the Model API comes from a live capture (AGENTS.md rule 13), and live checks run on the contributor model in an empty workspace, with their model calls counted. From 37ea35e94f2383392f3b67db740a748da494fd63 Mon Sep 17 00:00:00 2001 From: Randy Northrup Date: Mon, 28 Sep 2026 11:23:03 -0700 Subject: [PATCH 3/6] README: qualify the evidence claims Codex on PR #56: early milestones used Meta's documented shapes or a fake server without a live check (M7, M44), and some live checks ran in workspaces with stored sessions or project rules; say so. Co-Authored-By: Claude Opus 5.5 (1M context) --- README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2827c01d7..5835e2d87 100644 --- a/README.md +++ b/README.md @@ -1759,9 +1759,12 @@ owner, with every change held to the same gates as a human pull request. test must fail, and the file is restored byte for byte. The milestone's record in `docs/certification/` lists the drills, and anything it did not drill. -- **Evidence.** Anything parsed from Muse Code or the Model API comes from a - live capture (AGENTS.md rule 13), and live checks run on the contributor - model in an empty workspace, with their model calls counted. +- **Evidence.** Under AGENTS.md rule 13, a shape parsed from Muse Code or + the Model API is written from a live capture; each certification record + names its capture, or says where a shape came from Meta's documentation + or a fake server without a live check (as early milestones such as M7 + and M44 did). Live checks run on the contributor model in throwaway + workspaces, with their model calls counted. ## Support this project From c6e3b8ba4ef73a138caed3c73779e7d38e24aa3d Mon Sep 17 00:00:00 2001 From: Randy Northrup Date: Mon, 28 Sep 2026 11:26:08 -0700 Subject: [PATCH 4/6] README: describe the build process as it runs since September 2026 Codex's third round on PR #56 found more historical claims the records contradict, so the section is restructured instead of patched: it describes the current process and points to each milestone's certification record for what was run, including earlier milestones. It also records that the test machines run quality:gates, the secret scan and semgrep, with the accessibility gate run locally for the screens a change touches, and that Muse drafts are checked and finished by a Claude Code agent. Co-Authored-By: Claude Opus 5.5 (1M context) --- README.md | 53 ++++++++++++++++++++++++++--------------------------- 1 file changed, 26 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 5835e2d87..8f53c691e 100644 --- a/README.md +++ b/README.md @@ -1730,8 +1730,10 @@ published. ### How this extension is built -The extension is developed by a small team of AI agents under one human -owner, with every change held to the same gates as a human pull request. +Since September 2026 the extension has been developed by a small team of AI +agents under one human owner. This describes that process; each milestone's +record in `docs/certification/` says what was actually run for it, +including how earlier milestones were checked. - **The owner** sets the plan (`PLAN.md`), makes the product decisions, and approves anything that spends money, signs in or publishes. @@ -1739,32 +1741,29 @@ owner, with every change held to the same gates as a human pull request. builds the harder milestones itself (security-sensitive and stateful work), verifies every review finding in the code, and merges. - **Muse Code, the product's own backend, builds too.** Up to four - headless `muse exec` instances build well-scoped milestones in their own - git worktrees, on the Muse Spark contributor model. Their work goes - through exactly the same review and gates. -- **Reviewers.** Each change is reviewed before it is pushed, one defect - class at a time (concurrency and lifecycle; wire evidence, validation and - security; failure paths, honesty and docs). **Grok Build** runs that - review on a test machine, limited to reading files and inspecting git. - On the pull request, **Codex** reviews again. A finding is fixed with - every sibling of its class in one commit. Since September 2026, a change - that reaches a third review round is redesigned instead of patched - (earlier milestones, such as M45, went through more patch rounds). -- **Gates.** The full `npm run quality` (with the accessibility gate, the - secret scan and semgrep) runs on a dedicated test machine, Linux or - macOS, so it never competes with the owner's workstation; the - PowerShell lint runs only on Windows. CI then runs `quality:gates` on - Ubuntu, Windows and macOS, and the other gates as the jobs listed above. - A milestone's guards get red drills: each guard is broken on purpose, its - test must fail, and the file is restored byte for byte. The milestone's - record in `docs/certification/` lists the drills, and anything it did - not drill. + headless `muse exec` instances draft well-scoped milestones in their own + git worktrees, on the Muse Spark contributor model; a Claude Code agent + checks and finishes each draft, and it goes through the same review and + gates. +- **Reviewers.** A change is reviewed before it is pushed, one defect class + at a time (concurrency and lifecycle; wire evidence, validation and + security; failure paths, honesty and docs), by **Grok Build** on a test + machine (reading files and inspecting git only) or by Claude Code review + agents. On the pull request, **Codex** reviews again. A finding is fixed + with every sibling of its class in one commit, and a change that reaches + a third review round is redesigned instead of patched. +- **Gates.** `quality:gates`, the secret scan and semgrep run on a + dedicated test machine (Linux or macOS) so they never compete with the + owner's workstation; the accessibility gate runs locally for the screens + a change touches, and the PowerShell lint only on Windows. CI then runs + `quality:gates` on Ubuntu, Windows and macOS, and the other gates as the + jobs listed above. A milestone's new guards get red drills: each guard is + broken on purpose, its test must fail, and the file is restored byte for + byte; the record lists the drills and anything not drilled. - **Evidence.** Under AGENTS.md rule 13, a shape parsed from Muse Code or - the Model API is written from a live capture; each certification record - names its capture, or says where a shape came from Meta's documentation - or a fake server without a live check (as early milestones such as M7 - and M44 did). Live checks run on the contributor model in throwaway - workspaces, with their model calls counted. + the Model API is written from a live capture, and the record names it. + Live checks run on the contributor model in throwaway workspaces and + record their model-call counts. ## Support this project From e9ebe7aad7ee658821d4a43a0bf967bbd87c9aa5 Mon Sep 17 00:00:00 2001 From: Randy Northrup Date: Mon, 28 Sep 2026 11:30:51 -0700 Subject: [PATCH 5/6] README: exact date for the build process, and how the gates run today Codex on PR #56: 'since September 2026' covers the whole project, so the section now dates the process to 2026-09-28 and names earlier records' differences; it states that AGENTS.md requires npm run quality and how its parts run while headless Chrome is unreliable on the test machines. Co-Authored-By: Claude Opus 5.5 (1M context) --- README.md | 36 +++++++++++++++++++++--------------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 8f53c691e..8d29bc7eb 100644 --- a/README.md +++ b/README.md @@ -1730,10 +1730,12 @@ published. ### How this extension is built -Since September 2026 the extension has been developed by a small team of AI -agents under one human owner. This describes that process; each milestone's -record in `docs/certification/` says what was actually run for it, -including how earlier milestones were checked. +The extension is developed by a small team of AI agents under one human +owner. The process below has been in use since 2026-09-28. Each milestone's +record in `docs/certification/` says what was actually run for it; the +records of milestones before that date describe their own checks, which +sometimes differed (for example, M7 was certified against a fake server and +M44 took a response shape from Meta's documentation). - **The owner** sets the plan (`PLAN.md`), makes the product decisions, and approves anything that spends money, signs in or publishes. @@ -1752,18 +1754,22 @@ including how earlier milestones were checked. agents. On the pull request, **Codex** reviews again. A finding is fixed with every sibling of its class in one commit, and a change that reaches a third review round is redesigned instead of patched. -- **Gates.** `quality:gates`, the secret scan and semgrep run on a - dedicated test machine (Linux or macOS) so they never compete with the - owner's workstation; the accessibility gate runs locally for the screens - a change touches, and the PowerShell lint only on Windows. CI then runs - `quality:gates` on Ubuntu, Windows and macOS, and the other gates as the - jobs listed above. A milestone's new guards get red drills: each guard is - broken on purpose, its test must fail, and the file is restored byte for - byte; the record lists the drills and anything not drilled. +- **Gates.** AGENTS.md requires `npm run quality` to pass before a commit. + Its parts other than the accessibility suite (`quality:gates`, the secret + scan and semgrep) run on a dedicated test machine, Linux or macOS, so they + never compete with the owner's workstation. Headless Chrome does not yet + run reliably on those machines, so for now the accessibility suite runs + in CI (Ubuntu and Windows) on every pull request, and locally for the + screens a change touches. The PowerShell lint runs only on Windows. CI + also runs `quality:gates` on Ubuntu, Windows and macOS, and the other + gates as the jobs listed above. A milestone's new guards get red drills: + each guard is broken on purpose, its test must fail, and the file is + restored byte for byte; the record lists the drills and anything not + drilled. - **Evidence.** Under AGENTS.md rule 13, a shape parsed from Muse Code or - the Model API is written from a live capture, and the record names it. - Live checks run on the contributor model in throwaway workspaces and - record their model-call counts. + the Model API is written from a live capture, and the record names it or + says it did not have one. Live checks run on the contributor model in + throwaway workspaces and record their model-call counts. ## Support this project From defa4dab9728259f3571afdb0199fe2420f17176 Mon Sep 17 00:00:00 2001 From: Randy Northrup Date: Mon, 28 Sep 2026 12:04:16 -0700 Subject: [PATCH 6/6] README: one complete npm run quality on a test machine before each push All three test machines (Windows 11 VM, Kubuntu VM, Mac mini) now run the whole gate, accessibility suite included; the PowerShell lint runs on the Windows one. Co-Authored-By: Claude Opus 5.5 (1M context) --- README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 8d29bc7eb..7cb5660c5 100644 --- a/README.md +++ b/README.md @@ -1754,18 +1754,18 @@ M44 took a response shape from Meta's documentation). agents. On the pull request, **Codex** reviews again. A finding is fixed with every sibling of its class in one commit, and a change that reaches a third review round is redesigned instead of patched. -- **Gates.** AGENTS.md requires `npm run quality` to pass before a commit. - Its parts other than the accessibility suite (`quality:gates`, the secret - scan and semgrep) run on a dedicated test machine, Linux or macOS, so they - never compete with the owner's workstation. Headless Chrome does not yet - run reliably on those machines, so for now the accessibility suite runs - in CI (Ubuntu and Windows) on every pull request, and locally for the - screens a change touches. The PowerShell lint runs only on Windows. CI - also runs `quality:gates` on Ubuntu, Windows and macOS, and the other - gates as the jobs listed above. A milestone's new guards get red drills: - each guard is broken on purpose, its test must fail, and the file is - restored byte for byte; the record lists the drills and anything not - drilled. +- **Gates.** AGENTS.md requires `npm run quality` to exit 0 before a + commit is proposed. Every commit is gated before it is pushed: one + complete `npm run quality` run (formatting, lint, types, tests with + coverage, the accessibility suite, the secret scan and semgrep) on one of + three dedicated test machines (a Windows 11 virtual machine, a Kubuntu + virtual machine and a Mac mini), so it never competes with the owner's + workstation. The PowerShell lint runs only on Windows, so a change to a + PowerShell script gets its run there. CI then runs `quality:gates` on + Ubuntu, Windows and macOS, and the other gates as the jobs listed above. + A milestone's new guards get red drills: each guard is broken on purpose, + its test must fail, and the file is restored byte for byte; the record + lists the drills and anything not drilled. - **Evidence.** Under AGENTS.md rule 13, a shape parsed from Muse Code or the Model API is written from a live capture, and the record names it or says it did not have one. Live checks run on the contributor model in