docs(P4): Atelier skills mapping — 9 skill files + index + BA.A extension (REQ-221, REQ-222)

REQ-221: skills/ directory with 9 Atelier-derived skill files mapped to the BA.A citizen-developer catalog: api, security, data, testing, observability, errors, devops, infrastructure-as-code, compliance. Each names the Atelier source path, distills first-principles to the citizen-dev-relevant subset, links to agent-checklist triggers, maps to BA.A 5-skill catalog. REQ-222: docs/skills.md index (9-skill table, Atelier provenance, 8 core principles C1-C8, consumption instructions, reference-only domains, excluded domains). PROJECT.md BA.A decision extended with the Atelier-derived skill catalog reference. ---ci--- project: acdl phase: 4 milestone: v1.18 status: execute requirements: covered: [REQ-221, REQ-222] partial: [] ---/ci---
2026-08-06 15:11:12 +00:00
parent 6ffcbe8283
commit 2c08c778a9
11 changed files with 441 additions and 1 deletions
@@ -980,7 +980,7 @@ or user-directed scope). New v1.7 decisions:
 | W1.A | AI-refinement trigger | **Accept recommendation.** Joint condition: N ≥ 50 consecutive changes with zero rollbacks AND no L1/L2 incident in last 6 months AND Infra & Ops unilateral override. |
 | W1.B | Multi-stack edge case rule | **Accept recommendation.** Permitted only for (a) DR-region mirror, (b) time-boxed experimental stack with TTL ≤ 30d, (c) explicit Infra & Ops approval with `multiStack.justification`. |
 | W2.A | Tag mutability for prod | **Accept recommendation (Path B).** Tag for dev/qa, SHA for prod. Platform CLI resolves tag→SHA for prod-bound workflows. Justified by the "Audit truth lives outside the repository" bet. |
-| BA.A | Initial L3B skill catalog | **Accept recommendation.** 5 skills: web API, worker, scheduled job, static asset, basic observability bootstrap. Addition criteria: (a) reviewable for sensitive data, (b) expressible as a single contract submission, (c) documented use case. |
+| BA.A | Initial L3B skill catalog | **Accept recommendation.** 5 skills: web API, worker, scheduled job, static asset, basic observability bootstrap. Addition criteria: (a) reviewable for sensitive data, (b) expressible as a single contract submission, (c) documented use case. **Extended v1.18 (REQ-221/222):** the BA.A 5-skill catalog is extended with 9 Atelier-derived production-grade engineering skills under `skills/` (api, security, data, testing, observability, errors, devops, infrastructure-as-code, compliance), indexed by `docs/skills.md`. The Atelier skills extend, not replace, the BA.A catalog. |
 | W3.D | L1/L2 standard versioning | **Decided.** Semver: interface → MAJOR, behavior → MINOR, lifecycle → PATCH (same as the v1.0 demo D-rule, lifted to the real platform). Pin model: L2 contracts pin L1 by `name@semver`; the resolver picks the highest compatible. Evolution: MAJOR bumps require a new registry entry (immutable publication); old entry enters a 12-month deprecation window. |
 | W3.E | Schema mandatory vs optional inputs | **Decided.** Per-env mandatory table: dev requires `stack` + `environment`; qa adds `validation.e2eSuite` + `validation.loadTest`; prod adds `runbook` + `dashboard` + `oncall`; dr adds `drDrillRef`. `inputs` map is always optional. `profile: agentic` fields (`naturalLanguageIntent`, `confidenceAtSubmission`, `agentTrace`) optional everywhere. |
 | BA.B | Confidence threshold tuning | **Decided.** Starting thresholds frozen for v1. Tuning begins in v1.2: track FP/FN per environment quarterly; override authority = Infra & Ops + SRE joint sign-off; any override is itself a confidence-event in the audit stream. |
@@ -0,0 +1,88 @@
 # Skills — Production-Grade Guidance for the Citizen Developer
 > **Source of truth (v1.18, REQ-221, REQ-222).** The Nova skill catalog
 > extends the BA.A 5-skill catalog (web API, worker, scheduled job, static
 > asset, basic observability bootstrap) with Atelier-derived production-
 > grade engineering principles. Each skill is a markdown file under
 > `skills/` keyed to an Atelier domain path.
 ## How the Citizen Developer's AI Agent Consumes Skills
 1. **Before completing a task**, read the relevant skill file(s) that
   match the task's domain.
 2. **Run `review/agent-checklist.md`** (from Atelier) before finishing —
   the checklist items are the gate between "the code is written" and
   "the task is done."
 3. **Use the Atelier MCP server** (`mcp/atelier/server.py`, P5) for
   agentic validation — the `atelier.validate_against_principles` tool
   catches correctness/clarity/simplicity/observability gaps that
   deterministic scanners (Wiz, Checkmarx, Mend) cannot.
 ## The 9 Skills
 | Skill | Atelier Source | Core Principles | BA.A Mapping |
 |---|---|---|---|
 | [`api.md`](../skills/api.md) | `domains/api/` | C1, C2, C6 | web API |
 | [`security.md`](../skills/security.md) | `domains/security/` | C1 | cross-cutting (all 5) |
 | [`data.md`](../skills/data.md) | `domains/data/` | C1, C4, C6 | web API, worker, scheduled job |
 | [`testing.md`](../skills/testing.md) | `domains/testing/` | C1, C5 | UAT (citizen-dev RACI) |
 | [`observability.md`](../skills/observability.md) | `domains/observability/` | C7 | basic observability bootstrap |
 | [`errors.md`](../skills/errors.md) | `domains/errors/` | C1, C7 | web API, worker, scheduled job |
 | [`devops.md`](../skills/devops.md) | `domains/devops/` | C5, C7, C8 | scheduled job, worker |
 | [`infrastructure-as-code.md`](../skills/infrastructure-as-code.md) | `domains/infrastructure-as-code/` | C1, C5, C8 | static asset |
 | [`compliance.md`](../skills/compliance.md) | `domains/compliance/` | C1, C5 | cross-cutting (all 5) |
 ## Atelier Provenance
 The skills are derived from [Atelier](https://git.cloudinit.dev/coreci/atelier)
 — a first-principles docs-as-code engineering framework with 8 core
 principles (C1–C8) and 19 domains, each with 10 derived P-rules. The
 skills distill the citizen-developer-relevant subset of each domain's
 first-principles, link to the agent-checklist triggers, and map to the
 existing BA.A catalog.
 Atelier is vendored under `mcp/atelier/vendor/` (pinned tag, D-136) for
 audit reproducibility — an agentic validation result is replayable
 against the exact principles that produced it.
 ## The 8 Core Principles (from Atelier)
 | # | Principle | One-line |
 |---|---|---|
 | C1 | Correctness | The system does what it is supposed to do, and nothing else. |
 | C2 | Clarity | The intent of the code is obvious to its reader. |
 | C3 | Simplicity | The solution is as simple as possible, and no simpler. |
 | C4 | Locality | Decisions and their consequences live near each other. |
 | C5 | Reversibility | Every decision can be undone, and the cost of undoing is known. |
 | C6 | Composability | Parts combine into wholes, and the parts are reusable. |
 | C7 | Observability | The system's behavior is visible to those who must understand it. |
 | C8 | Economy | The system uses no more resources than the task requires. |
 Precedence: C1 > C2 > C3 > C4 > C5 > C6 > C7 > C8. Correctness is never
 sacrificed.
 ## Reference-Only Domains (cited inside skills, not elevated to skill files)
 These 4 Atelier domains are relevant to a citizen developer but are cited
 inside the 9 skills above rather than getting their own skill file:
 - **Performance** (`domains/performance/`) — cited in `observability.md` +
  `devops.md` (bounded operations, timeouts, N+1)
 - **Documentation** (`domains/documentation/`) — the runbook requirement
  (W3.E prod mandatory) is the documentation skill in practice
 - **Concurrency** (`domains/concurrency/`) — cited in `errors.md` +
  `devops.md` (bounded queues, cancellation, timeout)
 - **AI/ML** (`domains/ai-ml/`) — scope: engineering discipline (data
  versioning, evaluation, serving, drift), not algorithm design
 ## Excluded Domains (not relevant to Nova citizen developer)
 6 Atelier domains are excluded from the Nova skill catalog (not relevant
 to a citizen developer building on Nova's infrastructure platform):
 - UI/UX — Nova has no frontend (frontend-engineer deactivated, PERSONAS.md)
 - Kubernetes — Nova is AWS-only this milestone (NORTH_STAR Non-Goal #7)
 - GitOps + Operators — future roadmap (no GitOps reconciler today)
 - Edge — not in scope (Nova is cloud, not edge)
 - Messaging — not in scope (Nova deploys infra, not message brokers)
 - i18n — application-level concern, not infrastructure
@@ -0,0 +1,40 @@
 # Skill: API Design
 > **Atelier source:** `domains/api/` (first-principles + rest, graphql,
 > versioning, error-responses, pagination)
 > **Core principles:** C1 Correctness, C2 Clarity, C6 Composability
 > **BA.A mapping:** web API skill
 > **Consumer:** read this before authoring an API service contract.
 ## First Principles (citizen-developer-relevant subset)
 - **Endpoints are nouns, plural, lowercase-hyphenated.** (`/customers`,
  not `/getCustomer`)
 - **Status codes are correct.** 200/201/204/4xx/5xx per semantics.
 - **Errors are structured.** Every error response carries `code`,
  `message`, `request_id` — not a stack trace.
 - **Input is validated against a schema.** The contract's
  `infrastructure` map is validated at resolution time; the API must
  validate its own request bodies.
 - **Auth is required by default.** No unauthenticated endpoints unless
  explicitly declared in `policyPreconditions`.
 ## Agent-Checklist Triggers
 Before completing an API task, run these (from
 `review/agent-checklist.md` § API):
 - Endpoints are nouns, plural, lowercase-hyphenated
 - Status codes are correct per semantics
 - Errors are structured (code, message, request_id)
 - Input is validated against a schema
 - Auth is required by default
 ## How Nova Uses This
 The submission-readiness gate (`schemas/submission-readiness.schema.json`)
 checks that your contract declares `policyPreconditions`. The API skill
 tells you what the platform expects your application to enforce on its
 own surface (request validation, structured errors, auth). Nova does
 not author your API; it deploys it. The API skill ensures the
 application you deploy meets production-grade standards.
@@ -0,0 +1,49 @@
 # Skill: Compliance
 > **Atelier source:** `domains/compliance/` (first-principles + audit-logs,
 > data-retention, policy-as-code, evidence)
 > **Core principles:** C1 Correctness, C5 Reversibility
 > **BA.A mapping:** cross-cutting (all 5 skills)
 > **Consumer:** read this before any regulated-environment submission.
 ## First Principles (citizen-developer-relevant subset)
 - **Audit records are immutable once written.** Deletion/mutation is
  itself an auditable incident. Nova's Decision Ledger (SQLite
  hash-chain, v1.17; S3 Object Lock + JWS future) enforces this.
 - **The set of auditable actions is defined a priori.** "We forgot to log
  it" is a violation. The submission-readiness gate's
  `policyPreconditions` declare what the platform will audit.
 - **Policy violations block before the action.** Checkov runs pre-apply;
  the confidence signal gates; the HITL gate stops. Compliance is
  admission-time, not audit-time.
 - **Evidence gathered as a byproduct of operation.** Not assembled
  manually at audit time. Every pipeline run emits events into the
  Decision Ledger + the evidence stream.
 - **Every logged action traces to an authenticated principal.** No
  shared/generic identities. The HITL approver identity (D-042) is
  recorded with every prod/dr promotion.
 ## Agent-Checklist Triggers (§ Compliance)
 - Audit records are immutable once written; deletion/mutation is itself
  auditable (P1)
 - The set of auditable actions is defined a priori (P2)
 - Policy violations block before the action (admission/CI/CD-time) (P5)
 - Evidence gathered as a byproduct of operation, not assembled manually
  (P6)
 - Every logged action traces to an authenticated principal; no
  shared/generic identities (P7)
 ## How Nova Uses This
 Nova's compliance posture is framework-agnostic (D-024 in Atelier; the
 platform lists GDPR, SOX, SOC2, DORA — not any single framework). The
 compliance skill tells you what the platform enforces (immutable audit,
 pre-apply policy, evidence byproduct, authenticated principals) and what
 your application must enforce (the same standards on its own surface).
 The submission-readiness gate ensures your contract declares
 `policyPreconditions`; the compliance skill ensures your application
 respects them. This is the RACI compliance-standard equivalence made
 concrete: regardless of upstream source (AI agent, SDLC, dev platform),
 the same compliance standards apply to every submission.
@@ -0,0 +1,34 @@
 # Skill: Data
 > **Atelier source:** `domains/data/` (first-principles + schema-design,
 > migrations, indexing)
 > **Core principles:** C1 Correctness, C4 Locality, C6 Composability
 > **BA.A mapping:** web API, worker, scheduled job
 > **Consumer:** read this before authoring a service with a database.
 ## First Principles (citizen-developer-relevant subset)
 - **Schema reflects the domain, not the application.** Tables model
  real-world entities, not ORM classes.
 - **Constraints are in the schema.** NOT NULL, UNIQUE, FK — the database
  enforces integrity, not the application.
 - **Migration has an `up` and a `down`.** Every migration is reversible.
 - **Types are domain-accurate.** UUID for IDs, TIMESTAMPTZ for timestamps,
  DECIMAL for money — not string/integer/everything.
 - **No `SELECT *`; no N+1.** Explicit columns; eager-load relations.
 ## Agent-Checklist Triggers (§ Data)
 - Schema reflects the domain (not the application)
 - Constraints are in the schema (NOT NULL, UNIQUE, FK)
 - Migration has an `up` and a `down`
 - Types are domain-accurate (UUID, TIMESTAMPTZ, DECIMAL for money)
 - No `SELECT *`; no N+1
 ## How Nova Uses This
 Nova deploys your infrastructure (RDS, DynamoDB) but does not author your
 schema. The data skill ensures the schema you bring meets production-grade
 standards. The submission-readiness gate checks that your contract declares
 the infrastructure; the data skill checks that the application running on
 that infrastructure uses the database correctly.
@@ -0,0 +1,37 @@
 # Skill: DevOps
 > **Atelier source:** `domains/devops/` (first-principles + ci-cd,
 > environments)
 > **Core principles:** C5 Reversibility, C7 Observability, C8 Economy
 > **BA.A mapping:** scheduled job, worker
 > **Consumer:** read this before any deployment.
 ## First Principles (citizen-developer-relevant subset)
 - **The pipeline is the process.** No manual steps. Every change flows
  through the same pipeline: contract → resolver → plan → policy →
  confidence → (HITL gate for qa/prod/dr) → apply → evidence.
 - **Rollback path is known.** Every deployment has a documented rollback.
  Terraform state is the rollback mechanism; the pipeline replans to the
  prior state.
 - **Config is in code, not on the server.** Environment variables, SSM
  parameters, secrets — all declared, versioned, and reviewable. No
  hand-configured server state.
 - **Environments are parity.** dev = prod modulo data. The same contract
  deploys to all environments; only the environment field changes.
 ## Agent-Checklist Triggers (§ DevOps)
 - The pipeline is the process (no manual steps)
 - Rollback path is known
 - Config is in code, not on the server
 - Environments are parity (dev = prod modulo data)
 ## How Nova Uses This
 Nova IS the pipeline. The citizen developer's contract declares intent;
 Nova provides the process. The DevOps skill tells you what the platform
 expects from your submission: no manual steps (everything flows through
 the contract), a known rollback (Terraform state), config in code (SSM
 SecureString, not hand-configured servers), and environment parity (one
 contract, four environments).
@@ -0,0 +1,34 @@
 # Skill: Errors
 > **Atelier source:** `domains/errors/` (first-principles + patterns)
 > **Core principles:** C1 Correctness, C7 Observability
 > **BA.A mapping:** web API, worker, scheduled job
 > **Consumer:** read this before authoring error handling.
 ## First Principles (citizen-developer-relevant subset)
 - **Errors are not swallowed silently.** A bare `except: pass` is a bug.
  Every caught error is either handled, re-raised, or logged with context.
 - **Errors are specific.** Not `raise Exception("something went wrong")`
  — a named exception with the what/where/why.
 - **Errors preserve context.** The error carries the request ID, the
  user, the action — enough to debug without reproducing.
 - **Recovery is attempted when possible; fail fast when not.** Retry
  transient errors with backoff; fail fast on invariant violations.
 ## Agent-Checklist Triggers (§ Errors)
 - Errors are not swallowed silently
 - Errors are specific (not generic "something went wrong")
 - Errors preserve context (where, when, why, what)
 - Recovery is attempted when possible; fail fast when not
 ## How Nova Uses This
 Nova's confidence signal (D-040) uses error events as one of its 6 inputs.
 The error skill ensures your application's errors are structured enough to
 feed the signal: specific error types, preserved context, no silent
 swallows. The platform's `report_error` Lambda action (D-055) creates a
 GitHub issue on the platform repo when the pipeline fails — your
 application errors should be structured enough to flow through the same
 path.
@@ -0,0 +1,41 @@
 # Skill: Infrastructure as Code
 > **Atelier source:** `domains/infrastructure-as-code/` (first-principles +
 > terraform, opentofu, state, modules)
 > **Core principles:** C1 Correctness, C5 Reversibility, C8 Economy
 > **BA.A mapping:** static asset
 > **Consumer:** read this before authoring a contract that declares
 > infrastructure.
 ## First Principles (citizen-developer-relevant subset)
 - **Configuration is declarative, not scripted.** The contract declares
  what; Terraform reconciles how. No imperative scripts in the contract.
 - **Provider versions are pinned, never `latest`.** The contract's
  infrastructure map may pin module versions (semver); the platform pins
  provider versions.
 - **State is remote with locking; never committed.** Nova manages state
  in S3 + DynamoDB; the citizen developer never touches state files.
 - **`plan` is reviewed before every `apply`.** The confidence signal
  gates the apply; the HITL gate (qa/prod/dr) requires human attestation
  before the apply proceeds.
 - **No secrets in HCL; secrets via providers/stores.** Secrets live in
  SSM SecureString / Secrets Manager, not in the contract or HCL.
 ## Agent-Checklist Triggers (§ Infrastructure as Code)
 - Configuration is declarative, not scripted (P1)
 - Provider versions are pinned, never `latest` (P5)
 - State is remote with locking; never committed (P3, P8)
 - `plan` is reviewed before every `apply` (P4)
 - No secrets in HCL; secrets via providers/stores (P10)
 ## How Nova Uses This
 Nova IS the infrastructure-as-code platform. The citizen developer
 declares intent in the contract; Nova's adapter (stateless assembler,
 v1.11) translates to Terraform modules; the pipeline runs plan → policy →
 confidence → (HITL) → apply. The IaC skill tells you what the platform
 expects from your contract: declarative inputs (not scripts), pinned
 versions (not `latest`), no secrets in the contract (secrets via SSM),
 and acceptance that the platform owns state + the apply path.
@@ -0,0 +1,38 @@
 # Skill: Observability
 > **Atelier source:** `domains/observability/` (first-principles + logging,
 > metrics, tracing)
 > **Core principles:** C7 Observability
 > **BA.A mapping:** basic observability bootstrap
 > **Consumer:** read this before any production submission (W3.E requires
 > `dashboard` + `oncall` for prod).
 ## First Principles (citizen-developer-relevant subset)
 - **Logs are structured.** JSON with fields, not free-form text. Every
  log line carries a timestamp, level, message, and context fields.
 - **Every request has a correlation ID.** A request ID propagates from
  ingress through every downstream call. Logs, metrics, and traces share
  the same ID.
 - **No high-cardinality labels in metrics.** User IDs, request IDs, and
  other unbounded values go in logs/traces, not metric labels.
 - **Alerts have runbooks.** Every alert links to a runbook
  (`runbook` field in the submission, W3.E prod mandatory) that explains
  what to do when it fires.
 ## Agent-Checklist Triggers (§ Observability)
 - Logs are structured (JSON, fields)
 - Every request has a correlation ID
 - No high-cardinality labels in metrics
 - Alerts have runbooks
 ## How Nova Uses This
 The W3.E per-env mandatory table requires `runbook` + `dashboard` +
 `oncall` for `prod` submissions — the submission-readiness gate enforces
 this. The observability skill tells you what those artifacts must contain:
 structured logs, correlation IDs, bounded metric labels, and runbook-linked
 alerts. Nova provides the infrastructure (CloudWatch, the uptime
 monitor); you provide the application-level observability (structured
 logs, dashboards, runbooks).
@@ -0,0 +1,42 @@
 # Skill: Security
 > **Atelier source:** `domains/security/` (first-principles +
 > authentication, authorization, input-validation, secrets, supply-chain)
 > **Core principles:** C1 Correctness (security is correctness)
 > **BA.A mapping:** cross-cutting (all 5 skills)
 > **Consumer:** read this before any production submission.
 ## First Principles (citizen-developer-relevant subset)
 - **No secrets in code, logs, URLs, or error messages.** Secrets live in
  the platform's secret store (SSM SecureString, Secrets Manager), not
  your application repo.
 - **Input is validated at the boundary.** Every external input (HTTP
  body, query, header, file) is validated against a schema before
  processing.
 - **Output is encoded for its context.** HTML escaping, URL encoding,
  SQL parameterization — context-appropriate, not a blanket escape.
 - **Crypto uses vetted libraries.** No MD5/SHA1 for security. Use
  bcrypt/argon2 for passwords, AES-GCM for encryption.
 - **Authorization is checked, not assumed.** Every request verifies the
  caller's authority to perform the action.
 ## Agent-Checklist Triggers (§ Security)
 - No secrets in code, logs, URLs, or error messages
 - Input is validated at the boundary
 - Output is encoded for its context
 - Crypto uses vetted libraries (no MD5/SHA1 for security)
 - Authorization is checked, not assumed
 ## How Nova Uses This
 The submission-readiness gate checks `policyPreconditions` (e.g.,
 `public-ingress: false`, `encryption_enabled: true`). The security skill
 tells you what the platform enforces and what your application must
 enforce on its own surface. The platform enforces infrastructure-level
 security (IAM scoping, ABAC, encryption-at-rest, policy-as-code via
 Checkov); you enforce application-level security (input validation, output
 encoding, auth checks). The Atelier MCP server (`mcp/atelier/server.py`,
 P5) can validate your code against these principles agenticly — beyond
 what deterministic scanners like Wiz/Checkmarx/Mend catch.
@@ -0,0 +1,37 @@
 # Skill: Testing
 > **Atelier source:** `domains/testing/` (first-principles + pyramid,
 > fixtures)
 > **Core principles:** C1 Correctness, C5 Reversibility
 > **BA.A mapping:** UAT is the citizen developer's RACI responsibility
 > **Consumer:** read this before submitting for UAT.
 ## First Principles (citizen-developer-relevant subset)
 - **Tests are independent.** Order doesn't matter; one test's setup
  doesn't break another's.
 - **Tests are deterministic.** No `Date.now()`, no `random()`, no
  network calls in unit tests.
 - **Edge cases are covered.** Empty, single, max, invalid — not just
  the happy path.
 - **A failing test names the problem.** The assertion message explains
  what failed and why, not just "assertion failed".
 - **The pyramid: unit → integration → e2e.** Most tests are unit; few
  are e2e; the middle is integration. Don't invert the pyramid.
 ## Agent-Checklist Triggers (§ Testing)
 - Tests are independent (order doesn't matter)
 - Tests are deterministic (no `Date.now()`, no `random()`)
 - Edge cases are covered (empty, single, max, invalid)
 - A failing test names the problem specifically
 ## How Nova Uses This
 Per the RACI matrix (`docs/raci.md`), the **Citizen Developer is
 Responsible for User Acceptance Testing (UAT)**. The platform provides
 the QA checks (policy, confidence, schema); you provide the UAT. The
 testing skill ensures your UAT meets production-grade standards. The
 W3.E per-env mandatory table requires `validation.e2eSuite` +
 `validation.loadTest` for `qa` environment submissions — the
 submission-readiness gate enforces this.