@maycombhq/atticus 0.0.0-stage → 2.0.0-beta.10

package/dist/packages/extractors/dialects/terraform-azure.yaml

@@ -0,0 +1,212 @@
+# Azure resources in Terraform (azurerm) as catalog records. Shipped with Atticus (C2, ADR 0063).
+#
+# Applies to any repo with a .tf file (repoTypes "*", ADR 0062); values resolve from the
+# folder's variables, tfvars and locals, and through local modules (ADR 0063).
+#
+# What it reads:
+#   azurerm_servicebus_queue                      DataStore, storeType queue (as SQS queues are)
+#   azurerm_servicebus_topic, azurerm_eventhub    event-topic Endpoints (component unknown,
+#                                                 filled by merge from the publishing code)
+#   azurerm_linux_function_app, _windows_function_app, azurerm_function_app
+#                                                 Component (function) and Deployment
+#   azurerm_linux_web_app, _windows_web_app, azurerm_app_service
+#                                                 Deployment (platform app-service)
+#   azurerm_api_management_api                    GatewayRoute, with the ids the APIOps dialects use
+#   azurerm_cosmosdb_account                      DataStore, storeType document
+#   azurerm_mssql_server                          DataStore sqlserver   (moved from the infra extractor)
+#   azurerm_postgresql_flexible_server            DataStore postgresql  (moved from the infra extractor)
+#   azurerm_postgresql_server                     DataStore postgresql
+#   azurerm_mysql_flexible_server                 DataStore mysql
+#   azurerm_redis_cache                           DataStore cache
+#
+# Left to built-in readers: azurerm_storage_container (cloud-stores). No record:
+# azurerm_kubernetes_cluster. Not read: function triggers (they are in the function's code,
+# read by the serverless extractor), APIM operations and policies.
+#
+# A Deployment's environment is the resource's `env` tag, else "default".
+schemaVersion: 1
+name: terraform-azure
+version: 1.0.0
+description: Azure resources declared in Terraform as queues, topics, stores, functions, deployments and gateway routes.
+appliesTo:
+  repoTypes: ["*"]
+  marker: "**/*.tf"
+rules:
+  # ---- messaging
+  - id: servicebus-queue
+    description: A Service Bus queue is a queue store.
+    match: { hclBlock: resource.azurerm_servicebus_queue, files: ["**/*.tf"] }
+    emit:
+      kind: DataStore
+      id: "${attr.name | slug}"
+      fields: { storeType: queue, entitiesHeld: [] }
+      evidence: { source: infrastructure }
+    confidence: verified
+  - id: servicebus-topic
+    description: A Service Bus topic is an event topic.
+    match: { hclBlock: resource.azurerm_servicebus_topic, files: ["**/*.tf"] }
+    emit:
+      kind: Endpoint
+      id: "topic.${attr.name | slug}"
+      fields: { component: unknown, endpointType: event-topic, pathOrTopic: "${attr.name}" }
+      evidence: { source: infrastructure, side: definition }
+    confidence: verified
+  - id: eventhub
+    description: An event hub is an event topic.
+    match: { hclBlock: resource.azurerm_eventhub, files: ["**/*.tf"] }
+    emit:
+      kind: Endpoint
+      id: "topic.${attr.name | slug}"
+      fields: { component: unknown, endpointType: event-topic, pathOrTopic: "${attr.name}" }
+      evidence: { source: infrastructure, side: definition }
+    confidence: verified
+
+  # ---- compute
+  - id: linux-function-app
+    description: A Linux function app is a function component deployed on Azure Functions.
+    match: { hclBlock: resource.azurerm_linux_function_app, files: ["**/*.tf"] }
+    emit: &function-app
+      - kind: Component
+        id: "${attr.name | slug}"
+        fields:
+          system: "${attr.name | slug}"
+          repo: "${repo.name}"
+          type: function
+          runtime: azure-functions
+        evidence: { source: infrastructure }
+      - kind: Deployment
+        id: "${attr.name | slug}.${attr.tags.env | default('default') | slug}"
+        fields:
+          component: "${attr.name | slug}"
+          env: "${attr.tags.env | default('default')}"
+          platform: azure-functions
+        evidence: { source: infrastructure }
+    confidence: verified
+  - id: windows-function-app
+    description: A Windows function app is a function component deployed on Azure Functions.
+    match: { hclBlock: resource.azurerm_windows_function_app, files: ["**/*.tf"] }
+    emit: *function-app
+    confidence: verified
+  - id: function-app
+    description: A function app (the older resource type) is a function component deployed on Azure Functions.
+    match: { hclBlock: resource.azurerm_function_app, files: ["**/*.tf"] }
+    emit: *function-app
+    confidence: verified
+  - id: linux-web-app
+    description: A Linux web app is a deployment on App Service of the component it is named after.
+    match: { hclBlock: resource.azurerm_linux_web_app, files: ["**/*.tf"] }
+    emit: &web-app
+      kind: Deployment
+      id: "${attr.name | slug}.${attr.tags.env | default('default') | slug}"
+      fields:
+        component: "${attr.name | slug}"
+        env: "${attr.tags.env | default('default')}"
+        platform: app-service
+      evidence: { source: infrastructure }
+    confidence: verified
+  - id: windows-web-app
+    description: A Windows web app is a deployment on App Service.
+    match: { hclBlock: resource.azurerm_windows_web_app, files: ["**/*.tf"] }
+    emit: *web-app
+    confidence: verified
+  - id: app-service
+    description: An app service (the older resource type) is a deployment on App Service.
+    match: { hclBlock: resource.azurerm_app_service, files: ["**/*.tf"] }
+    emit: *web-app
+    confidence: verified
+
+  # ---- gateway
+  - id: api-management-api
+    description: An API Management API is a gateway route from its path to its backend.
+    match: { hclBlock: resource.azurerm_api_management_api, files: ["**/*.tf"] }
+    emit:
+      kind: GatewayRoute
+      id: "apim-${attr.path | default('') | slug | default('root')}"
+      fields:
+        proxy: "${attr.display_name}"
+        basepath: "/${attr.path | default('') | trimSlash}"
+        target: "${attr.service_url}"
+      evidence: { source: infrastructure, side: gateway }
+    confidence: verified
+
+  # ---- data
+  - id: cosmosdb-account
+    description: A Cosmos DB account is a document store.
+    match: { hclBlock: resource.azurerm_cosmosdb_account, files: ["**/*.tf"] }
+    emit:
+      kind: DataStore
+      id: "${attr.name | slug}"
+      fields: { storeType: document, entitiesHeld: [] }
+      evidence: { source: infrastructure }
+    confidence: verified
+  - id: mssql-server
+    description: An Azure SQL server.
+    match: { hclBlock: resource.azurerm_mssql_server, files: ["**/*.tf"] }
+    emit:
+      kind: DataStore
+      id: "${attr.name | slug}"
+      fields: { storeType: sqlserver, entitiesHeld: [] }
+      evidence: { source: infrastructure }
+    confidence: verified
+  - id: postgresql-flexible-server
+    description: An Azure Database for PostgreSQL flexible server.
+    match: { hclBlock: resource.azurerm_postgresql_flexible_server, files: ["**/*.tf"] }
+    emit:
+      kind: DataStore
+      id: "${attr.name | slug}"
+      fields: { storeType: postgresql, entitiesHeld: [] }
+      evidence: { source: infrastructure }
+    confidence: verified
+  - id: postgresql-server
+    description: An Azure Database for PostgreSQL single server.
+    match: { hclBlock: resource.azurerm_postgresql_server, files: ["**/*.tf"] }
+    emit:
+      kind: DataStore
+      id: "${attr.name | slug}"
+      fields: { storeType: postgresql, entitiesHeld: [] }
+      evidence: { source: infrastructure }
+    confidence: verified
+  - id: mysql-flexible-server
+    description: An Azure Database for MySQL flexible server.
+    match: { hclBlock: resource.azurerm_mysql_flexible_server, files: ["**/*.tf"] }
+    emit:
+      kind: DataStore
+      id: "${attr.name | slug}"
+      fields: { storeType: mysql, entitiesHeld: [] }
+      evidence: { source: infrastructure }
+    confidence: verified
+  - id: redis-cache
+    description: An Azure Cache for Redis is a cache.
+    match: { hclBlock: resource.azurerm_redis_cache, files: ["**/*.tf"] }
+    emit:
+      kind: DataStore
+      id: "${attr.name | slug}"
+      fields: { storeType: cache, entitiesHeld: [] }
+      evidence: { source: infrastructure }
+    confidence: verified
+tests:
+  - name: the Forge Azure estate
+    fixture: fixtures/terraform-azure/forge-azure-infra
+    expect:
+      - { kind: DataStore, id: orders-in, storeType: queue }
+      - { kind: Endpoint, id: topic.order-events, pathOrTopic: order-events, component: unknown }
+      - { kind: Endpoint, id: topic.device-telemetry, endpointType: event-topic }
+      - { kind: Component, id: billing-func, type: function, runtime: azure-functions }
+      - { kind: Deployment, id: billing-func.prod, env: prod, platform: azure-functions }
+      - { kind: Deployment, id: legacy-billing-func.default, env: default }
+      - { kind: Deployment, id: notifier-func.default, platform: azure-functions }
+      - { kind: Deployment, id: portal-web.prod, platform: app-service }
+      - { kind: Deployment, id: backoffice-web.default, platform: app-service }
+      - { kind: Deployment, id: statements-web.default, platform: app-service }
+      - kind: GatewayRoute
+        id: apim-orders
+        proxy: Orders API
+        basepath: /orders
+        target: "https://orders.forge.internal"
+      - { kind: DataStore, id: forge-catalog, storeType: document }
+      - { kind: DataStore, id: forge-reports-sql, storeType: sqlserver }
+      - { kind: DataStore, id: forge-ledger-pg, storeType: postgresql }
+      - { kind: DataStore, id: forge-legacy-pg, storeType: postgresql }
+      - { kind: DataStore, id: forge-loyalty-mysql, storeType: mysql }
+      - { kind: DataStore, id: forge-sessions, storeType: cache }
+    absent: [statements, forge-aks]

package/dist/packages/extractors/dialects/terraform-gcp.yaml

@@ -0,0 +1,109 @@
+# Google Cloud resources in Terraform as catalog records. Shipped with Atticus (C2, ADR 0063).
+#
+# Applies to any repo with a .tf file (repoTypes "*", ADR 0062); values resolve from the
+# folder's variables, tfvars and locals, and through local modules (ADR 0063).
+#
+# What it reads:
+#   google_sql_database_instance     DataStore by database_version (postgresql, mysql, sqlserver,
+#                                    else unknown); moved here from the infra extractor
+#   google_redis_instance            DataStore, storeType cache
+#   google_cloud_tasks_queue         DataStore, storeType queue
+#   google_spanner_database          DataStore, storeType relational, id <instance>-<database>
+#
+# Left to built-in readers, which do more than a rule can (environments from folders, owners
+# from labels and push endpoints, triggers): Cloud Run services, Pub/Sub topics and
+# subscriptions and IAM (gcp extractor), Cloud Functions (serverless), Cloud Scheduler (batch),
+# storage buckets and BigQuery datasets (cloud-stores). No record: google_container_cluster.
+schemaVersion: 1
+name: terraform-gcp
+version: 1.0.0
+description: Google Cloud databases, caches and task queues declared in Terraform as data stores.
+appliesTo:
+  repoTypes: ["*"]
+  marker: "**/*.tf"
+rules:
+  - id: sql-instance-postgresql
+    description: A Cloud SQL instance running PostgreSQL.
+    match: { hclBlock: resource.google_sql_database_instance, files: ["**/*.tf"] }
+    where: [{ value: "${attr.database_version | default('') | lower}", matches: "postgres" }]
+    emit:
+      kind: DataStore
+      id: "${attr.name | slug}"
+      fields: { storeType: postgresql, entitiesHeld: [] }
+      evidence: { source: infrastructure }
+    confidence: verified
+  - id: sql-instance-mysql
+    description: A Cloud SQL instance running MySQL.
+    match: { hclBlock: resource.google_sql_database_instance, files: ["**/*.tf"] }
+    where:
+      - value: "${attr.database_version | default('') | lower}"
+        matches: "^(?!.*postgres).*mysql"
+    emit:
+      kind: DataStore
+      id: "${attr.name | slug}"
+      fields: { storeType: mysql, entitiesHeld: [] }
+      evidence: { source: infrastructure }
+    confidence: verified
+  - id: sql-instance-sqlserver
+    description: A Cloud SQL instance running SQL Server.
+    match: { hclBlock: resource.google_sql_database_instance, files: ["**/*.tf"] }
+    where:
+      - value: "${attr.database_version | default('') | lower}"
+        matches: "^(?!.*(postgres|mysql)).*(mssql|sqlserver)"
+    emit:
+      kind: DataStore
+      id: "${attr.name | slug}"
+      fields: { storeType: sqlserver, entitiesHeld: [] }
+      evidence: { source: infrastructure }
+    confidence: verified
+  - id: sql-instance-other
+    description: A Cloud SQL instance whose version isn't written or isn't one of the above.
+    match: { hclBlock: resource.google_sql_database_instance, files: ["**/*.tf"] }
+    where:
+      - value: "${attr.database_version | default('') | lower}"
+        matches: "^(?!.*(postgres|mysql|mssql|sqlserver))"
+    emit:
+      kind: DataStore
+      id: "${attr.name | slug}"
+      fields: { storeType: unknown, entitiesHeld: [] }
+      evidence: { source: infrastructure }
+    confidence: verified
+  - id: redis-instance
+    description: A Memorystore for Redis instance is a cache.
+    match: { hclBlock: resource.google_redis_instance, files: ["**/*.tf"] }
+    emit:
+      kind: DataStore
+      id: "${attr.name | slug}"
+      fields: { storeType: cache, entitiesHeld: [] }
+      evidence: { source: infrastructure }
+    confidence: verified
+  - id: cloud-tasks-queue
+    description: A Cloud Tasks queue is a queue store.
+    match: { hclBlock: resource.google_cloud_tasks_queue, files: ["**/*.tf"] }
+    emit:
+      kind: DataStore
+      id: "${attr.name | slug}"
+      fields: { storeType: queue, entitiesHeld: [] }
+      evidence: { source: infrastructure }
+    confidence: verified
+  - id: spanner-database
+    description: A Spanner database is a relational store, named with its instance.
+    match: { hclBlock: resource.google_spanner_database, files: ["**/*.tf"] }
+    emit:
+      kind: DataStore
+      id: "${attr.instance | slug}-${attr.name | slug}"
+      fields: { storeType: relational, entitiesHeld: [] }
+      evidence: { source: infrastructure }
+    confidence: verified
+tests:
+  - name: the Forge Google Cloud estate
+    fixture: fixtures/terraform-gcp/forge-gcp-infra
+    expect:
+      - { kind: DataStore, id: ledger-db, storeType: postgresql }
+      - { kind: DataStore, id: loyalty-db, storeType: mysql }
+      - { kind: DataStore, id: reporting-db, storeType: sqlserver }
+      - { kind: DataStore, id: scratch-db, storeType: unknown }
+      - { kind: DataStore, id: forge-sessions, storeType: cache }
+      - { kind: DataStore, id: forge-emails, storeType: queue }
+      - { kind: DataStore, id: forge-spanner-accounts, storeType: relational }
+    absent: [forge-gke, topic.orders]

package/dist/packages/extractors/grammars/README.md

@@ -0,0 +1,11 @@
+# Vendored grammars
+
+Prebuilt tree-sitter grammars that aren't in `tree-sitter-wasms` (ADR 0060). Each is the `.wasm`
+file from the grammar's published npm package, unchanged, with its licence beside it.
+
+| File                      | From                                                              | Licence |
+| ------------------------- | ----------------------------------------------------------------- | ------- |
+| `tree-sitter-groovy.wasm` | `tree-sitter-groovy@0.1.2` (github.com/amaanq/tree-sitter-groovy) | MIT     |
+
+Vendored rather than depended on: the package also brings a native build (`node-gyp-build`,
+`node-addon-api`, `tree-sitter-java`) with install scripts that Atticus doesn't need.

package/dist/packages/extractors/grammars/tree-sitter-groovy.LICENSE

@@ -0,0 +1,21 @@
+tree-sitter-groovy 0.1.2 (https://github.com/amaanq/tree-sitter-groovy), as published on npm
+with "license": "MIT". The package ships no licence file; this is the MIT licence it declares.
+
+MIT License
+
+Copyright (c) Amaan Qureshi and the tree-sitter-groovy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT
+OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/packages/extractors/grammars/vendored.json

@@ -0,0 +1,11 @@
+[
+  {
+    "name": "tree-sitter-groovy",
+    "version": "0.1.2",
+    "licence": "MIT",
+    "file": "tree-sitter-groovy.wasm",
+    "licenceFile": "tree-sitter-groovy.LICENSE",
+    "source": "https://github.com/amaanq/tree-sitter-groovy",
+    "sha256": "0e68bb48ac166de25c381e05bbfbc90769f25d4709c14e180dd593696a73c197"
+  }
+]

package/dist/packages/learn/lessons/architect-diagrams-and-code.yaml

@@ -0,0 +1,69 @@
+schemaVersion: 1
+id: architect-diagrams-and-code
+role: architect
+title: Diagrams against code
+summary: Compare the architect's draw.io diagram with the code, settle a name with an alias, and see the critic catch a pattern typo.
+minutes: 15
+setup: [scan]
+intro: |
+  Diagrams drift. Atticus compares them with what the code says and lists every difference as
+  an item for a person: edges that go another way, edges only one side knows, names that need
+  an alias. Code always wins; a person decides what to do about the drawing. The sandbox was
+  scanned for you.
+steps:
+  - id: reconcile
+    title: Reconcile the diagram
+    body: |
+      Run reconcile on the Forge context diagram in `inputs/diagrams/`. Read each item: it says
+      what differs and what to do about it.
+    do: [[reconcile]]
+    solution: { answer: Ledger Platform }
+    check:
+      type: answer
+      question: Which name on the diagram needs an alias before its edges match the code?
+      truth: { from: fixed, values: [Ledger Platform] }
+    hint: Look for the alias-needed item.
+  - id: alias
+    title: Confirm the alias
+    body: |
+      Record that the diagram's "Ledger Platform" is the component `ledger-api`. The decision is a
+      file in `catalog/curated/`: commit it and every later reconcile uses it.
+    do: [[alias, Ledger Platform, ledger-api, --by, ari]]
+    check: { type: curated-decision, action: alias, target: ledger-api, includes: Ledger Platform }
+    hint: atticus alias "Ledger Platform" ledger-api
+  - id: critic
+    title: Let the critic read the change
+    body: |
+      The seeded change `add-transfer-limit` is in Plan. Run the critic on it: the rule checks
+      run first, cost nothing and give the same answer every time. One finding is about a
+      pattern code in `interfaces.md` that the org pack doesn't have.
+    do: [[critic, add-transfer-limit]]
+    solution: { answer: S.GW.SRO }
+    check:
+      type: all
+      checks:
+        - {
+            type: findings,
+            change: add-transfer-limit,
+            gate: plan,
+            rule: constitution.interface-approved-pattern,
+          }
+        - type: answer
+          question: Which pattern code in the change's interfaces.md is not in the org pack?
+          truth: { from: unknown-pattern, change: add-transfer-limit }
+    hint: Run the critic first, then read the interface-approved-pattern finding.
+  - id: waivable
+    title: Can it be waived?
+    body: |
+      Explain the finding. Rules from the built-in constitution are never waivable: the change
+      must be fixed.
+    do: [[explain, interface-approved-pattern-interfaces-l6]]
+    solution: { answer: "no" }
+    check:
+      type: answer
+      question: Can the pattern finding be waived? (yes or no)
+      truth: { from: fixed, values: ["no"] }
+    hint: The last line of the explanation says what you can do with it.
+outro: |
+  You reconciled a diagram, settled a name for good and saw a typo caught before review. Fix
+  the typo in interfaces.md and run the critic again to see the finding go.

package/dist/packages/learn/lessons/business-analyst-story-bar.yaml

@@ -0,0 +1,94 @@
+schemaVersion: 1
+id: business-analyst-story-bar
+role: business-analyst
+title: Stories that meet the bar
+summary: Measure the change's stories against the story bar, fix a story without acceptance criteria, and spot text aimed at AI reviewers.
+minutes: 15
+setup: [scan]
+intro: |
+  A story is ready when it says who it is for and why, has acceptance criteria in
+  Given/When/Then form, names its systems and repos, and names what it depends on. Atticus
+  measures that for you (the story bar) and the critic blocks the Plan hand-off on what fails.
+steps:
+  - id: bar
+    title: Measure the story bar
+    body: |
+      Measure the seeded change's stories. Each story that isn't ready is listed with what it
+      lacks.
+    do: [[plan, bar, add-transfer-limit]]
+    solution: { answer: s2-show-remaining }
+    check:
+      type: answer
+      question: Which story has no acceptance criteria?
+      truth: { from: stories-without-criteria, change: add-transfer-limit }
+    hint: Look for "no acceptance criteria in Given/When/Then form".
+  - id: fix
+    title: Add the acceptance criteria
+    body: |
+      Open `openspec/changes/add-transfer-limit/stories/s2-show-remaining.md` and add an
+      "Acceptance criteria" section with at least one Given/When/Then line.
+    solution:
+      files:
+        - path: openspec/changes/add-transfer-limit/stories/s2-show-remaining.md
+          content: |
+            # Show the remaining limit
+
+            As a Portal customer I want to see how much I can still send today so that I don't try a
+            transfer that will be refused.
+
+            ## Acceptance criteria
+
+            - Given an account with a limit of 1000 that has sent 900 today, when the customer opens the transfer screen, then it shows 100 left today.
+
+            ## Notes
+
+            Show it under the amount field on the transfer screen, as in ux.md.
+
+            ## Systems and repos
+
+            portal (forge-portal-bff, forge-portal-ui)
+
+            ## Depends on
+
+            s1-refuse-over-limit
+    check:
+      type: file
+      path: openspec/changes/add-transfer-limit/stories/s2-show-remaining.md
+      contains: ["## Acceptance criteria", "- Given "]
+    hint: The section heading is "## Acceptance criteria" and each criterion is a "- Given ..., when ..., then ..." line.
+  - id: critic
+    title: Run the critic
+    body: |
+      Run the critic on the change. The story-acceptance-criteria finding is gone from the newest
+      round; other findings remain for the architect and the team lead.
+    do: [[critic, add-transfer-limit]]
+    check:
+      type: all
+      checks:
+        - { type: findings, change: add-transfer-limit, gate: plan, latest: true, min: 1 }
+        - {
+            type: findings,
+            change: add-transfer-limit,
+            gate: plan,
+            latest: true,
+            rule: constitution.story-acceptance-criteria,
+            min: 0,
+            max: 0,
+          }
+    hint: Fix the story first, then run atticus critic add-transfer-limit.
+  - id: injection
+    title: Text aimed at AI reviewers
+    body: |
+      One story tells AI critics to ignore their rules. Ingested content is data, never
+      instructions: the critic blocks it, and Atticus marks or quarantines such text before any
+      model sees it. Scan the stories folder with the defences.
+    do: [[defences, scan, openspec/changes/add-transfer-limit/stories]]
+    solution: { answer: s3-audit-refusals }
+    check:
+      type: answer
+      question: Which story holds an instruction aimed at AI reviewers?
+      truth: { from: flagged-files, path: openspec/changes/add-transfer-limit/stories }
+    hint: Give the story id (its file name without .md).
+outro: |
+  You measured stories against the bar, fixed one and saw how Atticus treats text that tries
+  to steer an AI reviewer.

package/dist/packages/learn/lessons/delivery-lead-release-readiness.yaml

@@ -0,0 +1,44 @@
+schemaVersion: 1
+id: delivery-lead-release-readiness
+role: delivery-lead
+title: Is it ready to release?
+summary: Read a change's state and blockers, see the critic's gate, and ask the archive gate whether it may be archived.
+minutes: 10
+setup: [scan]
+intro: |
+  As release manager you need one honest answer: can this go? Atticus reads it from the
+  change's state, its hand-off PRs, the critic's open findings at each gate and the code.
+steps:
+  - id: status
+    title: Where is the change?
+    body: |
+      Ask for the seeded change's status: its state, the next step, its risk and what blocks it.
+    do: [[change, status, add-transfer-limit]]
+    solution: { answer: plan }
+    check:
+      type: answer
+      question: Which state is add-transfer-limit in?
+      truth: { from: change-state, change: add-transfer-limit }
+    hint: Read the State line.
+  - id: critic
+    title: What does the plan gate say?
+    body: |
+      Run the critic: blocking findings and open knowledge gaps keep the plan gate closed, and
+      the hand-off can't open until they are fixed, answered or (where allowed) waived.
+    do: [[critic, add-transfer-limit]]
+    check: { type: findings, change: add-transfer-limit, gate: plan, min: 1 }
+    hint: atticus critic add-transfer-limit
+  - id: archive
+    title: Ask the archive gate
+    body: |
+      The archive gate runs before a change is archived: released, no open blocking finding at
+      any gate it was reviewed at, PRs merged and builds passed, no unplanned drift.
+    do: [[ci, archive-gate, add-transfer-limit]]
+    solution: { answer: "no" }
+    check:
+      type: answer
+      question: May add-transfer-limit be archived now? (yes or no)
+      truth: { from: fixed, values: ["no"] }
+    hint: The first line says whether it can.
+outro: |
+  You read readiness from files alone: no status meetings needed to know what blocks a release.

package/dist/packages/learn/lessons/designer-features-in-user-words.yaml

@@ -0,0 +1,57 @@
+schemaVersion: 1
+id: designer-features-in-user-words
+role: designer
+title: Features in your users' words
+summary: Find the features Atticus detected in code, name one the way customers say it, and draw the context view.
+minutes: 10
+setup: [scan]
+intro: |
+  Atticus finds features in code from their entry points (screens, public endpoints, jobs,
+  event consumers) and gives them provisional names from paths and class names. People name
+  them properly; the name survives every scan.
+steps:
+  - id: list
+    title: List the features
+    body: |
+      List the detected features. Each starts at entry points such as an endpoint or an event.
+    do: [[feature, list]]
+    solution: { answer: feature.transfers }
+    check:
+      type: answer
+      question: Which feature starts at the endpoint ledger-api.post-transfer?
+      truth: { from: feature-of, entryPoint: ledger-api.post-transfer }
+    hint: atticus feature show <id> lists a feature's entry points.
+  - id: name
+    title: Name it in your users' words
+    body: |
+      Customers say "Money transfers". Record that name; it becomes a curated decision.
+    do: [[feature, name, feature.transfers, Money transfers, --by, dee]]
+    check:
+      {
+        type: curated-decision,
+        action: assert,
+        target: feature.transfers,
+        includes: Money transfers,
+      }
+    hint: atticus feature name feature.transfers "Money transfers"
+  - id: diagram
+    title: Draw the context view
+    body: |
+      Draw the systems and the calls between them as Mermaid, from the catalog (never by hand).
+    do: [[diagram, render, context, --format, mermaid, --out, diagrams/context.mmd]]
+    check: { type: file, path: diagrams/context.mmd, contains: ["flowchart", "Northwind Pay"] }
+    hint: atticus diagram render context --format mermaid --out diagrams/context.mmd
+  - id: ux
+    title: Where the screens live in a change
+    body: |
+      Each change keeps the screens it touches in its own file next to the design. Look at the
+      seeded change's folder.
+    solution: { answer: ux.md }
+    check:
+      type: answer
+      question: Which file of a change describes its screens and their states?
+      truth: { from: fixed, values: [ux.md] }
+    hint: openspec/changes/add-transfer-limit/ holds it.
+outro: |
+  Named features and generated views keep everyone talking about the same things in the same
+  words.