Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/architecture/05-building-block-view.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,12 +49,12 @@ owns.

## 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 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)
![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 first, then each dependency depth-first before what needs it, and the root last, unless the core tier already holds it. 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 |
| Opt-in | CI (`cicd`, `quality-gates`), security, devsecops, containers, deployment, config, data | When a project picks it as a root, or a chosen root's dependency tree names it | FR-03-03 |
| 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
Expand Down
4 changes: 2 additions & 2 deletions docs/architecture/06-runtime-view.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ orders, placing each rule where the output contract says.
|------|--------------|--------|
| 1 | The team names a root, such as a stack, and the agent generates its context by reading Markdown | FR-05-01 |
| 2-3 | The questions live in the fork's interview. A conflict the rules cannot settle goes to the team, and the answer is recorded in the file | ADR-049, FR-05-03 |
| 4 | The resolver seeds the core tier, then walks `depends_on` depth-first, without duplicates, base before layer before stack | FR-03-02, FR-04-01 |
| 4 | The resolver seeds the core tier, then walks `depends_on` depth-first, without duplicates, each dependency before what depends on it | FR-03-02, FR-04-01 |
| 5-6 | An override replaces a section, and each extension of the same ID adds to it. An inline file copies in every adopted rule. A hybrid file copies in every rule whose breach is silent and which no tool enforces, and any other rule may stay a reference | FR-04-02, FR-04-03, ADR-052 |
| 7-8 | The agent writes both files to the output contract, then runs the contract's self-check against them | FR-05-02, FR-05-04 |
| 9 | The emitter leaves out overridden rules and the sections the project declines, places each remaining section by its load, copies each rule's text unchanged, and builds the same files from the same input | ADR-058, proposed; FR-06-03, FR-06-06 |
Expand Down Expand Up @@ -100,5 +100,5 @@ takes, and only a regeneration or an edit changes its context files.
| Scenario | What happens | Source |
|----------|--------------|--------|
| A pull request upstream | CI runs smoke, conformance and fork sync, and the maintainer approves the merge | FR-10-01, FR-10-02 |
| Cutting a release | `tools/cut_changelog.py` writes an entry for each merged pull request from its `changelog:` label and cuts the `Unreleased` section into the version, and `tools/check_release.py` checks the section and the SemVer step before the tag | QG-03-02 |
| Cutting a release | `tools/cut_changelog.py` writes an entry for each pull request merged since the previous tag whose `changelog:` label names a section, and cuts the `Unreleased` section into the version, and `tools/check_release.py` checks the section and the SemVer step before the tag | QG-03-02, FR-09-04 |
| Deprecating a template | It keeps resolving until the next major, naming a live replacement | FR-09-02 |
5 changes: 3 additions & 2 deletions docs/architecture/08-crosscutting-concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,9 @@ A heading may carry several tag lines:
check enforces. A heading without one loads on every turn, and a
heading's subheadings take its load (ADR-058, proposed)
- A heading carries one load at most, among its tags, and none under a
heading that has one. A template that guards data, credentials or
authentication carries none. SYS-25 checks each of these
heading that has one. A section whose breaking exposes data, credentials
or an unauthenticated path carries none. SYS-25 checks each of these, the
last for the security templates and `backend/auth.md`
- 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
Expand Down
6 changes: 3 additions & 3 deletions docs/diagrams/building-blocks-manifest.drawio
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@
<mxCell id="c12" parent="c11" style="shape=module;jettyWidth=6;jettyHeight=3;html=1;fillColor=#FFFFFF;strokeColor=#B45309;strokeWidth=1.2;" value="" vertex="1"><mxGeometry x="276" y="7" width="15" height="14" as="geometry" /></mxCell>
<mxCell id="c13" parent="1" style="shape=folder;tabWidth=182;tabHeight=24;tabPosition=left;html=1;whiteSpace=wrap;fillColor=#FFFFFF;strokeColor=#94A3B8;strokeWidth=1.5;verticalAlign=top;align=left;spacingLeft=10;spacingTop=2;fontFamily=Segoe UI;fontSize=13;fontStyle=1;fontColor=#475569;" value="The chain, in order" vertex="1"><mxGeometry x="1000" y="120" width="400" height="460" as="geometry" /></mxCell>
<mxCell id="c14" parent="1" style="shape=note;size=14;whiteSpace=wrap;html=1;fillColor=#FFFFFF;strokeColor=#475569;strokeWidth=1.6;shadow=1;align=center;verticalAlign=middle;fontFamily=Segoe UI;fontSize=15;fontStyle=1;fontColor=#0F172A;spacingLeft=10;spacingRight=10;" value="1. Core tier" vertex="1"><mxGeometry x="1040" y="170" width="320" height="60" as="geometry" /></mxCell>
<mxCell id="c15" parent="1" style="shape=note;size=14;whiteSpace=wrap;html=1;fillColor=#FFFFFF;strokeColor=#475569;strokeWidth=1.6;shadow=1;align=center;verticalAlign=middle;fontFamily=Segoe UI;fontSize=15;fontStyle=1;fontColor=#0F172A;spacingLeft=10;spacingRight=10;" value="2. Base templates it reaches" vertex="1"><mxGeometry x="1040" y="270" width="320" height="60" as="geometry" /></mxCell>
<mxCell id="c16" parent="1" style="shape=note;size=14;whiteSpace=wrap;html=1;fillColor=#FFFFFF;strokeColor=#475569;strokeWidth=1.6;shadow=1;align=center;verticalAlign=middle;fontFamily=Segoe UI;fontSize=15;fontStyle=1;fontColor=#0F172A;spacingLeft=10;spacingRight=10;" value="3. Layer templates" vertex="1"><mxGeometry x="1040" y="370" width="320" height="60" as="geometry" /></mxCell>
<mxCell id="c17" parent="1" style="shape=note;size=14;whiteSpace=wrap;html=1;fillColor=#FFFFFF;strokeColor=#475569;strokeWidth=1.6;shadow=1;align=center;verticalAlign=middle;fontFamily=Segoe UI;fontSize=15;fontStyle=1;fontColor=#0F172A;spacingLeft=10;spacingRight=10;" value="4. The stack" vertex="1"><mxGeometry x="1040" y="470" width="320" height="60" as="geometry" /></mxCell>
<mxCell id="c15" parent="1" style="shape=note;size=14;whiteSpace=wrap;html=1;fillColor=#FFFFFF;strokeColor=#475569;strokeWidth=1.6;shadow=1;align=center;verticalAlign=middle;fontFamily=Segoe UI;fontSize=15;fontStyle=1;fontColor=#0F172A;spacingLeft=10;spacingRight=10;" value="2. Dependencies, depth-first" vertex="1"><mxGeometry x="1040" y="270" width="320" height="60" as="geometry" /></mxCell>
<mxCell id="c16" parent="1" style="shape=note;size=14;whiteSpace=wrap;html=1;fillColor=#FFFFFF;strokeColor=#475569;strokeWidth=1.6;shadow=1;align=center;verticalAlign=middle;fontFamily=Segoe UI;fontSize=15;fontStyle=1;fontColor=#0F172A;spacingLeft=10;spacingRight=10;" value="3. Each before what needs it" vertex="1"><mxGeometry x="1040" y="370" width="320" height="60" as="geometry" /></mxCell>
<mxCell id="c17" parent="1" style="shape=note;size=14;whiteSpace=wrap;html=1;fillColor=#FFFFFF;strokeColor=#475569;strokeWidth=1.6;shadow=1;align=center;verticalAlign=middle;fontFamily=Segoe UI;fontSize=15;fontStyle=1;fontColor=#0F172A;spacingLeft=10;spacingRight=10;" value="4. The root, if not core" vertex="1"><mxGeometry x="1040" y="470" width="320" height="60" as="geometry" /></mxCell>
<mxCell id="c18" parent="1" source="c11" target="c3" style="endArrow=open;endFill=0;endSize=10;dashed=1;dashPattern=6 4;html=1;strokeColor=#64748B;strokeWidth=1.8;rounded=1;arcSize=12;jumpStyle=arc;jumpSize=10;edgeStyle=orthogonalEdgeStyle;fontFamily=Segoe UI;fontSize=13;fontStyle=1;fontColor=#475569;labelBackgroundColor=#FFFFFF;exitX=0;exitY=0.0714;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" value="«seeds»" edge="1"><mxGeometry relative="1" as="geometry"></mxGeometry></mxCell>
<mxCell id="c19" parent="1" source="c11" target="c5" style="endArrow=open;endFill=0;endSize=10;dashed=1;dashPattern=6 4;html=1;strokeColor=#64748B;strokeWidth=1.8;rounded=1;arcSize=12;jumpStyle=arc;jumpSize=10;edgeStyle=orthogonalEdgeStyle;fontFamily=Segoe UI;fontSize=13;fontStyle=1;fontColor=#475569;labelBackgroundColor=#FFFFFF;exitX=0;exitY=0.357;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" value="«follows depends_on»" edge="1"><mxGeometry relative="1" as="geometry"></mxGeometry></mxCell>
<mxCell id="c20" parent="1" source="c11" target="c7" style="endArrow=open;endFill=0;endSize=10;dashed=1;dashPattern=6 4;html=1;strokeColor=#64748B;strokeWidth=1.8;rounded=1;arcSize=12;jumpStyle=arc;jumpSize=10;edgeStyle=orthogonalEdgeStyle;fontFamily=Segoe UI;fontSize=13;fontStyle=1;fontColor=#475569;labelBackgroundColor=#FFFFFF;exitX=0;exitY=0.643;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" value="«resolves when picked»" edge="1"><mxGeometry relative="1" as="geometry"></mxGeometry></mxCell>
Expand Down
Binary file modified docs/diagrams/building-blocks-manifest.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
33 changes: 17 additions & 16 deletions docs/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@ Status: skeleton. Each cluster holds a few requirements until its fill
| ID | Requirement | Source | Checked by |
|----|-------------|--------|------------|
| FR-01-01 | The system shall state each rule as a plain imperative, or with an RFC 2119 keyword where strength matters. | Chapter 8.9 | - |
| FR-01-02 | The system shall give a section an ID when something references it, unique across all templates. | Chapter 8.1 | SYS-02 |
| FR-01-03 | The system shall name another file's section in prose only where that file is in every chain carrying the rule. | Chapter 8.4 | SYS-11 |
| FR-01-02 | The system shall give a section an ID when something references it, unique across all templates. | Chapter 8.1 | SYS-02, partial, for uniqueness |
| FR-01-03 | The system shall name another file's section in prose only where that file is in every chain carrying the rule. | Chapter 8.4 | SYS-11, partial: it skips a root a stack already reaches |

### 02. Layers

Expand All @@ -36,16 +36,16 @@ Status: skeleton. Each cluster holds a few requirements until its fill

| ID | Requirement | Source | Checked by |
|----|-------------|--------|------------|
| FR-03-01 | The system shall register every template in one manifest entry, with an ID unique across all layers. | `AGENTS.md` 4.1 | SYS-03, MNF-01 |
| FR-03-01 | The system shall register every template in one manifest entry, with an ID unique across all layers. | `AGENTS.md` 4.1 | SYS-03, MNF-01, partial: nothing stops two entries naming one file |
| FR-03-02 | The system shall seed the core tier, `core:` then `fork_core:`, into every chain without a declaration. | Chapter 5.3 | - |
| FR-03-03 | The system shall reach an opt-in template only when a stack's `depends_on` names it. | Chapter 5.3 | - |
| FR-03-04 | The system shall treat the manifest's `depends_on` as authoritative where a template's dependency line disagrees with it. | Chapter 8.1 | SYS-04 |
| FR-03-03 | The system shall reach an opt-in template only when a project picks it as a root or a chosen root's dependency tree names it. | Chapter 5.3 | - |
| FR-03-04 | The system shall treat the manifest's `depends_on` as authoritative where a template's dependency line disagrees with it. | Chapter 8.1 | SYS-04, partial: it fails any disagreement |

### 04. Composition

| ID | Requirement | Source | Checked by |
|----|-------------|--------|------------|
| FR-04-01 | The system shall resolve a root to an ordered file list, base then layer then stack, depth-first and deduplicated. | Chapter 6.1 | - |
| FR-04-01 | The system shall resolve a root to an ordered file list, the core tier first, then each dependency before what depends on it, depth-first and deduplicated. | Chapter 6.1 | - |
| FR-04-02 | Where several templates name one section ID, the system shall apply the higher level, in the order base, layer, stack, interview answers. | Chapter 8.2 | - |
| FR-04-03 | The system shall apply an override, then every extension of the same ID on top of it. | Chapter 8.3 | - |
| FR-04-04 | The system shall refuse a chain that overrides one ID twice. | Chapter 8.3 | TPL-10 |
Expand All @@ -64,20 +64,20 @@ Status: skeleton. Each cluster holds a few requirements until its fill
| ID | Requirement | Source | Checked by |
|----|-------------|--------|------------|
| FR-06-01 | The system shall load a heading without a load directive on every turn, and give its subheadings its load. | Chapter 8.1, ADR-058 | - |
| FR-06-02 | The system shall load every rule of a template that guards data, credentials or authentication on every turn. | Chapter 8.1, ADR-058 | SYS-25 |
| FR-06-03 | The system shall build the root file and the skills from the resolved chain, leaving out overridden rules and the sections the project declines, and copy each remaining rule's text unchanged. | ADR-058 |SYS-26, partial, on a planted fixture |
| FR-06-02 | The system shall load on every turn every section whose breaking exposes data, credentials or an unauthenticated path. | Chapter 8.1, ADR-058 | SYS-25, partial, for the security templates and `backend/auth.md` |
| FR-06-03 | The system shall build the root file and the skills from the resolved chain, leaving out overridden rules and the sections the project declines, and copy each remaining rule's text unchanged. | ADR-058 | SYS-26, partial, on a planted fixture |
| FR-06-04 | The system shall list each skill in the root file with the task that triggers it. | ADR-058 | SYS-26 |
| FR-06-05 | The system shall reference a section marked `check` by its command and pass condition, never by copying the script body. | ADR-058 |SYS-26, partial, on a planted fixture |
| FR-06-05 | The system shall reference a section marked `check` by its command and pass condition, never by copying the script body. | ADR-058 | SYS-26, partial, on a planted fixture |
| FR-06-06 | The system shall build byte-identical files from the same input. | ADR-058 | SYS-26 |
| FR-06-07 | The system shall build files that name no template file, since an emitted project carries no templates. | ADR-058 | SYS-27 |
| FR-06-07 | The system shall build files that name no template file, since an emitted project carries no templates. | `AGENTS.md` 4.2 | SYS-27 |

### 07. Shipped checks

| ID | Requirement | Source | Checked by |
|----|-------------|--------|------------|
| FR-07-01 | The system shall state each mechanically checkable rule with its command in a fence and its pass condition beside it. | Chapter 8.9, ADR-031 | - |
| FR-07-02 | The system shall ship a check script over 15 lines as a hook listed in `.pre-commit-hooks.yaml`. | `AGENTS.md` 4.3, ADR-055 | - |
| FR-07-03 | The system shall have every check exit 0 on a pass, 1 on a failure and 3 when it does not apply. | Chapter 8.7 | - |
| FR-07-03 | The system shall have every check exit 0 on a pass, 1 on a failure and 3 when it does not apply; under pre-commit, 3 becomes a `not applicable:` line and exit 0. | Chapter 8.7, chapter 6.3 | - |

### 08. Fork extension

Expand All @@ -86,15 +86,16 @@ Status: skeleton. Each cluster holds a few requirements until its fill
| FR-08-01 | The system shall let a fork stay current by merging upstream, never by copying files. | Chapter 8.6 | - |
| FR-08-02 | The system shall keep a fork's entries under `stacks:`, `platform:` and keys of its own, never under `core:`, `base:`, `backend:` or `frontend:`. | Chapter 8.6 | SYS-20 |
| FR-08-03 | The system shall let a `fork_core:` entry depend only on core-tier IDs. | Chapter 8.6 | SYS-21 |
| FR-08-04 | The system shall let a project take its rules from upstream, or from a fork for its stacks, by clone or as a submodule pinned to a released tag. | Playbook, "Vendor the templates in a project" | - |
| FR-08-04 | The system shall let a project take its rules from upstream, or from a fork for its stacks, by submodule, clone or copy pinned to a released tag, or keep only its generated files when they copy in every rule, or only the shipped hooks. | Chapter 7.3 | - |

### 09. Versioned releases

| ID | Requirement | Source | Checked by |
|----|-------------|--------|------------|
| FR-09-01 | The system shall not remove, rename or change the meaning of a frozen element in a 3.x release, except for a security fix. | Chapter 8.7, ADR-051 | SYS-24, partial, for section splitting only |
| FR-09-02 | The system shall keep a deprecated template resolving until the next major, naming a live replacement. | Chapter 8.8 | SYS-22 |
| FR-09-02 | The system shall keep a deprecated template resolving until the next major, naming a live replacement. | Chapter 8.8 | SYS-22, partial, for a live replacement |
| FR-09-03 | The system shall change nothing in an existing context file when a project moves its pin. | Chapter 6.5 | - |
| FR-09-04 | The system shall write each release's changelog entries from the labels of the pull requests merged since the previous tag. | Chapter 6.6 | changelog-label gate, `cut_changelog.py --self-test`, partial: the tag range is untested |

### 10. Self-checks

Expand All @@ -116,7 +117,7 @@ Status: skeleton. Each cluster holds a few requirements until its fill

| ID | Subcharacteristic | Requirement | Source | Checked by |
|----|-------------------|-------------|--------|------------|
| QG-02-02 | Resource utilization | A change that shrinks the context shall count as better only where outcomes hold. | Chapter 10.1 | - |
| QG-02-02 | Resource utilization | A change that shrinks the context shall count as better only where outcomes hold. | Chapter 1.3 | - |

### 03. Flexibility

Expand All @@ -128,9 +129,9 @@ Status: skeleton. Each cluster holds a few requirements until its fill

| ID | Subcharacteristic | Requirement | Source | Checked by |
|----|-------------------|-------------|--------|------------|
| QG-04-02 | Modifiability | No template shall score below its baseline. | Chapter 10.1 | score ratchet |
| QG-04-02 | Modifiability | No template shall score more than 0.1 below its baseline. | Chapter 8.12 | score ratchet |

### Removed
## Removed

| ID | Now |
|----|-----|
Expand Down
Loading