docs(P48): vision gaps + badge system + substrate→engine + CR format + agentic tags
acdl-ci / Lint (push) Successful in 7s
acdl-ci / Test (push) Successful in 23s
acdl-ci / Platform check-only (offline) (push) Successful in 8s

9 requirements implemented across presentation decks and project docs:

1. DX closing slide: added 'Infrastructure as a utility, not a craft' bullet
   to convey the full vision (infrastructure consumed, not maintained;
   platform compounds value over time).
2. PW Problem slide: 'moving a merged change' → 'promoting a change'.
3. PW Problem slide: added 'Red tape' and 'Scalability without increasing
   headcount' bullets (4 frictions, not 2).
4. PW Roadmap slide: redesigned with side-by-side HTML table layout
   (Testing | Planned), 16px font, no overflow.
5. PW deck: added new slide 'What This Platform Is — and Isn't' after North
   Star (sovereign boundary, infrastructure as utility, 4 anti-goals).
   PW deck now 16 slides (was 15).
6. Maturity nomenclature: 'Available today'/'shipped' → 'Testing' across
   both decks + source markdown. New .testing badge (blue/teal #DBEAFE).
   Roadmap title: 'Testing vs. Planned'. The platform has 0 consumer
   adoption — 'shipped' was inaccurate.
7. Global: 'substrate' → 'engine' across entire project (88 matches, 30+
   files including .ciagent/, docs/, modules/, adapters/, schemas/, code).
8. Presentation files only: 'forge' → 'VCS' / 'version control system'
   (6 occurrences in 4 files). 'forge' retained in all technical docs and
   code as the industry-standard term.
9. New .agentic badge (purple/violet #EDE9FE) appended to agentic features
   in both decks: confidence signal, autonomous dev, pattern recognition,
   dynamic module creation, citizen developer surface, auto-promotion.

Also: Change Request ID format changed from 'CR-2026-001' to 'CHG0678912'
across presentation files, consumer guide, and test fixtures.

HTML re-rendered. PPTX rendered for release upload.

---ci---
phase: 48
milestone: v1.9
status: complete
requirements:
  covered: []
  partial: []
---/ci---
This commit is contained in:
Jon Chery
2026-07-23 14:58:29 +00:00
parent fc070ccb15
commit 7585c828f0
38 changed files with 582 additions and 398 deletions
+22 -22
View File
@@ -21,7 +21,7 @@ flowchart TD
A["Consumer surfaces"] --> B["Contract schema"]
B --> C["Central pipeline"]
C --> D["Modules + primitives"]
C --> E["Substrate adapter"]
C --> E["Angine adapter"]
C --> F["Confidence signal"]
C --> G["Evidence stream"]
D --> E
@@ -31,7 +31,7 @@ flowchart TD
The four layers:
1. **Primitives** — single-purpose, substrate-agnostic modules representing
1. **Primitives** — single-purpose, engine-agnostic modules representing
the smallest reusable infrastructure pieces (a VPC, an S3 bucket, an ECS
cluster). A primitive does not reference other primitives; it takes its
environment as input.
@@ -51,9 +51,9 @@ Both end in a contract submission that enters the same pipeline.
## 2. Primitives
Single-purpose, substrate-agnostic modules. Locked commitments:
Single-purpose, engine-agnostic modules. Locked commitments:
- No inter-primitive references. A primitive may call substrate data sources.
- No inter-primitive references. A primitive may call engine data sources.
- Semver with three triggers: interface → MAJOR, behavior → MINOR,
lifecycle → PATCH.
- Immutability on publication.
@@ -61,8 +61,8 @@ Single-purpose, substrate-agnostic modules. Locked commitments:
- AI refinement is a flag, triggered by a joint operational condition
(N ≥ 50 consecutive zero-rollback changes, no primitive/module incident in
6 months, Infra & Ops unilateral override).
- A primitive's interface is defined against the Target Stack (substrate-
agnostic), not against any substrate's variable block directly.
- A primitive's interface is defined against the Target Stack (engine-
agnostic), not against any engine's variable block directly.
## 3. Modules
@@ -79,9 +79,9 @@ Patterns that combine primitives into deployable shapes. Locked commitments:
creation, key/secret creation, external data transfer.
- Auto-promote after 3 observed usages.
- A module's pattern tree wires field is defined against the stack's
relationship type, not against any substrate's module block. The stack →
substrate translation is the substrate adapter's job (§12). The pattern
pipeline itself is substrate-agnostic.
relationship type, not against any engine's module block. The stack →
engine translation is the engine adapter's job (§12). The pattern
pipeline itself is engine-agnostic.
## 4. Developer Surface
@@ -110,7 +110,7 @@ Patterns that combine primitives into deployable shapes. Locked commitments:
- Central repo + generated client libraries.
- Multi-stage validation pipeline: schema → policy → NFR → confidence.
- Distributed enrichment.
- GitOps reconciler + substrate execution layer.
- GitOps reconciler + engine execution layer.
- The pipeline emits a `PolicyCheckResult` record per policy rule evaluated;
the confidence signal consumes these as one normalized input (§8).
@@ -174,12 +174,12 @@ integration, contract, security smoke, and performance smoke validation.
- The DynamoDB outbox enforces identity distinctness across environment
approvers.
## 12. Cross-Cutting — Substrate Execution
## 12. Cross-Cutting — Angine Execution
The technical execution layer. Primitives and modules are substrate-agnostic
in shape; substrate adapters are the only substrate-specific component.
The technical execution layer. Primitives and modules are engine-agnostic
in shape; engine adapters are the only engine-specific component.
The architecture defines a **Target Stack** — a substrate-neutral
The architecture defines a **Target Stack** — a engine-neutral
description of:
- The resources to create (typed against the stack schema).
@@ -189,7 +189,7 @@ description of:
The registry, the module pattern tree, the contract schema, and the
`PolicyCheckResult` schema are all defined against the stack schema. None is
defined against any specific substrate.
defined against any specific engine.
**v1 implementation reality:** the stack is shaped to round-trip cleanly to
Terraform because there is no other adapter to differentiate from. As
@@ -198,19 +198,19 @@ gain translation logic, but the primitive content, the module pattern tree,
and the contract schema do not change. This is the design that prevents a
polyglot mess.
The substrate adapter:
The engine adapter:
- Translates the stack-typed module pattern tree to a substrate root module
- Translates the stack-typed module pattern tree to a engine root module
that calls the primitive modules.
- Is a thin layer. It does not own primitive/module content; it only
translates.
- Is the only substrate-specific code in the platform.
- Is the only engine-specific code in the platform.
Policy checks run on the substrate plan output. Results are normalized to
Policy checks run on the engine plan output. Results are normalized to
`PolicyCheckResult` records by a policy adapter. The confidence signal
consumes the union of all `PolicyCheckResult` records, regardless of engine
substrate-agnostic over its inputs, matching the module model's
substrate-agnosticism over its outputs.
engine-agnostic over its inputs, matching the module model's
engine-agnosticism over its outputs.
## 13. Cross-Cutting — Platform Runners
@@ -237,5 +237,5 @@ See [Versioning](pipeline/versioning) for the consumer-facing details.
## 15. OpenTofu
Not in v1. The substrate abstraction (§12) makes OpenTofu a future adapter,
Not in v1. The engine abstraction (§12) makes OpenTofu a future adapter,
not an architecture change. Revisit when an OpenTofu adapter is requested.