Repository navigation
Chirality Library 3.4.0
A scope of work now leads and a deliverable is two files; every project's AGENTS.md can carry the same two passages on how work and agents are organised, with the project-entry template as their source. The entry layer and the way agents are organised changed in this edition: it is not a guidance-only revision, and a project on the three-file entry layout must change that layout to adopt it.
Source: 1bba3d170e7a25bc2a04e0a4dfe77b624ea440ca
Tag: library-v3.4.0
Archive: chirality-library-3.4.0-source.tar (779 tracked files)
SHA-256: b4f0ec20b5e9a26125a16002e95895e5171ebeb6d4e44664e400f18dfe9eb7b5
Changes since 3.3.0
Compare editions. The changes are in pull requests #31 to #41 and #43; each describes its own change.
Scopes of work and deliverable localities
- The scope leads.
workflows/scope-of-work/WORKFLOW.mdopens with a new section, "What a scope says": what each of a scope's six parts holds, that code is measured against the scope, and that a decision appears only as the current statement it settles. "Requirements and their grounds" and "Changing a statement" replace the earlier list of where an expected result comes from; decision labels, dates and quoted approvals no longer belong in a scope. The revise step no longer writes an amendment record into the scope. A new "Verification entries" section has each entry written or changed from now on state its kind: an executable check, a comparison with a named reference, or a judgment by a named role. An unchanged entry without a kind fails in no mode. The method also adds an independent reading: a reviewer who did not write a scope, and does not see the writer's reasoning, reads it against the PRD and decomposition, the code it represents and neighbouring scopes. - The scope validator no longer requires a revision pin. In 3.3.0,
tools/scope_of_workrejected a scope whosedecomposition_basisdid not bind a path and a revision with@. That check is removed. A scope with a pin still validates. A scope written without one fails the 3.3.0 validator and passes this one, so a project whose scopes follow the changed method needs this edition's tools. - A deliverable locality is
ScopeOfWork.mdanddeliverable.yaml; there is noWork/folder. Scaffolding (tools/scaffolding) no longer creates or requiresWork/; an existingWork/folder in a consumer's locality is tolerated and left untouched. The deliverables guide,bounded-reconciliation,dependency-extract,define-work,construct-local-work-graph, the audit and estimate workflows and thepreparationskill no longer read or write it.scope-change-packetreturns its result instead of writing a run record.docs/PRD.mdR08 defines the locality the same way. - Needs.
bounded-reconciliationand the entry passages have a contributor correct a need the work showed to be wrong, missing or no longer applicable, in the same pull request.dependency-extractstates that a need is not removed for being met, and addswhenwhere the source states when the need applies. A need'sconditionis now written as what the neighbour observably provides, in the provider's product terms, and tested by asking which acceptance criterion in the provider's scope makes it true; where none does, the need creates no obligation on the provider and the gap is returned. The workflow and the deliverables guide no longer document the optionalevidencefield of a need; the tools were not changed to reject it, so existing declarations that carry one need no edit. - How work will be known to be done.
software-decompgains a section 9, "Examination and Integrated Path" (each deliverable's expected examination, each objective's check, the thin end-to-end path, any coupled core), for decompositions begun under this text, and now states its conformance rules in the package: where ambiguity remains, the package's stated purpose governs interpretation, in place of the rationale of a standard held outside the Library.software-test-planningreturns a check of stated kind for each claim in a criterion and says how a miss would fail it.coordinated-knowledge-workcarries the criteria and the check in the brief and establishes the combined check first. In current project setup and package activation, where the project's own standing instructions call for independent scrutiny of a class of change, someone who did not write a verification entry asks whether it could pass while its criterion is unmet, before dependent implementation relies on it. That follows the project's existing scrutiny rules and is not a setup gate.
Entry instructions and how agents are organised
- Two-file entry layer. A project's entry is a root
init-prompt.mdandAGENTS.md(withCLAUDE.mdcontaining@AGENTS.md). There is noinit/folder and noloop/LOOP_INIT.md; what the loop entry held is inAGENTS.md. The Library's own entry documents follow this layout. - The project-entry template is the source of two common passages.
workflows/project-setup/resources/project-entry.mdholds "How the work is organised" (packages, deliverables, scopes of work, needs, code paths, the two queries, and when a scope, a need or a criterion is corrected or taken to the owner) and "How agents are organised" (Agent 0, Type 1 and Type 2; assignments and returns; independent review; the INTERLOCUTOR; which role text each relationship loads). A project copies them word for word and fills two named slots: its list of deliverables, and what<query>is there. The template's shared text no longer carries the role table, the working cycle or the criterion paragraph, which the passages replace. - What the passages change in meaning. A Type 1 agent is started in a new thread of its own, at the same level as Agent 0's, and the owner may work with it directly; a Type 2 agent is delegated as a child and starts no other agent. "Delegate" is kept for a Type 2. A Type 1 may start another Type 1; any agent may message any other, with assignments and returns usually following the line of assignment. Each independent review is a fresh reviewer. Models and effort come from the owner's steering for a session and are named in no file.
- Section order, postures, rules and grants. The template gives an order of sections for
AGENTS.md; two postures a project may select for a phase ("finishing toward a target" and "pruning and honing"); and a rule that a rule inAGENTS.mdstands on its own, with the owner's words kept only where they are a grant and define its extent or conditions. - What the finishing posture requires of a project that selects it. The posture is reusable and the grant is not: a project selects it only where its owner has delegated the decisions it describes, and inserts that grant itself, in the owner's words. Everything in it applies within the extent, conditions and reservations of that grant, including any limit on passing those decisions on. A Type 1 agent decides how the work within the locality of its assignment is done and takes a changed commitment, criterion or hold to Agent 0. A decision's record names the agent that decided, never the owner; and a criterion that requires the owner as actor is corrected in its scope, with its review, before it is relied on. The posture changes no verification, required check or independent review.
- Entry-prompt check.
init-prompt.mdconfirms that the checkout'sAGENTS.mdis the one on the repository's default branch and reports a difference before relying on it. A project working toward a release target also asks the first report for the path to that target and what it needs from the owner. - Root relationship. The template's shared text states what Root may do in a project: read session telemetry read-only and segregated by repository; change the project's files within work the owner has authorised, through a pull request there under the project's own instructions, checks and Git grant; and open an issue for an approved finding. In 3.3.0 the template said Root changes no files in a project.
- INTERLOCUTOR.
agents/AGENT_INTERLOCUTOR.mddescribes a Type 2 child that Agent 0 starts within its own session and continues by message, replaced only if it is lost or the owner asks; in 3.3.0 it described a separate paired session. In each review round it examines the findings and the proposed response against the undertaking's purpose and the earlier rounds before the response is settled, including rounds a Type 1 runs. - HELP_HUMAN. One sentence is removed from
agents/AGENT_HELP_HUMAN.md: "Keep a replaceable recovery note only when needed." - Packaged product instructions. The template tells an application that bundles agent instructions to keep canonical runtime assets in the product's source locations and list the maintained and shipped paths in
deliverable.yaml; it no longer asks for a master copy inWork/.
The retained setup route
-
project-setup-retainedis a new workflow package. It holds the retained DOMAIN and legacy phase and control-file contract and method that 3.3.0 kept inproject-setup. It is selected explicitly withWorkflow: project-setup-retained; existing files alone do not select it. Its DOMAIN and semantic phases are restored against today's packages; phases 2.1b, 2.5 and 4.3 are stated as not provided. Because phase 2.1b's ratification recheck is absent, DOMAIN drafting proceeds only on an acceptedCLUSTER_COHERENTverdict inKTY_Scope_Ratification.csvand halts for the human where the verdict or the register is missing; a retrieval index that changed after ratification is not rechecked, and incremental setup surfaces a changed index before dispatch. -
Pointers remain at the old paths.
workflows/project-setup/resources/contract.mdandworkflows/project-setup/resources/method.mdstill exist, are no longer a contract or a method, and say where each went. A persisted record that namesproject-setupinINITIALorINCREMENTALmode is read as namingproject-setup-retained.project-setupitself is the current PROJECT and SOFTWARE setup route. The workflow index lists 78 methods. -
Runtime telemetry instruction removed from package activation.
workflows/project-setup/resources/package-activation.mdno longer tells setup to collect runtime telemetry or bindRUNTIME_SUMMARY.json. The telemetry tool itself is still in the Library.
What a repository keeps
- No routine records, without the earlier exception. The template's shared text now reads "No receipts, notices, run records, accounts of the work, recovery notes or handoff chains". In 3.3.0 it prohibited routine records and allowed a replaceable recovery note where recovery needed one. Continuity comes from the actual artifacts and the review record: the scope, the code and the pull request.
reflect-on-workworks from the scopes, the code and the review record; a decision edits the text it governs and the pull request says what changed. It creates no reflection report; 3.3.0 prohibited only a recurring one.bounded-reconciliationcompares the scope with the code it represents and no longer revisesWork/material or keeps a current-state note.docs/document-metadata.mdnamesinit-prompt.mdas the bootstrap document and treatsloop/LOOP_INIT.mdas a retained form. Thesis chapters 4 and 8 and the glossary describe the two-file locality and treatWork/as historical.
The Library's own records
- The Library's eight deliverable scopes are rewritten under the changed method, and its own
AGENTS.mdadopts the two passages. These are the Library's project records, not material a consumer adopts. - Chirality in Practice, first edition, is re-rendered: four links to removed
Work/files now point at a fixed revision. Its text is otherwise unchanged.
Removed and moved paths
A consumer that reads any of these paths from a 3.3.0 checkout will not find them in 3.4.0.
| Path in 3.3.0 | In 3.4.0 |
|---|---|
init/init-prompt.md |
Moved to init-prompt.md at the repository root, and revised. |
loop/LOOP_INIT.md |
Removed. Its content is in AGENTS.md, under "Chirality Library development entry". |
execution/_Coordination/LOOP_INIT.md |
Removed. It was a pointer to the loop entry. |
execution/PKG-nn/DEL-nn-nn/Work/ (eleven files in eight folders) |
Removed. Each file's last content is at revision 1d536c58b787db14d544783667e0fbe4d8c44cbd of this repository, and all eleven are in the 3.3.0 archive. |
execution/PKG-05/DEL-05-01/Work/PublicationNotes.md, PublicationNotes-1.1.0.md, PublicationNotes-2.1.0.md |
Removed with the folder above. They are the publication notes of editions 1.0.0, 1.1.0 and 2.1.0, at the same revision and in the 3.3.0 archive. |
workflows/project-setup/resources/contract.md and method.md |
Kept as pointers; the content is in workflows/project-setup-retained/resources/. |
Anchors in the Library's AGENTS.md that other holdings cite are unchanged: #working-cycle, #holding-changes-and-recovery, #standing-git-grant and #chirality-library-development-entry. The "Working cycle" section is shorter; the rule it held on correcting a scope is now in "How the work is organised".
Adopting 3.4.0
Adoption is each project's own decision and change. A project that selects this edition should expect to:
- Change its entry layout if it still has three files. Move the prompt to a root
init-prompt.md, fold the loop entry intoAGENTS.md, and removeinit/andloop/. Add the entry-prompt check. - Place the two common passages from the template in its
AGENTS.md, word for word, filling the two slots, and take out of its own file whatever the passages now say. Local grants, delegations, reservations and holds stay in the project's file beside the action they govern; nothing in the template grants anything. - Check its scopes with this edition's validator. Scopes with or without a revision pin in
decomposition_basispass on that point. - Decide what to do with its own
Work/folders. The Library's tools no longer create or read them and do not remove them. Before removing one, check whether a scope, a need or later work rests on a record it holds. - Select
project-setup-retainedby name where it uses the retained DOMAIN or legacy setup route. - Reconcile adapted documents with
Workflow: compare-library-derivations, and advancemetadata.upstream.editiontolibrary-v3.4.0only for a document that has been wholly reconciled against this edition.
Verification and delivery
The archive was produced from the Git objects of the source commit. Its 779 entries equal that commit's tracked tree in path, bytes and executable mode, with nothing added, and it identifies the commit. A credential and machine-local symlink scan of all 779 files found nothing. In the extracted source, without Git: the workflow index equals what the package metadata generate; the workflow metadata and role instruction validators report no errors; 269 schema, role, catalog, runtime and scope tests pass; all eight Library scopes validate; and the committed reading edition of Chirality in Practice equals a fresh render of its source. This edition's validator accepts a 3.3.0 scope that carries a revision pin and a scope that carries none; the 3.3.0 validator rejects the latter. SHA256SUMS covers the attached archive. No source change was made for publication.
Read source files directly or run tools in place with their documented dependencies (Python 3 and PyYAML for the validators and queries; pyproject.toml declares the rest). Git-dependent queries need a clone with history.
Known limitations
- The two common passages, the postures and the changed INTERLOCUTOR text have had little use; whether agents follow them as intended has not been measured.
- The restored DOMAIN and semantic text in
project-setup-retainedwas checked field by field against today's packages and has not been run end to end. - No tool enforces a verification entry's stated kind.
project-decomphas no counterpart tosoftware-decompsection 9. - The scope format's required headings, identifier grammar and matrix columns are described only by the behaviour of
tools/scope_of_work. - The named compatibility probe for the App's workflow-package reader (
tools/workflow_runtime/fixtures/app_workflow_reader.rs) was run against earlier bytes ofcoordinated-knowledge-work, which this edition and 3.3.0 both change. The probe was not rerun, and the named-compatibility claim for that reader is not made for 3.4.0. A consumer that has that reader examines it against this edition'scoordinated-knowledge-workpackage when it adopts. - Some of the Library's own records refer to removed files without a revision and no longer resolve:
docs/thesis/08_implementation.mdlinksloop/LOOP_INIT.md;execution/_Decomposition/PROJECT_DECOMP.mdlinks and namesexecution/_Coordination/LOOP_INIT.md;docs/PRD.md§5 cites "DEL-03-02's evaluation basis"; and accepted amendment records underexecution/_ScopeChange/nameWork/files. The content each refers to is at revision1d536c58b787db14d544783667e0fbe4d8c44cbdand in the 3.3.0 archive. - Three of the Library's own scopes rest on results that were recorded in the removed
Work/files and are now only at that revision: the observed result of the compatibility probe (DEL-05-01), the verification of the evaluation tools' transfer to Root that the PRD cites (DEL-03-02), and the identification of the case DEL-04-02's criteria refer to. This affects the Library's account of its own deliverables, not the holdings a consumer selects. execution/_Coordination/PUBLICATION_ROADMAP.mddescribes the publication of edition 1.0.0 and is not a description of this edition.- Publication changes no consumer's selection. Each project adopts through its own change process and keeps separately pinned product assets on their own route.