Meta tags:
description=README quality fails when generated prose overwrites contracts that tests and operators still have to... Tagged with python, documentation, testing, opensource.;
keywords=python, documentation, testing, opensource, software, coding, development, engineering, inclusive, community;

Headings (most frequently used words):

the, readme, ledger, sign, model, with, from, this, is, to, lane, use, without, cells, what, draft, not, assemble, entry, points, and, tests, guarantees, by, hand, dev, community, failure, mode, built, catch, definitions, compiler, allowed, collect, repository, facts, emit, explicit, unsigned, decide, may, versus, human, must, fill, giving, contract, contracts, reviewer, name, regenerated, paragraph, prove, inventory, still, matches, tables, limitations, who, should, approach, top, comments, more, avery, lin,

Text of the page (most frequently used words):
the (98), and (53), that (36), not (31), #ledger (29), readme (29), #contract (26), draft (25), none (22), model (21), json (21), from (19), for (19), project (19), inventory (18), scripts (18), can (16), mode (16), fullscreen (14), import (14), dev (13), this (13), human (13), with (12), only (12), lane (12), path (12), support (12), python (11), test (11), keep (10), still (10), command (10), pyproject (10), unsigned (9), must (9), toml (9), cells (9), table (9), get (9), pathlib (9), docs (9), yes (9), use (8), signatures (8), already (8), than (8), entry (8), tests (8), should (8), into (8), because (8), missing (8), pytest (8), after (8), read_text (8), tomllib (8), name (8), your (7), documentation (7), prose (7), may (7), file (7), points (7), them (7), when (7), exit (7), enter (7), listed (7), loads (7), proposal (7), audience (7), sign (7), lanes (7), extras (7), share (6), before (6), more (6), you (6), are (6), tables (6), what (6), they (6), step (6), names (6), those (6), node (6), package (6), run (6), utf (6), encoding (6), readme_ledger (6), line (6), free (5), repository (5), signed (5), who (5), any (5), commands (5), facts (5), metadata (5), empty (5), until (5), claims (5), review (5), extra (5), block (5), command_table_markdown (5), def (5), rows (5), null (5), true (5), signature (5), copy (5), create (4), stay (4), community (4), compile (4), comments (4), will (4), rather (4), reviewer (4), hand (4), single (4), assistant (4), files (4), include (4), later (4), compiler (4), identifiers (4), executable (4), authentication (4), writes (4), assert (4), collected (4), stays (4), cell (4), print (4), raise (4), systemexit (4), value (4), keys (4), below (4), against (4), data (4), return (4), root (4), collect (4), where (3), date (3), software (3), source (3), code (3), about (3), testing (3), avery (3), lin (3), abuse (3), hide (3), monkeycode (3), server (3), allowlist (3), has (3), guarantees (3), skip (3), reviewers (3), marketing (3), installable (3), contracts (3), adds (3), without (3), non (3), cannot (3), workflow (3), product (3), never (3), prompt (3), set (3), search (3), add (3), fail (3), example (3), sentence (3), cli (3), failure (3), items (3), allowed (3), regenerated (3), target (3), main (3), markdown (3), heading (3), filled (3), key (3), pass (3), read (3), like (3), requires_python (3), dict (3), nodes (3), proc (3), sys (3), optional (3), collection (3), account (2), log (2), 2026 (2), built (2), open (2), terms (2), policy (2), conduct (2), database (2), out (2), drafted (2), devops (2), drafts (2), ships (2), user (2), person (2), sure (2), comment (2), become (2), post (2), visible (2), via (2), report (2), let (2), store (2), template (2), generate (2), access (2), option (2), feed (2), named (2), entire (2), method (2), tree (2), prove (2), fluent (2), write (2), short (2), change (2), time (2), save (2), packages (2), surface (2), map (2), changelog (2), through (2), drafting (2), credentials (2), even (2), workspace (2), exist (2), operator (2), outside (2), describe (2), close (2), move (2), remain (2), does (2), decision (2), supported (2), next (2), silent (2), need (2), requires (2), honest (2), fence (2), discard (2), fenced (2), runs (2), once (2), coverage (2), text (2), operators (2), nobody (2), required (2), leave (2), hashlib (2), blob (2), dumps (2), encode (2), fields (2), object (2), three (2), changes (2), previous (2), promise (2), churn (2), paragraph (2), contract_reviewer (2), sections (2), work (2), cheap (2), rewrite (2), reject (2), wrote (2), compare (2), chat (2), check (2), claim (2), hosted (2), locally (2), offers (2), expand (2), pull (2), instead (2), row (2), says (2), diff (2), formatting (2), flags (2), while (2), belongs (2), dates (2), hides (2), deprecations (2), sla (2), compatibility (2), window (2), goals (2), implies (2), retention (2), secrets (2), install (2), truth (2), section (2), paths (2), expectations (2), values (2), mkdir (2), then (2), promises (2), actually (2), build_ledger (2), collect_pytest_nodes (2), load_project (2), false (2), cwd (2), subprocess (2), else (2), script (2), output (2), treat (2), explicit (2), means (2), importlib (2), version (2), pprint (2), fact (2), semantics (2), windows (2), assemble (2), link (2), place, coders, grow, their, careers, made, love, 2016, ruby, rails, powers, other, inclusive, communities, forem, privacy, mlh, shop, postgres, contact, showcase, organization, accounts, advertise, help, education, tracks, videos, challenges, home, space, discuss, development, manage, career, severity, troubleshooting, pages, tutorial, alert, duties, runbook, symptoms, bind, reference, summaries, extracted, aug, joined, singapore, location, frontend, developer, crafting, beautiful, experiences, follow, further, actions, consider, blocking, reporting, confirm, child, well, want, hidden, but, permalink, dismiss, preview, submit, templates, quickly, answer, faqs, snippets, trusted, personal, subscribe, top, raw, written, split, refuse, stand, maintainers, rarely, spend, case, owned, whose, faster, reread, paragraphs, partition, labor, requirement, host, generation, particular, worth, inventorying, sites, blogs, investor, one, pagers, forcing, ceremony, verifier, live, customer, public, endpoints, strings, redacted, cheaper, control, approach, also, see, services, staging, diagrams, runbooks, git, systems, accept, cover, scrape, internal, wikis, gap, reintroduces, official, filename, nulls, conceptual, tutorials, architecture, records, legal, asked, safe, private, quarter, threat, models, teams, publish, cryptographic, medical, replace, including, counsel, limitations, whenever, someone, edits, schedule, keeps, refactor, touched, too, strict, experimental, shrink, disabling, assertion, smaller, unbounded, dump, group, findall, test_command_table_lists_only_declared_scripts, test_readme_ledger, reconstructs, compares, tested, label, image, becomes, matters, coupled, matches, enough, disagree, hold, easy, everyone, revoke, same, rule, applies, header, role, client, expect, state, invented, oauth, poetry, sort_keys, contract_sha256, sha256, hexdigest, join, hash, confident, adjective, require, publication, jobs, new, landed, wipe, asks, whether, holds, expected, defect, exists, make, expensive, pkg, render, placeholders, inside, over, html, fences, grep, find, second, such, publishing, pipeline, concatenate, concatenation, easier, audit, document, first, license, footer, unchanged, contains, credential, shaped, string, bearer, http, regeneration, mutated, after_path, separate, boundary, cut, polite, instruction, buried, long, plus, returns, byte, changed, snippet, quota, draft_allowlist, txt, context, disclosure, article, was, prepared, part, outreach, readable, receive, fill, giving, request, score, rereading, full, needs, usually, appear, merge, third, pretty, uncertainty, softer, back, break, owners, reads, uptime, release, softens, limitation, roadmap, deletion, slas, handling, mentions, tokens, bypasses, sample, auth, borrows, another, percentages, links, ids, how, invents, subcommands, targets, mirrors, sudo, wording, verbatim, tool, connected, restate, proved, authored, sounds, existing, voice, dated, age, independently, decide, versus, all, job, populated, guard, prevents, inheriting, under, requests, scrolling, rewritten, adjectives, turns, finish, __main__, __name__, indent, write_text, exist_ok, parents, parent, support_date, support_reviewer, contract_date, incident_expectations, compatibility_window, non_goals, data_handling, auth_semantics, test_map_markdown, install_table_markdown, pytest_nodes, optional_extras, console_scripts, package_name, append, startswith, strip, splitlines, stdout, returncode, capture_output, str, list, dependencies, sorted, isinstance, __import__, modules, annotations, __future__, labeled, inspect, sees, silence, approval, arrays, disk, emit, failures, defects, permission, guess, point, error, undocumented, paste, stack, traces, during, beside, notes, pip, index, versions, unknown, installed, editable, start, transcript, paraphrases, console, users, checked, mark, module, documented, fixture, roles, intended, authorization, deprecation, incident, response, anything, default, definitions, rewrites, silently, invent, which, had, examples, precision, artifacts, humans, own, every, binds, catch, quality, fails, generated, overwrites, have, honor, production, compiled, deterministic, statements, produces, separates, lands, opensource, posted, sep, mastodon, facebook, linkedin, copied, clipboard, pick, gem, boost, jump, fire, raised, hands, exploding, head, unicorn, reaction, powered, algolia, navigation, menu, content,

Text of the page (random words):
ia report abuse avery lin posted on sep 19 assemble a readme ledger from entry points and tests sign guarantees by hand opensource python testing documentation readme quality fails when generated prose overwrites contracts that tests and operators still have to honor in production inventory facts can be compiled from entry points pytest node identifiers and package metadata with deterministic scripts audience statements authentication semantics support windows and failure mode promises remain human signed work not model output the workflow below produces a ledger that separates those lanes so review time lands on claims rather than table formatting the failure mode this ledger is built to catch a model that rewrites an entire readme can silently expand compatibility hide required secrets or invent a support window reviewers then compare prose against prose which hides the fact that the contract lane never had a source of truth entry points and collected tests already encode installable commands and executable examples with more precision than marketing copy those artifacts should feed inventory tables while humans still own every sentence that binds the project to a promise lane definitions the compiler is allowed to use inventory lanes include command names module paths collected test node identifiers optional extra names and documented fixture roles contract lanes include intended audience authentication and authorization semantics data retention claims and explicit non goals support lanes include version windows deprecation dates incident response expectations and anything that implies an sla if a sentence cannot be regenerated from repository facts it belongs in a contract or support lane and stays unsigned by default 1 collect repository facts without a model start from files the package already ships not from a chat transcript that paraphrases them after the fact read pyproject toml for project name optional extras and console script entry points that users can actually install collect pytest node identifiers so example commands in the readme can be checked against tests that still exist the commands below are the only collection step they do not draft prose and they do not mark any contract cell as signed python c import tomllib pprint pathlib pprint pp tomllib loads pathlib path pyproject toml read_text pytest collect only q python m pip index versions 2 dev null python c import importlib metadata as m print m version unknown if false else use importlib metadata on an installed editable enter fullscreen mode exit fullscreen mode treat collection failures as ledger defects rather than as permission to guess a missing project scripts table means the command inventory stays empty until a human adds an entry point a pytest collection error means example rows stay unsigned because an undocumented test is not an executable readme claim do not paste stack traces into the readme during this step store them beside the ledger as operator notes 2 emit a readme ledger with explicit unsigned cells the proposal script below writes json that a later draft step may read and that a human must sign it is labeled a proposal because you should run it on your tree and inspect the output before any assistant sees the file keep contract and support values as null so a model cannot treat silence as approval inventory arrays may be filled from disk signature metadata stays empty until a named reviewer writes a date proposal run locally against a package that has pyproject toml from __future__ import annotations import json import subprocess import sys tomllib sys modules get tomllib or __import__ tomllib from pathlib import path root path cwd ledger root docs readme_ledger json def load_project dict data tomllib loads root pyproject toml read_text encoding utf 8 project data get project or scripts project get scripts or if isinstance project get scripts dict else extras sorted project get optional dependencies or keys return name project get name requires_python project get requires python scripts command k target v for k v in scripts items extras extras def collect_pytest_nodes list str proc subprocess run sys executable m pytest collect only q cwd root capture_output true text true check false if proc returncode not in 0 5 5 no tests collected return nodes for line in proc stdout splitlines line line strip if in line and not line startswith nodes append line return nodes 80 def build_ledger dict project load_project return inventory package_name project name requires_python project requires_python console_scripts project scripts optional_extras project extras pytest_nodes collect_pytest_nodes draft install_table_markdown none command_table_markdown none test_map_markdown none contract audience none auth_semantics none data_handling none non_goals none support compatibility_window none deprecations none incident_expectations none signatures contract_reviewer none contract_date none support_reviewer none support_date none def main none ledger parent mkdir parents true exist_ok true ledger build_ledger ledger write_text json dumps ledger indent 2 n encoding utf 8 print f wrote ledger with unsigned contract and support lanes if __name__ __main__ main enter fullscreen mode exit fullscreen mode run the compiler then fail the job if contract keys are already populated by a previous model pass that guard is cheap and prevents a regenerated readme from inheriting unsigned promises keep the ledger under docs so pull requests can diff json instead of scrolling through rewritten adjectives the next section turns that json into a review surface a human can actually finish mkdir p docs python readme_ledger py python c import json pathlib d json loads pathlib path docs readme_ledger json read_text assert all v is none for v in d contract values enter fullscreen mode exit fullscreen mode 3 decide what a model may draft versus what a human must sign use the decision table as the only allowlist when a drafting tool is connected later inventory cells may become markdown tables because they restate names and paths the compiler already proved contract cells must stay human authored even when the model offers a fluent paragraph that sounds like your existing voice support cells need a dated signature because they age independently of the code inventory and they create expectations outside the repository readme section source of truth model may draft human must sign reject if package name and extras pyproject toml no copy verbatim no wording changes from the toml install command table extras scripts yes table only no adds mirrors flags or sudo cli inventory project scripts yes names and targets no invents subcommands how we test map pytest node ids yes links node to heading no claims coverage percentages who this is for none no yes borrows audience from another product auth and secrets none no yes mentions tokens bypasses or sample keys data handling none no yes implies retention or deletion slas non goals none no yes softens a limitation into a roadmap compatibility window release policy no yes reads like an sla or uptime target deprecations changelog owners no yes back dates or hides a break copy the table into the pull request template so reviewers score rows instead of rereading the full readme a row that says model may draft still needs a diff against the ledger because table formatting is where extra flags usually appear a row that says human must sign should block merge while the signature object is null do not add a third lane for the model is pretty sure uncertainty belongs to the human not to a softer heading 4 fill draft cells without giving the model the contract lane draft cells can be filled locally or by a hosted assistant once the ledger json is the only prompt context disclosure this article was prepared as part of monkeycode s product outreach monkeycode offers free model access and a free server option that can expand inventory rows into readable markdown tables the assistant must receive the ledger file and a lane allowlist and it must not rewrite contract or support cells the prompt boundary is a file cut not a polite instruction buried in a long chat write docs draft_allowlist txt with the three draft keys and pass only inventory plus draft into the model workspace after the model returns re read contract support and signatures and fail if any byte changed the snippet below is a proposal for that check not a claim about any hosted quota or model name proposal compare unsigned lanes after a draft only model pass import json from pathlib import path before json loads path docs readme_ledger json read_text encoding utf 8 after_path is the file the draft step wrote keep it separate from signatures after json loads path docs readme_ledger after json read_text encoding utf 8 for lane in contract support signatures if before lane after lane raise systemexit f draft step mutated lane reject the readme regeneration for key value in after draft items if value is none raise systemexit f draft cell key still empty if http in value or bearer in value raise systemexit f draft cell key contains a credential shaped string print draft cells filled contract and support lanes unchanged enter fullscreen mode exit fullscreen mode render draft markdown into fenced placeholders inside readme md not over the signed sections html comments work as cheap fences that grep can find in review keep signed sections in a second file such as docs readme contract md if your publishing pipeline can concatenate them concatenation is easier to audit than a single document the model is allowed to rewrite from the first heading to the license footer ledger draft command_table_markdown command target pkg package cli main ledger draft command_table_markdown ledger contract audience human only leave empty until signatures contract_reviewer is set ledger contract audience enter fullscreen mode exit fullscreen mode 5 sign contracts with a reviewer name not with a regenerated paragraph a signature is a person a date and the hash of the contract object not a more confident adjective require those three fields in ci before readme publication jobs are allowed to run if the inventory changes because a new extra landed do not wipe the previous contract signature open a review that asks whether the promise still holds inventory churn is expected silent contract churn is the defect this ledger exists to make expensive python py import hashlib json pathlib p pathlib path docs readme_ledger json d json loads p read_text blob json dumps d contract sort_keys true encode print contract_sha256 hashlib sha256 blob hexdigest missing k for k v in d signatures items if v is none if missing raise systemexit unsigned fields join missing py enter fullscreen mode exit fullscreen mode when a human writes audience text keep it short enough that a later reviewer can disagree with a single sentence this cli is for operators who already hold database credentials is a contract easy to use for everyone is not a contract because nobody can test it and nobody can revoke it the same rule applies to authentication name the header the required role and the failure the client should expect or leave the cell null null is an honest state invented oauth poetry is not 6 prove the inventory still matches the readme tables add a test that reconstructs the command table from pyproject toml and compares it with the fenced draft block the test should fail on extra rows missing rows and command names that pytest never collected when the readme claims an example is tested label the test as a proposal until it runs in your ci image once it runs it becomes the only coverage that matters for this workflow documentation inventory stays coupled to installable facts proposal tests test_readme_ledger py import re from pathlib import path import tomllib readme path readme md read_text encoding utf 8 project tomllib loads path pyproject toml read_text encoding utf 8 def test_command_table_lists_only_declared_scripts scripts set project get project or get scripts or block re search r ledger draft command_table_markdown ledger draft command_table_markdown readme re s assert block missing draft fence for command table listed set re findall r block group 1 re m listed discard command listed discard assert listed scripts f readme commands not in pyproject scripts listed scripts assert scripts listed f pyproject scripts missing from readme scripts listed enter fullscreen mode exit fullscreen mode run the test whenever entry points move not only when someone edits readme prose that schedule is what keeps the compile lane honest after a refactor that never touched documentation files if the test is too strict for experimental packages shrink the fence to a single supported extra rather than disabling the assertion a smaller inventory is still a ledger an unbounded readme is a prompt dump limitations this workflow does not generate conceptual tutorials architecture decision records or legal terms and it should not be asked to pytest node identifiers describe what is executable not what is safe private or supported next quarter package metadata is silent about threat models so authentication cells stay empty until a human writes them teams that publish cryptographic or medical claims need a review path this ledger does not replace including counsel where the product already requires it the compiler also cannot see services that exist only in staging diagrams or in operator runbooks outside git if your readme must describe those systems keep them in the contract file and accept that the inventory test will not cover them do not scrape internal wikis into the draft lane to close that gap because that move reintroduces unsigned prose with a more official filename missing facts should remain visible nulls who should not use this approach skip this ledger if the repository has no tests no pyproject toml and no installable commands worth inventorying marketing sites changelog blogs and investor one pagers are not readme contracts and forcing them through unsigned json adds ceremony without a verifier do not use a drafting assistant on readme files that must include live credentials customer names or non public endpoints even when those strings are later redacted by hand the cheaper control is to keep those files out of the model workspace maintainers who already hand write a short readme and rarely change entry points will spend more time on the ledger than they save on tables in that case keep a single human owned readme and skip the compile step the method is for packages whose command surface and test map change faster than reviewers can reread marketing paragraphs it is a partition of labor not a requirement to host documentation generation on any particular server if you already generate inventory tables with monkeycode s free model access on the free server option feed it the ledger json and the allowlist rather than the raw repositor...