Merge pull request #91 from simplycubed/docs/audit-fixes

docs: fix what the docs claimed, and document what shipped

Author: charlesgreen

README.md

@@ -1,8 +1,20 @@
 # SimplyCubed Code
 
+[![An agent that runs in your GitHub, not ours. Open source. Your runners, your secrets. A human merges.](docs/assets/simplycubed-code.png)](https://simplycubed.com/code?utm_source=github&utm_medium=readme&utm_campaign=code)
+
 An autonomous coding agent that lives inside your own GitHub. You file an issue, it opens a pull request, and a human decides whether to merge.
 
-> Status: beta. `v0.1.6` is the latest release; expect rough edges. Product overview: [simplycubed.com/code](https://simplycubed.com/code?utm_source=github&utm_medium=readme&utm_campaign=code). See [Status](#status).
+> Beta, at `v0.1.6`. Product overview: [simplycubed.com/code](https://simplycubed.com/code?utm_source=github&utm_medium=readme&utm_campaign=code). See [Status](#status).
+
+### Try it without letting it write anything
+
+```sh
+simplycubed run owner/repo#12 --dry-run
+```
+
+That runs the whole loop, including the model and your own gate. It makes no GitHub writes and never pushes; it prints what it would have done instead.
+
+`simplycubed init --workflow` also writes a self-test into your repository. Dispatch it once and it checks, in your own runner, that the App token resolves to a bot, that it can read what it needs, and that it is denied Actions administration. The install fails if that denial does not hold. Delete the workflow once it passes.
 
 ## What it is
 
@@ -22,7 +34,7 @@ The loop is issue to pull request, driven entirely through GitHub.
 4. A human reviews. If they request changes, a fixer role reads the feedback, makes the changes, re-runs the gate, and pushes back to the same pull request for another look. Only feedback left against the current head is addressed, so the loop never re-litigates a comment it already handled.
 5. A human merges. The agent does not.
 
-A separate read-only reviewer role is defined in the code but is not yet wired into the loop, so today the review in step 4 is the human's. The roadmap below tracks it.
+An automated reviewer runs before step 4 if you turn it on (`review: true`, off by default). It comments; it never approves and never merges. Step 5 is a human either way.
 
 ### Label lifecycle
 
@@ -45,10 +57,44 @@ You can also drive it by comment, addressed to the bot at the start of a line:
 
 Only comments from people with write access are acted on, and only a comment that begins with the mention counts, so quoting an earlier comment never re-triggers a run. Note that a plain pull-request comment is not a review: to run the fixer from a review, submit it through **Files changed → Review changes**.
 
+### What triggers a run
+
+```mermaid
+flowchart LR
+    L["issue labelled sc:go"] --> R["run job"]
+    V["review submitted<br/>OWNER, MEMBER or COLLABORATOR"] --> A["address job"]
+    C["comment starting with<br/>@simplycubed-code"] --> P{"verb?"}
+
+    R --> RC["simplycubed run"]
+    A --> AC["simplycubed address"]
+    P -->|"go"| RC
+    P -->|"address"| AC
+    P -->|"help"| H["prints the commands"]
+    P -->|"anything else"| N["nothing"]
+
+    RC --> PR["pull request opens<br/>a human merges it"]
+    AC --> PR
+```
+
+A plain comment in the conversation box is not a review. To run the fixer from a review, submit it through **Files changed → Review changes**. Every path checks that the person has write access before anything else happens.
+
 ## Running in your own GitHub
 
 The whole thing runs on GitHub Actions, event-driven, with no server and no VM for SimplyCubed to operate. When you install the app and file issues, the work executes on your runners inside your organization.
 
+### What it can do to your repo, and what stops it
+
+It can open a pull request against a branch. That is the strongest action available to it.
+
+What stops it, roughly in order of how much you should trust each one:
+
+1. **It cannot merge, by construction.** The GitHub interface it is built against has no merge method: see [`internal/forge/forge.go`](internal/forge/forge.go). The model is not being asked to follow a rule here. The capability is absent from the code.
+2. The App holds three permissions: contents, pull requests, issues. Not workflows, administration, environments, or secrets. Each job mints its own token, scoped to one repository.
+3. That scope is proved on every run rather than claimed. The workflow calls an Actions-administration endpoint and expects the denial, so your run log carries the evidence.
+4. **The model's shell never holds a GitHub token.** `GH_TOKEN` and `GITHUB_TOKEN` are stripped from the engine's environment before it starts.
+5. Neither engine's "dangerous" bypass flag is set. When a change cannot be made under those constraints, the run stops and a human finishes it. [Why](docs/faq.md).
+6. No deploy credentials, and no path to production. Your branch protection rules decide what happens once the pull request exists.
+
 What this buys you:
 
 - Your code stays in your repos. SimplyCubed never receives it.
@@ -160,7 +206,7 @@ gate: make check
 engine: claude
 ```
 
-The first engine adapter targets the Codex CLI running against Azure OpenAI. Today the shipped setup needs an Azure endpoint, an API key, and optionally a deployment name override if you are not using the default `gpt-5.4`. A Claude Code adapter is planned. The `Runner` interface is the seam where other engines plug in.
+The first engine adapter targets the Codex CLI running against Azure OpenAI. Today the shipped setup needs an Azure endpoint, an API key, and optionally a deployment name override if you are not using the default `gpt-5.4`. A Claude Code adapter ships too, behind `engine: claude`. The `Runner` interface is the seam where other engines plug in.
 
 ## Status
 
@@ -173,7 +219,7 @@ Roadmap, roughly in order:
 - Wiring the read-only reviewer role into the loop so a diff is reviewed before it reaches a human.
 - The self-onboarding flow via `init` and `init --workflow`. **Done.**
 - The Codex on Azure OpenAI engine adapter. **Done.**
-- The Claude Code engine adapter.
+- Self-hosted models on Hugging Face.
 
 If you are evaluating it now, read that as beta software rather than a polished product. The core loops work; reviewer wiring is still in progress, and self-onboarding shipped as `init` and `init --workflow`.
 

STATUS.md

@@ -27,9 +27,8 @@ The Actions runtime authenticates as the `simplycubed-code[bot]` GitHub App.
 Each job mints its own installation token scoped to one repository with
 `contents`, `issues`, and `pull-requests` permissions only.
 
-`v0.1.5` is the current release. `go install
-github.com/simplycubed/code/cmd/simplycubed@v0.1.5` works today. `v0.1.2` and
-`v0.1.4` are retracted in `go.mod` because those tags pointed at the wrong
+`v0.1.6` is the current release. `go install
+github.com/simplycubed/code/cmd/simplycubed@v0.1.6` works today. `v0.1.2` and `v0.1.4` are retracted in `go.mod` because those tags pointed at the wrong
 commits.
 
 Both loops were dogfooded: the issue-to-PR loop produced the merged
@@ -40,15 +39,19 @@ dependency-upgrade PR on `charlesgreen/gsm`.
 ```
 cmd/simplycubed/      CLI: version, init, preflight, run, address
 internal/domain/      core types (Role, Issue, RunRequest, ReviewFeedback, Verdict)
-internal/engine/      Runner interface + fake; codex/ adapter (Azure OpenAI)
+internal/engine/      Runner interface + fake; codex/ (Azure OpenAI) and claude/ adapters
 internal/gate/        runs the repo gate command; exit code, output tail, signature
-internal/config/      .github/simplycubed.yml; refuses a missing gate; attribution flag
+internal/config/      .github/simplycubed.yml; refuses a missing gate; engine, review,
+                      prDescription, attribution
 internal/state/       sc: label lifecycle with mutual exclusion
 internal/roles/       implementer, reviewer, fixer as data; bounds; untrusted-input delimiting
 internal/loop/        goal -> act -> grade -> repeat; Run (issue->PR) and Fix (fix-on-request)
 internal/forge/       GitHub side as an interface (no merge method); gh/ adapter + recording fake
 internal/vcs/git/     commit, push, and sync-to-PR-head
 internal/describe/    generated PR walkthrough, changes table, and sequence diagram
+internal/verdict/     the reviewer verdict: schema, validation, findings for the fixer
+internal/command/     comment commands (@simplycubed-code go | address | help)
+internal/forge/dryrun/ records the GitHub writes a dry run skips
 internal/attribution/ the SimplyCubed Code marker on generated commits and PRs
 internal/ledger/      append-only JSONL run events
 internal/worktree/    an isolated git worktree per issue
@@ -69,16 +72,11 @@ via `.github/workflows/check.yml`; the required status check on `main` is the
 
 ## What is next
 
-- **Wire the read-only reviewer role into the loop.** The `Reviewer` role and the
-  `Verdict` type exist, but no loop calls the reviewer yet, so today the review is
-  the human's. Wiring it (reviewer emits a structured verdict, findings feed the
-  fixer, comment-only, never a bot approval) is the next core-loop step. The
-  README says so plainly rather than implying it is already done.
-- **Engine roadmap:** Codex on Azure (now) -> a Claude Code adapter -> Hugging
-  Face self-hosted models. Each is another `Runner` implementation; no core
-  rework.
+- **Engine roadmap:** Codex on Azure and Claude Code both ship. Self-hosted
+  models on Hugging Face are next. Each is another `Runner` implementation; no
+  core rework.
 
 ## Deliberately not done (maintainer decisions)
 
-- **CI actions are pinned by tag, not commit SHA.** Pin by SHA before this goes
-  past scaffolding.
+Nothing outstanding. The two items that lived here, SHA-pinned actions and a
+per-role bot identity, both shipped in v0.1.3 and v0.1.6.

docs/assets/simplycubed-code.png

@@ -58,10 +58,14 @@ open. Nothing in this repository sets it.
 
 ## Are the `sc:` labels created for me?
 
-Not automatically, yet. For now the labels are created once when you onboard a
-repo. The planned self-onboarding flow will propose them (and the config and
-workflow files) as a pull request you merge, so nothing is created behind your
-back. Until then, creating the six state labels is a one-time setup step.
+Yes, once. `simplycubed init --workflow` creates the six state labels through
+your own `gh` auth, and writes the config, the caller workflow, and the install
+self-test as local files.
+
+Nothing is created behind your back and nothing is merged for you. You open that
+setup pull request and merge it yourself, because the App holds no `workflows`
+permission and cannot add its own workflow files.
+
 
 ## The agent won't propose anything. Why?
 

docs/faq.md

@@ -26,8 +26,13 @@ simplycubed version
 simplycubed init --workflow
 ```
 
-That writes `.github/simplycubed.yml`, writes `.github/workflows/simplycubed.yml`,
-and creates the `sc:*` labels through your local `gh` auth. The files are local
+That writes three files and creates the `sc:*` labels through your local `gh`
+auth:
+
+- `.github/simplycubed.yml`, the repository config
+- `.github/workflows/simplycubed.yml`, the caller workflow
+- `.github/workflows/simplycubed-selftest.yml`, an install check you run once
+  and then delete The files are local
 changes in your repository; nothing is merged or installed remotely for you.
 
 3. Edit `.github/simplycubed.yml` and set a real gate that is already green on
@@ -72,16 +77,64 @@ a setup pull request, and merge it yourself. Setup files are written locally by
 `simplycubed init` and merged by a human, because the runtime holds no
 `workflows` permission and cannot add its own workflow files.
 
-6. File an issue that describes a small change and apply the `sc:go` label.
+6. Check the install before trusting it:
+
+```sh
+gh workflow run simplycubed-selftest
+```
 
-7. Wait for the workflow to open a pull request. Review it like any other PR:
+That runs in your own runner and reports whether the App token resolves to a
+bot, whether it is correctly denied Actions administration, whether a commit is
+possible, and whether the engine can start there. Delete the workflow once it
+passes; normal operation goes through the App and the `sc:go` label.
+
+7. File an issue that describes a small change and apply the `sc:go` label.
+
+8. Wait for the workflow to open a pull request. Review it like any other PR:
 
 - Merge it yourself if it is good.
 - Or request changes; the fixer loop will address feedback on the current head
   and push back to the same branch.
 
 That is the first end-to-end path: issue -> PR -> human merge.
 
+## Where each value goes
+
+The same two Azure values are needed in both places, and setting one does not
+set the other. A repository secret is not visible to your local shell, and a
+reusable workflow inherits nothing from SimplyCubed.
+
+```mermaid
+flowchart TB
+    cfg[".github/simplycubed.yml<br/>gate, engine, review<br/>committed, never holds a key"]
+
+    subgraph local["Local CLI: you are the identity"]
+        L1["your shell<br/>AZURE_OPENAI_ENDPOINT<br/>AZURE_OPENAI_API_KEY"]
+        L2["your gh auth"]
+        L3["simplycubed run / address"]
+        L4["commits and PR authored by you"]
+        L1 --> L3
+        L2 --> L3
+        L3 --> L4
+    end
+
+    subgraph actions["GitHub Actions: the App is the identity"]
+        A1["repository variables<br/>AZURE_OPENAI_ENDPOINT<br/>SIMPLYCUBED_GH_APP_ID"]
+        A2["repository secrets<br/>AZURE_OPENAI_API_KEY<br/>SIMPLYCUBED_GH_APP_PRIVATE_KEY"]
+        A3["per-job installation token<br/>contents, issues, pull requests"]
+        A4["simplycubed run / address"]
+        A5["commits and PR authored by<br/>simplycubed-code[bot]"]
+        A2 --> A3
+        A1 --> A4
+        A2 --> A4
+        A3 --> A4
+        A4 --> A5
+    end
+
+    cfg --> L3
+    cfg --> A4
+```
+
 ## Azure values
 
 The shipped Codex-on-Azure setup needs these values:
@@ -145,6 +198,21 @@ passes:
 The reusable workflow installs the CLI, exports the endpoint and key for the job,
 and runs `simplycubed run` or `simplycubed address`.
 
+## Watching it run before it writes
+
+Two commands answer "is this configured correctly" without changing anything.
+
+`simplycubed preflight` validates the repository config and the engine settings
+and exits. It is what the workflow runs before installing the rest of the
+toolchain, so a misconfigured repository finds out in seconds.
+
+`simplycubed run owner/repo#N --dry-run` runs the whole loop, including the
+engine and your real gate, and skips the push and every GitHub write. It prints
+what it would have done instead, and in Actions writes that to the run summary.
+
+If something goes wrong, [troubleshooting.md](troubleshooting.md) starts from
+the symptom.
+
 ## Optional model override
 
 If your Azure deployment name is not `gpt-5.4`, set it explicitly.