Initialise summit: project docs and repo-by-repo proofread automation - #2
Merged
Conversation
Replace the placeholder README with a description of summit as a meta-repository that aggregates the Spine SDK repositories as submodules for cross-repository automation, with a grouped submodule inventory and bootstrapping steps. Fill in docs/project.md (the .agents/project.md orientation doc) from the template. Also swap the delivery-server submodule for gcloud-jvm and reorder .gitmodules so the floating .agents/shared entry stays last. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Summit-owned tooling for running the `proofread` skill across the SDK repos one at a time, ending in a PR: - proofread-repo — the deterministic mechanics (config/pull, branch, bump, reports, sentinel-gated push + PR); idempotent and re-runnable. - docs/rollout/proofread.md — the agent-driven playbook (sweep + pre-PR). - docs/rollout/proofread-pr-body.md — the PR body template. - docs/rollout/proofread-fanout.workflow.js — a Workflow sketch for the parallel proofread sweep. Referenced from docs/project.md so a fresh session can find it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Mount SpineEventEngine/agents at `agents` (pinned, no tracked branch) as a dedicated automation target, distinct from the floating `.agents/shared` tooling mount. This lets the repo-by-repo automation target the agents repo like the other SDK submodules. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Fixes found by actually running the sketch: - Parse `args` whether the harness delivers it as a string or an object; the string case made `args.files` undefined -> 0 files, 0 agents, silent no-op. - Take absolute `catalog` and `files` paths plus a tunable `chunkSize`, since the Workflow runtime has no filesystem access and can't resolve repo-relative paths. - Exclude `.agents/` from the prose scope (old-layout repos commit the shared guidelines there). Validated by a live run against base-types: 33 files, 3 parallel proofreaders, 14 fixes, prose-only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Point summit at the merge commits: base-libraries #954 (7a05857) and base-types #54 (0f2898b), now that both proofread PRs have landed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Address the APPROVE-WITH-CHANGES items from the pre-PR documentation review: - README: document the pinned top-level `agents/` submodule (added on this branch) alongside the floating `.agents/shared` mount, so both checkouts of the tooling repo are explained. - Reflow widowed lines in `proofread.md` and `proofread-pr-body.md`. - Collapse double spaces after sentence periods in the `proofread-repo` comments and the `proofread-fanout.workflow.js` header. - Minor terminology/backtick consistency in `docs/project.md` and `proofread.md`. Prose and comments only; no behavioural change to the script or Workflow.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0ce48c8229
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
… validation - Report failed chunks (failedFiles / complete / chunksFailed) instead of silently dropping them via filter(Boolean). - Throw on missing repo/catalog, empty files, or malformed args JSON. - De-duplicate the file list so concurrent agents can't race on one path. - Reframe the header/playbook: separate "validated once, hardened" from "opt-in by design" (never auto-wired from proofread-repo).
Close the known failure mode: the sanitize-source-code.sh hook strips trailing whitespace inside a test string literal (this broke a StringsSpec trim test), a side effect the proofreaders never see and so cannot self-report. After the Proofread fan-out, a second Verify stage runs independently of what the proofreaders claimed: - discover: one read-only-git agent enumerates the ACTUAL working-tree changes (git diff --name-only) — ground truth, not self-reports. - inspect: one auditor per changed-file chunk reads each file's diff and flags any hunk that escaped prose, especially whitespace changed inside a string literal, returning per-file verdicts. The return gains a `verification` block (ran / verified / suspectFiles / unverifiedFiles / reconciliation). Verify only reads — never edits or commits; the caller works from `verification.suspectFiles` instead of eyeballing the whole diff. Adds a required `root` arg (absolute repo root) for the git calls. Syntax-checked under the runtime's async-wrapped model. The Verify stage is new and not yet exercised on a real corrupt diff.
Codex review (PR #2): `[ -d "$DIR/.git" ]` rejects a submodule initialised the normal way, whose `.git` is a gitfile pointing into the superproject's .git/modules rather than a directory. Since proofread-repo runs against summit's own (gitfile-initialised) submodules, the guard rejected every repo before prep or ship could cd in. Probe with `git -C "$DIR" rev-parse --is-inside-work-tree` instead — it accepts gitfile, directory, and worktree forms and still rejects an uninitialised dir (verified against base-types and a bogus path).
alexander-yevsyukov
changed the title
summit: project docs and repo-by-repo proofread automation
There was a problem hiding this comment.
Pull request overview
Initialises the summit superproject’s documentation and adds a repeatable, cross-repository “proofread” rollout workflow (script + playbook + optional Workflow fan-out), alongside updating the submodule set.
Changes:
- Expanded
README.mdanddocs/project.mdto documentsummit’s role, submodule model, and bootstrapping flow. - Added repo-by-repo proofread automation assets:
proofread-repo, rollout playbook, PR body template, and a saved Workflow script for proofread fan-out + verification. - Updated
.gitmodulesto removedelivery-serverand addgcloud-jvmand a pinnedagentssubmodule (in addition to the floating.agents/sharedmount).
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Documents the superproject purpose, submodule inventory, and bootstrap steps. |
| docs/project.md | Defines summit’s role/architecture and links cross-repo workflows under docs/rollout/. |
| proofread-repo | Adds deterministic “prep/ship” mechanics for repo-by-repo proofread runs. |
| docs/rollout/proofread.md | Playbook describing the judgement steps and how to use proofread-repo. |
| docs/rollout/proofread-pr-body.md | Template PR body for per-repo proofread PRs. |
| docs/rollout/proofread-fanout.workflow.js | Optional Workflow script to fan out proofread + verify diffs for non-prose edits/whitespace corruption. |
| .gitmodules | Updates the set of SDK submodules assembled by the superproject. |
armiol
approved these changes
Jul 23, 2026
… prompts
proofread-repo:
- Escape the current version's dots before using it as a sed BRE, so the bump
substitution matches the literal version, not a `2X0X0-...` variant.
- Guard a clean working tree before `./config/pull`, so the follow-up `git add -A`
stages only config/pull's output, never pre-existing local or untracked files.
proofread-fanout.workflow.js:
- Quote ${root} (and the <file> placeholder) in the read-only-git commands shown
to the verifier agents, so they don't break on paths containing spaces.
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
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.
Summary
Initialises the
summitsuperproject — its documentation and a repeatable,cross-repository proofread workflow — and brings the submodule set current.
summitis a Git superproject (meta-repository): it assembles the Spine SDKrepositories as submodules so agents and the shared
config/CI tooling can actacross the whole SDK from one working tree. It ships no code and has no build of
its own.
What's in this PR
Project description
README.md— public landing page: tagline, submodule inventory grouped byfunction, getting started (clone
--recursive, or./init-submodules→./config/pullon a fresh worktree), and the cross-repository focus.docs/project.md— the agent/contributor-facing description (target of the.agents/project.mdsymlink): role as a coordination superproject, thepinned-vs-floating submodule model, the bootstrap order, and an explicit
"not a JVM build" note.
Repo-by-repo proofread automation (
docs/rollout/)proofread-repo— a repo-owned bash script codifying the deterministicmechanics:
./config/pullfirst,JAVA_HOMEexport, idempotentbranch/bump/report steps (
prep), and a sentinel-checkedship.docs/rollout/proofread.md— the playbook pairing that script with the twoagent-driven judgement steps (the proofread sweep and
pre-pr).docs/rollout/proofread-fanout.workflow.js— a saved-Workflow sketch of thesweep as a single deterministic fan-out, validated end-to-end on
base-types.docs/rollout/proofread-pr-body.md— a generic PR-body template for theper-repo runs.
Submodules
delivery-server; addedgcloud-jvm.agentsrepo as a pinned top-level submodule — an automationtarget, distinct from the floating
.agents/sharedtooling mount.base-librariesandbase-typesto their mergedmaster— thefirst two repos taken through the new proofread workflow.
Verification
summithas no Gradle build.review-docs— APPROVE WITH CHANGES, no Must-fixes; allShould-fixes applied in the final commit.
🤖 Generated with Claude Code