Initialise `summit`: project docs and repo-by-repo proofread automation by alexander-yevsyukov · Pull Request #2 · SpineEventEngine/summit

alexander-yevsyukov · 2026-07-22T16:00:35Z

Summary

Initialises the summit superproject — its documentation and a repeatable,
cross-repository proofread workflow — and brings the submodule set current.

summit is a Git superproject (meta-repository): it assembles the Spine SDK
repositories as submodules so agents and the shared config/CI tooling can act
across 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 by
function, getting started (clone --recursive, or ./init-submodules →
./config/pull on a fresh worktree), and the cross-repository focus.
docs/project.md — the agent/contributor-facing description (target of the
.agents/project.md symlink): role as a coordination superproject, the
pinned-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 deterministic
mechanics: ./config/pull first, JAVA_HOME export, idempotent
branch/bump/report steps (prep), and a sentinel-checked ship.
docs/rollout/proofread.md — the playbook pairing that script with the two
agent-driven judgement steps (the proofread sweep and pre-pr).
docs/rollout/proofread-fanout.workflow.js — a saved-Workflow sketch of the
sweep 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 the
per-repo runs.

Submodules

Removed delivery-server; added gcloud-jvm.
Added the agents repo as a pinned top-level submodule — an automation
target, distinct from the floating .agents/shared tooling mount.
Advanced base-libraries and base-types to their merged master — the
first two repos taken through the new proofread workflow.

Verification

Documentation and tooling only; summit has no Gradle build.
Reviewed with review-docs — APPROVE WITH CHANGES, no Must-fixes; all
Should-fixes applied in the final commit.

🤖 Generated with Claude Code

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

💡 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).

Copilot

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.md and docs/project.md to document summit’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 .gitmodules to remove delivery-server and add gcloud-jvm and a pinned agents submodule (in addition to the floating .agents/shared mount).

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.

… 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.

alexander-yevsyukovand others added 6 commits July 21, 2026 19:32

Update base-libraries and base-types to their merged master
f62b927
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>

alexander-yevsyukov self-assigned this Jul 22, 2026

alexander-yevsyukov added this to v2.0 Jul 22, 2026

alexander-yevsyukov moved this to 🏗 In progress in v2.0 Jul 22, 2026

chatgpt-codex-connectorBot reviewed Jul 22, 2026
View reviewed changes

Comment threadproofread-repo Outdated

alexander-yevsyukov added 3 commits July 22, 2026 17:24

alexander-yevsyukov requested a review from Copilot July 22, 2026 19:37

Copilotstarted reviewing on behalf of alexander-yevsyukov July 22, 2026 19:38 View session

alexander-yevsyukov requested a review from armiol July 22, 2026 19:39

alexander-yevsyukov moved this from 🏗 In progress to In Review in v2.0 Jul 22, 2026

alexander-yevsyukov changed the title ~~Initialise summit: project docs and repo-by-repo proofread automation~~Initialise summit: project docs and repo-by-repo proofread automationJul 22, 2026

CopilotAI reviewed Jul 22, 2026
View reviewed changes

Comment threadproofread-repo
Comment threadproofread-repo
Comment threaddocs/rollout/proofread-fanout.workflow.js Outdated
Comment threaddocs/rollout/proofread-fanout.workflow.js Outdated

armiol approved these changes Jul 23, 2026
View reviewed changes

alexander-yevsyukov merged commit 27ce22b into masterJul 23, 2026
1 check passed

github-project-automationBot moved this from In Review to ✅ Done in v2.0 Jul 23, 2026

Navigation Menu

Uh oh!

Initialise `summit`: project docs and repo-by-repo proofread automation - #2

Initialise `summit`: project docs and repo-by-repo proofread automation#2
alexander-yevsyukov merged 10 commits into
masterfrom
init-project-description

alexander-yevsyukov commented Jul 22, 2026

Uh oh!

chatgpt-codex-connectorBot left a comment

Uh oh!

Uh oh!

CopilotAI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

alexander-yevsyukov commented Jul 22, 2026

Summary

What's in this PR

Verification

Uh oh!

chatgpt-codex-connectorBot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants