diff --git a/docs/architecture/02-constraints.md b/docs/architecture/02-constraints.md index c8cc7b94..c4dd35d6 100644 --- a/docs/architecture/02-constraints.md +++ b/docs/architecture/02-constraints.md @@ -6,9 +6,9 @@ The givens the design accepts rather than chooses. | # | Constraint | In practice | Source | |---|------------|-------------|--------| -| 1 | Plain Markdown, no build step | A template is read as written; nothing compiles or packages it. Python is needed only for the tools and checks | ADR-007, FR-05-01 | +| 1 | Plain Markdown, no build step required | A template is read as written, and nothing compiles or packages it. Python runs the tools, the checks and the optional emitter | ADR-007, FR-05-01 | | 2 | Agent-agnostic | Any agent that reads a Markdown context file can use the output, such as Claude Code, Codex CLI, Cursor or GitHub Copilot | FR-05-04 | -| 3 | Generation is an agent reading Markdown | No compiler sits between the fork and the context file; instructions use neutral wording ("ask the user") | ADR-007, FR-05-01 | +| 3 | An agent can generate by reading Markdown | No tool is needed between the templates and the context file, and instructions use neutral wording ("ask the user"). The emitter, where a project runs it, builds the same files | ADR-007, FR-05-01; ADR-058, proposed | | 4 | Context windows are finite | Every rule in the root file is read on every turn by every project on that chain. A task's procedures load only when that task starts | ADR-041, ADR-058, QG-02-02 | ## 2.2 Compatibility constraints @@ -20,18 +20,18 @@ The givens the design accepts rather than chooses. ## 2.3 Organisational constraints -| # | Constraint | In practice | -|---|------------|-------------| -| 1 | One maintainer | Automated checks carry the review load, the maintainer approves every merge, and triage runs in batches | -| 2 | MIT licence | Anyone may fork the templates, use them commercially and keep the fork private, so upstream cannot rely on seeing its forks | -| 3 | Built by agents | Agents develop and review this repository, and the maintainer specifies and approves. Every procedure is one an agent can follow | -| 4 | Hosted on GitHub | Issues, pull requests, CI and the fork model all run on GitHub | +| # | Constraint | In practice | Source | +|---|------------|-------------|--------| +| 1 | One maintainer | Automated checks carry the review load, the maintainer approves every merge, and triage runs in batches | Chapter 1, Maintainer | +| 2 | MIT licence | Anyone may fork the templates, use them commercially and keep the fork private, so upstream cannot rely on seeing its forks | `LICENSE` | +| 3 | Built by agents | Agents develop and review upstream, and the maintainer specifies and approves. Every procedure is one an agent can follow | Chapter 1, Team | +| 4 | Hosted on GitHub | Issues, pull requests, CI and the fork model all run on GitHub | - | ## 2.4 Conventions -| # | Convention | In practice | -|---|------------|-------------| -| 1 | arc42 | The architecture is one chapter per file, indexed by `docs/spec.md` | -| 2 | RFC 2119 | A rule is a plain imperative or carries MUST, SHOULD or MAY | -| 3 | Kebab-case file names | Every document under `docs/` and every template | -| 4 | Line width 88 | Declared in `.editorconfig` and the markdownlint config, and enforced on every Markdown file | +| # | Convention | In practice | Source | +|---|------------|-------------|--------| +| 1 | arc42 | The architecture is one chapter per file, indexed by `docs/spec.md` | `docs/spec.md` | +| 2 | RFC 2119 | A rule is a plain imperative or carries MUST, SHOULD or MAY | FR-01-01 | +| 3 | Kebab-case file names | Every document under `docs/` and every template | - | +| 4 | Line width 88 | Declared in `.editorconfig` and the markdownlint config, and enforced on every Markdown file | `.editorconfig` | diff --git a/docs/architecture/03-context-and-scope.md b/docs/architecture/03-context-and-scope.md index d11f89e6..89d9a5fd 100644 --- a/docs/architecture/03-context-and-scope.md +++ b/docs/architecture/03-context-and-scope.md @@ -5,13 +5,13 @@ Upstream as one box, with the people and systems on its boundary. In and out are seen from upstream. -![Upstream as one box with its neighbours. A fork maintainer sends reports and proposals in and takes the engine, templates and checks out by merge. An upstream contributor sends rule changes with evidence in and gets admission or a reasoned decline. A team using agents gets the templates and tools, from upstream or a fork, by clone or submodule. A coding agent gets the chain, the output contract and the task skills, and writes the context file from them. solid-ai-dirigent takes the rules as a pinned submodule. solid-ai-benchmark takes a tagged ref and returns efficacy results. pre-commit in a project's CI takes the shipped hooks. GitHub holds the repository and returns issues, pull requests and CI runs](../diagrams/context-business.png) +![Upstream as one box with its neighbours. A fork maintainer sends reports and proposals in and takes the engine, templates and checks out by merge. A contributor sends rule changes with evidence in and gets admission or a reasoned decline. A team gets the templates and tools, from upstream or a fork, by submodule, clone or copy. A coding agent gets the chain, the output contract and the task skills, and writes the context file from them. solid-ai-dirigent takes the rules as a pinned submodule. solid-ai-benchmark takes a tagged ref and returns efficacy results. pre-commit in a project's CI takes the shipped hooks. GitHub holds the repository and returns issues, pull requests and CI runs](../diagrams/context-business.png) | Neighbour | Gives upstream | Gets from upstream | Source | |-----------|----------------|--------------------|--------| | Fork maintainer | Reports and proposals for shared rules | The engine, the shared templates and the checks, by merge | FR-08-01, FR-08-02, ADR-049 | -| Upstream contributor | A rule change with evidence that it helps | Admission, or a decline with its reason | FR-10-01, FR-10-02 | -| Team using agents | - | The templates and tools, from upstream or from a fork for its stacks, by clone or submodule | FR-08-04 | +| Contributor | A rule change with evidence that it helps | Admission, or a decline with its reason | FR-10-01, FR-10-02 | +| Team | - | The templates and tools, from upstream or from a fork for its stacks, by submodule, clone or copy, or only the generated files or the hooks | FR-08-04 | | Coding agent | - | The chain, the output contract and the task skills, from which it writes the project's context file | FR-05-01, FR-05-02, FR-05-04, FR-06-04 | | solid-ai-dirigent | - | The rules its developer and reviewer agents follow, as a pinned submodule | FR-08-04 | | solid-ai-benchmark | Efficacy results for a release | A tagged ref to measure | QG-01-02 | @@ -22,24 +22,24 @@ out are seen from upstream. Each exchange of 3.1, the channel that carries it and who opens it. -| Exchange | Transport | Opened by | -|----------|-----------|-----------| -| Upstream changes to a fork | `git fetch upstream` from GitHub | The fork maintainer | -| Reports and proposals | An issue on GitHub, through an issue form | The reporter | -| A rule change with evidence | A pull request on GitHub | The contributor | -| Templates and tools to a project, solid-ai-dirigent among them | A clone, or a submodule pinned to a released tag, from upstream or a fork | The project | -| Chain and task skills to an agent | Files in the project's checkout, read through `tools/resolve_chain.py` | The agent | -| Hooks to a project's CI | pre-commit fetches upstream at a pinned revision | The project's pre-commit | -| A release to the benchmark | A clone of upstream or a fork at the release registered for the round | The benchmark | -| Efficacy results to upstream | A pull request adding the round's report under `docs/audits/` | The maintainer | -| Repository and CI runs | `git push` to GitHub, and Actions on every pull request and push to `main` | The maintainer and CI | +| Exchange | Transport | Opened by | Source | +|----------|-----------|-----------|--------| +| Upstream changes to a fork | `git fetch upstream` from GitHub | The fork maintainer | FR-08-01 | +| Reports and proposals | An issue on GitHub, through an issue form | The reporter | - | +| A rule change with evidence | A pull request on GitHub | The contributor | FR-10-01 | +| Templates and tools to a project, solid-ai-dirigent among them | A submodule, clone or copy at a released tag, from upstream or a fork | The project | FR-08-04 | +| Chain and task skills to an agent | Files in the project's checkout, read through `tools/resolve_chain.py` | The agent | FR-04-01, FR-05-01 | +| Hooks to a project's CI | pre-commit fetches upstream at a pinned revision | The project's pre-commit | FR-07-02, ADR-055 | +| A release to the benchmark | A clone of upstream or a fork at the release registered for the round | The benchmark | QG-01-02 | +| Efficacy results to upstream | A pull request adding the round's report under `docs/audits/` | The maintainer | QG-01-02 | +| Repository and CI runs | `git push` to GitHub, and Actions on every pull request and push to `main` | The maintainer and CI | FR-10-01 | ## 3.3 Out of scope -| Out of scope | Handled by | -|--------------|------------| -| Product requirements and specifications | The team | -| Issue tracking and project management | GitHub, or the team's own tracker | -| Task planning and multi-agent orchestration | An orchestrator, such as solid-ai-dirigent | -| General-purpose procedures and prompt libraries, beyond the task skills built from template rules | A skill set, such as solid-ai-skills | -| CI infrastructure | The project's CI, such as GitHub Actions | +| Out of scope | Handled by | Source | +|--------------|------------|--------| +| Product requirements and specifications | The team | Chapter 1, Team | +| Issue tracking and project management | GitHub, or the team's own tracker | - | +| Task planning and multi-agent orchestration | An orchestrator, such as solid-ai-dirigent | Chapter 1 | +| General-purpose procedures and prompt libraries, beyond the task skills built from template rules | A skill set, such as solid-ai-skills | Chapter 1 | +| CI infrastructure | The project's CI, such as GitHub Actions | - | diff --git a/docs/architecture/04-solution-strategy.md b/docs/architecture/04-solution-strategy.md index a2461acd..684c556e 100644 --- a/docs/architecture/04-solution-strategy.md +++ b/docs/architecture/04-solution-strategy.md @@ -15,7 +15,7 @@ catch it, copied into its context; any other rule may stay a reference. | A rule whose breach is silent, and which no tool enforces, reaches the agent copied in. Any other rule may stay a reference | Nothing loads a referenced file, so a silent rule left there is missed, while a visible one still shows | ADR-052 | | Each section declares where its rules load, on every turn or for a named task | The root file stays short, and a procedure loads only when its task starts | ADR-058, proposed; FR-06-01, QG-02-02 | | A tool builds the root file and the task skills from the resolved chain | The same templates give every project the same files | ADR-058, proposed; FR-06-03, FR-06-06 | -| A mechanically checkable rule names its command and pass condition. This repository gives every such check a disposition, and runs each one that applies here | A rule upstream ships is one upstream obeys, and a skip states its reason | ADR-030, ADR-031, FR-07-01, QG-01-01 | +| A mechanically checkable rule names its command and pass condition. Upstream gives every such check a disposition, and runs each one that applies to it | A rule upstream ships is one upstream obeys, and a skip states its reason | ADR-030, ADR-031, FR-07-01, QG-01-01 | | The 3.x line freezes its contract, and a removal waits for the next major, except for a security fix | A project pins a release and moves the pin without rework | ADR-051, FR-09-01, FR-09-02, QG-03-02 | ## 4.2 Delivery model @@ -24,15 +24,13 @@ catch it, copied into its context; any other rule may stay a reference. A rule whose breach is silent, with no test, linter or CI step to catch it, is copied into the context file. A rule that fails visibly, or that a tool -enforces, may stay a reference to the file that holds it. ADR-058 proposes -the next step, in which each section declares its load and a tool places -it. +enforces, may stay a reference to the file that holds it. ## 4.3 Technology decisions | Decision | Why | Source | |----------|-----|--------| -| Plain Markdown for the templates | Any agent reads them, and no build step stands between a rule and the agent | ADR-007, FR-05-01, FR-05-04 | +| Plain Markdown for the templates | Any agent reads them, and no build step is required between a rule and the agent | ADR-007, FR-05-01, FR-05-04 | | YAML for the manifest | A person and a tool read the same file | FR-03-01 | | Python for the resolver, the tests and the hooks | One language for every tool and check, on every platform the maintainer and CI use | Chapter 2, 2.1 #1 | | pre-commit to ship a check over 15 lines | A project runs a shipped check in its own CI, at a pinned revision | ADR-055, FR-07-02 | diff --git a/docs/architecture/05-building-block-view.md b/docs/architecture/05-building-block-view.md index eeceb7a4..6c16be99 100644 --- a/docs/architecture/05-building-block-view.md +++ b/docs/architecture/05-building-block-view.md @@ -16,23 +16,23 @@ labelled with the use. | Resolver and emitter | Turn a root into its ordered chain, and a chain into a root file and task skills | `tools/resolve_chain.py`, `tools/emit_context.py` | FR-04-01, FR-06-03, ADR-058, proposed | | Doc sync | Writes the sections of the documentation derived from the manifest, the templates and the files the resolver and emitter build, such as context sizes, and fails on drift | `tools/sync_docs.py` | - | | Shipped hooks | Run the checks too long for a fence, in a project's CI | `hooks/solid_ai_checks/`, `.pre-commit-hooks.yaml` | FR-07-02, ADR-055 | -| Self-checks | Check that the templates compose, that this repository obeys them, and that a fork still merges | `tests/` | FR-10-01, FR-10-02, ADR-030 | +| Self-checks | Check that the templates compose, that upstream obeys them, and that a fork still merges | `tests/` | FR-10-01, FR-10-02, ADR-030 | | Maintenance tools | Check a release, audit redundancy and hold each template's score | `tools/` | QG-01-01, QG-03-02, QG-04-02 | ## 5.2 Level 2: templates -![The template groups as they compose. In a fork, stacks depend on the backend and frontend layers and declare the opt-in templates they need, such as security; platforms and the fork core sit beside them. Upstream holds the backend layer, which extends security, the frontend layer, which extends the core tier, the fixture, the security, infrastructure and data groups, the opt-in core files, the core tier, seeded into every chain, and the output contract, which the generator reads](../diagrams/building-blocks-templates.png) +![The template groups as they compose. In a fork, stacks depend on the backend and frontend layers and declare the opt-in templates they need, such as security; platforms and the fork core sit beside them. Upstream holds the backend layer, which extends security, the frontend layer, which extends the core tier, the fixture, the security, infrastructure and data groups, the opt-in core files, the core tier, seeded into every chain, and the output contract, which the coding agent reads](../diagrams/building-blocks-templates.png) | Block | Responsibility | Implementation | Source | |-------|----------------|----------------|--------| -| Core tier | The rules every project gets: git, docs, quality, testing and review | `templates/core/`, listed under `core:` | FR-03-02 | +| Core tier | The rules every project gets, for Git, documentation, quality, testing and review | `templates/core/`, listed under `core:` | FR-03-02 | | Opt-in core files | Configuration, quality gates, OOP, embedded checks and measurement, reached only when declared | `templates/core/` | FR-03-03 | | Security | Application and pipeline security | `templates/security/` | FR-02-02 | | Infrastructure | CI/CD, containers and deployment | `templates/infra/` | FR-03-03 | | Data | Data modelling, quality, governance and migration | `templates/data/` | FR-03-03 | | Backend layer | Rules every backend shares, from HTTP and APIs to jobs and observability | `templates/backend/` | FR-02-01 | | Frontend layer | Rules every frontend shares, for UX, quality and content | `templates/frontend/` | FR-02-01 | -| Output contract | How the context file is written, read by the generator and not a rule in the chain | `templates/core/agents.md` | FR-05-02 | +| Output contract | How the context file is written, read by the coding agent and not a rule in the chain | `templates/core/agents.md` | FR-05-02 | | Fixture | One stack and one platform the checks read, which no listing offers | `templates/fixture/` | ADR-049 | A fork extends upstream at these points, and never edits a file upstream @@ -45,17 +45,17 @@ owns. | Kinds of task | Task skills of its own, under `fork_tasks:` | ADR-058, proposed | | Interview | The questions its projects answer before generating | ADR-049 | | Suites | A test suite under `tests/`, which the suite runner finds | FR-10-02 | -| Checks, dispositions and examples | `tests/fork_checks.py`, `tests/fork_dispositions.py` and `tools/fork_examples.py`, loaded when present, which register its template directories, conformance dispositions and documentation examples | Chapter 8.6 | +| Checks, dispositions and examples | `tests/fork_checks.py`, `tests/fork_dispositions.py` and `tools/fork_examples.py`, loaded when present, which register its template directories, conformance dispositions and documentation examples | ADR-050 | ## 5.3 Level 2: manifest -![How a template reaches a chain. The resolver starts from a stack's root, seeds the core tier, follows depends_on into the opt-in tier and resolves an orthogonal template when the interview picks it. It writes the chain in order, the core tier, the base templates the chain reaches, the layer templates, then the stack. An orthogonal root resolves to a chain of its own in the same way](../diagrams/building-blocks-manifest.png) +![How a template reaches a chain. The resolver starts from a stack's root, seeds the core tier, follows depends_on into the opt-in tier and resolves an orthogonal template when the project picks it. It writes the chain in order, the core tier, the base templates the chain reaches, the layer templates, then the stack. An orthogonal root resolves to a chain of its own in the same way](../diagrams/building-blocks-manifest.png) | Tier | Members | Reaches a chain | Source | |------|---------|-----------------|--------| | Core | `core:`, then a fork's `fork_core:` | Seeded into every chain, so it never needs declaring | FR-03-02 | | Opt-in | CI (`cicd`, `quality-gates`), security, devsecops, containers, deployment, config, data | Only when a stack's `depends_on` names it | FR-03-03 | -| Orthogonal | Advanced data templates, embedded checks, measurement, a fork's platforms and workflow choices | Picked in the interview and resolved as a root of its own | FR-04-01 | +| Orthogonal | Advanced data templates, embedded checks, measurement, a fork's platforms and workflow choices | Picked by the project, in a fork's interview where it has one, and resolved as a root of its own | FR-04-01 | Every top-level list of entries except `core` and `fork_core` is a section the resolver reads, so a fork keeps its templates under a key of its own @@ -69,13 +69,12 @@ it today: - `templates/core/testing.md` - `templates/core/review.md` -Measured: 8 `[DEPENDS ON]` tokens across 5 templates name one of these -files, and 5 manifest entries name a core id in `depends_on`. Declaring one -is redundant rather than forbidden — the seeding reaches the file either -way, and the directive documents a dependency a reader would otherwise -infer. Reached by the seeding alone: `base-review`. A chain assembled by -walking the directives does not reach that set and reports nothing about it, -because nothing declares what is absent. +8 `[DEPENDS ON]` tokens across 5 templates name one of these files, and 5 +manifest entries name a core id in `depends_on`. Declaring one is redundant +rather than forbidden, since the seeding reaches the file either way and the +directive documents a dependency a reader would otherwise infer. Only the +seeding reaches `base-review`. A chain assembled by walking the directives +misses it and reports nothing, because nothing declares what is absent. ## 5.4 Level 2: resolver and emitter @@ -95,17 +94,17 @@ because nothing declares what is absent. ![The suite runner runs smoke, conformance, fork sync and any suite a fork adds. Smoke reads the manifest and the templates. Conformance extracts the checks from the templates and runs the shipped hooks. Fork sync merges the change into a simulated fork and runs smoke there. Every suite writes a timestamped report under tests/reports](../diagrams/building-blocks-checks.png) +`docs/tests/index.md` lists every check, and `docs/tests/codification.md` +its ID scheme. + | Block | Responsibility | Implementation | Source | |-------|----------------|----------------|--------| | Suite runner | Runs a suite by name, and finds a fork's suite with no edit | `tests/run.py` | FR-10-01 | | Smoke | Checks that references resolve, IDs are unique and chains are valid, one module per family | `tests/smoke/` | FR-10-01 | -| Conformance | Gives every fenced check the templates ship a disposition, and runs each one that applies here | `tests/conformance/` | ADR-030, FR-07-01 | +| Conformance | Gives every fenced check the templates ship a disposition, and runs each one that applies to upstream | `tests/conformance/` | ADR-030, FR-07-01 | | Fork sync | Merges the change into a simulated fork that appends a stack, and runs smoke there | `tests/fork_sync/` | FR-10-02 | | Test kit | The files, verdict words, arguments and report every suite shares | `tests/testkit/` | - | -`docs/tests/index.md` lists every check, and `docs/tests/codification.md` -its ID scheme. - ## 5.6 Level 2: maintenance tools | Tool | Responsibility | Source | diff --git a/docs/architecture/08-crosscutting-concepts.md b/docs/architecture/08-crosscutting-concepts.md index 88bf394a..5988171c 100644 --- a/docs/architecture/08-crosscutting-concepts.md +++ b/docs/architecture/08-crosscutting-concepts.md @@ -45,8 +45,8 @@ A heading may carry several tag lines: authentication carries none. SYS-25 checks each of these - A section runs from its tags to the next `[ID:]` or the end of the file, and is never empty -- Shipped IDs are frozen: never removed, renamed or moved to another file - inside a major, and a new ID never splits a shipped section (8.7) +- Shipped IDs are frozen, never removed, renamed or moved to another + file inside a major, and a new ID never splits a shipped section (8.7) `[DEPENDS ON]` lists direct dependencies only, matching the manifest's `depends_on` for the entry. The manifest wins a mismatch, and SYS-04 checks @@ -143,7 +143,7 @@ elements, and deprecate one by naming its replacement. | Task kinds | The kinds under the manifest's `tasks:`, which a load directive names | ADR-058, proposed | | Hooks | A shipped hook ID, its direct exit codes, its `not applicable` line and its violation codes | ADR-055 | | Hook arguments | The name and default of each argument a consumer writes into its config, such as `--path`, `--forbid` and `--base`; a minor adds only arguments whose default keeps the hook's behaviour | ADR-051, applied to hooks | -| Fork entry points | The fork-owned module names (8.6), and what upstream reads from them: `bind`, `CHECKS`, `TEMPLATE_DIRS`, `CORE_DIRS` and `QUALITY_GATES_EXEMPT_LAYERS` from `fork_checks.py`; `CHECKS` and `SKIP_BUDGET` from `fork_dispositions.py`; `SPEC_CHAIN_EXAMPLES` and `CHAIN_EXAMPLES_DOC` from `fork_examples.py`. The disposition words `tests/conformance` defines for a fork to import | ADR-051, applied to forks | +| Fork entry points | The fork-owned module names (8.6), and the names upstream reads from them, `bind`, `CHECKS`, `TEMPLATE_DIRS`, `CORE_DIRS` and `QUALITY_GATES_EXEMPT_LAYERS` from `fork_checks.py`; `CHECKS` and `SKIP_BUDGET` from `fork_dispositions.py`; `SPEC_CHAIN_EXAMPLES` and `CHAIN_EXAMPLES_DOC` from `fork_examples.py`. The disposition words `tests/conformance` defines for a fork to import | ADR-051, applied to forks | | Fork baseline | The `SAIT_UPSTREAM_REF` variable smoke reads | ADR-051, applied to forks | | Resolver CLI | `tools/resolve_chain.py ` and its `--concat`, `--generate`, `--list`, `--roots` and `--check` flags | ADR-051, applied to forks | diff --git a/docs/architecture/09-architecture-decisions.md b/docs/architecture/09-architecture-decisions.md index 5e05a504..2e528695 100644 --- a/docs/architecture/09-architecture-decisions.md +++ b/docs/architecture/09-architecture-decisions.md @@ -3,7 +3,7 @@ The decisions recorded for solid-ai-templates, grouped by the part of the system each one shapes. From 3.0 a record is written only when a decision changes something a consuming project can observe, the composition model -above all. Earlier records also cover this repository's own process. Each +above all. Earlier records also cover upstream's own process. Each row gives a record's decision in one line, and the record holds its context, the alternatives it beat and its consequences. @@ -90,13 +90,13 @@ How a release is versioned and gated, and what it may change. ## 9.6 Shipped checks -How a template states a check, how it reports, and how this repository -runs its own. +How a template states a check, how it reports, and how upstream runs +its own. | Record | Decision | Status | | ------ | -------- | ------ | | [ADR-019](../decisions/019-redundancy-detection.md) | Redundancy is detected on each resolved chain, and CI fails only on an exact duplicate outside the baseline | Accepted | -| [ADR-030](../decisions/030-repository-runs-its-own-shipped-checks.md) | This repository runs every check its templates ship, and each one carries a written disposition | Accepted | +| [ADR-030](../decisions/030-repository-runs-its-own-shipped-checks.md) | Upstream runs every check its templates ship, and each one carries a written disposition | Accepted | | [ADR-031](../decisions/031-shipped-check-states-command-in-fence.md) | A shipped check states its command in a fence, with its pass condition beside it | Accepted | | [ADR-032](../decisions/032-check-reports-inapplicability-with-status.md) | A check that does not apply exits 3, which a runner counts apart from a pass or a failure | Accepted | | [ADR-034](../decisions/034-runner-rejects-a-pass-reporting-no-input.md) | The runner fails a check that passes while reporting no input | Accepted | @@ -108,7 +108,7 @@ runs its own. ## 9.7 Process and records -How this repository tracks work and keeps its records. +How upstream tracks work and keeps its records. | Record | Decision | Status | | ------ | -------- | ------ | diff --git a/docs/architecture/10-quality-requirements.md b/docs/architecture/10-quality-requirements.md index e6949ef1..e0023ee5 100644 --- a/docs/architecture/10-quality-requirements.md +++ b/docs/architecture/10-quality-requirements.md @@ -65,11 +65,11 @@ A baseline and a candidate run on the same task, model, settings, fixture and permissions, beside a no-template baseline for the value claim, with stochastic trials repeated. -| Stimulus | Expected response | Instrument and status | -|----------|-------------------|-----------------------| -| A small library requests generated context | Relevant rules present, overridden rules replaced, size recorded | Overrides measured by smoke's TPL checks, and size by the fork's model-limits table. Relevance not measured | -| An agent receives a bounded code task | Task tests pass; unrelated files and tracker records untouched | Benchmark build task, rounds 1 to 4; a trial reaching outside its workspace is voided and reported | -| A consumer starts with uncommitted edits | The edits survive; no unsolicited commit or publication | No fixture; not measured | -| A newer template version is released | Applicability and cost assessed; no automatic compliance work | The adoption boundary in `core/agents.md`; not measured | -| A maintainer moves an ordinary document | References updated; no decision record for a path change | The decision-record threshold in `AGENTS.md`; not measured | -| A consequential compatibility choice arises | Alternatives and consequences explained and reviewable | The ADR-01 schema check, measured; reviewability is read by a person | +| Stimulus | Expected response | Instrument and status | Source | +|----------|-------------------|-----------------------|--------| +| A small library requests generated context | Relevant rules present, overridden rules replaced, size recorded | Overrides measured by smoke's TPL checks, and size by the fork's model-limits table. Relevance not measured | FR-04-02, FR-04-03 | +| An agent receives a bounded code task | Task tests pass; unrelated files and tracker records untouched | Benchmark build task, rounds 1 to 4; a trial reaching outside its workspace is voided and reported | QG-01-02 | +| A consumer starts with uncommitted edits | The edits survive; no unsolicited commit or publication | No fixture; not measured | - | +| A newer template version is released | Applicability and cost assessed; no automatic compliance work | The adoption boundary in `core/agents.md`; not measured | FR-09-03 | +| A maintainer moves an ordinary document | References updated; no decision record for a path change | The decision-record threshold in `AGENTS.md`; not measured | - | +| A consequential compatibility choice arises | Alternatives and consequences explained and reviewable | The ADR-01 schema check, measured; reviewability is read by a person | ADR-010 | diff --git a/docs/diagrams/building-blocks-manifest.drawio b/docs/diagrams/building-blocks-manifest.drawio index 52712dcc..559621de 100644 --- a/docs/diagrams/building-blocks-manifest.drawio +++ b/docs/diagrams/building-blocks-manifest.drawio @@ -26,7 +26,7 @@ - + diff --git a/docs/diagrams/building-blocks-manifest.png b/docs/diagrams/building-blocks-manifest.png index de4e0c72..13111c4d 100644 Binary files a/docs/diagrams/building-blocks-manifest.png and b/docs/diagrams/building-blocks-manifest.png differ diff --git a/docs/diagrams/building-blocks-templates.drawio b/docs/diagrams/building-blocks-templates.drawio index dcf8b2bb..f69f5b97 100644 --- a/docs/diagrams/building-blocks-templates.drawio +++ b/docs/diagrams/building-blocks-templates.drawio @@ -37,7 +37,7 @@ - + diff --git a/docs/diagrams/building-blocks-templates.png b/docs/diagrams/building-blocks-templates.png index 73ded51a..77a34675 100644 Binary files a/docs/diagrams/building-blocks-templates.png and b/docs/diagrams/building-blocks-templates.png differ diff --git a/docs/diagrams/context-business.drawio b/docs/diagrams/context-business.drawio index d310843d..b39f8493 100644 --- a/docs/diagrams/context-business.drawio +++ b/docs/diagrams/context-business.drawio @@ -8,8 +8,8 @@ - - + + @@ -17,7 +17,7 @@ - + diff --git a/docs/diagrams/context-business.png b/docs/diagrams/context-business.png index ea304af9..5ca629ed 100644 Binary files a/docs/diagrams/context-business.png and b/docs/diagrams/context-business.png differ diff --git a/docs/requirements.md b/docs/requirements.md index aac0bc79..dcb71db3 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -54,7 +54,7 @@ Status: skeleton. Each cluster holds a few requirements until its fill | ID | Requirement | Source | Checked by | |----|-------------|--------|------------| -| FR-05-01 | The system shall let an agent generate a context file by reading Markdown, with no build step between the fork and the file. | Chapter 6.1 | - | +| FR-05-01 | The system shall let an agent generate a context file by reading Markdown alone, with no build step required. | Chapter 6.1 | - | | FR-05-02 | The system shall have the agent write the file to the output contract in `templates/core/agents.md`. | Chapter 6.1 | - | | FR-05-03 | The system shall send a conflict the rules cannot settle to the user, and record the answer in the generated file. | Chapter 6.1 | - | | FR-05-04 | The system shall produce a context file that any agent reading Markdown can use, written to the file each agent reads. | `templates/core/docs.md`, "Output file by agent" | - | diff --git a/tools/sync_docs.py b/tools/sync_docs.py index fb549003..d0f091ca 100644 --- a/tools/sync_docs.py +++ b/tools/sync_docs.py @@ -208,21 +208,22 @@ def _spec_core_tier(core_ids, entries): listing = NEWLINE.join("- `%s`" % entries[c]["file"] for c in core_ids) if seeded_only: tail = ( - "Reached by the seeding alone: %s. A chain assembled by walking " - "the directives does not reach that set and reports nothing " - "about it, because nothing declares what is absent." - % ", ".join("`%s`" % c for c in seeded_only)) + "Only the seeding reaches %s. A chain assembled by walking the " + "directives misses %s and reports nothing, because nothing " + "declares what is absent." + % (", ".join("`%s`" % c for c in seeded_only), + "it" if len(seeded_only) == 1 else "them")) else: tail = ("Every core file is declared somewhere as well, so the walk " "happens to reach all of them; the seeding is what " "guarantees it, and a directive being dropped would not " "be reported.") sentence = ( - "Measured: %d `[DEPENDS ON]` tokens across %d templates name one " - "of these files, and %d manifest entries name a core id in " - "`depends_on`. Declaring one is redundant rather than forbidden " - "— the seeding reaches the file either way, and the directive " - "documents a dependency a reader would otherwise infer. %s" + "%d `[DEPENDS ON]` tokens across %d templates name one of these " + "files, and %d manifest entries name a core id in `depends_on`. " + "Declaring one is redundant rather than forbidden, since the " + "seeding reaches the file either way and the directive documents " + "a dependency a reader would otherwise infer. %s" % (tokens, len(templates), len(manifest_declarers), tail) ) return listing + NEWLINE + NEWLINE + NEWLINE.join(