@rasensio/aidlc-content 1.15.2 → 1.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.15.2",
+  "version": "1.17.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,6 +16,7 @@
     "skills/",
     "templates/",
     "guidance/",
+    "packs/",
     "capabilities/",
     "phases/",
     "tutorials/",

package/packs/soc2/controls.yaml

@@ -0,0 +1,261 @@
+# SOC 2 Trust Services Criteria — the Common Criteria only.
+#
+# `kind` says what the AIDLC artifact trail can establish:
+#
+#   evidenced     the trail genuinely demonstrates the control
+#   checked-only  the control operates over a running system, so no document
+#                 evidences it; the pack supplies a fail condition an agent
+#                 applies, and the trail records only that the check happened
+#
+# `check_kind` says who applies the fail condition: `mechanical` controls carry a
+# pattern the diff check evaluates itself, `agent` controls need a review session.
+#
+# Exactly one control is `evidenced`. Six are `checked-only`. Twenty-six Common
+# Criteria points are not covered at all, each listed below with its reason.
+#
+# `references` points at the guidance layer whose rule a control restates, so the
+# duplication is traceable and a later edit to that layer can be found. The pack's
+# own constraint layer does not restate those rules.
+
+controls:
+  # -------------------------------------------------------------------------
+  # Evidenced: the lifecycle trail is real evidence for this control.
+  # -------------------------------------------------------------------------
+  - id: CC8.1
+    kind: evidenced
+    check_kind: agent
+    severity: critical
+    phases:
+      - requirements
+      - design
+      - implementation
+      - testing
+      - deployment
+    requires: >-
+      The entity authorizes, designs, develops, configures, documents, tests,
+      approves and implements changes to infrastructure, data, software and
+      procedures to meet its objectives.
+    look_at: >-
+      requirements.md for numbered acceptance criteria; design.md for the design
+      the change was built to; tasks.md for the link from each task to the criteria
+      it satisfies; the review findings files; transitions.log for the recorded
+      phase progression; and deployment-record.md for the release.
+    fails_when: >-
+      A change reached deployment without an artifact recording each of
+      authorization, design, test and approval — that is, any of requirements.md,
+      design.md, a completed review findings file, test-results.md or
+      deployment-record.md is absent or names no outcome for the change.
+    evidence_artifact: design.md
+
+  # -------------------------------------------------------------------------
+  # Checked-only: these operate over a running system. The pack gives you a fail
+  # condition to apply; the trail records that you applied it, never that the
+  # control operates.
+  # -------------------------------------------------------------------------
+  - id: CC6.1
+    kind: checked-only
+    check_kind: agent
+    severity: critical
+    phases:
+      - design
+      - implementation
+    requires: >-
+      The entity implements logical access security software, infrastructure and
+      architectures over protected information assets to meet its objectives.
+    look_at: >-
+      Request handlers and data-access code in the change: where authorization is
+      decided, and whether any read or write of a protected record can be reached
+      without that decision. Also any credential handling.
+    fails_when: >-
+      A code path reads or writes a protected record without an authorization check
+      on the same path, or a credential, key or token appears in source.
+    references: secure-defaults#authentication-and-authorization
+
+  - id: CC6.6
+    kind: checked-only
+    check_kind: agent
+    severity: major
+    phases:
+      - design
+      - implementation
+    requires: >-
+      The entity implements logical access security measures to protect against
+      threats from sources outside its system boundaries.
+    look_at: >-
+      Every place external input crosses into the system in this change: HTTP
+      handlers, message consumers, file uploads, and any parser reached from them.
+    fails_when: >-
+      External input reaches a parser, query, filesystem path or command without
+      validation at the boundary, or an authentication endpoint has no rate limit.
+    references: secure-defaults#input-validation
+
+  - id: CC6.7
+    kind: checked-only
+    check_kind: mechanical
+    severity: major
+    phases:
+      - implementation
+      - deployment
+    requires: >-
+      The entity restricts the transmission, movement and removal of information to
+      authorized internal and external users and processes, and protects it during
+      transmission, movement or removal.
+    look_at: Network client configuration and request targets in the change.
+    fails_when: >-
+      An added line targets a plain-HTTP URL, so protected information could be
+      transmitted without transport encryption.
+    pattern: "http://(?!localhost|127\\.0\\.0\\.1|\\[::1\\])"
+    references: secure-defaults#transport-and-data-protection
+
+  - id: CC6.8
+    kind: checked-only
+    check_kind: agent
+    severity: major
+    phases:
+      - implementation
+      - deployment
+    requires: >-
+      The entity implements controls to prevent or detect and act upon the
+      introduction of unauthorized or malicious software.
+    look_at: >-
+      Dependency manifests and lockfiles in the change, and any script that fetches
+      and executes code at build or run time.
+    fails_when: >-
+      A dependency is added without a lockfile entry, a dependency range is
+      unpinned, or a script pipes a downloaded payload straight into a shell.
+    references: secure-defaults#dependency-security
+
+  - id: CC7.1
+    kind: checked-only
+    check_kind: agent
+    severity: major
+    phases:
+      - implementation
+      - deployment
+    requires: >-
+      The entity uses detection and monitoring procedures to identify changes to
+      configurations that result in the introduction of new vulnerabilities, and
+      susceptibilities to newly discovered vulnerabilities.
+    look_at: >-
+      Configuration and infrastructure changes in the diff, and whether a
+      vulnerability audit runs over the dependency set.
+    fails_when: >-
+      A configuration change relaxes a security setting with no stated reason, or the
+      project has no dependency vulnerability audit in its build or CI.
+    references: secure-defaults#dependency-security
+
+  - id: CC7.2
+    kind: checked-only
+    check_kind: agent
+    severity: major
+    phases:
+      - implementation
+      - deployment
+      - maintenance
+    requires: >-
+      The entity monitors system components and the operation of those components
+      for anomalies indicative of malicious acts, natural disasters and errors
+      affecting the entity's ability to meet its objectives.
+    look_at: >-
+      Error handling and logging in the change: whether failures are recorded with
+      enough context to notice an anomaly, and whether anything sensitive is logged.
+    fails_when: >-
+      A failure path swallows an error without logging it, a log statement records a
+      secret or personal data, or a user-facing error exposes a stack trace or
+      internal path.
+    references: secure-defaults#error-handling-and-logging
+
+# ---------------------------------------------------------------------------
+# Not covered. Twenty-six of the thirty-three Common Criteria points.
+#
+#   organizational  the control is about the entity's governance, people or
+#                   processes; a tool that reads code cannot speak to it
+#   not-yet-built   a code lifecycle could say something here, and this pack does
+#                   not yet
+# ---------------------------------------------------------------------------
+excluded:
+  # CC1 — control environment. Board oversight, integrity and ethics, competence.
+  - id: CC1.1
+    reason: organizational
+  - id: CC1.2
+    reason: organizational
+  - id: CC1.3
+    reason: organizational
+  - id: CC1.4
+    reason: organizational
+  - id: CC1.5
+    reason: organizational
+
+  # CC2 — communication and information.
+  - id: CC2.1
+    reason: organizational
+  - id: CC2.2
+    reason: organizational
+  - id: CC2.3
+    reason: organizational
+
+  # CC3 — risk assessment.
+  - id: CC3.1
+    reason: organizational
+  - id: CC3.2
+    reason: organizational
+  - id: CC3.3
+    reason: organizational
+  - id: CC3.4
+    reason: organizational
+
+  # CC4 — monitoring activities.
+  - id: CC4.1
+    reason: organizational
+  - id: CC4.2
+    reason: organizational
+
+  # CC5 — control activities.
+  - id: CC5.1
+    reason: organizational
+  - id: CC5.2
+    reason: organizational
+  - id: CC5.3
+    reason: organizational
+
+  # CC6 — the access-management points, as distinct from the code-facing ones above.
+  - id: CC6.2
+    reason: organizational
+    note: >-
+      Registering and authorizing new users is the entity's access-management
+      process. An application's provisioning code is not the control.
+  - id: CC6.3
+    reason: organizational
+    note: >-
+      Removing access is the entity's process. Deprovisioning code in an
+      application is not the control.
+  - id: CC6.4
+    reason: organizational
+    note: Physical access to facilities is outside a code tool's reach entirely.
+  - id: CC6.5
+    reason: organizational
+    note: Disposal of physical media is outside a code tool's reach entirely.
+
+  # CC7 — the incident-response points.
+  - id: CC7.3
+    reason: organizational
+    note: Evaluating security events is an incident-response process, not a code property.
+  - id: CC7.4
+    reason: organizational
+    note: Responding to identified security incidents is an incident-response process.
+  - id: CC7.5
+    reason: organizational
+    note: Recovering from identified security incidents is an incident-response process.
+
+  # CC9 — risk mitigation.
+  - id: CC9.1
+    reason: organizational
+    note: Mitigating business-disruption risk is a continuity programme.
+  - id: CC9.2
+    reason: not-yet-built
+    note: >-
+      Vendor and business-partner risk has a real code angle — dependency
+      inventory, lockfiles and vulnerability audit. Those rules already exist in the
+      secure-defaults guidance layer and CC6.8 checks them, but this pack does not
+      claim them as CC9.2 evidence: a dependency audit is one input to vendor risk
+      management, not the control itself.

package/packs/soc2/guidance/soc2-constraints.md

@@ -0,0 +1,69 @@
+---
+name: soc2-constraints
+description: SOC 2 Common Criteria constraints that apply while code is being written
+---
+# SOC 2 Constraints
+
+**This pack's control text has not been reviewed by a compliance practitioner.**
+It was written by an engineer reading the Trust Services Criteria. Treat it as a
+working draft: useful for applying controls while you write code, not as an opinion
+on whether your controls are adequate. Nothing here makes a project SOC 2 certified,
+attested, or audit-ready.
+
+## Which controls apply, and when
+
+| Phase | Controls to have in mind |
+|---|---|
+| Requirements, design | CC8.1, CC6.1, CC6.6 |
+| Implementation | CC6.1, CC6.6, CC6.7, CC6.8, CC7.1, CC7.2, CC8.1 |
+| Testing | CC8.1 |
+| Deployment | CC6.7, CC6.8, CC7.1, CC7.2, CC8.1 |
+| Maintenance | CC7.2 |
+
+Run `aidlc compliance check` for each control's exact fail condition. Apply the fail
+condition as written rather than your reading of the criterion — that is what makes
+two reviews of the same change agree.
+
+## One control is evidenced. Six are only checked.
+
+**CC8.1 is evidenced.** It is a control over the change process, and this lifecycle
+*is* a change process, so the artifact trail demonstrates it.
+
+**CC6.1, CC6.6, CC6.7, CC6.8, CC7.1 and CC7.2 are checked only.** They operate over
+a running system. No document establishes that your system monitors components for
+anomalies or restricts information in transmission — so the pack gives you a fail
+condition to apply, and the trail records that you applied it. A report will say
+which is which. Never present a checked-only control as evidence.
+
+## What CC8.1 asks of you while you build
+
+Make sure each of these leaves a record, because the record is the evidence:
+
+- **Authorization.** `requirements.md` carries numbered acceptance criteria and the
+  change stays inside them. Work no criterion asks for is unauthorized change,
+  however small.
+- **Design.** `design.md` exists before implementation and names what the change
+  touches.
+- **Traceability.** Every task in `tasks.md` references the criteria it satisfies. A
+  task referencing none is a gap to state, not to hide.
+- **Test.** Every active criterion has a referencing test.
+- **Approval.** A completed review findings file exists for each required artifact,
+  and no critical finding is left open.
+- **Release.** `deployment-record.md` records what shipped.
+
+## What CC8.1 does not evidence here
+
+The trail shows a change passed through requirements, design, review and deployment.
+It does **not** establish that `requirements.md` and the shipped code still agree.
+There is no reopen protocol and no impact walk, so a requirement can change after
+design signed off and every gate still passes. Closing that gap is tracked as
+`item-20260815-change-management`. Until it ships, do not represent this pack's CC8.1
+output as evidence of requirement-to-code agreement.
+
+## Security rules live in one place, not here
+
+This pack does not restate the project's security rules. Read
+`.aidlc/guidance/secure-defaults.md` and apply it. The six checked-only controls
+reference its sections — authentication and authorization, input validation,
+transport and data protection, dependency security, error handling and logging — so
+there is exactly one place to change when a rule changes.

package/packs/soc2/pack.yaml

@@ -0,0 +1,25 @@
+id: soc2
+regime: SOC 2
+version: 0.2.0
+
+# SOC 2 is a service-organization examination, not an industry standard, so it
+# applies to any industry. The field exists so an industry-scoped regime can use
+# it later; the wizard skips the industry level while every pack is `any`.
+industries:
+  - any
+
+entitlement: unrestricted
+
+# Null on purpose. The control text in this pack was written by an engineer, not
+# a compliance practitioner. Nulling this field obliges the constraint layer to
+# say so, obliges every report to say so, and makes a doctor check watch for
+# someone editing the statement out.
+reviewed_by: null
+
+layers:
+  - name: soc2-constraints
+    file: soc2-constraints.md
+    # Pack layers are delivered as a read-instruction whatever their size. A small
+    # layer that got inlined would put pack text inside an emitted skill, which is
+    # forbidden outright.
+    always_pointer: true

package/skills/00-overview.md

@@ -178,6 +178,14 @@ An instance's **completion moment** is when the last applicable phase (template
 - `lessons.md` is the retrospective-fed guidance layer: historical observations from completed instances. Read it via the index like any other layer; treat entries as observations, not directives
 - Load context relevant to the current phase; avoid re-reading unchanged files
 
+### The constitution rule
+
+This is the canonical statement of the rule. Other skills point here instead of restating it, so there is no second copy to drift.
+
+When `.aidlc/context/constitution.md` exists, read it before shaping work. It records what this repo owns (`IN-<n>` entries) and what it must never do (`NOT-<n>` entries), each citing the vision statement it was derived from. **If the work in front of you crosses a prohibition, name that prohibition by its id and say plainly that it does, before going further.** The user may still choose to proceed, or to amend the constitution — but the crossing gets stated out loud at the start rather than discovered in review.
+
+The constitution never fails a gate and never blocks a transition; its whole force is that somebody read it out at the right moment. An absent file is a normal state, not a gap to fill — it is written by the **aidlc-constitution** skill, and only a project with a vision document to import has one.
+
 ## Security
 
 Before executing any sensitive operation (infrastructure changes, permission modifications, file deletions), you MUST:

package/skills/04-roadmap.md

@@ -112,6 +112,8 @@ Moving an `inbox/` item to `backlog/` means "we agree to do this". Moving it to
 
 Triage is the one flow that reads into the body, and it reads **the executive summary and nothing else**. Six labelled lines per item is what makes triaging a full inbox in one sitting possible; opening whole items is what makes triage something nobody ever gets round to. Show the summary, say which way you would go and why, and let the human decide. If an item has no executive summary, write one from what the item says before asking for a decision — a decision made without one is a decision made twice.
 
+Read `.aidlc/context/constitution.md` when it exists and apply the constitution rule in **aidlc-overview**: an item that crosses a prohibition is the clearest `hold/` there is, and naming the prohibition turns "not for us" into a reason the submitter can read.
+
 ## Promote
 
 Promotion is where the roadmap meets the lifecycle:

package/skills/05-constitution.md

@@ -0,0 +1,186 @@
+---
+name: aidlc-constitution
+description: Turns a product vision document into the repo's constitution — what this repo is for and what it must never become — and keeps it in step when the vision is updated
+phase: ideation
+priority: 88
+trigger: When the user points at a product vision document, asks what this repo is or is not allowed to do, asks to create or update a project constitution, or when the vision document has changed
+native_mode_hint:
+  claude-code: >-
+    This skill imports a document and drafts prose for the user to correct. Do
+    not enter plan mode. Never rewrite an existing constitution from the vision
+    in one step — propose changes into the inbox and apply only what the user
+    accepts.
+---
+# Constitution
+
+A product has a vision. A repo usually builds only part of it. The constitution
+writes down which part, and — more usefully — what this repo must never grow into.
+
+Two files, and the difference between them matters:
+
+- `.aidlc/context/vision-source.md` — the vision document's text, extracted and
+  hashed. Machine-written, never hand-edited.
+- `.aidlc/context/constitution.md` — what this repo owns and what it is forbidden
+  to do, each line citing the vision statement it came from. Drafted by this
+  skill, owned by the user.
+
+The vision is imported. The constitution is a judgement about the vision, and
+judgement is why this is a skill and not just a command.
+
+## First run
+
+### Step 1 — Import the vision document
+
+Ask for the path if the user has not given one. Then:
+
+```
+aidlc constitution import <path>
+```
+
+`.docx`, `.md`, `.markdown` and `.txt` are read directly. For a PDF, a Google Doc,
+or anything else: read it yourself, save a markdown copy next to the original, and
+import that — the command tells you the same thing if you try.
+
+The command prints one line per statement, each with a `V-` id derived from that
+statement's own text. Those ids are the vocabulary for everything below.
+
+If anything in the extracted text looks like a credential — an API key, a token, a
+password, a connection string — say so, and do not let it reach
+`.aidlc/context/vision-source.md`. Ask the user to remove it from the source
+document and re-import. The snapshot is committed; the vision document may not be.
+
+### Step 2 — Read the repo, not just the document
+
+The vision says what the product is. Only the code says what this repo does. Read
+`.aidlc/context/architecture.md` if it exists, then look at the top-level layout
+and the entry points. You are deciding one thing: which slice of the vision this
+repo carries.
+
+### Step 3 — Draft the constitution
+
+Write `.aidlc/context/constitution.md`:
+
+```markdown
+---
+generated_by: aidlc-constitution
+generated_at: <ISO 8601 UTC>
+vision_source: <path as imported>
+---
+# Constitution — <repo or component name>
+
+## Mandate
+
+One paragraph, plain words: which part of the product this repo owns, and which
+parts belong to something else.
+
+## In scope
+
+- IN-1 [V-a1b2c3d4]: <what this repo builds>
+- IN-2 [V-e5f6a7b8, V-11223344]: <another>
+
+## Prohibitions
+
+- NOT-1 [V-99887766]: <what this repo must never do>
+- NOT-2 [V-a1b2c3d4]: <another>
+
+## Amendments
+
+<empty on the first run>
+```
+
+Four rules that make the file usable later:
+
+1. **Every entry cites at least one `V-` id.** An entry with no citation is an
+   opinion someone had, and a re-run cannot tell whether the vision still supports
+   it. If you cannot find a supporting statement, that is a finding — say so and
+   leave the entry out.
+2. **`IN-` and `NOT-` ids are assigned once.** Never renumbered, never reused. An
+   entry that no longer holds is recorded in Amendments with a date and a reason,
+   not deleted — a deleted prohibition and one that never existed look identical.
+3. **A prohibition is a sentence someone can be shown.** "No customer PII in this
+   service" is checkable. "Keep it simple" is not.
+4. **Derive, do not invent.** A prohibition the vision does not support is your
+   opinion wearing the document's authority.
+
+### Step 4 — Hand it back
+
+Show the Mandate and the Prohibitions and ask the user to correct them. They will
+know things the document does not say. Their corrections are the point — and step
+2 of the re-run flow exists to protect them.
+
+## When the vision is updated
+
+The user replaces the vision document and re-runs this skill. Never rewrite
+`.aidlc/context/constitution.md` from the new vision in one step: a human's
+correction to a derived line and a genuine change in the vision are
+indistinguishable once overwritten, and if corrections do not survive nobody makes
+them twice.
+
+### Step 1 — Ask what moved
+
+```
+aidlc constitution check
+```
+
+It reports statement ids **added** and **removed** relative to the snapshot. An
+edited statement appears as one of each, because ids come from content. It also
+names every constitution entry citing a removed id — those are the entries at
+risk, and it exits 0 either way. This is advisory. It never fails a phase.
+
+### Step 2 — Propose, do not apply
+
+Write a proposal to `.aidlc/inbox/constitution-update-<YYYY-MM-DD>.md`, one
+checkbox per change, following the User Input Protocol in the overview skill:
+
+```markdown
+# Constitution update — <date>
+
+Vision source: <path> (<n> statements added, <m> removed)
+
+## NOT-2 cites V-99887766, which is gone
+
+The vision no longer says: "<old statement text>"
+It now says: "<new statement text, if there is a successor>"
+
+- [ ] Re-cite NOT-2 against V-<new id>, wording unchanged
+- [ ] Reword NOT-2: <proposed wording>
+- [ ] Retire NOT-2 — the vision no longer supports it
+- [ ] Leave NOT-2 as it is (a deliberate local rule the vision never carried)
+
+## V-<new id> is new and nothing covers it
+
+"<statement text>"
+
+- [ ] Add IN-<next>: <proposed wording>
+- [ ] Add NOT-<next>: <proposed wording>
+- [ ] Nothing — this statement is about a different repo
+```
+
+Include the last option every time. "The vision changed and this repo's boundary
+did not" is a common and correct answer.
+
+### Step 3 — Apply only what is checked
+
+Then re-import so the snapshot matches the vision the decisions were made against:
+
+```
+aidlc constitution import <path>
+```
+
+Append one line to Amendments for every applied change — date, entry id, what
+changed, why. Amendments are how the next reader tells a deliberate local rule from
+a stale derivation. Offer to delete the inbox file once its content has landed.
+
+## Consulting the constitution
+
+Reading it during other work is not this skill's job — the overview skill carries
+that rule, and the requirements, design and roadmap skills point at it. This skill
+writes the file; they read it.
+
+## Exit criteria
+
+- `.aidlc/context/vision-source.md` exists and its `source_path` names a real file.
+- `.aidlc/context/constitution.md` has a Mandate, at least one prohibition, and a
+  cited `V-` id on every entry.
+- On a re-run: every proposed change was either applied or explicitly declined, and
+  each applied one has an Amendments line.

package/skills/10-ideation.md

@@ -30,7 +30,7 @@ and open questions.
 
 > {{glossary:artifact}}
 
-1. **Consult the knowledge graph first.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase ideation` before exploring the codebase — the graph is the first source of understanding; re-explore only what it doesn't cover. Also read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
+1. **Consult the knowledge graph first.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase ideation` before exploring the codebase — it is the cheapest way to find where in the code to look, and re-exploring what it already covers wastes the phase. It is an index, not an authority: a specific symbol it names may have been renamed or deleted by a later instance, so open the source before treating any named component, table, or registry as real. Also read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
 2. **Clarify the problem.** Ask the user what they want to build and why. Identify the core need vs. nice-to-haves.
 3. **Explore constraints.** Document: timeline, technical constraints, platform limitations, team size, budget considerations.
 4. **Generate options.** Propose 2-3 approaches. For each, note trade-offs (complexity, time, risk).

package/skills/20-requirements.md

@@ -25,7 +25,7 @@ Translate the ideation output (or the user's direct request) into precise, testa
 
 > {{glossary:artifact}}
 
-1. **Gather requirements.** If a Full scope, read the ideation phase's artifact for context (`idea.md` for the feature templates, `research-question.md` for `spike`; `phase-ideation.yaml` names it). Otherwise, ask the user to describe desired behavior. Read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
+1. **Gather requirements.** If a Full scope, read the ideation phase's artifact for context (`idea.md` for the feature templates, `research-question.md` for `spike`; `phase-ideation.yaml` names it). Otherwise, ask the user to describe desired behavior. Read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills. Read `.aidlc/context/constitution.md` when it exists and apply the constitution rule in **aidlc-overview**.
 2. **Write user stories.** Use the format: "As a [role], I want [capability], so that [benefit]."
 3. **Define acceptance criteria.** Each criterion must be:
    - Specific and unambiguous

package/skills/30-design.md

@@ -26,14 +26,15 @@ Produce a technical design that satisfies the requirements. Define architecture,
 > {{glossary:gate}}
 
 1. **Review requirements.** Read `requirements.md` (or its summary if one exists). Identify the key technical challenges. When requirements carry `AC-n` IDs, note in each design section which criteria it addresses — that linkage is what reviewers and the testing phase trace against.
-2. **Consult the knowledge graph.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase design` for existing architecture, decisions, and conventions before re-deriving them from code. Also read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills.
-3. **Define architecture.** Describe the high-level structure: components, their responsibilities, and how they communicate.
-4. **Specify interfaces.** For each component boundary, define the contract (function signatures, API shapes, data types).
-5. **Data flow.** Document how data moves through the system — inputs, transformations, storage, outputs.
-6. **Design decisions.** Record each significant decision with rationale and alternatives considered. Persist accepted decisions as `decision` entities: `aidlc knowledge add --type decision --id <slug> --name "<title>" --description "<rationale>"`.
-7. **Address non-functional concerns.** Map performance, security, and accessibility requirements to design choices.
-8. **Identify risks.** Note technical risks and mitigation strategies.
-9. **Produce the task breakdown.** For templates that require it (full-feature, quick-feature), write `tasks.md` in the instance state directory as the final design step — the design is not done until it is actionable. Decompose the design into commit-sized tasks: each one reviewable in one sitting and independently verifiable. One task per line, in this exact grammar:
+2. **Consult the knowledge graph, then check it against the source.** If the project has a knowledge graph (`.aidlc/knowledge/` exists), run `aidlc knowledge context --scope phase --phase design` for existing architecture, decisions, and conventions. The graph is an index into the code, not an authority over it: an entry naming a component, table, column, function, or registry is a pointer to open, and an entry written by an earlier instance may name something a later one renamed or deleted. Confirm a named symbol exists in the source before designing against it — `aidlc knowledge verify <id>` records that you did, and `aidlc knowledge update <id>` corrects an entry that no longer matches. A design built on a symbol that is not there produces code against an API nobody has, and nothing downstream catches it until implementation. Also read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills. Read `.aidlc/context/constitution.md` when it exists and apply the constitution rule in **aidlc-overview**.
+3. **Find the seams before proposing structure.** A project is brownfield from its second instance onwards, so start from the assumption that something in the codebase already does part of what the requirements ask for. For each capability in `requirements.md`, locate and read the existing code that carries any of it — the scheduler that already fires, the settings shape that already persists, the registry that already dispatches — and name those files in `design.md` before describing a single new component. Keep it narrow: the seams the requirements actually touch, a handful of files, not a survey. When nothing exists, write that down — "no existing seam" is a finding, and stating it is what separates a genuinely new component from one designed alongside the code that should have absorbed it.
+4. **Define architecture.** Describe the high-level structure: components, their responsibilities, and how they communicate. Say for each one whether it extends a seam found in step 3 or is new.
+5. **Specify interfaces.** For each component boundary, define the contract (function signatures, API shapes, data types).
+6. **Data flow.** Document how data moves through the system — inputs, transformations, storage, outputs.
+7. **Design decisions.** Record each significant decision with rationale and alternatives considered. Persist accepted decisions as `decision` entities: `aidlc knowledge add --type decision --id <slug> --name "<title>" --description "<rationale>"`.
+8. **Address non-functional concerns.** Map performance, security, and accessibility requirements to design choices.
+9. **Identify risks.** Note technical risks and mitigation strategies.
+10. **Produce the task breakdown.** For templates that require it (full-feature, quick-feature), write `tasks.md` in the instance state directory as the final design step — the design is not done until it is actionable. Decompose the design into commit-sized tasks: each one reviewable in one sitting and independently verifiable. One task per line, in this exact grammar:
 
    ```
    - [ ] T<n>: <title>
@@ -47,6 +48,8 @@ Produce a technical design that satisfies the requirements. Define architecture,
 ## Exit Criteria
 
 - `design.md` exists with architecture, interfaces, and at least one design decision with rationale
+- `design.md` names the existing code the change extends, or states that no such code exists
+- Every knowledge-graph symbol the design builds on was checked against the source
 - The design addresses all acceptance criteria from `requirements.md`
 - For templates requiring it: `tasks.md` exists and every active acceptance criterion is claimed by at least one task, or the gap is deliberate
 - The user has confirmed the design direction

package/skills/40-implementation.md

@@ -26,7 +26,7 @@ Produce working code that satisfies the design and requirements. Follow project
 
 > {{glossary:gate}}
 
-1. **Load context.** Read `.aidlc/context/style-guide.md` and `.aidlc/context/architecture.md` if they exist. Match the project's established patterns. If the project has a knowledge graph (`.aidlc/knowledge/` exists), also run `aidlc knowledge context --scope phase --phase implementation` and query it (`aidlc knowledge query <term>`) before re-exploring code it already describes.
+1. **Load context.** Read `.aidlc/context/style-guide.md` and `.aidlc/context/architecture.md` if they exist. Match the project's established patterns. If the project has a knowledge graph (`.aidlc/knowledge/` exists), also run `aidlc knowledge context --scope phase --phase implementation` and query it (`aidlc knowledge query <term>`) before re-exploring code it already describes — as an index into the source, never a substitute for reading it. Open the file before calling anything the graph names; an entry can outlive the symbol it describes.
 2. **Load guidance.** Read all active guidance layers from `.aidlc/guidance/index.yaml`. Apply their rules during implementation.
 3. **Execute the task breakdown.** When the instance has a `tasks.md` (produced in Design for full/quick-feature scope), read it and execute tasks in order: complete a task, then mark its checkbox `[x]` as part of the same work unit — never batch checkbox updates for later. A task that should not be done is deferred in place (`- [>] T<n>: <title> (deferred YYYY-MM-DD: <reason>)`) with a dated reason, never skipped silently or deleted; the implementation→testing gate blocks on open tasks. For bugfix scope, create the optional `tasks.md` at implementation start when the fix spans more than one commit-sized unit. For Micro scope, reference the task description and acceptance criteria directly — no task file.
 4. **Write code.** Follow the design interfaces. Match existing code style (naming, formatting, error handling patterns).

package/skills/60-deployment.md

@@ -31,19 +31,20 @@ deployment checklist.
 > {{glossary:gate}}
 > {{glossary:artifact}}
 
-1. **Validate readiness.** Check the phase state files: every preceding required phase must be complete (all required artifacts `complete`). If any gate fails, address the gap before proceeding. (CLI shortcut: `aidlc gate <instance> deployment` — the phase name is the second argument, not the first.)
-2. **Write release plan.** Document in the phase's required artifact (see Required Artifacts above):
+1. **Load guidance.** Read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills. Layers can be added to a project after these skills were installed, so read the index rather than assuming the layers named at the bottom of this skill are the only ones.
+2. **Validate readiness.** Check the phase state files: every preceding required phase must be complete (all required artifacts `complete`). If any gate fails, address the gap before proceeding. (CLI shortcut: `aidlc gate <instance> deployment` — the phase name is the second argument, not the first.)
+3. **Write release plan.** Document in the phase's required artifact (see Required Artifacts above):
    - What is being deployed (version, changes summary)
    - Target environment(s)
    - Deployment steps in order
    - Rollback procedure
    - Monitoring and verification steps post-deploy
-3. **Pre-deployment checks.** Verify:
+4. **Pre-deployment checks.** Verify:
    - CI pipeline passes
    - No critical findings open from adversarial reviews
    - Dependencies are pinned and audited
-4. **Execute deployment.** Follow the release plan step by step.
-5. **Verify.** Confirm the deployment succeeded using the monitoring steps.
+5. **Execute deployment.** Follow the release plan step by step.
+6. **Verify.** Confirm the deployment succeeded using the monitoring steps.
 
 ## Exit Criteria
 

package/skills/70-maintenance.md

@@ -26,15 +26,16 @@ and follow-up items.
 
 ## Instructions
 
-1. **Monitor.** Check that the deployed changes behave as expected in their target environment. Note any anomalies.
-2. **Update documentation.** Ensure project docs reflect the new state:
+1. **Load guidance.** Read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills. Layers can be added to a project after these skills were installed, so read the index rather than assuming the layers named at the bottom of this skill are the only ones.
+2. **Monitor.** Check that the deployed changes behave as expected in their target environment. Note any anomalies.
+3. **Update documentation.** Ensure project docs reflect the new state:
    - README or user-facing docs updated if behavior changed
    - Architecture docs updated if new components were added
    - API docs updated if endpoints changed
-3. **Gather feedback.** Collect user/team feedback on the delivered feature.
-4. **Record known issues.** Document any edge cases, limitations, or technical debt introduced. If the project has a knowledge graph, record debt as entities (`aidlc knowledge add --type debt …`) and update facts invalidated by code changes (`aidlc knowledge update` / `verify`); list candidates with `aidlc knowledge stale --check-git`.
-5. **Plan follow-up.** If feedback or monitoring reveals needed improvements, document them as potential future lifecycle instances.
-6. **Close the instance.** When maintenance tasks are complete, mark the lifecycle instance as done.
+4. **Gather feedback.** Collect user/team feedback on the delivered feature.
+5. **Record known issues.** Document any edge cases, limitations, or technical debt introduced. If the project has a knowledge graph, record debt as entities (`aidlc knowledge add --type debt …`) and update facts invalidated by code changes (`aidlc knowledge update` / `verify`); list candidates with `aidlc knowledge stale --check-git`.
+6. **Plan follow-up.** If feedback or monitoring reveals needed improvements, document them as potential future lifecycle instances.
+7. **Close the instance.** When maintenance tasks are complete, mark the lifecycle instance as done.
 
 ## Exit Criteria
 

package/skills/80-review.md

@@ -30,7 +30,9 @@ You MUST perform this review with fresh eyes. If you authored the artifact being
 
 1. **Read the target artifact completely.** Do not skim.
    - When reviewing a design artifact and the instance has a `tasks.md`, review it together with the design: breakdown completeness (every design section covered by a task), task sizing (commit-sized units), and AC linkage (tasks reference the criteria they satisfy). Record its findings in the design review's findings file — no separate `tasks.review.md`.
-2. **Examine for each dimension:**
+2. **Load guidance.** Read all active guidance layers from `.aidlc/guidance/index.yaml` (including `lessons.md` — lessons from completed instances) so fresh guidance applies without recompiling skills. A newly installed layer takes effect immediately, so do not assume the layers named in this skill are the only active ones.
+3. **Check for installed compliance controls.** Run `aidlc compliance list`. If nothing is installed, skip this step and the compliance findings stream below entirely — there is nothing to check and no file to write. If a pack is installed, run `aidlc compliance check` to get the controls that apply to this phase, each with what it requires, where to look, and its fail condition. Apply those fail conditions **as written**: they are the pack's, and reinterpreting one turns a stated control into your opinion.
+4. **Examine for each dimension:**
    - **Ambiguities** — Vague terms, undefined behavior, unclear scope
    - **Contradictions** — Requirements that conflict with each other
    - **Missing edge cases** — Inputs, states, or scenarios not addressed
@@ -43,13 +45,27 @@ You MUST perform this review with fresh eyes. If you authored the artifact being
      deserialization. Apply the secure-defaults guidance below as the checklist.
    - **Scalability concerns** — Performance bottlenecks or resource limits
    - **Scope creep** — Functionality beyond the stated scope
-3. **Write findings.** For each issue found, record:
+5. **Write findings.** For each issue found, record:
    - **Severity**: `critical`, `major`, or `minor`
    - **Section**: The specific part of the artifact
    - **Issue**: Clear description of the problem
    - **Suggestion**: A concrete resolution or question to ask
    - **Status**: `open` (always for new findings)
-4. **Save the findings file** as `<artifact>.review.md` in the instance namespace.
+6. **Save the findings file** as `<artifact>.review.md` in the instance namespace.
+7. **Write the compliance findings stream**, only when a pack is installed. It is a
+   **separate file**: `<artifact>.compliance.md`, never mixed into
+   `<artifact>.review.md`. The separation is load-bearing — the phase transition gate
+   reads only `*.review.md`, so keeping control findings out of it is what lets them
+   be advisory by default. See "Compliance Findings Format" below.
+
+   Every applicable control must appear in exactly one of two places, or it counts as
+   unchecked:
+   - a finding block carrying its **Control** id, when the fail condition is met;
+   - a line in `## Controls Checked` reading `- **Control:** <id> — no issues`, when
+     you looked and found nothing.
+
+   Do not write a cleared line for a control you did not actually examine. An
+   unchecked control reported as covered is the one outcome worse than no check at all.
 
 {{guidance:secure-defaults}}
 
@@ -70,11 +86,40 @@ reviewer: <session-id>
 - **Status:** open
 ```
 
+## Compliance Findings Format
+
+Only written when a compliance pack is installed. File: `<artifact>.compliance.md`.
+
+```markdown
+---
+artifact: <filename>
+reviewed_at: <ISO 8601 UTC>
+reviewer: <session-id>
+---
+
+## Finding 1
+- **Control:** <control id from the pack>
+- **Severity:** critical | major | minor
+- **Section:** <where in the artifact or diff>
+- **Issue:** <how the fail condition is met>
+- **Suggestion:** <what would satisfy the control>
+- **Status:** open
+
+## Controls Checked
+- **Control:** <control id> — no issues
+- **Control:** <control id> — no issues
+```
+
+The `Control` bullet is what links a finding to a control. A finding without one
+satisfies nothing, and a control appearing in neither section counts as unchecked.
+
 ## Exit Criteria
 
 - Findings file exists in the instance namespace
 - Every dimension was considered (even if no issues found — state "no issues" for that dimension)
 - Findings are actionable (each has a concrete suggestion or question)
+- When a compliance pack is installed: `<artifact>.compliance.md` exists and every
+  applicable control appears either as a finding carrying its id or as a cleared line
 
 ## Review Gate