quirework 0.1.0__tar.gz

quirework-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ademar Reis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quirework-0.1.0/PKG-INFO

@@ -0,0 +1,444 @@
+Metadata-Version: 2.4
+Name: quirework
+Version: 0.1.0
+Summary: Tools for writing and researching books and sites with an AI companion
+Author: Ademar Reis
+License-Expression: MIT
+Project-URL: Homepage, https://quirework.com
+Project-URL: Source, https://github.com/adereis/quirework
+Project-URL: Documentation, https://github.com/adereis/quirework/tree/main/docs
+Project-URL: Issues, https://github.com/adereis/quirework/issues
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: capture
+Requires-Dist: websocket-client>=1.6; extra == "capture"
+Provides-Extra: quarto
+Requires-Dist: quarto-cli>=1.5; extra == "quarto"
+Requires-Dist: pypdf>=4; extra == "quarto"
+Requires-Dist: fonttools[woff]>=4.40; extra == "quarto"
+Requires-Dist: Pillow>=9.4; extra == "quarto"
+Provides-Extra: semantic
+Requires-Dist: numpy>=1.24; extra == "semantic"
+Requires-Dist: fastembed>=0.4; extra == "semantic"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Provides-Extra: dev
+Requires-Dist: quirework[capture,quarto,semantic,test]; extra == "dev"
+Dynamic: license-file
+
+# Quirework
+
+Quirework is a set of tools for writing and researching with an AI
+companion such as Claude Code or Codex. The work can be a book, a site
+of long-lived posts, or anything else that has to stay consistent with
+itself while it grows. The companion works in your project. Quirework
+gives it a durable spec, named procedures, consistency checks,
+publication tools, and controlled ways to ask other models for an
+independent view.
+
+You can run every command yourself. That is not the workflow Quirework
+was made for. The normal workflow is to tell your companion what you
+want to accomplish, let it follow the project's procedure, and judge the
+evidence it brings back.
+
+Quirework does not write your work and it does not settle editorial
+questions. It gives the collaboration a memory and a method. It builds
+the artifacts, catches drift across chapters or posts, and preserves
+enough evidence for you to make the call.
+
+A Quarto book can use it, and so can a site of Markdown pages such as a
+Hugo blog. One installation serves several, because a project is
+selected by a `quirework.toml` found from the working directory and
+never by where the package happens to live.
+
+The website, [quirework.com](https://quirework.com), shows the tool at
+work: the spec and its trail, the procedures, and a fictional sample
+book you can read in every edition it was published in. AI wrote that
+book to test the tool, and no person reviewed its prose. Every deploy
+renders it again from the same commit of this repository.
+
+## The default workflow
+
+The author sets the aim and keeps editorial authority. The AI companion
+coordinates the work. Quirework makes that work inspectable and
+repeatable.
+
+A typical revision starts with a request in Claude Code or Codex. The
+companion then follows this loop:
+
+1. Read the project's guide and resolve the relevant SOP with
+   `quirework sop explain NAME`.
+2. Load the work's commitments, the guidance for the chapter or post at
+   hand, and its bindings with `quirework spec notes --primer`.
+3. Inspect the prose and the prior human decisions the task needs.
+   `quirework spec trail SLUG` leads from a commitment to the author's
+   own turns that shaped it.
+4. Draft or revise inside the limits of the SOP.
+5. Convene a writers room, a roundtable, a prose workshop, or blind
+   readers when the task benefits from independent perspectives.
+6. Reconcile those reports against the spec instead of treating a model
+   answer as authority.
+7. Run the structural, editorial, and publication checks named by the
+   SOP, and an independent consistency review where it asks for one.
+8. Return the change, the evidence, and any remaining author decision.
+
+The spec is the center of that loop. It states what the work currently
+holds. Sidecars bind passages to those commitments. When one commitment
+changes, the companion can find every chapter or post that expresses it
+before a local edit becomes a contradiction somewhere else.
+
+SOPs make the rest of the loop project-specific. A project can define
+how its companion writes a chapter or a post, checks a claim, researches
+a source, runs a workshop, or prepares a blind read. Quirework catalogs
+those procedures and generates thin skill routes for Claude Code and
+portable agents. The SOP remains the source of truth.
+
+The foreground companion is not tied to the models it supervises. A
+Codex session can send a blind reading to Claude. A Claude Code session
+can convene a room with Codex, Claude, and Antigravity seats. Each seat
+declares its harness, model, effort, materials, and access policy. The
+receipt records what the provider actually served.
+
+The
+[workflow guide](https://github.com/adereis/quirework/blob/main/docs/workflows.md)
+develops this loop through five especially useful patterns: writers
+rooms, roundtables of models working together as themselves, independent
+prose workshops, blind-reader panels, and contextual consistency
+reviews.
+
+## What it does
+
+### Keeps the claims from drifting apart
+
+A work that argues something has commitments, and after a year they live
+in one chapter's phrasing and contradict another's. Quirework gives them
+a file. Each commitment is a section with a slug, each chapter names the
+sections it expresses, and `spec notes bind --slug S` answers the
+question that matters when you change one: which other chapters have to
+change with it.
+
+A site argues one thing per post, so each post can keep a spec of its
+own: its reader, its thesis, its boundaries. A shared spec holds what
+several posts lean on, and a post that binds another's claim is listed
+when that claim changes.
+
+The shared spec can span several files read as one register, such as
+what the work claims in one and how it states it in another. A project
+can publish some of those files and keep the rest to itself, and the
+gate then refuses a published page that cites a section its reader
+cannot open. A slug is a name, and a section can outgrow it.
+`spec rename OLD NEW` rewrites a slug everywhere it is written, and
+refuses before writing anything if it cannot.
+
+The annotations live in a sidecar rather than in the prose, so the
+rendered text never carries them and reflowing a paragraph never
+disturbs them. A book keeps them beside each chapter, and a site keeps
+them outside the tree its generator renders. A derived edition's
+documents bind the same spec, so a commitment can be followed from the
+chapter that states it into every edition that retells it.
+`spec notes --check` gates the structure: a mark left in the prose, a
+sidecar that no longer mirrors its chapter, a binding that names a
+commitment the spec does not declare, a reading order that disagrees
+with the files on disk. `spec quotes` checks that a phrase quoted in
+metadata still exists in the work, and `--grep TERM` lists every
+quotation of a term you just retired from the prose.
+
+### Keeps track of what the work stands on
+
+Research gets a register too. Each source has a slug, in one file of
+sections or one file per source, and a mark cites it as `@source(slug)`.
+`spec sources --slug S` then lists every chapter or post that leans on a
+source, and the gate refuses a citation of a source the register does
+not hold. A source can keep a plain-text capture of itself, and a
+quotation from it is checked against that capture, so a misremembered
+line is caught the way a misquoted chapter is. A references register,
+which says where the work stands on each source, cites the spec by slug,
+and the gate holds each of those citations to a section that exists.
+
+### Remembers how the work was written
+
+`provenance` captures your Claude Code, Codex and Antigravity sessions
+from their local stores, and web conversations too. The captures go to a
+store outside your repository and wait there until you read and accept
+them. The repository keeps only the decisions: which sessions count,
+each with a hash that proves its bytes. So the transcripts never bloat
+the work's history, and a grep across the repository never wades through
+them. `provenance store backup` copies the store to the destinations it
+names, through rclone, a mounted directory, git or a script of your own.
+It never deletes a session at a destination before the copy that
+replaced it has arrived. `provenance search` then reads the human's own
+turns, by keyword or by meaning; the semantic index is built and stored
+locally, so corpus text never leaves the machine.
+
+`spec trail` connects that record to the spec without putting any of it
+in the spec. A trail sidecar, kept beside the private corpus, points
+each spec section at the conversations where the author seeded,
+sharpened or reversed it: a session and the time a turn was logged, not
+a copy of the words. A companion about to change a commitment reads the
+author's own turns, oldest first, and opens as much of each conversation
+as it needs. For a spec that grew before it had a trail,
+`spec trail backfill` has cheap readers flag every session once and
+leaves the decision for each section to a strong model. Each read
+records the turns it saw, so a session that later gains turns is handed
+out again for those turns alone.
+
+On top of that corpus it measures things about the making. `metrics`
+estimates the division of labor between the human and the AI, with its
+caveats attached rather than laundered away. `input` compiles the
+human's verbatim words. `coldread` puts the record in front of blind
+analysts and caches their reports by content, so changing the recipe
+misses the cache deliberately rather than reusing an answer to a
+different question.
+
+### Turns procedures into something your companion can follow
+
+Procedures are files the project writes, and the catalog makes them
+navigable: `sop explain NAME` prints required reading in dependency
+order with its word count, while follow-up work is recorded and
+deliberately never traversed for you. Personas say who is reading,
+instruments say what they are asked, and both are versioned data
+composed at preparation and frozen with the run. `sop skills` generates
+thin entry points so Claude Code or Codex can be pointed at a procedure
+by name. A procedure that declares modes has them named in its entry
+point, and `sop show NAME --mode MODE` prints only the part a request
+needs. An entry point stops once it has presented its plan, before any
+run starts, unless the request opens with `go`.
+
+### Runs models under conditions you declared
+
+A run is a plan: seats, ordered turns, an explicit model and effort.
+Prepare freezes the prompts and the inputs and hashes them, start
+executes through Codex, Claude Code or Antigravity, and the receipt
+records the model actually served rather than the one requested. Each
+claim in it names its source: the effort is read from the harness's own
+session record where the harness keeps one, and the billing names the
+kind of credential the seat ran on, never the credential itself. A
+Claude seat can run through a gateway the project declares, and then
+never borrows the host's own login.
+
+The controls are the point. A seat can be confined by the operating
+system rather than asked nicely, and where a provider can only offer an
+audited boundary the run says so instead of claiming isolation. Delivery
+is a separate choice from exposure: plain text, prose with its figures,
+rendered PDF pages, native file attachments. A pending request is never
+blindly resubmitted, a run stopped by a quota limit is continued in its
+own session rather than restarted, and a compaction event is always
+reported even when the answer looks fine. `sop runs watch` follows a run
+as it goes, and `export` hands back the answers and a sanitized receipt.
+
+The five patterns build on that engine, and what tells them apart is who
+sees what. A writers room (`sop room`) develops one answer through
+disagreement on a shared board. A roundtable (`sop roundtable`) has
+models work together as themselves, each seeing every turn as it
+happens. A prose workshop (`sop workshop`) gives every writer the same
+frozen packet and never another writer's draft, and keeps the drafts
+anonymous under a sealed key. A blind-reader panel (`sop panel`) shows
+each reader only the reader-facing material. A consistency review
+(`sop review`) gives an independent reviewer the project guide, the
+spec, the marks, a brief and a Git range, with the repository read-only.
+
+### Publishes a book in four formats, or a site through its generator
+
+Publishing is a backend the project names. A site built by Hugo keeps
+its own configuration, theme and deploy, and `publish build` builds it
+into the project's build tree, where it cannot overwrite the directory
+the site deploys from. A project that publishes more than one thing,
+such as a book and the site that serves its editions, names each as a
+target, and a target can take another's output into its own. A book gets
+the rest of this section.
+
+`publish build` renders a Quarto manuscript to every format its
+`_quarto.yml` lists: HTML, PDF through Typst, EPUB and DOCX for a book
+that lists all four, as the authoring guide's example does. It stages
+three trees to do it, because the formats disagree about what they will
+carry, and it checks afterwards that a figure has the same number in
+every edition rather than assuming so. The source tree is never written
+into.
+
+Every derived edition renders the same way: a memo for a manager, a
+version for young readers, the book as poems, each composed beside the
+book with a `_quarto.yml` of its own.
+
+It also does the things that go wrong silently. It generates a grayscale
+figure set from the color one, because e-ink desaturates color into mud.
+It validates the EPUB with the W3C reference checker, pinned by version
+and checksum, because a file every desktop reader opens can still be
+rejected by a retailer. It refuses to render in a substituted typeface,
+because Typst and rsvg substitute without complaining and the whole book
+comes out in the wrong face.
+
+### Hands copies to readers and brings their marks back
+
+A reader's note is only useful if it finds the text it was written
+against. Until a book is published, it can render every copy as a proof
+named for its commit, with the commit stamped on its pages, and the
+build stops if one page lacks the stamp. `publish copy --for NAME`
+renders a proof for one person from a committed tree. The copy takes the
+next number in a log kept outside the project, and its file is named by
+that number, never by the person.
+
+The marks come back the same way they went out. `publish redpen` builds
+a reviewable DOCX and reads the reviewer's marks back onto the source.
+`publish kindle` delivers a copy to a Kindle library from a signed-in
+browser tab, then finds each highlight and note from the reader's
+exported notebook in the manuscript. Marks on a copy made for the author
+become the author's own turns in the record, and another reader's are
+kept apart as that reader's feedback. `provenance rulings archive` keeps
+the rulings the author makes on a review sheet as turns of theirs too,
+so a spec trail can point at one.
+
+### Formats and inspects the prose
+
+`text wrap` applies the project's own conventions, and it can apply
+different ones per path, declared as a table of globs: one sentence per
+line in chapters or posts, hard wrapped at a column in guides.
+`text check` reports field jargon in reader-facing prose against a term
+list the project writes, so a word must be avoided, glossed on first
+use, or confined to where it belongs. A phrase the project has retired
+goes on the same list and fails the check if it ever comes back.
+`text tells` reports the habits a model leaves in prose it drafted: the
+contrast move, which says what a thing is by saying what it is not, and
+phrases the project lists. `--since REV` prints only what the working
+tree adds over a revision, which is the warning a commit hook or a
+review pass wants; like `text check`, it never gates. Quirework ships no
+default phrase list, since a stale one would read as clean prose;
+`config template tells` prints a dated seed and the recipe for keeping
+it current.
+
+## Install
+
+Python 3.11 or later is required. A checkout of this repository brings
+the two examples along with the tool:
+
+```bash
+git clone https://github.com/adereis/quirework.git
+cd quirework
+python3 -m venv --system-site-packages .venv
+.venv/bin/python -m pip install -e '.[quarto]'
+```
+
+Put `.venv/bin` on your `PATH`, or copy `.envrc.example` to `.envrc` and
+let direnv do it. To install the released package into an environment of
+your own without a checkout, run `pip install 'quirework[quarto]'`.
+
+The extras follow the work. `quarto` installs Quarto, which brings Typst
+for the PDF, and what a book's render needs besides. A site needs none.
+`semantic` adds local semantic search of the corpus, `capture` captures
+web conversations from a browser, and `test` runs the test suite. `dev`
+includes all of them.
+
+The core and command discovery use the Python standard library. Other
+programs are needed only by the operations that use them:
+
+- Model seats run through the Codex, Claude Code or Antigravity CLI,
+  each installed separately.
+- Enforced filesystem isolation uses bubblewrap on Linux, and an
+  Antigravity seat also needs `xdg-dbus-proxy`.
+- A book's PDF and SVG work uses Poppler and librsvg, and the typeface
+  check uses Fontconfig.
+- EPUB validation needs Java and the W3C checker, which
+  `quirework publish epubcheck --install` fetches pinned by version and
+  checksum. A render without them says the EPUB was not validated.
+- A site renders with Hugo, and a store backup uses rclone when one of
+  its targets does.
+
+A missing required program stops the operation with an error.
+
+## Let the companion choose the tools
+
+You normally work by describing the job to your AI companion. The
+command groups below are the vocabulary it uses to carry out that job:
+
+```text
+quirework spec        Read and check the spec, marks, sources, quotations and trail
+quirework publish     Render the manuscript and inspect its editions
+quirework text        Format and inspect writing
+quirework provenance  Capture, organize, and search source history
+quirework sop         Find procedures and operate supervised workflows
+quirework dev         Repository checks and tooling maintenance
+quirework config      Inspect and validate project configuration
+quirework usage       Report which commands, procedures and seats get used
+```
+
+You can also run the commands directly. Add `--help` at any level to
+inspect the actual options. Help does not require a project, a private
+corpus, or a provider account.
+
+Common operations include:
+
+```bash
+quirework spec notes --primer -c opening
+quirework spec notes bind --slug kettle-signal
+quirework spec trail kettle-signal
+quirework spec notes --check
+quirework publish build --to html
+quirework publish copy --for Ada
+quirework publish redpen build --chapter opening
+quirework text wrap manuscript/opening.qmd
+quirework text tells --since main
+quirework provenance search 'an earlier idea'
+quirework sop list
+quirework sop explain review
+quirework sop runs prepare plan.json /path/to/private/run
+quirework sop runs start /path/to/private/run --timeout 60 --wait-quota 0
+quirework sop runs watch /path/to/private/run
+```
+
+Starting from nothing? The
+[authoring guide](https://github.com/adereis/quirework/blob/main/docs/authoring.md)
+is the path from an empty directory to a manuscript with a spec, marked
+chapters, figures and its own procedures, and its last part does the
+same for a site.
+[examples/side-quest](https://github.com/adereis/quirework/tree/main/examples/side-quest)
+is a short complete book that walked it: a comic memoir with a spec and
+its trail, a book in four formats, three derived editions bound to the
+same spec, an extension of its own, the fifteen sessions it was written
+in, and the records of the workshop, writers room, blind read,
+roundtable and consistency review that made parts of it. Its editions
+can be read at
+[quirework.com/examples](https://quirework.com/examples/).
+[examples/demo-site](https://github.com/adereis/quirework/tree/main/examples/demo-site)
+is the site version: posts with a spec each, a shared spec, marks kept
+outside the rendered tree, and a voice policy the checks enforce.
+
+Both examples are test fixtures, not showcases. Their authors are
+invented, AI wrote them, and no person edited or reviewed their prose.
+Every session of the book was driven by an AI playing its author, which
+the example's own README says. Read them for the structure Quirework
+keeps, not as examples of the writing it helps an author make.
+
+The
+[configuration guide](https://github.com/adereis/quirework/blob/main/docs/configuration.md)
+explains how to connect a project. The
+[workflow guide](https://github.com/adereis/quirework/blob/main/docs/workflows.md)
+covers procedures, research, model runs, and saved evidence. The
+[development guide](https://github.com/adereis/quirework/blob/main/docs/development.md)
+covers architecture and tests.
+
+## A project owns its choices
+
+Place `quirework.toml` at the project root. Quirework discovers it from
+the working directory, including subdirectories. Use
+`quirework --project PATH ...` to select a different project explicitly.
+Installing Quirework never selects a project by the package's location.
+`quirework config template book` or `site` prints an annotated file to
+start from. Private corpus paths and account identities go in an ignored
+`quirework.local.toml` beside it. What belongs to you across every
+project, such as where the session store lives and which devices receive
+your copies, goes in `~/.config/quirework/config.toml`.
+
+A book's Quarto file remains the source of its publication settings and
+reading order; a site's own generator configuration does the same job
+for the site. Personas, questions, custom procedures, editorial
+policies, and private corpora belong to the project. A project without
+provenance can use the publishing and run tools independently.
+
+Quirework is one distribution with one Python namespace. Its domain
+modules are designed for reuse without the CLI or a particular project.
+The software is licensed under the MIT license.