acdl/.ciagent/RESEARCH.md

Nova — v1.11 RESTART Research Findings

Phase: research (pre-Phase 56). Milestone: v1.11 (RESTART). Status: research. Researcher: ci-researcher. Autonomy: full (CLARIFY auto-resolved; all binding decisions D-097..D-107 are committed in the CLARIFY stage). Branch: milestone/v1.11-restart (branched off tag v1.10.2, per D-097). Sources: ACDL codebase (v1.10.2 tree) + git history (failed first attempt on phase/56-iam-re-bootstrap + phase/57-live-deploy-microservice) + the CLARIFY commit (80b7286).

This file overwrites the prior v1.1 research artifact. v1.11 is a fresh milestone; the v1.1 research (Gitea OIDC, Checkov, IR shape, outbox) is historical and preserved in git history. This file documents the technical findings that ground the v1.11 restart plan.

---

Background — why v1.11 is a restart

v1.11 is a restart, not a continuation. The first attempt (phase/56 + phase/57, abandoned per D-097) made five defects worse, not better. The restart branches off the clean v1.10.2 tag and corrects three structural defects that the CLARIFY stage locked as binding decisions:

1. Stateless adapter (D-098, D-099, D-100). The current adapter is a 750-line monolith with 3 constant tables and 39 type-specific branches that duplicate what interface.json already declares and hardcode defaults that belong in the module. v1.11 makes it a ~80-line stateless assembler; each L1 ships a real terraform/ module dir that owns its resource shape, nested blocks, and defaults.
2. Terraform owns lifecycle (D-101). The first attempt added a Python script (verify_deploy_microservice.py) that ran terraform init -reconfigure in a fresh temp dir each time, which contributed to the 4-VPC bug. v1.11 deletes that script; run_platform.sh gains --apply and --destroy modes; Python never runs terraform.
3. Pipeline-driven testing (D-102, D-103, D-104). No per-module Python/pytest. A modules-lifecycle pipeline matrix-runs each L1 module's examples/{simple,complex}.yml contracts through apply→modify→destroy against live AWS. The "test" = the pipeline cell going green.

---

FINDING 1 — Adapter monolith audit

1.1 The three constant tables

adapters/terraform/adapter.py (750 lines on the v1.10.2 tree) is built around three constant tables:

Table	Line	What it encodes	Entries
TYPE_MAP	26	Stack type (aws:<service>:<kind>) → Terraform resource type (aws_s3_bucket, aws_vpc, …).	19
INPUT_MAP	51	Stack input name → Terraform arg name, per stack type. Only non-identity mappings are listed; an input not present uses the stack name as the Terraform arg (identity).	19 (one per stack type)
OUTPUT_MAP	75	Stack output name → Terraform attribute name, per stack type. Only non-identity mappings.	19 (one per stack type)

Why they duplicate interface.json. Each L1 module already declares its inputs, outputs, and stack type in interface.json (engine-agnostic). The three tables are the engine binding — the Terraform-specific name mappings that interface.json deliberately omits (it is engine-agnostic per ARCHITECTURE.md §12). The duplication is therefore intentional in the original design: the adapter was meant to be a thin translator that holds the engine binding in three tables, and the L1 holds the engine-agnostic content.

The drift. What was not intended is that the tables grew into 39 type-specific branches (§1.2) that hardcode resource shapes, nested HCL blocks, and defaults (§1.3) — content that belongs in the module, not the adapter. The adapter stopped being a thin translator and became a per-resource-type code generator. D-098 corrects this: the engine binding moves into a per-module terraform/ subdir (the real Terraform module), and the adapter becomes a stateless assembler that emits module "x" { source = "..." ... } blocks. The three tables are deleted.

1.2 The 39 type-specific branches across 18 stack types

_emit_resource (line 156) is a generic loop that, for each input, looks up the Terraform arg in INPUT_MAP, renders the value, and appends arg = value. But 18 of the 19 stack types have a specialized branch inside _emit_resource that runs after the generic loop and emits nested HCL blocks, hardcoded defaults, or resource-specific wiring. The count of 39 branches is the sum of the per-type specializations (some types have 2–3 branches). The full inventory:

#	Stack type	Terraform type	Specialized logic (what the branch does)
1	aws:s3:bucket	aws_s3_bucket	versioning {} block (default true); server_side_encryption_configuration {} block (SSE-KMS, CMK ref or managed-key fallback with stderr warning); kms_key_arn is not a bare arg — emitted as the SSE block.
2	aws:ec2:vpc	aws_vpc	tags { Name = ... } from the name input; hardcoded cidr_block = "10.0.0.0/16" default when the L2 doesn't supply a CIDR (line 288).
3	aws:ec2:subnet	aws_subnet	vpc_id = aws_vpc.vpc-vpc.id hardcoded ref when not in inputs; hardcoded cidr_block = "10.0.1.0/24" default (line 296); tags { Name = ... }.
4	aws:ec2:routetable	aws_route_table	vpc_id = aws_vpc.vpc-vpc.id hardcoded ref; route { cidr_block = "0.0.0.0/0" gateway_id = aws_internet_gateway.vpc-igw.id } hardcoded default route; tags { Name = "<name>-rt" }.
5	aws:ecs:cluster	aws_ecs_cluster	Hardcoded name = "acdl-microservice" default when not in inputs (line 300).
6	aws:ecs:task_definition	aws_ecs_task_definition	_container_definitions() helper: jsonencodes image/port/env into a container_definitions block; hardcoded family = "app" default (line 279).
7	aws:ecs:service	aws_ecs_service	network_configuration {} block (subnets + security_groups wrapped in list brackets); load_balancer {} block from lb_target_group_arn with hardcoded container_name = "app" + container_port = 8080; hardcoded desired_count = 1, launch_type = "FARGATE", task_definition = aws_ecs_task_definition.service-task-definition.arn, name = "acdl-microservice".
8	aws:iam:role	aws_iam_role	managed_policy_arns = [...] from comma-separated string; hardcoded ECS task execution assume_role_policy JSON when not supplied (line 326–331); hardcoded name = "acdl-microservice-role" default.
9	aws:elbv2:loadbalancer	aws_lb	subnets/security_group wrapped in list brackets; hardcoded load_balancer_type = "application" default.
10	aws:elbv2:listener	aws_lb_listener	default_action { type = "forward" target_group_arn = aws_lb_target_group.alb-targetgroup.arn } hardcoded; load_balancer_arn = aws_lb.alb-loadbalancer.id hardcoded ref.
11	aws:elbv2:targetgroup	aws_lb_target_group	Hardcoded target_type = "ip", vpc_id = aws_vpc.vpc-vpc.id, protocol = "HTTP", port = 8080.
12	aws:ecr:repository	aws_ecr_repository	Hardcoded name = "acdl-microservice" default; encryption_configuration {} block (not a bare kms_key_arn arg).
13	aws:cloudfront:distribution	aws_cloudfront_distribution	origin {} block (origin_id, domain_name, origin_access_control_id, s3_origin_config {}); default_cache_behavior {} block (viewer_protocol_policy, target_origin_id, ttls, allowed/cached methods); enabled = true; price_class; restrictions { geo_restriction {} }; viewer_certificate { cloudfront_default_certificate = true }; web_acl_id from WAF ref. ~8 nested blocks.
14	aws:cloudfront:originaccesscontrol	aws_cloudfront_origin_access_control	name; hardcoded origin_access_control_origin_type = "s3", signing_behavior = "always", signing_protocol = "sigv4".
15	aws:wafv2:webacl	aws_wafv2_web_acl	name; hardcoded scope = "CLOUDFRONT"; default_action {} (allow/block from input, default allow); visibility_config {}; custom rule {} blocks as nested HCL (P1-4 fix) or default AWS-managed-rules block. ~5 nested blocks.
16	aws:rds:instance	aws_db_instance	NFR-derived backup_retention_period (default 7), deletion_protection (default true); storage_encrypted = true default; skip_final_snapshot = true (dev safety).
17	aws:kms:key	aws_kms_key	NFR-derived enable_key_rotation = true default.
18	aws:ecs:uptime-service	aws_ecs_service	Feature-flag gate (returns "" when disabled); container_definitions jsonencode for uptime-kuma; hardcoded subnets = ["subnet-uptime"], security_groups = ["sg-uptime"], assign_public_ip = true; hardcoded desired_count = 1, launch_type = "FARGATE".

Plus a global prevent_destroy lifecycle block emitted for every resource when nfrs.deletion_protection is true (line 576–581), and the _emit_igw() helper that synthesizes an internet gateway + route table association from the VPC resource (line 585).

1.3 Hardcoded defaults that belong in the module

The defaults below are emitted by the adapter when the L2 composition does not supply the input. They are resource shape decisions — CIDR ranges, trust policies, network config — that belong in the module's locals.tf (D-100), not in the adapter. The adapter should pass only resolved contract inputs; if a default is wrong, fix the module, not the adapter.

Default	Adapter line	What it is	Where it belongs
cidr_block = "10.0.0.0/16"	288	VPC CIDR default	modules/l1/vpc/terraform/locals.tf
cidr_block = "10.0.1.0/24"	296	Subnet CIDR default	modules/l1/vpc/terraform/locals.tf
ECS task execution assume_role_policy JSON	326–331	Trust policy for the IAM role	modules/l1/iam-role/terraform/main.tf (or locals.tf)
ECR/logs inline policy / encryption_configuration {}	304–315, 380	ECR KMS encryption block	modules/l1/ecr/terraform/main.tf
Fargate requires_compatibilities / launch_type = "FARGATE"	261–263	ECS launch config	modules/l1/ecs-service/terraform/locals.tf
assign_public_ip (uptime)	565	ECS network config	modules/l1/uptime/terraform/main.tf
Listener/target ports (port = 8080, container_port = 8080)	201, 348	ALB + ECS container ports	modules/l1/alb/terraform/locals.tf + modules/l1/ecs-service/terraform/locals.tf
Security group emission (security_groups = [...])	255–258, 564	ECS network config	modules/l1/ecs-service/terraform/main.tf
name = "acdl-microservice" (cluster, ECR, service)	265, 300, 303	Resource name defaults	modules/l1/*/terraform/locals.tf
family = "app"	279	Task definition family	modules/l1/ecs-service/terraform/locals.tf
target_type = "ip", protocol = "HTTP"	345, 347	ALB target group defaults	modules/l1/alb/terraform/locals.tf
load_balancer_type = "application"	342	ALB type default	modules/l1/alb/terraform/locals.tf
desired_count = 1	260	ECS desired count	modules/l1/ecs-service/terraform/locals.tf
WAF scope = "CLOUDFRONT", managed-rules default block	421, 472–490	WAF defaults	modules/l1/waf/terraform/main.tf
CloudFront signing_behavior = "always", signing_protocol = "sigv4", origin_type = "s3"	365–367	OAC defaults	modules/l1/cloudfront/terraform/main.tf
CloudFront viewer_certificate { cloudfront_default_certificate = true }, restrictions {}	403–410	Distribution defaults	modules/l1/cloudfront/terraform/main.tf
RDS backup_retention_period = 7, skip_final_snapshot = true	497, 506	RDS defaults	modules/l1/rds/terraform/locals.tf
KMS enable_key_rotation = true	510	KMS rotation default	modules/l1/kms-key/terraform/main.tf
prevent_destroy = true lifecycle (global)	576–581	Deletion protection	Each module's main.tf (or a shared lifecycle.tf)

1.4 Why this is a drift from the original vision

ARCHITECTURE.md §12.2 states: "The adapter is a thin layer; it does not own L1/L2 content — it only translates." STANDARDS.md §8 (line 448–506) documents the intended design: "a thin translator with 3 tables + specialized branches." The drift was baked into the standards doc itself — §8.2 explicitly blesses "specialized _emit_resource branches" for "resources with nested HCL blocks" and §8.3 step 4 instructs module authors to "add a specialized branch in _emit_resource keyed on that stack type" when a new L1 needs nested blocks.

The result: every new L1 with a nested block (CloudFront, WAF, ECS, uptime) added 30–80 lines of resource-shape code to the adapter. The adapter grew from a spike-era ~150 lines to 750 lines, with the resource shape (CIDR ranges, trust policies, container ports, managed-rule sets) encoded as Python string concatenation rather than Terraform HCL. D-098 corrects the drift: the standards doc §8 must be rewritten to document the new pattern (per-module terraform/ subdir + stateless assembler), and the "specialized branch" guidance is removed.

Confidence: 0.95. The audit is a direct line-by-line read of the v1.10.2 adapter.py; the drift is structural and unambiguous.

---

FINDING 2 — State-key root cause of the 4-VPC bug

2.1 The state key

adapter.py line 664 + 676:

stack_name = stack.get("name", "spike")
terraform_tf = (
    ...
    f'    key    = "spike/{stack_name}/terraform.tfstate"\n'
    ...
)

core/contract_resolver.py line 569:

"stack": {
    "name": contract["id"],
    ...
}

So stack_name = contract["id"] and the state key is spike/{contract.id}/terraform.tfstate.

2.2 The 5 microservice contracts

All five microservice contracts share id: msvc and differ only in environment:

Contract file	id	environment
contracts/microservice.yml	msvc	dev
contracts/microservice.dev.yml	msvc	dev
contracts/microservice.qa.yml	msvc	qa
contracts/microservice.prod.yml	msvc	prod
contracts/microservice.dr.yml	msvc	dr

The state key does not include the environment. So all four environment contracts (dev/qa/prod/dr) collide on the same state key: spike/msvc/terraform.tfstate.

2.3 The two root causes

Root cause 1 — the adapter emits per-contract state keys with no VPC sharing. The microservice composition (modules/l2/microservice/ composition.json) includes a vpc child (vpc@1.0.0). Every contract that resolves through this composition emits its own VPC resource. There is no platform VPC to share; each contract deploys its own VPC. D-105 corrects this: terraform/platform owns ONE VPC; the microservice composition drops its vpc child and references the platform VPC via a data source. The standalone vpc L1 module stays (consumers deploy their own VPCs). No per-contract VPC ever again.

Root cause 2 — the state key does not distinguish environments. Because the state key is spike/{contract.id}/terraform.tfstate and all four env contracts share id: msvc, every environment's terraform apply writes to the same remote state key. Combined with the first attempt's verify_deploy_microservice.py running terraform init -reconfigure in a fresh temp dir each time, each run created a fresh local state that diverged from the remote key. The first run (dev) created VPC #1 and pushed it to spike/msvc/terraform.tfstate. The second run (qa) ran -reconfigure in a fresh temp dir, pulled the remote state (which had dev's VPC), but because the local state was fresh and the composition emitted a new VPC resource address, terraform saw the VPC as "to add" again — creating VPC #2 and overwriting the remote state. Repeating for prod and dr created VPCs #3 and #4. Four VPCs, one state key, no environment discrimination.

D-106 corrects this: the composition must be deterministic — same contract → same resolved stack → same state key, every time. State keys become env-aware and stable across apply/modify/destroy: spike/{id}/{env}/terraform.tfstate. The environment is part of the key, so dev/qa/prod/dr never collide.

2.4 Why -reconfigure in a fresh temp dir made it worse

terraform init -reconfigure forces terraform to re-read the backend config and pull remote state into the local working directory. When the working directory is a fresh temp dir (as verify_deploy_microservice.py did), there is no local .terraform/ state cache — terraform must pull the remote state fresh. If the remote state key is shared across environments (root cause 2) and the composition emits a new VPC each time (root cause 1), the -reconfigure pull merges the prior environment's state with the new resource addresses, and the subsequent apply creates a new VPC because the resource address in the new composition run differs from the one in the remote state (the L2 namespacing or the fresh temp dir caused terraform to treat the VPC as a new resource). D-101 deletes verify_deploy_microservice.py entirely; run_platform.sh gains --apply and --destroy modes that run terraform in a stable working directory (not a fresh temp dir per run), and Python never runs terraform.

Confidence: 0.90. The state-key derivation is a direct code read (adapter.py:664,676 + contract_resolver.py:569). The 5 contracts are read verbatim. The 4-VPC mechanism is the only consistent explanation for the observed symptom (4 VPCs in the account after 4 env runs). The 0.10 residual is for the possibility that the resource-address divergence was caused by a separate composition-namespacing bug rather than the fresh temp dir alone — but either way, the two root causes (shared state key + per-contract VPC) are confirmed and D-105/D-106 correct both.

---

FINDING 3 — Per-module terraform module design

3.1 What the per-module terraform/ subdir should contain

D-098/D-099: each L1 module ships a real terraform/ module dir. The canonical layout for a multi-resource module:

modules/l1/<name>/
  interface.json          # engine-agnostic (unchanged)
  instance.json          # regression baseline (unchanged)
  README.md
  examples/
    simple.yml
    complex.yml
  terraform/              # NEW — the engine binding
    versions.tf           # required_version + required_providers
    variables.tf          # from interface.json inputs
    locals.tf             # default interpolation (heavy use, D-099)
    main.tf               # resource blocks (resource shape + nested blocks)
    outputs.tf            # from interface.json outputs

Trivial single-resource modules (e.g. s3) may inline locals in main.tf (D-099). Multi-resource modules (vpc, ecs-service, alb, microservice-shaped) get the full split.

3.2 The three reference modules (from interface.json)

s3 (modules/l1/s3/interface.json):

• variables.tf: bucket_name (string, required), region (string, required), kms_key_arn (string, optional).
• locals.tf: sse_algorithm = "aws:kms", versioning default true, managed-key fallback (alias/aws/s3 when kms_key_arn is null), the prevent_destroy lifecycle.
• main.tf: resource "aws_s3_bucket" "this" { bucket = var.bucket_name ... } + versioning {} block + server_side_encryption_configuration {} block (CMK ref or managed fallback).
• outputs.tf: bucket_arn (→ aws_s3_bucket.this.arn), bucket_name (→ aws_s3_bucket.this.id), bucket_regional_domain_name (→ aws_s3_bucket.this.bucket_regional_domain_name).
• versions.tf: terraform { required_version = ">= 1.9, < 1.10" required_providers { aws = { source = "hashicorp/aws", version = "~> 5.0" } } }.

vpc (modules/l1/vpc/interface.json — multi-resource: vpc + subnet + routetable):

• variables.tf: cidr (string, required), azs (string, required), name (string, required), region (string, required).
• locals.tf: cidr_block = coalesce(var.cidr, "10.0.0.0/16"), subnet CIDR derivation (cidrsubnets(local.cidr_block, 8, 8, ...) per AZ), name tag interpolation, the IGW + route table association.
• main.tf: aws_vpc, aws_subnet (count/for_each over azs split), aws_route_table, aws_internet_gateway, aws_route_table_association — all the resources that the adapter's _emit_igw() helper synthesized dynamically now live here as real HCL.
• outputs.tf: vpc_id, subnet_ids (join the subnet ids).
• versions.tf: same provider block.

ecs-service (modules/l1/ecs-service/interface.json — multi-resource: task_definition + service):

• variables.tf: image, port, cpu (default 256), memory (default 512), env (optional), cluster_arn, subnets, security_group, lb_target_group_arn (optional), region, kms_key_arn (optional), desired_count (default 1), launch_type (default "FARGATE"), family (default "app").
• locals.tf: container_definitions jsonencode (image/port/env/cpu/ memory), requires_compatibilities = ["FARGATE"] when launch_type is FARGATE, log group name + KMS ref, the prevent_destroy lifecycle.
• main.tf: aws_ecs_task_definition (family, container_definitions, requires_compatibilities, execution_role_arn) + aws_ecs_service (name, cluster, task_definition, desired_count, launch_type, network_configuration {}, load_balancer {} block).
• outputs.tf: service_arn, task_def_arn.
• versions.tf: same provider block.

3.3 How the stateless adapter assembles them

The new adapter (D-098) is a ~80-line stateless assembler. It:

1. Reads modules/registry.json → for each resource in the resolved stack instance, looks up the L1 module by module field (<name>@<semver>).
2. Gets the terraform_dir from the registry entry (or derives it as modules/l1/<name>/terraform/).
3. Emits a root main.tf with one module "x" { source = "<terraform_dir>" ... } block per resource, passing the resolved contract inputs as module arguments.
4. Wires refs via module "x".<output> interpolations: a ref:<id>.<out> input value becomes module.<id>.<out> in the consuming module block.
5. Emits the stack-level output {} blocks (passthrough from the producing module's outputs).
6. Emits terraform.tf (backend config with the env-aware state key, D-106) + providers.tf (aws provider, region from the first resource).

The adapter holds no TYPE_MAP, INPUT_MAP, OUTPUT_MAP, and no type-specific branches. The engine binding (stack type → Terraform resource type, input → arg name, output → attribute name, nested blocks, defaults) lives entirely in the per-module terraform/ subdir. interface.json stays engine-agnostic.

Confidence: 0.90. The module layout is grounded in the existing interface.json files (read verbatim) and the Terraform module convention (versions/variables/locals/main/outputs split). The assembler design is D-098/D-099 (user-confirmed). The 0.10 residual is for the exact terraform_dir registry field shape (not yet implemented) and the ref-wiring syntax (module.<id>.<out> vs a locals alias).

---

FINDING 4 — Existing pipeline architecture

4.1 The central pipeline contract

pipelines/contract.yml is the declarative deployment pipeline spec (a contract, not an executable workflow). It declares 9 stages: validate-contract → resolve-stack → terraform-plan → checkov → confidence → apply (dev only) → publish-outputs → deploy-uptime → comment-outputs. Each stage has name, command, required (bool), and optional description. The executable workflow (.github/workflows/deploy.yml + .gitea/workflows/deploy.yml, byte-identical) implements these stages by invoking scripts/run_platform.sh. Validated against schemas/deploy-pipeline.schema.json.

4.2 The plan-only pipelines (existing, run on every PR)

Two platform pipelines run on every PR to main (offline, free):

Pipeline	File	Matrix	What it does
Primitives plan	.github/workflows/primitives-plan.yml (+ .gitea/ byte-identical)	s3, vpc, ecs-cluster, ecs-service, iam-role, alb, ecr, cloudfront, waf, rds (10 primitives)	For each L1 primitive, runs bash scripts/run_primitive_plan.sh --check-only <primitive> — resolves the primitive's instance.json, runs the adapter, validates the emitted Terraform structure (offline, no AWS).
Patterns plan	.github/workflows/patterns-plan.yml (+ .gitea/ byte-identical)	static-assets, microservice (2 modules)	For each L2 module, runs bash scripts/run_pattern_plan.sh --check-only <module> — resolves the sample contract, runs the adapter, validates the emitted Terraform (offline).

Both trigger on pull_request: branches: [main], run on ubuntu-latest, install jsonschema pyyaml boto3. The --check-only mode is offline (no AWS, no Checkov, no DynamoDB) — it resolves the contract/instance, runs the adapter, and validates the emitted Terraform file structure. This is what makes the pipelines free.

4.3 run_platform.sh — plan only, never apply/destroy

scripts/run_platform.sh (521 lines) has three modes today:

• --check-only (offline, no AWS): contract → resolver → adapter → stream TF → validate → exit 0.
• --plan-only (requires AWS): contract → resolver → adapter → terraform init -reconfigure -lock=false → terraform validate → terraform plan -lock=false -out=tfplan → exit 0 (line 274–297).
• default (requires AWS + Checkov + DynamoDB): contract → resolver → adapter → terraform plan → Checkov → confidence → outbox.

Critically, line 287 runs terraform plan only. There is no terraform apply and no terraform destroy in run_platform.sh today. The apply stage in pipelines/contract.yml (line 54–57) declares command: bash scripts/run_platform.sh --plan-only — a misnomer; it runs plan, not apply. The lifecycle modes (--apply, --destroy) must be added (D-101). Python never runs terraform; run_platform.sh is the only shell entry point.

4.4 run_primitive_plan.sh

scripts/run_primitive_plan.sh (65 lines) runs the platform pipeline for a single primitive. --check-only mode: resolves instance.json, runs the adapter, validates the emitted {main.tf,terraform.tf,providers.tf} exist and main.tf is non-empty. Default mode (requires AWS): terraform init -backend=false → terraform validate → terraform plan. This is the per-primitive plan check that the primitives-plan pipeline matrix invokes.

4.5 The byte-identical Gitea+GitHub convention

pipelines/README.md:22 documents the convention: "Create byte-identical workflow YAMLs in .gitea/workflows/<name>.yml and .github/workflows/<name>.yml." Both workflows must implement the same stages, commands, triggers, and runner declared in the contract. tests/test_pipeline_contract.py validates that the Gitea and GitHub workflow YAMLs are byte-identical and conform to the schema. The only difference is the forge runtime (Gitea Actions vs GitHub Actions). The new modules-lifecycle pipeline (D-102) must follow this convention: byte-identical .gitea/workflows/modules-lifecycle.yml + .github/workflows/modules-lifecycle.yml.

Confidence: 0.95. All pipeline files are read verbatim from the v1.10.2 tree. The "plan only, never apply/destroy" finding is a direct read of run_platform.sh line 287 + the --plan-only exit at line 293.

---

FINDING 5 — PERSONAS.md update for v1.11

The existing PERSONAS.md (v1.9) has 6 active personas: lead-developer, backend-engineer, platform-engineer (custom), security-engineer (custom), lambda-engineer (custom, v1.9), frontend-engineer. v1.11 changes the roster:

• Deactivate lambda-engineer — no per-module Python this milestone (D-102: testing is pipeline-driven, not pytest). The v1.9 Lambda (core/lambda/contract_ingestor.py) persists but is not touched in v1.11.
• Deactivate cost-engineer — not in the v1.9 roster (the v1.9 data-engineer is already deactivated). v1.11 has no cost-engineer work; cost is documented in COST.md (REQ-119) by the lead-developer.
• Keep backend-engineer — owns the adapter rewrite (stateless assembler) + core/contract_resolver.py (env-aware state keys, D-106).
• Keep data-engineer (reactivated) — owns terraform/ (platform VPC, D-105) + the per-module terraform/ subdirs (the engine binding, D-098/D-099/D-100). This is the heaviest territory in v1.11: 12 L1 modules each get a real terraform/ module dir.
• Keep general (the lead-developer + backend-engineer pipeline work) — owns pipelines/ + .gitea/workflows/ + .github/workflows/ (the modules-lifecycle pipeline, D-102) + scripts/run_platform.sh (--apply/--destroy modes, D-101).

Territory alignment (v1.11)

Persona	Territory	Domain
backend-engineer	adapters/terraform/adapter.py (rewrite to stateless assembler), core/contract_resolver.py (env-aware state keys), schemas/stack.schema.json (if touched)	backend
data-engineer	terraform/ (platform VPC, D-105), modules/l1/*/terraform/ (per-module terraform subdirs — the engine binding), modules/l1/*/interface.json (defaults move from adapter to interface), modules/registry.json (terraform_dir field)	data
general (lead-developer + backend-engineer)	pipelines/modules-lifecycle.yml, .gitea/workflows/modules-lifecycle.yml + .github/workflows/modules-lifecycle.yml (byte-identical), scripts/run_platform.sh (--apply/--destroy), scripts/run_primitive_plan.sh (if extended), modules/STANDARDS.md §8 rewrite	coordination + pipelines

Territory enforcement: warn

Co-authoring is expected on the adapter + run_platform.sh boundary (backend-engineer rewrites the adapter; general adds the lifecycle modes to run_platform.sh that invoke it). warn keeps it frictionless — cross-territory edits are logged in the commit message but do not fail the task.

Domain priority (v1.11)

data → backend → general

Rationale: the terraform foundation (per-module terraform/ subdirs + platform VPC) is the binding constraint — the stateless adapter cannot be written until the reference s3 module exists (D-107: P56a proves the design with s3 first). Backend (adapter/resolver) follows once the module shape is proven. General (pipelines/workflows) wires the lifecycle modes last, once the adapter + modules produce valid terraform.

The updated PERSONAS.md is written to /root/acdl/.ciagent/PERSONAS.md (see that file). YAML frontmatter with active, phase_specific, and reason fields per persona.

Confidence: 0.90. The persona changes are grounded in the CLARIFY decisions (D-098..D-107) and the v1.11 scope (no per-module Python → lambda-engineer deactivated; terraform module authoring is the heaviest work → data-engineer reactivated).

---

Assumptions logged

ID	Assumption	Confidence	Rationale
A-1.1	The terraform_dir field will be added to modules/registry.json entries (or derived as modules/l1/<name>/terraform/) so the stateless adapter can locate each module's terraform subdir.	0.85	D-098 says the adapter reads registry.json → gets terraform_dir. The exact field name is not yet locked; the derivation path is the obvious fallback.
A-1.2	The ref-wiring syntax in the root main.tf will be module.<id>.<output> (standard Terraform module output interpolation), not a locals alias.	0.85	The existing _ref_expr already produces <tf_type>.<id>.<attr>; the module equivalent is module.<id>.<output>. Standard Terraform convention.
A-2.1	The 4-VPC bug's resource-address divergence was caused by the fresh temp dir + -reconfigure pull merging remote state with new composition runs, not a separate composition-namespacing bug.	0.80	The two confirmed root causes (shared state key + per-contract VPC) are sufficient to explain 4 VPCs. The exact terraform-state mechanics of the divergence are inferred, not observed in a debug log.
A-3.1	Trivial single-resource modules (s3) may inline locals in main.tf; multi-resource modules (vpc, ecs-service, alb) get the full 5-file split.	0.90	D-099 states this explicitly.
A-4.1	The modules-lifecycle pipeline will matrix-run each L1 module's examples/{simple,complex}.yml contracts (the modify variants), not new contract files.	0.90	D-103: "Uses the module's own existing example contracts as the modify variants. No extra contract files needed."
A-5.1	platform-engineer and security-engineer from the v1.9 roster are folded into data-engineer and backend-engineer for v1.11 (the v1.11 scope is terraform + adapter + pipelines, not security adapters or HITL gates).	0.75	The v1.11 scope (D-097..D-107) does not touch Wiz/Kyverno/Checkov/HITL. The persona roster is simplified to the three active domains.

---

Decisions surfaced (research → already bound in CLARIFY)

All v1.11 binding decisions (D-097..D-107) were committed in the CLARIFY stage (80b7286) before this research ran. This research grounds those decisions with codebase evidence; it does not surface new binding decisions. The decisions are summarized in §Background above and documented in full in the CLARIFY commit.

---

v1.12 Addendum — Presentation Refinement Research

Generated: 2026-07-29. Phase 66. Milestone v1.12. Mode: docs-only NFR milestone focused on the leadership decks. Surface: docs/presentations/ (PW + DX, all four layers) + one real adapter fix + two probe fixes required to make deck claims true.

Background — why v1.12 exists

v1.11 (P56a–P65) landed the stateless adapter, pipeline-driven lifecycle testing, single platform VPC, COST.md, PRE_MORTEM.md, and a teardown to zero-cost. P65's plan (REQ-118) required the decks to be rewritten to "Verified live-aws via lifecycle pipeline; torn down to zero-cost." That rewrite did not fully land on the deck artifacts. This research is a drift audit: a systematic comparison of the deck artifacts against the v1.11-verified reality.

FINDING 1 — Drift audit (9 items)

Systematic comparison of docs/presentations/* against .ciagent/CAPABILITY_INVENTORY.md, .ciagent/COST.md, .ciagent/PRE_MORTEM.md, .ciagent/ROADMAP.md, and git log.

1. Wrong verification status. Both rendered HTML decks still say "6 cloud capabilities are design-verified + locally emulated, deploy-unverified (IAM drift)" (PW "Testing vs. Planned" slide; DX slide A6). CAPABILITY_INVENTORY.md says 22/22 Verified and the IAM-drift framing was removed in P65. The decks contradict the inventory. Verified: grep -c "deploy-unverified\|IAM drift\|design-verified" docs/presentations/*.html → 3 hits per deck.
2. Re-verification header stale. Both source .md headers say "Re-verification (2026-07-27)… v1.10 Phase 54… 16/16… 6 IAM-gated escalated." Should reflect v1.11: 22/22 Verified, torn down.
3. Road to the North Star diagram stale. docs/presentations/assets/mmd/road-to-north-star.mmd shows v1.10 as "NEXT" with "HITL wiring / all-runner OIDC / regulatory ledger". v1.11 is complete; the diagram must advance.
4. Rendered HTML not re-rendered. git log shows the HTML was last touched at 10b87a6 (P57), before v1.11. P65's "re-render HTML" task did not reach the rendered artifacts.
5. Version refs stale. Decks reference @v1.10 in deploy.yml uses: snippets (Safe Promotion Path, Safe Decommission). Ship tag is now v1.11.0; will be v1.12.0 at Phase 70 complete.
6. Cost story has no real numbers. COST.md exists ($0.001883 over 8 days, ~$0.007/mo, S3-dominated, zero BAU compute) but the decks' A6 "Operating Model & Cost" slide is generic prose with no figures.
7. Pre-mortem unreferenced. P65 planned to add a pre-mortem reference; PRE_MORTEM.md exists (v1.10 decay root cause + four forward failure modes) but no deck slide references it.
8. Two v1.11 stories absent. (a) Architectural simplicity: adapter 918→~80 lines, defaults centralized in per-module terraform/ dirs. (b) Verifiable deploys: a modules-lifecycle pipeline matrix-runs each module apply→modify→destroy against live AWS. Neither is in the decks.
9. Duplicated story-beat lines. how-the-platform-works.md slides 3–10 each repeat their intro line twice (a copy-paste artifact).

FINDING 2 — Regression gate surfaces real decay (D-091)

The v1.12 regression gate run (Phase 66) re-ran the D-091 regression gate to back every deck claim. It found 3 Broken capabilities: {'Verified': 19, 'Decayed': 0, 'Broken': 3}.

CAP-013 — live-aws — REAL platform defect (Class A)

adapters/terraform/adapter.py:159-172 (the seen dedup loop) collapses the two ecs-service sub-resources (service-task-definition

• service-service, both module ecs-service@1.0.0) into ONE module "service-task-definition" block. But the stack output service_arn (resolver from: "service-service") is emitted as value = module.service-service.service_arn — referencing a module call that was never emitted. terraform validate fails: "No module call name." The same defect silently breaks the alb L1 too. Static- assets (CAP-014) doesn't hit it because its L1s are single-resource. Classification A — real platform defect. The adapter produces invalid Terraform for any multi-resource L1 with stack-level outputs. Fix required before decks can claim 22/22 Verified.

CAP-017 — lifecycle-pipeline — regression-probe bug (Class B/C)

core/regression_verify.py:444 hardcodes required = ["versions.tf", "variables.tf", "locals.tf", "main.tf", "outputs.tf"]. The CAP-017 probe targets the rds L1 module, whose main.tf uses only var.* and aws_db_subnet_group.this — no local.* references, so locals.tf is legitimately absent. The probe is over- strict. The rds module is correctly structured; the capability works. Classification B/C — trivial probe fix. Drop locals.tf from the required list, or make it conditional on local. usage.

CAP-018 — lifecycle-pipeline — regression-probe bug (Class B/C)

core/local_emulators.py:273 defines LocalLambdaStub as a dataclass with one required field outbox: FlatFileOutbox. Every real caller passes it (core/local_emulators.py:464, the tests). The CAP-018 probe at core/regression_verify.py:486-491 is the only caller that instantiates it bare: LocalLambdaStub() → TypeError. The probe was added in P63 and never aligned with the real signature. The capability is exercised green by CAP-011. Classification B/C — trivial probe fix. Pass an outbox to the constructor.

Implication for the decks

CAPABILITY_INVENTORY.md claims 22/22 Verified, but the regression gate (D-091 — the exact mechanism PRE_MORTEM.md FM-3 says backs every deck claim) shows CAP-013 is genuinely broken. The inventory overstates. v1.12 cannot ship decks claiming 22/22 until CAP-013 is fixed and the gate re-runs clean. This is the structural mitigation the pre-mortem requires (verified-only claims; decks unfrozen only after re-verification). The user decision: fix the defect inside v1.12 (Phase 67), then the decks can honestly claim 22/22.

FINDING 3 — Talking points structure gap

Both talking-points files have only 5 appendix sections (A1–A5) while the Marp decks have 6 (A6 = "Operating Model & Cost"). The A6 content exists in the Marp deck and source markdown but was never distilled into the talking points. The re-distill step (Phase 69) must add the A6 section to both talking-points files.

FINDING 4 — Versioning facts

• Current ship tag: v1.11.0 (v1.11 complete).
• deploy.yml still references v1.9 in comments + ref: v1.9 — v1.11 apparently did not bump the deploy workflow uses: tag (the bump is a separate concern; decks use the current ship tag).
• Decks should show @v1.11 in examples (current state); Phase 70 bumps to @v1.12 after the tag exists.

Assumptions logged

• No automated ci-doc-verifier script exists in the repo. The plan's "ci-doc-verifier confirms" is satisfied by a manual grep-based verification recorded in the Phase 70 VERIFY step (consistent with how prior NFR-patch phases handled it). Confidence 0.90 — verified by ls scripts/ | grep doc and grep -rl deck tests/.
• PPTX export requires Chromium + Marp CLI; the environment has it (/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome). PPTX is uploaded to the Gitea release, not committed. Confidence 0.85 — README documents the path; the chromium binary exists.

Decisions surfaced (research → bound in CLARIFY-equivalent)

• D-108 — v1.12 includes one real adapter fix (CAP-013) and two probe fixes (CAP-017, CAP-018) as Phase 67 prerequisites, so the decks can honestly claim 22/22 Verified. The milestone is "presentation refinement" but the verified-only-claims pre-mortem mitigation makes the fixes mandatory. The user confirmed this scope (interactive decision, 2026-07-29).
• D-109 — Decks use @v1.11 in examples during Phase 68 (current state), bumped to @v1.12 at Phase 70 complete after the tag exists. Avoids a dangling reference to a tag that doesn't exist yet.

---

v1.14 Research Addendum — NFR Refinement scope audit (2026-07-29)

Phase 0 RESEARCH for milestone v1.14 (NFR Refinement). A full codebase survey (8 categories, file:line evidence) was conducted to populate the 20-phase scope. This addendum records the findings; the phase list is in ROADMAP.md §v1.14; the requirements are in REQUIREMENTS.md §v1.14.

Survey method

Read-only survey of /root/acdl at v1.13.2 (HEAD 139224ff, 533 tests collected). 8 categories: stubs, P1/P2 backlog, security, docs drift, test gaps, terraform gaps, workflow gaps, config hygiene. All file:line references verified against the live codebase.

Finding 1 — Open P1/P2 backlog (REVIEW.md v1.11)

5 P1 + 4 P2 findings from the v1.11 multi-persona review remain open:

ID	File:Line	Status	v1.14 phase
P1-1	adapter.py:159-170 (silent drop of unregistered-module resources)	open	P1
P1-2	static-assets/composition.json (unwired cloudfront inputs; WAF unconditional)	open	P2
P1-3	run_l2_lifecycle_*.sh (vestigial [ci-vpc-outputs.json] arg)	open	P3
P1-4	CAPABILITY_INVENTORY.md:9-16 (summary table stale)	fixed (now 22/22)	—
P1-5	regression_verify.py:432-519 (CAP-017..022 offline proxy, no terraform validate)	open	P4
P2-1	alb/main.tf:9 (name_prefix="tg-ci-" discards var.name)	open	P6
P2-2	test_adapter.py (no dedup-merge or remote-state-key test)	open	P5
P2-3	waf/complex.yml + locals.tf (redundant upper() + uppercase example)	open (post-hoc)	folded into P2
P2-4	COST.md:106 (account ID published; accepted exposure)	open (post-hoc)	folded into P8 (centralize code-side)

Finding 2 — Security posture gaps

Swallowed errors (6 sites):

• core/local_emulators.py:374 — except Exception: pass in _fake_urlopen; if patching fails, urlopen stays real → network egress. [SEC] → P7.
• core/lambda/contract_ingestor.py:157 — GitHub search failure → existing = [] → duplicate issues. → P7.
• terraform/bootstrap/create_state_backend.py:51 — over-broad except Exception: on head_bucket → spurious create_bucket on permissions/network errors. → P7.
• core/output_publisher.py:100,168 — SSM/GitHub failure → silent None/False. → P7.
• terraform/bootstrap/apply_iam_baseline.py:78 — over-broad on old-version delete. → P7.

Hardcoded account ID 581513795199 (15+ sites): adapter.py:125,140, apply_iam_baseline.py:33, create_state_backend.py:33,35, push_consumer_image.py:32, terraform state-bucket names, ECR image ref. → P8 (externalize to ACDL_AWS_ACCOUNT_ID / data.aws_caller_identity).

IAM policy wildcards (6 Resource: "*" statements): spike_runner_policy.json — cloudfront (line 117), wafv2 (129), kms (218), iam (236). KMS allows key creation/deletion on ANY key; IAM allows role creation on ANY role. → P9 (scope to acdl-* ARNs).

Contract-ingestor identity validation gap: contract_ingestor.py:221-245 — _validate_caller_identity validates consumerRepo format only; doesn't verify caller owns the repo (ABAC reliance). No contractId/environment/error validation. → P10.

Schema validation gaps: contract.schema.json + environment.schema.json — no additionalProperties: false (undocumented fields pass silently); no format validation for bucket/ARN/CIDR. → P11.

Credential hygiene: .gitignore covers .env*/*.tfstate* but no credential-pattern catch-all (*.pem/*.key/*.p12). → P12.

Audit ledger integrity (D-083): audit_ledger_design.md:47-70 — JWS + Object Lock + DLQ deferred. Per D-096, stays deferred; documented in P19. The hash-chain + DynamoDB outbox is the v1.14 audit record.

Finding 3 — Stubs / missing functionality

• adapters/kyverno/kyverno_adapter.py:11,115-116 — --kube-version parsed then discarded (_ = kube_version). → P13 (implement or remove + document).
• scripts/__pycache__/verify_deploy_microservice.cpython-312.pyc — orphan bytecode for a deleted source file. → P14.
• core/regression_verify.py:237 — DynamoDB write deferred to Phase 54 (outbox hash-chain verified, no real DynamoDB write). Accepted deferral.
• adapters/wiz/wiz_adapter.py — real GraphQL client (not a stub); degrades gracefully. OK.
• core/separation_of_duties.py — route_halt_artifact is real (SNS + outbox fallback). OK.
• core/lambda/contract_ingestor.py — report_error is real (GitHub issues via Secrets Manager). OK.

Finding 4 — Documentation drift

• ARCHITECTURE.md — no v1.11/v1.12/v1.13/v1.14 addendum; line 500-506 still describes the old parameterized adapter (pre-stateless rewrite). → P19.
• Stale @v1.6–@v1.9 workflow refs in README.md:225, docs/consumer-guide.md (12 sites), docs/architecture.md:233, docs/pipeline/versioning.md:29, docs/pipeline/index.md:42. → P19.
• modules/STANDARDS.md §8 references TYPE_MAP (deleted in v1.11); §9.4 requires 5-file split but §489-492 allows inlining — inconsistent. → P18.
• COST.md window stops at v1.10; no v1.11–v1.13 spend. → P19.
• GRILL.md G-005/G-008 escalations — CAP-017..022 now Verified via lifecycle pipeline; COST.md now exists. → P19 (mark resolved).
• IAM_POLICY.md — reflects v1.11 re-bootstrap but not v1.12/v1.13. → P19.
• Decks reference "v1.12" verification status; not re-synced for v1.13.2. → P19.

Finding 5 — Test coverage gaps

• 533 tests collected; 5 @pytest.mark.slow (deselected from fast suite). 7 scripts with no test: seed_uptime_monitors.py, push_consumer_image.py, sync_to_gl.sh, post_stage_comment.sh, rotate_spike_key.sh, create_state_backend.py, create_iam_user.py. → P15.
• Adapter dedup-merge + ACDL_REMOTE_STATE_KEY override — no unit test (P2-2). → P5.

Finding 6 — Terraform gaps

• 3 L1 modules lack locals.tf (ecr, ecs-cluster, rds). → P18.
• static-assets/composition.json unwired inputs (P1-2). → P2.
• terraform/platform/main.tf:255 — hardcoded CIDR; count=2 subnets not data-driven. → P20.
• terraform/bootstrap/create_state_backend.py:51 — over-broad except (Finding 2). → P7.

Finding 7 — Workflow / pipeline gaps

• 4 GitHub-only workflows (patterns-plan, platform-test, primitives-plan, release) — no Gitea mirror. → P16.
• rotate_spike_key.sh (only set -u), sync_to_gl.sh (no set flags). → P16.
• 3 shared workflows (ci, deploy, modules-lifecycle) byte-identical (verified). OK.
• modules-lifecycle matrix covers all 12 L1 + 2 L2. OK.

Finding 8 — Config / project hygiene

• config.json bash_allowlist has dead JS entries (npm/node/jest/eslint /tsc — no package.json). → P14/P17.
• config.json branching_strategy: "phase" mismatched with flat-workflow practice. → P17.
• config.json ollama-cloud.base_url: "" (empty; no glm model configured). → P17.
• config.json frontend-engineer persona still in personas[] (PERSONAS.md:80 says inactive). → P17.
• pyproject.toml version 1.3.0 (stale); coverage source acdl_platform (renamed to core in v1.6). → P14.

Persona assessment (v1.14)

The v1.14 milestone is NFR-only (bug fixes, security, tests, docs). The active persona roster from v1.11 (PERSONAS.md) carries forward unchanged:

• lead-developer (active) — coordination; owns the wave ordering + cross-phase dependencies.
• backend-engineer (active) — owns adapters/, core/ (adapter dedup, contract ingestor, regression gate, output publisher).
• data-engineer (active) — owns terraform/, modules/ (ALB fix, static-assets wiring, platform VPC, IAM policy, STANDARDS).
• frontend-engineer (inactive) — no frontend; decks are markdown (lead-developer territory). Stays deactivated per PERSONAS.md:80.

No custom personas needed for v1.14 (no new domains). Territory enforcement = warn (config.json:167). The v1.14 work is concentrated in adapters/, core/, terraform/, scripts/, tests/, docs/, .ciagent/ — all within existing persona territories.

---

v1.15 Research Addendum — Nova Rebrand scope audit (2026-07-30)

Survey method

A thorough, exhaustive codebase survey (via the explore subagent) plus targeted grep -rni counts. The survey covered 346 tracked files, reporting occurrence counts and the mechanical-vs-judgment split per category. The full survey is recorded in the planning conversation transcript; the binding conclusions are summarized here.

Finding 1 — Brand string surface area

• 1,465 total ACDL/acdl occurrences across 205 files.
• 17 occurrences of the full "Agentic Cloud Delivery Platform" phrase (all prominent titles/headers: README, docs/index, vision, pyproject, decks, .ciagent/*.md).
• 0 existing references to "nova" (case-insensitive) — no collision risk.
• User-facing (docs/, README, decks, contracts, schemas, module READMEs): high-priority for rebrand.
• Internal (.ciagent/*.md, tests/, terraform/, scripts/, workflows): mechanical but voluminous.

Finding 2 — Code identifiers (judgment category)

• Python package name: pyproject.toml name = "acdl" (no acdl/ package dir exists — source lives in core/, adapters/; the name is a metadata label). Mechanical rename.
• Python file: adapters/terraform/policy/custom_rules/acdl_tagging.py (+ Checkov registration in schemas/tagging-standard.json line 5 + adapter config). Rename file + update registration.
• Env var prefixes: 21 distinct ACDL_* prefixes (ACDL_LIFECYCLE_MODE 66×, ACDL_AWS_ACCESS_KEY_ID 40×, ACDL_AWS_SECRET_ACCESS_KEY 37×, ACDL_REMOTE_STATE_KEY 22×, ACDL_AWS_ACCOUNT_ID 21×, ACDL_TAG_NAMING 20×, ACDL_KMS_KEY_ID 16×, ACDL_BOOTSTRAP_AWS_* 15× each, ACDL_SOD_HALT_TOPIC_ARN 14×, ACDL_LOCAL_TIER 13×, etc.). No centralized env loader exists today (scattered os.environ.get). D-108: a new core/env.py get_env() helper centralizes the dual-read fallback.
• Workflow name:: .github/workflows/release.yml line 11 name: acdl-release — mechanical.

Finding 3 — AWS resource names (high-risk migration)

Terraform creates real AWS resources with acdl- prefixes. Renaming forces destroy+recreate (downtime, data loss for DynamoDB/state bucket). D-102: full rename with migration (user-directed).

Resource	Type	Migration
acdl-contracts / acdl-change-requests	DynamoDB	scan+copy data, verify row counts
acdl/github-token	Secrets Manager	recreate secret, repoint Lambda
acdl-contract-ingestor (role/policy/Lambda)	IAM+Lambda	recreate role/Lambda, update trigger
acdl-sod-halt	SNS	recreate topic, repoint publisher
acdl-ecs-sg	SG	recreate (brief ECS disruption)
alias/acdl-platform	KMS alias	repoint alias (cheap)
acdl-microservice (cluster/ECR/service/task/role)	ECS+ECR	re-push images, recreate service
acdl-spike-runner (user/policy)	IAM	re-bootstrap with new key
acdl-tfstate-581513795199-us-east-1	S3 state bucket	terraform init -migrate-state, back up state JSON
acdl-alb (name prefix)	ALB	recreate (brief downtime)

Finding 4 — Consumer/infra conventions (judgment category, D-104)

• AWS tag keys acdl:owner|environment|contract|cost-center|ref (5 keys, ~109 tag assignments) — matched by ABAC session policies. Parallel-tag period (add nova:*, swap policy, remove acdl:*).
• SSM path /acdl/{env}/{contractId}/{output} (67 refs) — deploy outputs stored here. Migration script copies params, readers updated, old deleted.
• Consumer path .acdl/contract.yml (23 refs) — consumer repos depend on this. Renamed .nova/contract.yml + migration guide.

Finding 5 — Docs & decks (mechanical)

• README.md (16), docs/index.md, docs/vision.md, docs/architecture.md, docs/consumer-guide.md (35), docs/modules/index.md (28), all .ciagent/.md, modules/STANDARDS.md, schemas/README.md, pipelines/README.md, adapters/README.md, terraform//README.md.
• Deck markdown + mermaid .mmd sources (5 files) + rendered HTML. PNGs re-exported from edited .mmd sources.
• S&P visual theme (sp-theme.json, deck CSS) is client branding — D-107: untouched. Only product-brand text (ACDL→Nova) changes.
• Schema $id URLs (https://acdl.cloudinit.dev/schemas/...) → https://nova.cloudinit.dev/schemas/... (D-110: illustrative, no DNS resolution needed for validation).

Finding 6 — CI / pipeline / release

• Workflow files mirrored in .gitea/workflows/ + .github/workflows/ (modules-lifecycle 31×, deploy 22×, ci 2×, release 3×).
• release.yml release title ACDL vX.Y.Z → Nova vX.Y.Z (forward only; past releases keep names).
• Git branches/tags use milestone/v* / phase/* / v* — no brand name present, no change needed (D-112: flat-branch convention preserved).
• config.json release.gitea.repo stays acdl (D-105: real repo name unchanged; doc URLs illustrative only).

Finding 7 — External / URLs

• github.com/acdl/... (~20 refs in docs + module READMEs + reusable-workflow uses: refs) — D-105: illustrative, updated to nova for prose. Real GitHub org/repo rename is out of scope.
• git.cloudinit.dev/continuous-intelligence/acdl* (incl. sister repos acdl-contracts, acdl-evidence) — updated in prose to nova*.
• README has no badges (no shields.io, no img src).

Finding 8 — Nomenclature / tagline

• "DevSecOps", "New Dawn", "enabler" appear nowhere in the repo today — clean insertion, no collisions to reconcile (D-106).
• Current tagline ("North Star" / "consumers declare intent") is retained; Nova tagline added alongside.
• "bottleneck" (6 occurrences in deck talking points) — compatible with the Nova "no bottleneck" messaging; left in place.

Persona assessment (v1.15)

No new personas needed for v1.15 — the rebrand touches existing territories (docs, code, terraform, CI, tests). The active roster: lead-developer (docs/decks/.ciagent meta + verification + migration runbooks), backend-engineer (core/env.py dual-read helper, contract resolver path, Lambda, output_publisher, regression_verify), data-engineer (terraform resource names/tagging, state bucket migration, DynamoDB data migration, ECR re-push, schemas/tagging-standard). The frontend-engineer remains deactivated (no UI; decks are markdown = lead-developer territory). A security-engineer persona is not activated — the ABAC session-policy + tag-key migration (REQ-162) is data-engineer territory (terraform IAM) with lead-developer review. Territory enforcement = warn (co-authoring expected at the core/env.py + terraform boundary, and the contract-resolver + deploy-workflow boundary).

Assumptions logged

• A1 (confidence 0.9): No live AWS access is available during P0–P4 execution (the acdl-spike-runner IAM user's creds are in .env.secrets but live apply/modify/destroy is gated by NOVA_LIFECYCLE_MODE defaulting to plan-only). The terraform changes are validated via terraform validate; live apply is exercised by the modules-lifecycle workflow when explicitly set to full. This matches the v1.11–v1.14 established pattern.
• A2 (confidence 0.85): .env.secrets contains live rotated AWS credentials keyed by ACDL_AWS_*. P2 renames the KEYS only (values stay). The runtime reads via the new core/env.py dual-read helper (NOVA_AWS_ACCESS_KEY_ID preferred, ACDL_AWS_ACCESS_KEY_ID fallback), so no re-rotation is needed until P5 removes the fallback.
• A3 (confidence 0.8): The Gitea release API (POST .../releases) is reachable for v1.14.x tags (the v1.14 milestone shipped releases through v1.13.24 / release id 285). P0 ship targets v1.14.0.

---

v1.16 NFR Simplification — Research Addendum (2026-07-30)

Milestone: v1.16-Nova-Simplification (NFR). Research is codebase- grounded (not domain/ecosystem) — the two explore passes identified concrete, file:line-verified residual debt the v1.15 rebrand left, plus genuine simplification and the onboarding request-path scaffolding.

R1. v1.14 NFR categories already closed (do NOT re-propose)

v1.14 (REQ-135..154) swept: over-broad excepts (REQ-141), hardcoded account-ID externalization (REQ-142, ACDL_AWS_ACCOUNT_ID env + live fallback G-102), IAM Resource:"*" scoping to nova-* ARNs (REQ-143, G-104), contractId/env/error validation (REQ-144), additionalProperties:false schemas (REQ-145), .gitignore credential catch-all (REQ-146), Kyverno --kube-version removal + deferral doc (REQ-147, G-103), orphan bytecode/dead-config cleanup (REQ-148), 7 untested-script test coverage (REQ-149), set -euo pipefail parity + Gitea workflow parity (REQ-150), config/persona/backend hygiene (REQ-151), STANDARDS.md TYPE_MAP consistency (REQ-152), ARCHITECTURE/COST/GRILL doc sync (REQ-153), platform-VPC CIDR/subnet parameterization (REQ-154).

The v1.16 grill (G-101..G-106) and escalation E-001 are all CLOSED. v1.16 finds NEW residual signals (D-117).

R2. Fresh debt the v1.15 rebrand left (verified file:line)

High-severity correctness regressions (P1):

• adapters/terraform/adapter.py:117 — emits state_bucket = f"acdl-tfstate-{account_id}-us-east-1". The live state bucket was renamed to nova-tfstate-* in v1.15 P4 (REQ-163), but the adapter's emitted terraform backend still references acdl-tfstate-*. In plan-only mode this is latent (no real init against the bucket), but a full-mode lifecycle run would point at a non-existent bucket.
• adapters/kyverno/policies/require-resource-labels.yml:6,21,25,33,37 — enforces acdl:owner/acdl:environment labels. nova_tagging.py hard-fails on any acdl:* key post-P5 (REQ-164). The Kyverno policy contradicts the Nova tagging standard.

User-facing brand misses (P2):

• core/environment_check.py:59,61 — onboarding message header/body say "ACDL Environment Onboarding" / "ACDL environments are platform- managed" (user-facing).
• core/lambda/contract_ingestor.py:145,191 — GitHub issue alert title [ACDL-ALERT] + body "auto-created by the ACDL platform Lambda" (user-facing artifact).
• scripts/post_stage_comment.sh:39,46 — PR comment header "ACDL Stage"
  • footer "ACDL deploy pipeline" (user-facing).
• scripts/run_ci.sh:39 — CI banner "ACL CI Pipeline".
• Module docstrings: core/contract_resolver.py:1,474, core/confidence_signal.py:1, adapters/terraform/adapter.py:1, adapters/kyverno/kyverno_adapter.py:1, adapters/wiz/wiz_adapter.py:1, adapters/README.md:1, adapters/kyverno/README.md:4,18.

Dead code + stale comments (P3):

• scripts/run_platform.sh:153 — export ACDL_ENVIRONMENT_OVERRIDE="$ENVIRONMENT_OVERRIDE" # legacy fallback, removed in P5 — comment says "removed in P5" but the line is STILL present (dead code, P5 already shipped).
• Stale dual-read comments across core/local_emulators.py:15-16,503,505, core/regression_verify.py:318-319,333, scripts/run_regression.sh, scripts/run_lifecycle_*.sh (reference the retired G-106 fallback).
• acdl_* temp-dir prefixes: core/local_emulators.py:71,252, core/regression_verify.py:183,234, scripts/run_pattern_plan.sh:29, scripts/run_primitive_plan.sh:29, scripts/run_lifecycle_*.sh:36,41.

R3. Simplification opportunities (verified)

• core/regression_verify.py:328-409 — _check_live_terraform_plan_ microservice + _check_live_terraform_plan_static_assets are ~95% identical (resolve → adapt → init → validate → plan). Extract _check_live_terraform_plan(contract, label) (~35 lines saved).
• core/regression_verify.py:149-178 — _check_resolver_static_assets + _check_resolver_microservice identical except contract path. Extract _check_resolver(contract).
• core/regression_verify.py:477-503 — duplicated lifecycle-contract- resolve block. Extract _assert_contracts_resolve(module_dir).
• scripts/run_platform.sh:336-350 + :452-466 — duplicated HITL attestation block. Extract run_hitl_gate() shell fn (~14 lines).
• core/contract_resolver.py:50-68 duplicates core/environment_check.py: 36-54 env loader verbatim. Import instead.
• scripts/run_platform.sh:145-146 — hardcoded CONTRACT_ID UUID + WORK="/tmp/acdl_platform_run_v18" (v18 stale). Make config/env- derived.
• .gitea/workflows/ ↔ .github/workflows/ — 3 byte-identical pairs (ci.yml, deploy.yml, modules-lifecycle.yml, ~20 KB) maintained by hand + a test asserting identity. Generator (D-115) eliminates manual-sync risk.
• core/contract_resolver.py:540 — is_l2 = "l2" in interface_path or "composition" in interface_path fragile string heuristic. Add kind to registry entries (P7).
• scripts/run_platform.sh (610 lines) — decommission block (:180-237)
  • uptime block (:520-606) are self-contained. Extract to scripts/run_decommission.sh + scripts/run_uptime.sh (P9).

R4. Security gaps (verified, NEW — not v1.14 duplicates)

• core/lambda/contract_ingestor.py:251-252 — if not caller_arn: pass silently skips identity validation when IAM identity absent; relies on ABAC layer only (no defense-in-depth). Fail closed instead (P10).
• core/lambda/contract_ingestor.py:269 — valid_envs = {"dev","qa", "prod","dr"} hardcoded; the core/environments/ dir is the source of truth. Derive from the directory (P10).
• core/lambda/contract_ingestor.py — submit_contract checks the contract key exists but never validates the blob's size or schema. Unbounded payload → DynamoDB write amplification. Size cap + schema validation (P11).
• scripts/migrate_ssm_paths.py:113 — except Exception: pass (claims ParameterNotFound but catches all). Last true broad-swallow. Narrow to ParameterNotFound (P4).
• core/output_publisher.py:112,182 — except Exception in publish_to_ssm + post_github_comment swallow all (not narrowed by REQ-141 which targeted 6 other sites). Narrow to specific exceptions.

R5. Onboarding request-path scaffolding (already present)

The infrastructure for a zero-human request path already exists:

• terraform/platform/main.tf:153-183 deploys contract_ingestor Lambda
  • Function URL (IAM auth).
• core/lambda/contract_ingestor.py:325-362 dispatches submit_contract | report_error | validate_change_request. Adding onboard_consumer is a small extension (P18, D-119: writes a pending CMDB row, no provisioning).
• terraform/platform/consumer_invoke_policy.json is the ABAC policy template (aws:PrincipalTag/nova:owner == ${consumerRepo} scoped lambda:InvokeFunctionUrl).
• core/environments/*.json are static JSON templates with placeholder account_id: "000000000000" — auto-generation from a request is straightforward (P19).

Missing for "no humans": (a) onboard_consumer action + onboarding schema (P18), (b) core/onboarding.py to auto-generate <env>.json + emit a PR (P19), (c) cross-account deploy-role + ABAC tag Terraform, offline-proven (P20, D-114). Real AWS account/network/state creation stays a future feature (D-113).

R6. Developer experience gaps

• scripts/run_platform.sh has no --help (:82 rejects --* flags). --deploy-uptime (:532) is undocumented in the header. --local is absent from the README (P15).
• No .github/workflows/README.md cataloging the 7 workflows' inputs/ secrets/triggers (P16).
• No single getting-started path; README "How to run" lists 3 manual bootstrap steps. The offline happy path (run_ci.sh + run_platform.sh --check-only/--local) is not surfaced first (P17).

Assumptions logged (v1.16)

• A1 (0.9): No live AWS access during execution (consistent with v1.11–v1.15). NOVA_LIFECYCLE_MODE defaults to plan-only; terraform changes validated via terraform validate. The state-bucket drift (P1) is latent in plan-only mode but must still be fixed for correctness.
• A2 (0.85): The onboard_consumer Lambda action (P18) is offline- testable via moto / the local Lambda stub (D-092), consistent with the existing submit_contract/report_error test pattern.
• A3 (0.8): The workflow generator (P8, D-115) must preserve the byte-identity property as a test assertion (generated outputs match committed files), not lose it — the dedup is mechanical, not a semantic change to the workflows.
• A4 (0.85): The regression gate (D-091, D-118) at P9 and P21 confirms "simplify without regressions" — 22/22 capabilities must stay Verified. The gate is the credible control for the simplification wave.

---

v1.17 Research — Strategic Direction, Leadership Metrics & Unified Story

Phase: research (P0). Milestone: v1.17. Status: research. Researcher: ci-researcher + explore agent (signal inventory). Autonomy: full. Decisions D-120..D-132 locked in the planning conversation (PROJECT.md). NORTH_STAR.md drafted (pending GRILL).

1. Telemetry Signal Inventory (grounding audit)

Methodology: every claim below is grounded in a concrete file path + line number in /root/acdl. No speculation. The explore agent performed a full sweep of the repo. The finding: Nova has no metrics/telemetry/ dashboard aggregation layer today. What exists is a set of discrete, structured, file-based signal artifacts (JSON reports, JSONL logs, hash-chained outbox events, PR comments, Checkov JSON) plus unstructured stdout logs. A metrics milestone must aggregate these existing signals — it must not invent new ones without first adding emitters.

(a) Signals that EXIST TODAY and are STRUCTURED (groundable)

Signal	File / Emitter	Schema	Persistent?
Regression report (22 caps, status, duration_ms, gate)	.ciagent/REGRESSION_REPORT.json ← core/regression_verify.py:643-667	regression_verify.py:82-91	Yes (committed file)
Regression report (markdown mirror)	.ciagent/REGRESSION_REPORT.md	same	Yes
Checkpoint (milestone/phase/tag/regression summary)	.ciagent/CHECKPOINT.json (CIAgent-managed)	ad-hoc	Yes
PolicyCheckResult list (per-rule pass/fail/severity/resourceRef)	$WORK/pcr.json ← run_platform.sh:395 + checkov_adapter.py:50-71	schemas/policy_check_result.schema.json	No (ephemeral /tmp/)
Confidence signal (score, band, perInput, reasonCodes)	$WORK/signal.json ← run_platform.sh:412-426 + confidence_signal.py:60-65	confidence_signal.py:60-65	No (ephemeral)
Outbox event (hash-chained, CONFIDENCE_COMPUTED)	$WORK/event.json + $WORK/outbox_item.json ← run_platform.sh:444-459 + outbox_writer.py:44-56	audit_ledger_design.md:44-45,81-97	No (ephemeral; live DynamoDB torn down D-096)
Resolved Target Stack	$WORK/stack.json ← contract_resolver.py:581-603	schemas/stack.schema.json	No (ephemeral)
Lambda return bodies (submit/report_error/validate_cr/onboard)	core/lambda/contract_ingestor.py:171,265,284,392,446	ad-hoc JSON	No (Lambda not live; local stub only)
DynamoDB CMDB rows (submitted/pending contracts)	nova-contracts table ← contract_ingestor.py:160-170,433-445	ad-hoc	No (table torn down D-096)
SSM parameters (deploy outputs)	/nova/<env>/<contractId>/<name> ← output_publisher.py:123-156	ad-hoc	No (live AWS, torn down)
PR stage comment (mode, runId)	GitHub PR API ← post_stage_comment.sh:34-48 + deploy.yml:141	markdown table	Yes (GitHub)
PR deploy-outputs comment	GitHub PR API ← output_publisher.py:159-189	markdown table	Yes (GitHub)
GitHub issue (deploy failure alert)	GitHub API ← contract_ingestor.py:179-290 + deploy.yml:143-152	issue body	Yes (GitHub)
Local E2E result (stack_name, tier, outbox_events, chain_verified, lambda_status)	stdout JSON ← core/local_emulators.py:498-508,519	ad-hoc	No (stdout)
HITL gate result	core/hitl_gates.py:87,90 + run_platform.sh:179-185	stdout HITL PASS/BLOCK	No (stdout)
Attestation matrix result	core/attestation_matrix.py:184,187	stdout ATTESTATION PASS/BLOCK	No (stdout)
Cost figures	.ciagent/COST.md (manual Cost Explorer query)	markdown table	Yes (manual, not automated)

(b) Signals that EXIST but are UNSTRUCTURED (log-only)

Signal	Source	Format
CI pipeline result	scripts/run_ci.sh:70-71	stdout banner === CI PIPELINE OK ===
Platform stage banners + summaries	scripts/run_platform.sh:222,241,258,263,315,383,411,442,463,490,496	stdout === Step N: ... === + summary lines
Terraform init/validate/plan/apply/destroy logs	$WORK/tf-*.log ← run_platform.sh:320,324,328,352,375	raw terraform stdout (via tee)
Lifecycle test results	scripts/run_lifecycle_test.sh etc.	exit code only (no report file)
Decommission step counts	scripts/run_decommission.sh:40,54	stdout decommission step N: M resources...
Uptime endpoint count	scripts/run_uptime.sh:72,87	stdout uptime: N endpoint(s) to monitor
Onboarding prompt	core/environment_check.py:57-81	stdout text block
Pytest results	pyproject.toml:25 (-v --tb=short)	stdout only (no junit/json)
sync_workflows result	scripts/sync_workflows.py:56,53	stdout OK: 3 workflow pairs match / DRIFT: ...

(c) Proposed executive metrics with NO grounding today (DEFERRED)

Proposed metric	Why no grounding	Controlling decision
Live infrastructure health (ECS running count, ALB 5xx, RPS)	Live AWS torn down; CAP-013..016 Skipped	D-096
Live outbox write rate / ledger append latency	DynamoDB outbox table absent	D-096
Tamper-evident ledger checkpoint count / JWS signature rate	S3 Object Lock + JWS + async worker deferred	D-083
Onboarding funnel: requested → granted conversion	Only "requested" (pending row) is emitted; no grant event	D-113, D-114, D-119
Time-to-provision (onboarding SLA)	Real AWS provisioning deferred	D-113
Cross-account role grant count	Offline-proven only, no live apply	D-114
Drift detection (scheduled terraform plan -detailed-exitcode)	Needs live AWS workspaces + a scheduler Nova doesn't have	D-096 + no scheduler
GreenOps / carbon (WattTime/Electricity Maps API)	No grounding; new external API	future emitter
Predictive vs Reactive ratio	Requires an ML anomaly-forecasting service	future emitter
Multi-cloud normalization (Azure/GCP/K8s, FOCUS spec)	Nova is AWS-only	future
Red Team MTTR	No red-team program exists	future
Self-healing velocity	Nova has no auto-remediator	future emitter
SLA / unplanned downtime	Needs live service uptime monitoring against SLOs	D-096
Per-module lifecycle success rate over time	No structured report file written; only exit code	gap (no decision)
Test pass rate / test count time-series	No junit/json reporter configured	gap (add --junitxml to addopts)
Code coverage trend	pytest-cov installed but not in addopts	gap
Deploy frequency / lead time / MTTR (DORA)	No deploy-event emitter; pipeline runs not counted	gap
Policy pass rate time-series	pcr.json emitted but ephemeral; not persisted	gap (D-096 blocks live persistence)
Confidence score distribution over time	signal.json emitted but ephemeral	gap
Consumer adoption count / active consumers	PROJECT.md:487 explicitly states "0 consumer adoption today"	honest scope
Cost time-series (automated)	COST.md is a one-shot manual query; no automated emitter	gap

Bottom line: the single richest existing structured signal is .ciagent/REGRESSION_REPORT.json (22 capabilities × {status, tier, duration_ms, detail} + summary counts + boolean gate). The next richest is the per-run $WORK/*.json family (pcr.json, signal.json, event.json, stack.json) — but these are ephemeral and not persisted in CI. The lowest-friction grounding for a "no-humans" dashboard is therefore: (1) regression report → capability health, (2) PR comments + GitHub issues → deploy/failure activity, (3) add --junitxml to pytest → test trend, (4) persist $WORK/*.json → policy/confidence/outbox time-series, (5) extend outbox_writer → Decision Ledger, (6) add Infracost → pre-apply cost estimates.

2. Telemetry Reference Architecture (Nova-native adaptation)

The PO provided a full distributed-system telemetry reference architecture (CloudEvents 1.0 envelope, OpenTelemetry SDK, Kafka/NATS event bus, Prometheus hot path, ClickHouse warehouse, QLDB decision ledger, Infracost, drift detection, ML anomaly forecasting). Per D-120, we adopt the principles but implement with Nova-native minimal tech. The mapping:

Direction's principle	Nova-native implementation (v1.17)
Events are the source of truth; dashboards are projections	Hybrid (D-125): existing file signals stay as files; collector reads them and emits normalized CloudEvents into metrics/events.jsonl + SQLite. New emitters emit CloudEvents directly.
Every AI action is logged with confidence + alternatives	Decision Ledger (D-121): outbox_writer.py extended → SQLite append-only hash-chain table. ai.decision.made modeled from confidence_signal (D-122): decision_id=run_id, chosen_action=band, confidence=score, alternatives=perInput, human_override=HITL block.
Hot/cold storage split	Cold-only SQLite (D-126): metrics/nova_metrics.db. Hot path deferred (no live ops, D-096).
Read-only external integrators	Infracost (pre-apply, offline, reads plan JSON). Cloud billing CUR deferred (D-096). Carbon APIs deferred (future).
CloudEvents 1.0 envelope	Adopted. core/metrics/event_envelope.py defines the envelope + platform.* semantic conventions.
Decision Ledger = append-only with hash chain + outcome backfill	SQLite append-only table with hash chain (D-121). Outcome backfilled from apply.completed via decision_id → request_id correlation. Honors D-083 (no S3 Object Lock/JWS).
Cost governance: mandatory tags + Infracost pre-apply	Nova already enforces nova:* tags (nova_tagging.py, hard mode). Infracost added as plan post-processor (D-120). Post-apply CUR deferred (D-096).
Definition-of-success docs for every KPI	Per-KPI docs in docs/metrics/ (D-127).
Replay-ability	SQLite store + JSONL event log are replayable by design.

CloudEvents envelope (Nova-native)

{
  "specversion": "1.0",
  "id": "<uuid>",
  "source": "nova.platform",
  "type": "nova.run.completed",
  "time": "<ISO8601>",
  "subject": "<contractId>/<env>",
  "datacontenttype": "application/json",
  "platform": {
    "tenant_id": "acdl",
    "run_id": "run-<epoch>",
    "contract_id": "<uuid>",
    "environment": "dev|qa|prod|dr",
    "actor": {"type": "confidence-gate", "id": "confidence_signal"},
    "trace_id": "<run_id>"
  },
  "data": {
    "duration_ms": 4800,
    "stages": ["resolve", "adapt", "validate", "plan", "apply"],
    "exit_code": 0,
    "confidence": {"score": 0.94, "band": "pass", "perInput": {...}},
    "policy": {"passed": 12, "failed": 0, "skipped": 0},
    "hitl": {"gate": "dev", "result": "autonomous", "block": false},
    "cost_estimate_usd": -12.40,
    "decision_id": "run-<epoch>",
    "outcome": "succeeded"
  }
}

Core event types (Nova-native minimum viable set)

Event type	Emitted by	Purpose	Grounding
nova.run.started	run_platform.sh	Measures demand; provisioning lead time start	new emitter (P1)
nova.run.completed	run_platform.sh	Run count, stage durations, exit, MTTR	new emitter (P1)
nova.run.failed	run_platform.sh	Failure count, MTTR numerator	new emitter (P1)
nova.policy.evaluated	checkov_adapter.py	Policy pass rate, compliance KPIs	grounded (pcr.json → P1 persists)
nova.confidence.computed	confidence_signal.py	Confidence distribution, decision accuracy	grounded (signal.json → P1 persists)
nova.ai.decision.made	outbox_writer.py (extended)	Decision Ledger entry	grounded (D-121, D-122)
nova.attestation.recorded	hitl_gates.py	Attestation Coverage, human-in-the-loop audit	grounded (D-132)
nova.cost.estimated	Infracost post-processor	Pre-apply cost estimate	new emitter (P1, Infracost)
nova.capability.verified	regression_verify.py	Capability health, regression gate	grounded (REGRESSION_REPORT.json)
nova.test.completed	pytest (junit XML)	Test count, pass rate	new (P1 adds --junitxml)

3. Metric-to-Signal Scorecard (the "no fabrication" contract)

Executive metric (NORTH_STAR target)	Status	Source / formula	Decision
Touchless Resolution Rate ≥99%	grounded (after P1)	runs without operational HITL block ÷ total runs (attestation gates excluded)	D-122, D-132
Human Escalation Frequency <0.1%	grounded (after P1)	operational HITL blocks ÷ total runs (attestation sign-offs excluded)	D-122, D-132
MTTR (p95) <60s	grounded (platform-run)	apply.failed.time → successful retry.time	D-131
Predictive vs Reactive ≥3:1	deferred	requires ML forecasting (future emitter)	future
AI Decision Accuracy ≥99.5%	grounded (after decision ledger)	decisions not followed by apply.failed/incident within 5min	D-121, D-122
Drift Auto-Reversal ≥95%	deferred	requires drift detection (D-096 + scheduler)	D-096
Cloud Spend Reduction ≥25%	partial	pre-apply estimate grounded (Infracost); actuals deferred (D-096 CUR)	D-120
L1/L2 Ops Hours Avoided ≥70%	derived	formula: run count × manual baseline minutes × blended rate	D-127
Platform ROI ≥250%	derived	formula: (labor savings + cloud savings + avoided downtime) ÷ platform op cost	D-127
Decision Ledger Coverage 100%	grounded (this milestone)	outbox_writer.py → SQLite hash-chain	D-121
Attestation Coverage 100%	grounded	hitl_gates.py + outbox approver_* attributes; prod/dr	D-132
AI-Agent Intent Share ≥40%	future	no AI-agent consumers today; placeholder view	future
Capability health (18V+4S)	grounded	REGRESSION_REPORT.json	existing
Confidence score distribution	grounded (after P1)	signal.json → decision ledger	D-121
Policy pass rate	grounded (after P1)	pcr.json → persisted	D-120
Test count / pass rate	grounded (after P1)	pytest --junitxml	D-120
Provisioning Lead Time	grounded (after P1)	run.started → run.completed	D-120
Deployment Frequency	grounded (after P1)	count(run.completed) per day	D-120
Deploy-failure alert count	grounded	GitHub issues via Lambda report_error (D-055)	existing
Cost figures (actuals)	manual one-shot	COST.md (Cost Explorer query)	existing
FTE Hours Saved / TRV	derived	formula over run count + COST.md	D-127
Self-healing velocity	deferred	no auto-remediator	future
SLA / unplanned downtime	deferred	needs live service uptime (D-096)	D-096
GreenOps / carbon	deferred	WattTime/Electricity Maps API (future)	future
Red Team MTTR	deferred	no red-team program	future
Multi-cloud normalization	deferred	Nova is AWS-only	future
Live CUR reconciliation	deferred	needs live AWS billing (D-096)	D-096

4. Deferred-Decision Ledger (constraints on this milestone)

Decision	Scope	Grounding impact
D-096	Live AWS torn down post-v1.11	BLOCKS all live-AWS metrics (CAP-013..016 Skipped; live outbox; live state bucket; live CUR)
D-083	S3 Object Lock + JWS + async worker deferred	BLOCKS tamper-evident ledger; v1.17 uses SQLite hash-chain instead
D-113/D-114/D-119	Onboarding = request-path only; no auto-grant	BLOCKS onboarding funnel "granted" half
D-091/D-118	Regression gate (D-091) gates milestone completion	ENABLES the strongest metric signal (REGRESSION_REPORT.json)
D-092	Local emulating adapters	ENABLES offline E2E metrics (CAP-011/012)
D-055	report_error Lambda action creates GitHub issues	ENABLES deploy-failure alert metric
D-050	Publish deploy outputs to SSM + GitHub PR comment	ENABLES outputs-published metric
D-054/D-043/D-109	Nova tagging standard (hard mode)	ENABLES tagging-compliance metric
D-084	8-concern attestation matrix	ENABLES attestation metrics (operator-supplied evidence artifacts)
D-089	Signature verification skipped when signing key unset (dev/CI)	Signature metrics are no-ops in dev

5. Deck-Storytelling Research (x3 arc + per-slide benefit)

The "tell them x3" structure

The PO's direction: "Tell them what you're going to tell them, then tell them, then tell them what you told them." Applied at two levels:

Deck level (the 5-act arc):

1. Opening slide = "what I'm going to tell you" — the full arc preview: Problem → Vision → How → Proof → Roadmap.
2. Body (acts 1–5) = "tell them" — each act delivers its content.
3. Closing slide = "what I told you" — recap of the 5 acts + the ask.

Per slide:

1. Slide opens with what it'll cover (1 line: "This slide shows X").
2. Slide delivers the content (bullets, diagram, or table).
3. Slide closes with an explicit "benefit of this stage" callout (1 line: "Benefit: you now know Y" or "Why this matters: Z").

Fluidity conventions

• Transitions are written, not hand-waved. Each slide's opening line references the previous slide's close ("Having seen X, now consider Y").
• No disjointed jumps. If a topic shift is needed, a bridge slide or a transition sentence carries the audience across.
• The arc is visible. A small "act indicator" in the Marp footer (e.g., Act 3/5: How it works) keeps the audience oriented.

Existing deck inventory (to be retired)

Two decks exist today in docs/presentations/:

• how-the-platform-works.md (32,916 bytes) → marp → html → talking-points
• the-developer-experience.md (27,509 bytes) → marp → html → talking-points

Both follow a 4-step process (source .md → Marp → HTML → talking-points) documented in docs/presentations/README.md. Per D-130, both are merged into one unified narrative deck and retired.

Grounded metrics already cited in existing decks

• "22/22 auto-verifiable capabilities Verified" — stale vs current REGRESSION_REPORT.json (18V+4S post-D-096). The unified deck must derive this from the report, not copy the stale claim.
• Confidence thresholds: dev ≥0.50, qa ≥0.75, prod ≥0.90, dr ≥0.95 — grounded in core/confidence_signal.py:57 (THRESHOLDS).
• RPO = 0 (evidence write synchronous) — grounded in core/audit_ledger_design.md:27,103.
• Cost figures — how-the-platform-works.md:461; cites COST.md.
• Confidence signal 6 inputs + weights — grounded in core/confidence_signal.py:40-47.
• "~80-line stateless adapter" vs "918-line monolith" — grounded in ROADMAP/RESEARCH prose.

Planned deck structure (for PLAN to detail)

The unified deck "Nova — The No-Humans Infrastructure Platform":

Act	Slides	Content	Proof source
1. Problem	2–3	The no-humans imperative; why operators are the bottleneck; the trust gap	NORTH_STAR vision
2. Vision/Direction	2–3	Nova's vision; 4 strategic objectives; anti-goals; the attestation model (autonomy in operations, human at stage gates)	NORTH_STAR
3. How it works	3–4	Contract → resolver → adapter → confidence → HITL gate; the Decision Ledger; the 8-concern attestation matrix	code grounding
4. Proof (metrics)	3–4	Capability health (18V+4S); confidence distribution; policy pass rate; Decision Ledger coverage; Attestation Coverage; cost estimates; the grounded/derived/deferred honesty model	metrics export
5. Roadmap/Ask	2	12–18mo targets (committed); deferred metrics (honest); the ask	NORTH_STAR targets

Total: ~12–16 slides. Opening = arc preview; closing = recap + ask.

6. Assumptions logged (v1.17)

• A1 (0.9): No live AWS access during execution (consistent with v1.11–v1.16). All metrics that require live AWS ship as placeholder views. The Infracost integration runs offline (reads plan JSON).
• A2 (0.85): The Decision Ledger SQLite hash-chain is sufficient for v1.17's audit needs. The full tamper-evident ledger (S3 Object Lock + JWS, D-083) is a future milestone. The hash-chain provides append-only + integrity verification locally.
• A3 (0.8): The "AI decision" framing (D-122) is honest: Nova's "AI" is the confidence-gated policy engine (confidence_signal + HITL gate), not an LLM planner. The deck and METRICS.md must frame this accurately — overclaiming "AI" would violate the "no fabrication" constraint.
• A4 (0.85): The unified deck's "Proof" section cites only grounded metrics with real numbers. Deferred metrics are shown as "Planned" with the <span class="badge planned">Planned</span> badge. No fabricated numbers in any slide.
• A5 (0.8): --junitxml + --json-report added to pytest addopts does not break the existing test suite (the flags are additive; pytest continues to run normally). CAP-009 (offline pytest suite passes) must remain Verified after the change.
• A6 (0.75): Infracost is available as a CLI tool that can be installed in the CI environment and run locally. It reads terraform plan -out=plan.tfplan + terraform show -json plan.tfplan to produce a cost estimate. No live AWS access required. If Infracost is not available, the cost.estimated event is omitted (degraded mode, not a failure).

---

v1.18 Research — Citizen Developer & Production-Grade Guidance

Phase 0 RESEARCH. Autonomy = full. Findings are evidence-grounded (fetched from live sources, not assumed). The Atelier repo, the MCP Python SDK v2 docs, the existing Nova schemas/ingestor, and the Marp CLI README were all fetched directly. Decisions are logged with confidence scores; low-confidence items are flagged.

1. Atelier Integration Reference

1.1 The 8 core principles (C1–C8)

Source: core/first-principles.md (fetched 2026-08-06 from https://git.cloudinit.dev/coreci/atelier/raw/branch/main/core/first-principles.md). Precedence is a total order — a lower-numbered principle is never sacrificed for a higher-numbered one (C1 never sacrificed; C2 only for C1; C3 only for C1/C2; C4–C8 tradeable among themselves but always below C1–C3).

ID	Principle	One-line description
C1	Correctness	The system does what it is supposed to do, and nothing else. Highest principle; never overridden. Security is a subset (exploitable code is incorrect). Includes temporal correctness (a late answer is wrong when the deadline mattered).
C2	Clarity	The intent of the code is obvious to its reader. Optimize for the reader; names reveal intent; comments explain why not what. Unclear code is where bugs hide.
C3	Simplicity	The solution is as simple as possible, and no simpler. Complexity is the enemy of correctness; every line is a liability. Not laziness — the result of removing everything unnecessary.
C4	Locality	Decisions and their consequences live near each other. State, logic, side effects that depend on each other live near each other. A change needing many distant files is a locality violation.
C5	Reversibility	Every decision can be undone, and the cost of undoing is known. Migrations/deploys/schema/API changes reversible by default. Versioning, feature flags, rollback paths are the mechanisms.
C6	Composability	Parts combine into wholes, and the parts are reusable in new wholes. A part that does one thing well composes; the boundary is its contract. Composable parts are understandable in isolation.
C7	Observability	The system's behavior is visible to the people who must understand it. Logs/metrics/traces are first-class, designed in. An observable system answers "what/why/what next" without reading source.
C8	Economy	The system uses no more resources than the task requires (time, memory, attention, money, complexity). Most tradeable principle; unbounded growth in any resource is a defect.

The precedence string (from core/first-principles.md §3): C1 Correctness > C2 Clarity > C3 Simplicity > C4 Locality > C5 Reversibility > C6 Composability > C7 Observability > C8 Economy.

Conflict resolution (core/conflict-resolution.md, fetched): a deterministic 6-step procedure. The hierarchy is core/first-principles.md > domains/<x>/first-principles.md > domains/<x>/<topic>.md > languages/<lang>.md > examples/<x>.md. Same-level conflicts resolve by core derivation (via the matrix), then by specificity, then by filing an issue (a tie is a defect). A domain's "non-tradeable" declaration (e.g. Security: 8 of 10) promotes those rules to C1-equivalent — a binding escalation recorded in the matrix's derivation.

1.2 The 19 domains and Nova-citizen-dev relevance

Source: matrix/principles-matrix.md (fetched) + the releases page (v0.4 milestone = 19 domains, 190 P-rules, confirmed in the v0.3.6 release notes and the matrix Coverage Summary).

#	Domain	Atelier path	P-rules	Nova-citizen-dev relevant?	Reason
1	UI/UX	domains/uiux/	10	NO — excluded	v1.18 has no frontend (Out of Scope: "A Nova-built frontend / dashboard"). Decks are markdown, not a UI.
2	API Design	domains/api/	10	YES	A citizen developer building a web API / worker / scheduled job touches API contracts. Maps to skills/api.md.
3	Security	domains/security/	10	YES	Zero-trust, input validation, secret hygiene, fail-securely — universal for any production-grade service. Maps to skills/security.md.
4	Data	domains/data/	10	YES	Schema-as-truth, migration safety, referential integrity — applies to any stateful service. Maps to skills/data.md.
5	Testing	domains/testing/	10	YES	Tests-as-specification, determinism, edge-case coverage — required for a citizen developer's UAT. Maps to skills/testing.md.
6	Performance	domains/performance/	10	YES (reference, not a skill)	Measure-first, bounded operations, no N+1, timeouts. NOT one of the 9 REQ-221 skills; Performance principles are cited inside the 9 skills + the index.
7	Observability	domains/observability/	10	YES	Structured logs, correlation IDs, no secrets in logs — the "basic observability bootstrap" BA.A skill. Maps to skills/observability.md.
8	Errors	domains/errors/	10	YES	Errors are data, fail loudly + specifically, preserve context — production-grade error handling. Maps to skills/errors.md.
9	Documentation	domains/documentation/	10	YES (reference, not a skill)	Docs-as-code, audience awareness, examples mandatory. REQ-221 does NOT list skills/documentation.md; a self-referential "documentation skill" is redundant. Principles cited inside docs/skills.md index.
10	Concurrency	domains/concurrency/	10	YES (reference, not a skill)	Immutability, bounded queues, timeouts — advanced for a citizen developer's first 5 skills. REQ-221 does NOT list skills/concurrency.md. Top rules cross-referenced inside skills/api.md + skills/errors.md.
11	DevOps	domains/devops/	10	YES	Reproducibility, rollback-first, config-as-code — the citizen developer co-owns Release Management (RACI). Maps to skills/devops.md.
12	Infrastructure as Code	domains/infrastructure-as-code/	10	YES	Declarative intent, idempotence, plan-before-apply, no secrets in HCL — directly relevant to the Nova contract→Terraform path. Maps to skills/infrastructure-as-code.md.
13	Kubernetes	domains/kubernetes/	10	NO — excluded	Nova emits Terraform (ECS/Fargate per the architecture), not K8s manifests. Kyverno adapter is "ready but inactive" (D-053). Not citizen-dev-relevant.
14	GitOps + Operators	domains/gitops-operators/	10	NO — excluded	Nova uses a push pipeline (contract → resolve → plan → apply), not a pull-based reconciler. Not citizen-dev-relevant.
15	AI/ML	domains/ai-ml/	10	YES (reference, not a skill)	Reproducibility, data versioning, drift detection — relevant to Nova itself (Nova is an agentic platform), but a citizen developer on Nova is NOT building ML models; they consume Nova's agentic capability. REQ-221 does NOT list skills/ai-ml.md; the Atelier AI/ML domain is platform-team guidance, not citizen-dev guidance.
16	i18n	domains/i18n/	10	NO — excluded	Not relevant to a citizen developer's first production-grade service on Nova.
17	Compliance	domains/compliance/	10	YES	Audit logs append-only, policy-as-code, evidence-by-operation — directly relevant (Nova's compliance posture is a selling point). Maps to skills/compliance.md.
18	Edge	domains/edge/	10	NO — excluded	Nova does not deploy edge/CDN for the citizen developer's first 5 skills; Route53/ACM/CloudFront are consumer-supplied extension points (D-049).
19	Messaging	domains/messaging/	10	NO — excluded	The citizen developer's first 5 skills (web API / worker / scheduled job / static asset / observability bootstrap) do not require a broker; messaging is a future capability.

Relevant count: 13 of 19 are relevant to some Nova audience (YES or YES-reference). Of those, 9 become skills (per REQ-221, the planned count). The other 4 relevant domains (Performance, Documentation, Concurrency, AI/ML) are reference-only — their principles are cited inside skills or the docs/skills.md index, but they do NOT get their own skill file. This matches REQ-221's exact 9-skill list.

Excluded count: 6 of 19 (UI/UX, Kubernetes, GitOps, i18n, Edge, Messaging) are not relevant to a Nova citizen developer building a production-grade application — confirmed.

1.3 Atelier domain → Nova skill mapping (final 9-skill list)

REQ-221 names exactly 9 skills. The research confirms the planned 9 — no adjustment needed. The mapping (each skill cites its Atelier source path + distills the citizen-developer-relevant subset + links to agent-checklist triggers + maps to the BA.A 5-skill catalog):

Nova skill file	Atelier domain path	P-rules distilled	BA.A catalog skill it extends
skills/api.md	domains/api/	P1 Contract Fidelity, P2 Clarity, P5 Versioning, P6 Idempotency, P8 Security, P9 Error Transparency	web API
skills/security.md	domains/security/	P1 Zero Trust, P2 Least Privilege, P4 Input Validation, P6 Crypto Correctness, P8 Fail Securely, P9 Secret Hygiene	all 5 (cross-cutting)
skills/data.md	domains/data/	P1 Truth, P3 Invariants in Schema, P4 Migration Safety, P7 Type Fidelity, P9 Referential Integrity	web API, worker, scheduled job
skills/testing.md	domains/testing/	P1 Tests as Specification, P3 Determinism, P5 Coverage of Behavior, P9 Edge Case Coverage, P10 No Test Theater	all 5 (UAT is a citizen-developer RACI responsibility)
skills/observability.md	domains/observability/	P1 Structured by Default, P2 Correlation, P6 No Secrets in Obs, P7 Actionable Alerts	basic observability bootstrap
skills/errors.md	domains/errors/	P1 Errors are Data, P2 Fail Loudly, P3 Fail Specifically, P4 Preserve Context, P5 Recoverable When Possible	web API, worker, scheduled job
skills/devops.md	domains/devops/	P1 Reproducibility, P4 Rollback First, P5 Progressive Delivery, P6 Config as Code, P8 Security at Every Layer	scheduled job, worker (deploy/release is co-owned Release Mgmt)
skills/infrastructure-as-code.md	domains/infrastructure-as-code/	P1 Declarative Intent, P2 Idempotence, P4 Plan Before Apply, P5 Version Everything, P10 Secrets Never in Code	static asset (the contract→Terraform path)
skills/compliance.md	domains/compliance/	P1 Audit Logs Append-Only, P2 Every Significant Action Logged, P4 Policy is Code, P5 Policy is Evaluated as a Gate, P9 Secrets Redacted in Audit	all 5 (cross-cutting; Nova's compliance posture)

Final recommendation: 9 skills, exactly as REQ-221 planned. Confidence 0.95 — the planned list maps cleanly to the relevant Atelier domains and to the BA.A 5-skill catalog; the 4 "reference-only" domains (Performance, Documentation, Concurrency, AI/ML) are correctly not elevated to skills (a citizen developer's first production-grade service does not need a standalone Concurrency or AI/ML skill; Performance and Documentation principles are cited inside the 9 skills + the index).

1.4 Agent-checklist → MCP atelier.validate_against_principles checks

Source: review/agent-checklist.md (fetched). The checklist has a Core (C1–C8) section (8 subsections, ~30 boolean items) plus domain-specific trigger sections (one per domain; Nova-relevant ones: API, Security, Data, Testing, Performance, Observability, Errors, Concurrency, DevOps, IaC, Compliance).

The MCP atelier.validate_against_principles tool (REQ-223, in plugins/validation.py) runs the relevant checklist items against a code/diff snippet. The tool input model:

class ValidateInput(BaseModel):
    snippet: str               # the code/diff to validate
    language: str               # e.g. "python", "terraform", "yaml"
    domains: list[str]          # e.g. ["security", "api"] — which domain triggers to run
    run_core: bool = True       # always run C1–C8 unless explicitly skipped

The structured output model (Pydantic, returned as structured_content):

class Violation(BaseModel):
    principle: str              # e.g. "C1", "security/P9"
    checklist_item: str         # the verbatim checklist question
    severity: str               # "C1" (blocking) | "non-tradeable" | "tradeable"
    evidence: str               # the snippet substring + why it fails
    fix_hint: str               # the principle's remediation guidance

class ValidateResult(BaseModel):
    snippet_id: str             # hash of the snippet for replay
    passed: bool
    violations: list[Violation]
    domains_checked: list[str]
    core_checked: bool

Checklist → check mapping (the validation plugin encodes each checklist item as a boolean predicate over the snippet + language):

Checklist section	MCP check behavior	Nova-relevant?
C1 Correctness (4 items)	Run all 4; any fail → severity: "C1" (blocking).	YES — always run (core)
C2 Clarity (4 items)	Heuristic checks: name smell (data/temp/x/doStuff), comment-why ratio.	YES — always run
C3 Simplicity (4 items)	Dead-code heuristic, function-length, premature-abstraction.	YES — always run
C4 Locality (3 items)	Cross-file-change heuristic (for diffs); within-file coupling.	YES — always run
C5 Reversibility (3 items)	Migration-has-down, deploy-has-rollback presence checks.	YES — always run
C6 Composability (3 items)	Single-responsibility heuristic, boundary-typed check.	YES — always run
C7 Observability (4 items)	Log-presence, error-context, metric, no-secrets-in-logs (hard check).	YES — always run
C8 Economy (3 items)	Unbounded-growth, no-timeout, resource-leak heuristics.	YES — always run
If API	5 items: nouns-plural-lowercase, status codes, structured errors, schema validation, auth-required.	YES — when domains includes "api"
If Security	5 items: no-secrets-in-code/logs/URLs, input-validation, output-encoding, vetted-crypto, authz-checked. All 5 are non-tradeable (Security domain §3).	YES — when "security"
If Data	5 items: schema-reflects-domain, constraints-in-schema, migration-up-down, domain-types, no-SELECT-star.	YES — when "data"
If Testing	4 items: independence, determinism, edge-cases, failure-specificity.	YES — when "testing"
If Performance	4 items: no-unbounded, no-N+1, timeouts, cache-invalidation.	YES — when "performance"
If Observability	4 items: structured-logs, correlation-id, no-high-cardinality, alerts-have-runbooks.	YES — when "observability"
If Errors	4 items: not-swallowed, specific, context-preserved, recovery-attempted.	YES — when "errors"
If Concurrency	5 items: shared-state-minimized, minimal-locks, bounded-queues, timeouts, cancellation.	YES — when "concurrency"
If DevOps	4 items: pipeline-is-process, rollback-known, config-in-code, env-parity.	YES — when "devops"
If IaC	8 items: declarative, pinned-providers, remote-locked-state, plan-before-apply, no-secrets-in-HCL, versioned-modules, drift-is-incident, least-priv-providers.	YES — when "infrastructure-as-code"
If Compliance	10 items: append-only-audit, a-priori-action-set, retention-as-policy, policy-as-code, policy-as-gate, continuous-evidence, attributable-identity, subject-access, redacted-secrets, observable-posture.	YES — when "compliance"

The validation plugin reads the vendored review/agent-checklist.md (frozen at the pinned tag — §1.6) so the checks are replayable against the exact checklist version that produced a result. The plugin maps each checklist line to a predicate function keyed by (language, principle) so a "no secrets in code" check runs differently for Python (ast scan for string-constant assignment) vs Terraform (HCL scan for hardcoded provider keys) vs YAML (scan for api_key: literals).

1.5 Principle-lookup query model

atelier.lookup_principle(domain: str, principle_id: str) (REQ-223, in plugins/principles.py) resolves a principle reference to its full text + core derivation + checklist items. Resolution model:

Input:

class LookupInput(BaseModel):
    domain: str         # "security" | "api" | "data" | ... | "core"
    principle_id: str   # "P4" | "C1" (core) | "P9"

Resolution path (the lookup algorithm):

1. If domain == "core": load vendor/core/first-principles.md, parse the ### C<n>. <Name> section for principle_id (e.g. C1 → the "C1. Correctness" section). Return the full principle text.
2. Else: load vendor/domains/<domain>/first-principles.md, parse the ### P<n>. <Name> section for principle_id (e.g. security/P4 → the "P4. Input Validation" section).
3. Cross-reference the matrix: load vendor/matrix/principles-matrix.md, find the row for <Domain> P<n>, extract the Core column (e.g. Security P4 → C1). This is the core derivation.
4. Cross-reference the checklist: load vendor/review/agent-checklist.md, find the If <Domain> section, extract the checklist items tagged with P<n> (the IaC section tags items with (P1), (P10) etc.; the Security section items map to P9, P4, P5, P6, P1/P10 by content).
5. Check non-tradeable status: load vendor/domains/<domain>/first-principles.md §3 (Conflict Resolution); if the principle is listed as "never sacrificed", mark non_tradeable: true (escalates it to C1-equivalent per core/conflict-resolution.md §6).

Return (structured output):

class PrincipleLookup(BaseModel):
    domain: str                   # "security"
    principle_id: str             # "P4"
    name: str                     # "Input Validation"
    text: str                     # full principle body
    core_derivation: list[str]   # ["C1"]  (from the matrix)
    non_tradeable: bool           # True for security P1-P8, P9; False for P10
    checklist_items: list[str]    # the verbatim checklist questions for this P-rule
    source_path: str              # "domains/security/first-principles.md" (relative to vendor/)

Example resolution — atelier.lookup_principle("security", "P4"):

• name: "Input Validation"
• text: "All input is untrusted until proven otherwise. Validation happens at the boundary, against a schema, with explicit failure modes."
• core_derivation: ["C1"] (matrix row: Security P4 → C1)
• non_tradeable: true (Security §3 lists P4 as "never sacrificed")
• checklist_items: ["Input is validated at the boundary", "Output is encoded for its context"] (from review/agent-checklist.md If Security)
• source_path: "domains/security/first-principles.md"

The two companion tools:

• atelier.list_domains() → returns the 19 domain names + their P-rule counts + relevance flag (the plugin hardcodes the Nova-relevance table from §1.2 so the citizen developer's agent can filter to the 13 relevant / 9 skill-bearing domains).
• atelier.matrix_lookup(domain: str) → returns the full domain→core mapping for one domain (all 10 P-rules → their core C-rule(s)), used by validate_against_principles to set severity and by conflict resolution when two findings collide.

1.6 Recommended Atelier pinned tag to vendor

Recommendation: vendor tag v0.3.6 (the v0.4 milestone release).

Evidence (from https://git.cloudinit.dev/coreci/atelier/releases, fetched 2026-08-06):

• The latest release is v0.3.6, dated 2026-08-05 16:22:58 +00:00, tagged v0.3.6 (commit 66b4767d25), marked Stable, with the title "v0.3.6 — v0.4 milestone: Edge + Messaging + Language-Derived Docs".
• It is the v0.4 milestone release (the release notes state: "v0.4 — Edge + Messaging + Language-Derived Docs (Milestone Release). Tag: v0.3.6 (NFR milestone — final patch IS the deliverable; no separate minor tag per branch-strategy.md)").
• The matrix is at its complete state: 19 domains, 190 P-rules (the Coverage Summary in matrix/principles-matrix.md confirms this exactly; the v0.3.6 release notes confirm "170 → 190 P-rules across 19 domains"). All 190 P-rules trace to ≥1 core C-rule (no orphans — verified in the release audit).
• -11 commits to main since this release — there is post-release activity on main, which is exactly why pinning matters: vendoring main HEAD would be a moving target. v0.3.6 is the frozen, audited, reproducible snapshot. This satisfies D-136 (vendor for audit reproducibility) — an agentic validation result must be replayable against the exact principles that produced it.

Vendoring mechanics (for REQ-224):

• mcp/atelier/vendor/ = a clean copy of the Atelier repo at tag v0.3.6 (the core/, domains/, matrix/, review/ directories — the docs the MCP tools read; examples/ and languages/ are optional but cheap to include for completeness).
• mcp/atelier/vendor/VERSION.md records: tag v0.3.6, commit 66b4767d25, date 2026-08-05, milestone "v0.4 Edge + Messaging + Language-Derived Docs", P-rule count 190, domain count 19.
• scripts/update_atelier_vendor.sh = a helper that takes a tag arg, fetches the tarball from https://git.cloudinit.dev/coreci/atelier/archive/<tag>.tar.gz, extracts the doc directories into mcp/atelier/vendor/, and updates VERSION.md. Intentional upgrades only (re-run + re-audit).

Confidence: 0.95. The only risk is that a v0.5 milestone lands before P5 ships — but the pinning model (VERSION.md + update script) makes a future upgrade a deliberate, audited action, not a silent drift.

---

2. MCP Python SDK v2 Reference

Source: https://py.sdk.modelcontextprotocol.io/ (the official Python SDK docs, fetched 2026-08-06) + the Tools page (.../servers/tools/) + the Structured Output page (.../servers/structured-output/). The docs document v2, the current stable release line (Python 3.10+).

2.1 Confirmed API patterns

1. Server creation + import path. The v2 high-level server class is MCPServer (NOT FastMCP — that was v1; v2 renamed/restructured):

   from mcp.server import MCPServer
   mcp = MCPServer("atelier")   # one arg = server name
   

   This is the exact pattern shown in the docs' landing-page example and the Tools-page example. There is no FastMCP import in v2.

2. @mcp.tool() decorator — inputSchema from type hints. Confirmed verbatim from the docs: "No JSON Schema. a: int, b: int is the schema." The SDK reads three things from the function:

   • name = the function name (search_books)
   • description = the docstring (the model sees this)
   • arguments = the type hints (query: str, limit: int) The SDK generates the JSON Schema and sends it during tools/list. Type hints are the contract — if a client sends "limit": "ten", the SDK rejects it before the function runs. Optional args = default values (limit: int = 10 → leaves required, gains default: 10). Richer constraints via Annotated[int, Field(ge=1, le=50, description="...")]. Enums via Literal["a", "b"]. Pydantic BaseModel parameter = structured "body" (nested as $defs).

3. Multiple tools / dynamic registration (plugin-registry). The @mcp.tool() decorator is called on the mcp object. A plugin receives mcp and calls @mcp.tool() on it — this is plain Python decorator application, no registration magic. The plugin-registry pattern (D-140):

   # plugins/principles.py
   from mcp.server import MCPServer
   def register(mcp: MCPServer) -> None:
       @mcp.tool()
       def atelier_lookup_principle(domain: str, principle_id: str) -> PrincipleLookup:
           """Look up an Atelier principle by domain + ID."""
           ...
   

   server.py scans plugins/, imports each module, calls register(mcp). Each plugin's @mcp.tool() calls register the tool on the shared mcp object. This is the confirmed dynamic- registration pattern — no add_tool() API is needed; the decorator does it.

4. stdio transport. The landing-page example shows uv run mcp dev server.py (Inspector). For stdio transport (D-135: stdio now), the server runs over stdio via the SDK's run entry point. The v2 server object supports stdio as the default transport. The exact run call is mcp.run() (the SDK handles the transport based on how the process is launched — stdio when invoked by an MCP host over stdio). The README's "no protocol handling" promise means mcp.run() is the only call needed. (HTTP transport is on the same server object — Out of Scope for v1.18, future milestone; the server object is transport-agnostic so adding HTTP later is a transport-only change, confirming D-135.)

5. outputSchema / structured output. Confirmed: the return type annotation IS the output schema. From the Structured Output page: "the return type annotation is the output schema. It's published in tools/list as output_schema." A Pydantic BaseModel return type produces an unwrapped object schema (no result wrapper); a TypedDict or dataclass works identically. The result carries both content (text, for the model) and structured_content (data, for the application). Validation is enforced: whatever the function returns is validated against the schema before it leaves the server — a mismatch is a tool error (not a corrupt result). This is exactly what atelier.validate_against_principles needs: a ValidateResult(BaseModel) return type gives the host a structured violations list while giving the model a JSON-text rendering of the same object. structured_output=False opts out (text-only); we do NOT opt out for the validation tool.

6. listChanged capability / dynamic tool registration. The v2 docs (Tools page + landing page) describe tool registration as declarative (@mcp.tool() at import time). The docs do NOT document a runtime listChanged notification API on the high-level MCPServer. For Nova's use case (plugins loaded once at server startup, not added/removed at runtime), this is fine — all 4 tools are registered before mcp.run(). A future milestone that adds tools at runtime would need the low-level Server (advanced/low-level-server/) for explicit notification control. Conclusion: no listChanged needed for v1.18; the plugin-registry loads at startup, before the stdio loop. Confidence 0.85 (the docs are silent on a high-level listChanged; the low-level server has it, but we use the high-level server).

2.2 Skeleton for mcp/atelier/server.py (P5 basis)

This is the 15-line pattern Nova's server should follow (the basis for P5 implementation):

import importlib, pathlib
from mcp.server import MCPServer

mcp = MCPServer("atelier")  # server name; stdio transport is the default

# Plugin-registry: scan plugins/, import each, call register(mcp).
for p in sorted(pathlib.Path(__file__).parent.glob("plugins/*.py")):
    if p.stem != "__init__": importlib.import_module(f".plugins.{p.stem}", __package__).register(mcp)

@mcp.tool()
def atelier_list_domains() -> list[dict]:
    """List the 19 Atelier domains with P-rule counts + Nova-relevance."""
    return [{"domain": "security", "p_rules": 10, "nova_relevant": True}, ...]

if __name__ == "__main__":
    mcp.run()  # stdio transport (D-135); HTTP-ready on the same object (future)

Notes on the skeleton:

• MCPServer("atelier") — one import, one constructor arg (the name).
• The plugin loop uses importlib + a register(mcp) convention (D-140). Each plugin's register body contains @mcp.tool() calls that register that plugin's tools on the shared mcp object. sorted() makes plugin load order deterministic (audit reproducibility — a plugin load order that changes between runs would break replay).
• The sample tool shows the pattern: @mcp.tool(), type hints ARE the input schema, docstring IS the description, return type IS the output schema. The real atelier_list_domains returns a list[DomainInfo] (a list[BaseModel] → wrapped in {"result": [...]}, per the Structured Output docs).
• mcp.run() — the single entry point; stdio is the default. No transport boilerplate. Adding HTTP later = a transport argument or a different run call on the same object (D-135, Out of Scope for v1.18).
• The vendored Atelier snapshot (mcp/atelier/vendor/) is read by the plugin tool functions (not shown in the skeleton); the plugins load the markdown files lazily on first tool call and cache the parsed structure in module-level dicts (C8 Economy — don't re-parse the matrix on every lookup).

---

3. Submission-Readiness Gap Analysis

3.1 contract.schema.json defines SHAPE, not the readiness gate

Confirmed by reading /root/acdl/schemas/contract.schema.json (51 lines). The schema defines the contract shape only:

• required: ["id", "name", "environment", "infrastructure"]
• id: pattern ^[a-z][a-z0-9-]{2,5}$ (3–6 char acronym)
• name: minLength 3
• environment: enum ["dev", "qa", "prod", "dr"]
• infrastructure: map keyed by module name, each entry has version (optional semver) + inputs (required, additionalProperties allowed)
• additionalProperties: false (top-level + per-module)

What it does NOT define (the gap):

• ❌ No tags field (the 5 required Nova tags per D-054)
• ❌ No per-env mandatory metadata (the W3.E table: dev=stack+environment; qa+=e2eSuite+loadTest; prod+=runbook+dashboard+oncall; dr+=drDrillRef)
• ❌ No policyPreconditions field (declared policy expectations)
• ❌ No profile field (developer | agentic; agentic requires naturalLanguageIntent, confidenceAtSubmission, agentTrace)
• ❌ No appSource field (repo + ref pointer for runtime fetch)
• ❌ No contractId field at the top level (the ingestor payload has contractId in the Lambda envelope, but the contract blob itself does not — the readiness schema promotes it to a required field per REQ-217)

The schema's own description confirms this is the shape: "A consumer contract declares intent: which infrastructure to deploy, in which environment, with which inputs." It is the intent shape, not the ready-to-start gate.

3.2 The readiness schema is a SUPERSET gate ABOVE contract-schema validity

Confirmed by PROJECT.md (lines 635–643, the v1.18 scope statement) and REQ-217. The relationship:

contract.schema.json  (SHAPE — id/name/environment/infrastructure)
        ▲
        │  references but does NOT redefine contract fields
        │
submission-readiness.schema.json  (GATE — superset above shape validity)
        = contract-shape-valid  (delegate to contract.schema.json)
        + tags                  (5 required Nova tags, D-054)
        + per-env mandatory     (W3.E table)
        + policyPreconditions   (declared policy expectations)
        + profile               (developer | agentic + agentic markers)
        + appSource             (repo + ref pointer)
        + contractId            (non-empty, promoted to required)

PROJECT.md hard constraint (line 674–676): "The submission-readiness schema is a superset gate above contract.schema.json, NOT a duplicate — it references but does not redefine contract fields."

This means submission-readiness.schema.json uses $ref to contract.schema.json for the contract shape (or validates the contract blob against it as a first step), then adds the gate fields alongside it. The validator (REQ-218) calls contract.schema.json validation first (the existing _validate_contract_schema in the ingestor), then the readiness checks. This is a two-layer gate, not a merged schema.

3.3 Fields the new schemas/submission-readiness.schema.json must add

Per REQ-217 + W3.E (PROJECT.md line 888) + D-054 (tagging standard):

Field	Type	Required	Source / rule
contractId	string (non-empty)	YES	REQ-217. Promoted from the Lambda envelope to a contract-level required field.
environment	enum dev/qa/prod/dr	YES	Already in contract.schema.json; the readiness schema references it (does not redefine) and uses it to select the per-env mandatory set.
tags	object	YES	D-054 / schemas/tagging-standard.json. Required keys: nova:owner, nova:contract, nova:environment, nova:cost-center (nova:ref optional). The readiness schema references tagging-standard.json's required_tags shape.
policyPreconditions	object (map of string→boolean/string)	YES	REQ-217. Declared policy expectations the platform will enforce (e.g. {"public-ingress": false}).
profile	enum developer | agentic	YES	REQ-217 / W3.E.
profile == agentic → requires: naturalLanguageIntent (string), confidenceAtSubmission (number 0–1), agentTrace (object/string)	per W3.E	conditional	REQ-22 / W3.E. These are "optional everywhere" per W3.E (a developer profile omits them) but required when profile is agentic.
appSource	object {repo: string, ref: string}	YES	REQ-217. Repo + ref pointer for runtime fetch.
Per-env mandatory (W3.E):
dev	stack + environment	YES	W3.E. (These are the base contract fields; the readiness schema enforces their presence for dev.)
qa adds	validation.e2eSuite + validation.loadTest	YES for qa	W3.E.
prod adds	runbook + dashboard + oncall	YES for prod	W3.E.
dr adds	drDrillRef	YES for dr	W3.E.
inputs map	object	optional everywhere	W3.E ("inputs map is always optional").

The per-env mandatory table is a conditional allOf in JSON Schema draft 2020-12: an if/then keyed on environment that requires the env-specific fields. The reason code ENV_MISSING_MANDATORY:<env>:<field> (REQ-218) maps directly to this conditional check.

3.4 How contract_ingestor.py currently works (P3 wiring point)

Read /root/acdl/core/lambda/contract_ingestor.py (502 lines). The current entry point + dispatch:

• Entry point: lambda_handler(event, context) (line 460). Parses event["body"] (JSON string) → payload. Reads action (default "submit_contract").
• Identity validation: _validate_caller_identity(event, payload) (line 293) — checks IAM caller ARN, consumerRepo format, contractId format (regex ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$), environment enum (from core/environments/*.json, P10/REQ-174), error-length cap. Fails closed if no IAM identity (P10).
• Action dispatch (line 475):
  • submit_contract → _submit_contract(payload) (line 135): validates required fields (consumerRepo, contractId, contract, environment), size-caps the contract blob (256 KB, P11/REQ-175), calls _validate_contract_schema(contract) (line 57 — validates against schemas/contract.schema.json via jsonschema; no-op if schema/jsonschema unavailable; bypassed by NOVA_LAMBDA_LOCAL_BYPASS), writes to DynamoDB nova-contracts (PK consumerRepo, SK contractId#submittedAt).
  • report_error → _report_error (D-055, GitHub/Gitea issue).
  • validate_change_request → _validate_change_request (REQ-93).
  • onboard_consumer → _onboard_consumer (P18/REQ-182, validates against schemas/onboarding.schema.json).
• Error mapping: ValueError → 400 (or 401 for identity failures); other Exception → 500 (defensive top-level guard, pragma: no cover).

Where P3 adds --check-readiness (D-133):

The ingestor is a Lambda handler, not a CLI. D-133 says the validator is "invoked as contract_ingestor.py --check-readiness subcommand" — this is a local CLI mode for citizen-developer pre-flight validation, NOT a new Lambda action. The implementation pattern (confirmed by the existing code structure):

1. Add a if __name__ == "__main__": block at the bottom of contract_ingestor.py that parses sys.argv (argparse or manual). The existing file has NO __main__ block (it's Lambda-only); P3 adds one.
2. The --check-readiness subcommand loads a contract file (or reads stdin), validates it against schemas/submission-readiness.schema.json (REQ-217) via the new core/submission_readiness.py validator (REQ-218), and prints a structured ReadinessResult (pass/fail per check + reason codes).
3. The validator (core/submission_readiness.py) calls _validate_contract_schema(contract) first (reusing the existing function — the shape gate), then runs the readiness checks (tags, per-env mandatory, policyPreconditions, profile:agentic markers, appSource).
4. On fail → the CLI exits non-zero with a citizen-developer-facing error (not a stack trace) — REQ-218. On pass → proceeds to existing ingestion (in the Lambda path, the readiness check would be a pre-write gate; in the CLI path, it's a pre-flight check that returns 0).

Reason codes (REQ-218, the validator's return vocabulary): MISSING_TAGS, ENV_MISSING_MANDATORY:<env>:<field>, AGENTIC_MISSING_INTENT, MISSING_APP_SOURCE, POLICY_PRECONDITION_MISSING. Each maps to a failed check in the schema's conditional allOf. The validator returns a list of these (not a single error) so a citizen developer sees all gaps at once, not one-at-a-time (C2 Clarity — the reader understands the full scope of fixes needed).

3.5 Gitea release-asset API endpoint (for scripts/attach_release_asset.py)

Confirmed from the existing scripts/ship_phase.sh (line 38) which already uses the Gitea releases API, and from the Gitea API swagger (https://gitea.com/api/swagger, fetched — the OpenAPI/Swagger JSON is published there; the endpoint is standard Gitea).

Release creation (existing pattern, ship_phase.sh line 38):

POST https://git.cloudinit.dev/api/v1/repos/continuous-intelligence/acdl/releases
Authorization: token <NOVA_GITEA_TOKEN>
Content-Type: application/json
Body: {"tag_name": "...", "name": "...", "body": "..."}
Response: {"id": <release_id>, ...}

Release asset attachment (the new endpoint, for attach_release_asset.py):

POST https://git.cloudinit.dev/api/v1/repos/continuous-intelligence/acdl/releases/{release_id}/assets
Authorization: token <NOVA_GITEA_TOKEN>
Content-Type: multipart/form-data
Form fields:
  name       = <filename, e.g. "nova-no-humans-platform.pptx">
  attachment = <the file, multipart>
Response: {"id": <asset_id>, "name": "...", "size": ..., "download_count": 0, ...}

The Gitea API endpoint is POST /api/v1/repos/{owner}/{repo}/releases/{id}/assets with a multipart form containing name (the display filename) and attachment (the file binary). The {id} is the numeric release ID returned by the release-creation call (the d.get('id') in ship_phase.sh line 40). attach_release_asset.py (REQ-228) takes a release tag (or ID) + a file path, resolves the tag → release ID (GET /api/v1/repos/.../releases/tags/{tag} if only the tag is known), then POSTs the multipart form. The token comes from .env.secrets (NOVA_GITEA_TOKEN, same as ship_phase.sh line 35).

Implementation note: urllib (used throughout contract_ingestor.py and ship_phase.sh) does not natively produce multipart form bodies — attach_release_asset.py must either (a) construct the multipart boundary + body manually (the standard urllib pattern), or (b) use requests if available. The repo's convention is stdlib-only (urllib, no requests dependency in the ingestor), so the script should construct the multipart body manually (C3 Simplicity — no new dependency for one script; C8 Economy — stdlib is sufficient). A ~30-line multipart_encode(fields, files) helper is the standard stdlib pattern.

---

4. Marp PPTX Theme Fidelity

4.1 The PPTX export path and inline-CSS survival

Source: the Marp CLI README (https://github.com/marp-team/marp-cli, fetched) + the existing docs/presentations/README.md (lines 93–105)

• the v1.9.2 theme commit ae0cb58 (verified via git show).

Confirmed export command (from docs/presentations/README.md line 96–99):

CHROME_PATH=/root/.cache/ms-playwright/chromium-1217/chrome-linux64/chrome \
  npx --yes @marp-team/marp-cli@latest --allow-local-files \
  docs/presentations/nova-no-humans-platform-marp.md \
  -o <output-path>.pptx

How PPTX export works (from the Marp CLI README, --pptx section): The default (non-editable) PPTX "consists of pre-rendered background images." Marp renders each slide in a headless browser (Chrome/Chromium via the --browser-path / CHROME_PATH env), captures the rendered slide as a high-resolution image (default scale factor 2x — the README states: "By default, Marp CLI will use 2 as the default scale factor in PPTX"), and embeds those images as full-slide background pictures in the PPTX. Presenter notes are supported; the PPTX opens in PowerPoint, Keynote, Google Slides, LibreOffice Impress.

Inline style: CSS survival — CONFIRMED YES. Because the slides are rasterized in a headless browser, the browser's rendering engine applies the inline style: CSS block (H1/H2 #D6002A, title-slide bg #1B1B1B with 8px #D6002A accent, body text #1B1B1B, blockquote border #D6002A, table headers #F0F0F0, font 'Akkurat Pro' + fallbacks) exactly as it does for HTML export. The CSS is baked into the pixels of each slide image. The PPTX is a sequence of images, not editable PPTX shapes — so there is no "CSS stripping" step. The S&P Global Energy theme survives PPTX export in the standard (non-editable) path.

The current unified deck (docs/presentations/nova-no-humans-platform-marp.md) already has the style: | block in its frontmatter (verified: line 8 style: |, line 2 marp: true, line 3 theme: default). So the S&P theme is already inline; PPTX export will honor it.

Caveat — --pptx-editable (NOT used): The experimental --pptx-editable flag generates editable PPTX (texts/shapes, not images), and the README warns: "If the theme and inline styles are providing complex styles into the slide, --pptx-editable may throw an error or output the incomplete result." Nova does NOT use --pptx-editable (the S&P theme is complex inline CSS); the standard image-based PPTX is the path. REQ-228 specifies --pptx --allow-local-files, not --pptx-editable.

4.2 Fallback (NOT needed, documented for completeness)

If PPTX export ever strips inline CSS (it does NOT in the standard path, per §4.1), the fallback is a Marp custom theme CSS file referenced via --theme <path>:

CHROME_PATH=... npx @marp-team/marp-cli@latest --allow-local-files \
  --theme docs/presentations/assets/sp-theme.css \
  docs/presentations/nova-no-humans-platform-marp.md \
  -o output.pptx

Marp CLI supports custom theme CSS files via --theme <path> (the README's "Use custom theme" section: "A custom theme created by user also can use easily by passing the path of CSS file"). The CSS file would be docs/presentations/assets/sp-theme.css containing the same rules currently in the inline style: block, prefixed with the @theme meta comment (Marpit convention: /* @theme sp-energy */). The deck's frontmatter theme: directive would then be set to the custom theme name instead of default.

Recommendation: do NOT use the fallback. The inline style: block survives the standard PPTX path (rasterized images). The fallback adds a file to maintain in sync with the inline block (a DRY violation — two sources of truth for the S&P colors). REQ-214 restores the S&P theme in the unified deck's inline style: block (the v1.9.2 pattern); the PPTX export uses the same deck file. The S&P colors survive PPTX export via the inline style: block. No --theme flag, no separate CSS file needed. Confidence 0.90 (the only residual risk is a Marp CLI version regression that changes the rasterization path — mitigated by @marp-team/marp-cli@latest pinning in the render script and the PPTX slide-count/media verification step already in docs/presentations/README.md lines 332–340).

4.3 ship_phase.sh release pattern + attach_release_asset.py extension

Confirmed from scripts/ship_phase.sh (read in full, 46 lines):

• Line 38: POST https://git.cloudinit.dev/api/v1/repos/continuous-intelligence/acdl/releases with Authorization: token <NOVA_GITEA_TOKEN> (read from .env.secrets, line 35) + JSON body {"tag_name", "name", "body"} (line 37). The response's id is the release ID (line 40: d.get('id')).
• The script creates the tag, pushes, creates the release, prints release_id: <id> tag: <tag>.

How attach_release_asset.py extends it (REQ-228): attach_release_asset.py is a separate script (not a modification to ship_phase.sh) that runs after the release exists. It takes a release tag (or ID) + a file path, then:

1. Resolve tag → release ID (if only the tag is known): GET /api/v1/repos/continuous-intelligence/acdl/releases/tags/{tag} → the release object's id.
2. Upload the asset: POST /api/v1/repos/continuous-intelligence/acdl/releases/{id}/assets with multipart form (name = filename, attachment = file binary)
   • Authorization: token <NOVA_GITEA_TOKEN> (same .env.secrets source).
3. Print asset_id: <id> release: <tag> file: <name> for the ship log.

The render+attach flow (REQ-228, triggered by any docs/presentations/*-marp.md or docs/presentations/assets/ change, D-142):

render_deck.sh  →  HTML (committed) + PPTX (committed, D-141)
                ↓
attach_release_asset.py  →  PPTX uploaded to the phase's Gitea release

PPTX is a first-class artifact (PROJECT.md line 682–683): committed to git (history) + attached to the release (download) — both always, not optional. This is the D-141 decision (no LFS — the binary is committed directly).

---

5. Assumptions logged (v1.18)

• A1 (0.92): The Atelier v0.3.6 tag is the correct pin. It is the latest release (2026-08-05), the v0.4 milestone release, and the complete matrix state (19 domains, 190 P-rules). -11 commits to main since this release confirms main is a moving target — pinning is required for audit reproducibility (D-136). Risk: a v0.5 lands before P5 ships — mitigated by VERSION.md + update script (deliberate upgrade, not silent drift).
• A2 (0.88): The MCP Python SDK v2 high-level server class is MCPServer (import from mcp.server import MCPServer), NOT FastMCP. The docs (landing page + Tools page) use MCPServer consistently; FastMCP was the v1 name. D-137 (MCP Python SDK v2) resolves to this import. Risk: the v1→v2 rename — if a future SDK patch restores a FastMCP alias, both imports would work, but the v2 canonical name is MCPServer.
• A3 (0.85): mcp.run() starts the stdio transport by default (no explicit transport argument needed for the stdio path). The docs show uv run mcp dev server.py (Inspector) and the "no protocol handling" promise implies mcp.run() is the single entry point. The exact run() signature for stdio vs HTTP is not spelled out on the landing page (it's in the "Running your server" section, not fetched in full); the D-135 decision (stdio now, HTTP-ready on the same object) is consistent with a single run() entry point. P5 implementation should verify the exact run call from the "Running your server" docs page.
• A4 (0.90): The standard (non-editable) PPTX export bakes inline style: CSS into the rasterized slide images. The Marp README states PPTX "consists of pre-rendered background images" — the browser rendering applies the CSS before rasterization. The S&P theme survives PPTX export. The --pptx-editable path (NOT used) is the only path that could strip CSS, and Nova does not use it.
• A5 (0.88): The Gitea release-asset endpoint is POST /api/v1/repos/{owner}/{repo}/releases/{id}/assets with multipart name + attachment. This is the standard Gitea API (the swagger at gitea.com/api/swagger publishes the OpenAPI spec); the existing ship_phase.sh uses the sibling .../releases endpoint, confirming the API root + auth pattern. The {id} is the numeric release ID (resolvable from the tag via GET .../releases/tags/{tag}).
• A6 (0.85): The submission-readiness schema uses JSON Schema draft 2020-12 conditional allOf / if-then for the per-env mandatory table (W3.E). This is the standard pattern for "if environment=qa then require validation.e2eSuite + validation.loadTest." The jsonschema library (already a dependency, used in contract_ingestor.py) supports draft 2020-12 conditionals. The validator (core/submission_readiness.py) may implement the per-env check in Python (clearer reason codes) rather than relying solely on schema conditionals — the schema is the shape, the validator is the gate with the citizen-developer-facing reason codes (REQ-218).
• A7 (0.80): The --check-readiness CLI mode is added as a if __name__ == "__main__": block in contract_ingestor.py (which currently has none — it's Lambda-only). D-133 says "invoked as contract_ingestor.py --check-readiness" — this is a local pre-flight CLI, not a new Lambda action. The validator lives in core/submission_readiness.py (REQ-218); the ingestor dispatches to it. This keeps the Lambda path unchanged (the readiness gate is a pre-write step in _submit_contract only if desired; the CLI path is the citizen-developer pre-flight). Risk: the exact wiring (does the Lambda also gate on readiness, or only the CLI?) is a P3 implementation decision — REQ-218 says "On pass → proceeds to existing contract ingestion," implying the gate is in the submission path, but the CLI mode is the pre-flight surface.
• A8 (0.90): The 9-skill list in REQ-221 is final (no adjustment). The research confirms the 9 Atelier domains map cleanly to the BA.A 5-skill catalog; the 4 "reference-only" domains (Performance, Documentation, Concurrency, AI/ML) are correctly NOT elevated to skills. Adding a 10th skill would break REQ-221's exact list and the BA.A mapping.
• A9 (0.88): The mcp-engineer persona is NOT needed — it folds into backend-engineer. The MCP plugin-registry (D-140) is a Python backend pattern (decorators, type hints, stdio, urllib). The SDK v2 API surface is small and FastAPI/Pydantic-style (already in backend-engineer's range). D-143 logged in PERSONAS.md records this.

---

v1.22 Research — Nova Deck Layout Fix (2026-08-11)

Investigation into the systemic layout/formatting problems in the Nova presentation deck reported as "completely out of whack" after the v1.21 P5 re-render. This research IS the investigation — the findings below are the empirical root-cause analysis that drives the v1.22 requirements (REQ-254..262).

Background — why v1.22 exists

The v1.21 milestone shipped a refined deck (renamed to "Autonomous Cloud Delivery Platform", 4-beat arc, 18 main + 1 appendix slides). The P5 phase re-rendered the HTML + PPTX and added two new mermaid diagrams (platform-pipeline.png, telemetry-live-ops.png). After P5, the user reported that the layout is "completely out of whack" and that "they all have layout issues." This research identifies the root cause and the fix scope.

FINDING 1 — Theme CSS has ZERO section padding (CONFIDENCE: VERY HIGH)

docs/presentations/assets/nova-sp-theme.css line 1 is /* @theme nova-sp */ — a comment, not the @theme directive that Marp uses to register a theme name. The theme does not @import Marp's default theme. Marp's built-in default theme applies section { padding: 56px 64px; }. Because this custom theme neither imports the default nor sets its own padding, the rendered <section> has zero padding.

Verification: grep for padding:56px / padding:64px / padding:96px in the rendered HTML returns zero matches. The only section rules in the rendered HTML are:

• section{width:1280px;height:720px;box-sizing:border-box;overflow:hidden;position:relative;...} (marpit base — no padding)
• section{font-family:...;font-size:22px;color:var(--sp-black);background:var(--sp-white)} (theme — no padding)

Effect: Content is jammed against the slide edges (left/top/right/ bottom all 0px), header/footer chrome overlaps content, and there is no breathing room. This alone makes every slide look "out of whack."

FINDING 2 — overflow:hidden silently clips dense content (CONFIDENCE: VERY HIGH)

The marpit base rule sets overflow:hidden on section. The theme adds no overflow override, no scaling, no shrink-to-fit. Any slide whose content exceeds 720px is clipped with no visual indication. Combined with zero padding, content-dense slides (tables, image+bullets) lose their bottom rows / benefit paragraphs.

Per-slide overflow risk table (available content height ≈ 720px − header(~35px) − footer(~35px) − padding(0px) = ~650px):

#	Slide	Est. height	Fits?	Issue
3	Objectives + Anti-Goals	~780px	NO	Densest text slide; nested list
5	RACI (8-row × 5-col)	~700px	NO	Cell text wraps to 2 lines
6	Pipeline (image + 4 bullets)	~750px	NO	Image + bullets overflow
8	Attestation (10-row × 4-col)	~780px	NO	Description column wraps
9	Telemetry (image + 4 bullets)	~720px	NO	Image + bullets overflow
12	Deferred (8-row table)	~720px	NO	Blocking-work column wraps
15	Quarter-by-Quarter (5-col)	~720px	NO	Wide table, long text
A1	Glossary (13-row × 3-col)	~700px	NO	On title-class (dark bg)
1,4,10,11,13,16,17,18	various	~620px	TIGHT	Cramped with 0 padding
2,7,14	various	~520px	YES	Manageable density

8 of 19 slides overflow; 8 more are cramped.

FINDING 3 — Image aspect-ratio catastrophe on slides 6 & 9 (CONFIDENCE: HIGH)

The two new P5 PNGs have extreme, opposite aspect ratios:

• platform-pipeline.png = 1568×116 (aspect 13.52, ultra-wide/short). The deck uses ![w:1000]. At width=1000px, height = 1000/13.52 = 74px. The max-height:320px rule never engages. The image renders as a 1000×74 thin strip — text in nodes is nearly unreadable, and the 10-node LR flowchart is squashed.

• telemetry-live-ops.png = 1024×1628 (aspect 0.63, tall). The deck uses ![w:900]. At width=900px the natural height would be 1428px — but max-height:320px clamps it, so the image actually renders at ~201×320. The w:900 directive is completely overridden by max-height:320px. The image is tiny and the explicit width is ignored. The .mmd uses flowchart TB (top-bottom) — exactly the failure mode the README (line 168) warns against.

FINDING 4 — Header+footer chrome on every slide (CONFIDENCE: HIGH)

The frontmatter sets both header: and footer: to the full 51-char deck title "Nova — The Autonomous Cloud Delivery Platform" on every slide (including the title slide, which has data-header/data-footer attributes present but _paginate: false only suppresses the page number, not the header/footer). The theme gives header a border-bottom and footer a border-top, each consuming ~30-40px of vertical chrome. With zero section padding, the header text sits at the very top edge and the footer at the very bottom edge, visually colliding with slide content. This reduces the effective content area from 720px to roughly 640-650px on every slide.

FINDING 5 — render_deck.sh produces unthemed output (CONFIDENCE: MEDIUM-HIGH)

scripts/render_deck.sh (line 44) runs marp-cli without --theme, relying on the frontmatter theme: nova-sp. But nova-sp is not a built-in Marp theme — it's a custom CSS file. Marp resolves theme: frontmatter against its built-in theme registry (default, gaia, uncover) and registered custom themes via --theme-set. Without --theme <file> or --theme-set, Marp cannot resolve nova-sp and falls back to the default theme (or errors). The committed HTML was rendered by render_slides.sh (which correctly passes --theme), so the committed artifact is fine — but render_deck.sh is a stale, dangerous script that would produce an unthemed/default-themed deck if anyone ran it. The README (line 201) documents render_slides.sh as canonical; render_deck.sh is not mentioned in the build-commands section.

FINDING 6 — render_slides.sh missing 2x scale + transparent bg (CONFIDENCE: HIGH)

render_slides.sh mermaid invocation (lines 51-55) does NOT pass -s 2 (2x scale) or -b transparent, despite the README (line 193) documenting both as required. This is why platform-pipeline.png is only 1568px wide (1x) instead of 3136px (2x) — the rendered PNGs are lower resolution than the README specifies, contributing to illegibility when scaled.

FINDING 7 — P5 marp-cli version bump (CONFIDENCE: LOW — not the cause)

The P3→P5 HTML diff is 831 changed lines, but the theme CSS portion is byte-identical (verified: font-size:22px, max-height:320px, marpit-root-font-size:22px, --sp-red:#D6002A all match; sp-red appears exactly once in both). The large diff is:

• (a) marp-cli boilerplate (bespoke-marp presenter/overview/transition CSS) changed due to a marp-cli version bump (neither script pins a version — both use @latest), and
• (b) content changes: title "No-Humans Infrastructure Platform" → "Autonomous Cloud Delivery Platform", footer "Act %{page}/5 — v1.20" → deck title, slide count 20 → 19.

The version bump did not alter the slide layout engine or the theme rules. This is not the regression source. The layout problems are inherent to the theme CSS (zero padding, no overflow handling, blunt image rule) which has been unchanged. P5 made the content denser (new diagrams with extreme aspect ratios, longer deck-title header/footer) which made the pre-existing theme flaws more visible.

FINDING 8 — Test coverage gaps (CONFIDENCE: VERY HIGH)

tests/test_slides_pipeline.py (268 lines) checks static file properties only:

• Theme CSS file exists and contains #D6002A / #1B1B1B
• Frontmatter references nova-sp, not default
• render_slides.sh exists, is executable, invokes mermaid-cli + marp-cli
• Every .mmd has a .png
• No maturity badges, no version in footer, slide count = 18+1
• No D-###/REQ-###/internal .py paths in slides

What is NOT tested (the gaps that let layout regressions through):

1. NO rendered-dimension / overflow test — no test renders the HTML and checks that each slide's content height ≤ 720px.
2. NO theme-CSS structural test — no test asserts section has padding, that overflow is handled, or that img rules don't conflict with w:/h: directives.
3. NO image aspect-ratio / legibility test — no test checks that PNG dimensions are reasonable for a 16:9 slide.
4. NO render-script theme-flag test — no test asserts render_deck.sh passes --theme (it doesn't), so the broken script passes CI.
5. NO rendered-HTML structural assertion — no test parses the committed HTML to verify the theme is actually embedded.
6. NO mermaid render-scale test — no test verifies PNGs are 2x scale.

Conclusion: A layout regression — including the current zero-padding, image-clamping, and table-overflow problems — would pass every existing test. This is why the user's "completely out of whack" report was not caught.

Theme CSS gaps (summary)

1. NO padding on section (lines 21-26 set font/color/bg only).
2. NO overflow handling on section.
3. NO @import of a base theme (line 1 is a comment, not @theme).
4. NO rule for the h2 + bold-lead-paragraph pattern (default <p> margins waste ~44px each).
5. Table cell padding 6px 10px too generous for 10-13 row tables.
6. img { max-height: 320px } is a blunt instrument that breaks w: directives on tall images and does nothing for ultra-wide images.
7. Header/footer have no padding/margin — collide with content at 0 section padding.
8. section.title does not suppress header/footer.
9. NO rule for ol (only ul/li styled).
10. NO @media print overrides for PPTX export fidelity.

Assumptions logged (v1.22)

• A1 (0.95): The theme CSS is the primary root cause. Adding section { padding: 48px 56px 40px; } alone would fix the "jammed against edges" look on all 19 slides. Confidence grounded in the grep verification (zero padding matches in rendered HTML).
• A2 (0.9): The P5 re-render is NOT a regression — the theme CSS is byte-identical P3→P5. P5's denser content (new diagrams, longer header/footer) made pre-existing flaws visible. Grounded in the byte-level diff comparison.
• A3 (0.9): render_deck.sh should be deleted, not fixed. The README already documents render_slides.sh as canonical; keeping a second broken script is a footgun. Grounded in the README build- commands section (line 201) which does not mention render_deck.sh.
• A4 (0.85): Splitting slides 3 and 8 (18 → 20 main) is preferable to trimming content, because the content is leadership-relevant and should not be lost. The slide-count test + README convention are updated to match. Grounded in the overflow estimates (slides 3 and 8 are the densest at ~780px).
• A5 (0.8): Pinning marp-cli/mermaid-cli versions is necessary to prevent uncontrolled boilerplate-CSS drift. The exact pinned versions will be determined during P2 execution by testing which version produces stable output in this environment.

Decisions surfaced (research → bound in CLARIFY)

All 5 CLARIFY decisions are grounded in these findings:

• Comprehensive scope (FINDINGS 1-8 span 4 layers)
• Full pipeline (new milestone, complete audit trail)
• Re-layout to LR (FINDING 3 — TB produced 0.63 aspect)
• Delete render_deck.sh (FINDING 5 — stale, unthemed)
• Split slides 3+8 (FINDING 2 — densest overflow)