Skip to content

Chirality Library 3.4.0

Latest

Choose a tag to compare

@sgttomas sgttomas released this 12 Nov 03:29
· 13 commits to main since this release
1bba3d1

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.md opens 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_work rejected a scope whose decomposition_basis did 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.md and deliverable.yaml; there is no Work/ folder. Scaffolding (tools/scaffolding) no longer creates or requires Work/; an existing Work/ 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 the preparation skill no longer read or write it. scope-change-packet returns its result instead of writing a run record. docs/PRD.md R08 defines the locality the same way.
  • Needs. bounded-reconciliation and 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-extract states that a need is not removed for being met, and adds when where the source states when the need applies. A need's condition is 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 optional evidence field 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-decomp gains 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-planning returns a check of stated kind for each claim in a criterion and says how a miss would fail it. coordinated-knowledge-work carries 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.md and AGENTS.md (with CLAUDE.md containing @AGENTS.md). There is no init/ folder and no loop/LOOP_INIT.md; what the loop entry held is in AGENTS.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.md holds "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 in AGENTS.md stands 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.md confirms that the checkout's AGENTS.md is 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.md describes 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 in Work/.

The retained setup route

  • project-setup-retained is a new workflow package. It holds the retained DOMAIN and legacy phase and control-file contract and method that 3.3.0 kept in project-setup. It is selected explicitly with Workflow: 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 accepted CLUSTER_COHERENT verdict in KTY_Scope_Ratification.csv and 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.md and workflows/project-setup/resources/method.md still exist, are no longer a contract or a method, and say where each went. A persisted record that names project-setup in INITIAL or INCREMENTAL mode is read as naming project-setup-retained. project-setup itself 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.md no longer tells setup to collect runtime telemetry or bind RUNTIME_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-work works 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-reconciliation compares the scope with the code it represents and no longer revises Work/ material or keeps a current-state note.
  • docs/document-metadata.md names init-prompt.md as the bootstrap document and treats loop/LOOP_INIT.md as a retained form. Thesis chapters 4 and 8 and the glossary describe the two-file locality and treat Work/ as historical.

The Library's own records

  • The Library's eight deliverable scopes are rewritten under the changed method, and its own AGENTS.md adopts 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:

  1. Change its entry layout if it still has three files. Move the prompt to a root init-prompt.md, fold the loop entry into AGENTS.md, and remove init/ and loop/. Add the entry-prompt check.
  2. 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.
  3. Check its scopes with this edition's validator. Scopes with or without a revision pin in decomposition_basis pass on that point.
  4. 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.
  5. Select project-setup-retained by name where it uses the retained DOMAIN or legacy setup route.
  6. Reconcile adapted documents with Workflow: compare-library-derivations, and advance metadata.upstream.edition to library-v3.4.0 only 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-retained was 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-decomp has no counterpart to software-decomp section 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 of coordinated-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's coordinated-knowledge-work package 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.md links loop/LOOP_INIT.md; execution/_Decomposition/PROJECT_DECOMP.md links and names execution/_Coordination/LOOP_INIT.md; docs/PRD.md §5 cites "DEL-03-02's evaluation basis"; and accepted amendment records under execution/_ScopeChange/ name Work/ files. The content each refers to is at revision 1d536c58b787db14d544783667e0fbe4d8c44cbd and 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.md describes 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.