Two builds: Product Manual and Quick-Start Builder, and Runbook Reconciler - #45
Open
CulturalProfessor wants to merge 55 commits into
Open
Two builds: Product Manual and Quick-Start Builder, and Runbook Reconciler#45CulturalProfessor wants to merge 55 commits into
CulturalProfessor wants to merge 55 commits into
Conversation
Deterministic core: one spec as source of truth, the manual and the card as two projections of it. Nothing talks to the API yet. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…alisation API client, one-turn multi-document edit and localisation -- each of the three graded criteria with a mechanism and a test. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…e guessed Marks which endpoints are verified against the live service and which are guessed from the convention the verified ones follow. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…tements Troubleshooting rows reference the step they belong to; a spec missing its warranty or disposal statement is refused by id. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
French, and German for the new sections: two locales prove the layout is not shaped around one language's habits. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…t bugs Drawings render from the localised spec, including the words printed inside the SVG. Two layout bugs with them. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Both documents render as laid-out blocks carrying a language-independent id, so a page is measured rather than reparsed from HTML. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Pagination is measured, not asserted -- an identical outline does not survive one locale running ten percent longer. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ort completes the spine check prints where the pages fall and the headroom per locale, build draws the page rules, export completes the spine. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
README plus the screenshot it claims: page 8 in three languages, same step, same diagram, same page. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
sync now swaps the new diagram URL into the published documents; the README had described code that did not exist. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
… its nose Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Found by finally running it: almost every shape was wrong, starting with .env values keeping their quotes into a 401. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
One turn cannot edit two documents, so the pair guarantee becomes two turns with nothing applied until both have proposed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
It claimed a verified spine that had never been run, and a one-turn multi-document edit the API does not do. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ive upload A session runs one turn at a time and a parked turn holds it, so each document gets its own session. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…story The swap was reusing a session that kept re-proposing a change rejected in it earlier, so sync never completed a clean run. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ly has sync swapped all eight diagrams in the manual and none in the card, and called it clean -- ask each document what it has. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Every number re-checked by running it; the install line is uv now, since pip install -e is refused under PEP 668. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two free commands that export both live documents and check the two claims that can otherwise fail silently. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…verything ./mb takes care of the virtualenv and runs from anywhere, and one command checks everything. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Export is keyed by session and a session serves whatever it is focused on, so verify was reading the manual twice. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…he spec The pair check compares the documents against each other, not against a spec that an approved edit moves them both away from. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Thirteen findings against the live API, moved in from a private notes repo; most explain why a piece of this code is shaped as it is. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
… cost A second pass over the prose docs found six more bugs, corrected four of the thirteen, and showed three wrong endpoints. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Plans a reconciler treating infra config as ground truth, with a human gate and passage-scoped edits. preflight names the scoped-token 401. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Layout, lint and format config, entry point. superdocs.py is copied from the sibling build with a provenance note rather than imported across folders. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A fabricated two-repo estate and eight storage-format runbooks, with expected.yaml written before the checker exists. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claims, findings and the cost ledger in one SQLite file, with claim_id derived from passage text and heading path, never from position. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
One pure module per source, each record carrying a SourceRef that resolves to a real file and line, so rule 8 holds at the reader. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The parser returns offsets into the exact body string, so a splice cannot land inside an entity. The claim patterns are data. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Vertical checks plus bidirectional coverage, free and in under a tenth of a second: precision 1.000 and recall 1.000 against the stage-1 key. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Auth is probed rather than assumed, since scoped and classic tokens want opposite hosts, and the write is two-phase. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Every finding on a page batches into one turn, so cost is one operation per page per sweep rather than one per finding. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
ReviewQueue holds the decisions and knows nothing about prompts, so the MCP server can drive the same gate the terminal does. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The gate's own tests pin its three properties, including that ReviewQueue contains no input() at all. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The watcher ignores its own writes through a version ledger, because every route to 'who am I' is 401 for a scoped token. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Half two, from the same register. Both documents carry their own limitations rather than leaving them in a README. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
analyze, propose, approve and apply, calling the same ReviewQueue the terminal loop calls, with a test asserting no second gate. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
README rewritten from 'nothing works yet' to measured results, BUGS.md against Confluence Cloud, and a staged selftest. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The sync chat turn returns no job_id while approve requires one, so the operation is spent and can never be approved. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The diagnostic no longer fails on an optional key it then reports as fine, and names keys in .env that are absent from the example. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
seed.py plants seven contradictions in a real space; run live, all seven found and four written back as minimal changed ranges. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Twelve paced stages, each printing its cost before it runs, --offline stopping before credentials. Two failures found. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The suite's process hygiene becomes a checked property rather than a claim, and names the test that breaks it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A dropped unit and a whole list pasted for one name both passed the length cap and reached a live page. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Five worded and two escalated, not six written -- two of the six were the wrong edits that prompted the guards. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
272 tests, and stage 12 tries to delete rather than deletes: a scoped token has no delete scope. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Names the Documentation drift detector card and the two departures from it. PLAN.md leaves the tree with it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Nine Confluence, two SuperDocs API and three model behaviour here; the intro had claimed all fourteen were Confluence. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Seventeen openings said how many hours a bug took; the consequence after the comma was always the useful half. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
paginate.py said German runs twelve per cent longer where `mb check` measures 110%, and the README counted fourteen verify cases against thirteen in the file. Co-Authored-By: Claude Opus 5 <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.
Two builds for a SuperDocs round, submitted as one pull request: the Product Manual and Quick-Start Builder (my assigned card) and the Runbook Reconciler (from the open list). Both live under my own folder in the section that fits them, and nothing outside those two folders is touched.
1. Product Manual and Quick-Start Builder
Lives in
use-cases/CulturalProfessor/product-manual-builder/.From one structured product spec it generates the full product manual and the folded quick-start card as two projections of the same source, localised into three launch markets. Both documents derive from that one spec and edits are applied to both in the same reviewed batch, so they cannot drift into disagreeing with each other. The pagination is measured, so a German page still breaks where the English one does.
It uses chat editing, multi-document sessions, review and approve, templates, images and export.
2. Runbook Reconciler
Lives in
extensions/CulturalProfessor/runbook-reconciler/.Operational runbooks describe infrastructure that changes underneath them, and nothing tells the runbook. This reads infrastructure config as ground truth (Prometheus rules, Terraform, Kubernetes, Backstage, PagerDuty), checks whether the runbooks in Confluence still tell the truth about it, and puts every difference in front of a human. Approved fixes land as surgical edits to the exact passage, with every other byte on the page provably unchanged. It reads DevOps files and writes documents; it never edits infrastructure.
It uses chat editing, review and approve, multi-document, templates and export, and ships an MCP server exposing the same gate a person drives.
This is the open list's Documentation drift detector card, and two things depart from it that the README spells out. The card's ground truth is another document, a changelog or a spec snapshot, where this reads a running system's declared state. And the second half runs the other way round, turning verification output into a document: an on-call readiness report and a DR evidence pack, both built from the claim register the checker writes.
What is measured, and what is not
fixtures/expected.yamlin the reconciler is the measurement key, and it was written before the checker existed, so precision and recall are scored against planted drift rather than against whatever the implementation happened to find../rr measurereproduces it: precision 1.000 and recall 1.000, for zero paid operations. The sample is small and synthetic, and the README says so in the same breath.402 tests pass across the two builds, 272 and 130, with no API key and no network.
Both projects carry a
BUGS.mdholding 35 findings against the live services, each one saying whose it is: Confluence Cloud, the SuperDocs API, or the model's behaviour reached through it. One of them is a demo that announced every stage passed while its cleanup had silently failed.Honest limitations
Stated at length in each README rather than hidden here. The reconciler is Confluence Cloud only, it reads git-declared config and not live cloud state, and its value decays after the first sweep: the first run finds years of accumulated drift and the tenth finds last week's. An open Confluence editor tab will silently revert API writes, and no API surface lets the tool detect that.
Author
Vinayak Sharma, GitHub @CulturalProfessor
Licensed MIT, same as the repository.