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

package/dist/fixtures/forge/metarepo/org-pack/checklists/architecture.yaml

@@ -0,0 +1,115 @@
+# Architecture and release checks for the Forge platform. Contract C3.
+# Hand-written sample; the critic that runs it arrives in M3. Each rule names the
+# seeded discrepancy in fixtures/forge/expected/discrepancies.yaml it should catch.
+schemaVersion: 1
+name: forge-architecture
+version: 0.1.0
+description: Integration, resilience and operability checks for changes on the Forge platform.
+rules:
+  - id: vendor-calls-through-gateway
+    title: Calls to vendors go through the gateway
+    description: Catches d01. Pattern S.GW.VND requires the gateway between a service and an external vendor.
+    layer: constitution
+    lens: architecture
+    appliesTo: { artifacts: [interfaces, catalog] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: interface-via-matches-pattern
+      params: { pattern: S.GW.VND, via: gateway }
+    waivable: false
+    source: wiki/integration-patterns.md
+    needs:
+      - kind: Interface
+        field: via
+        scope: touched-interfaces
+        question: "Does ${record} call the vendor directly or through the gateway?"
+
+  - id: pattern-code-known
+    title: Every pattern code is in the registry
+    description: Catches d07. A code that isn't in the pattern registry is usually a typo.
+    layer: org
+    lens: architecture
+    appliesTo: { artifacts: [interfaces] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: pattern-code-in-registry
+    waivable: true
+    source: wiki/integration-patterns.md
+
+  - id: every-hop-labelled
+    title: Every hop names its pattern
+    description: Catches d08.
+    layer: org
+    lens: architecture
+    appliesTo: { artifacts: [interfaces] }
+    severity: risk
+    check:
+      type: deterministic
+      check: interface-has-pattern
+    waivable: false
+    source: wiki/integration-patterns.md
+
+  - id: vendor-timeouts-set
+    title: Vendor calls have timeouts and retries
+    description: Raises d09 as a knowledge gap when the settings are unknown.
+    layer: org
+    lens: architecture
+    appliesTo: { artifacts: [design, catalog] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: settings-present
+      params: { settingKinds: [timeout, retry], forVia: [direct, gateway], forBoundary: vendor }
+    waivable: true
+    source: Platform resilience standard
+    needs:
+      - kind: Setting
+        field: settingKind
+        scope: touched-components
+        freshForDays: 180
+        question: "What timeout and retry settings does ${record} use for its vendor calls?"
+
+  - id: jobs-have-alerts
+    title: Jobs and services have alerts
+    description: Raises d10 as a knowledge gap.
+    layer: org
+    lens: release
+    appliesTo: { artifacts: [catalog, release] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: observability-present
+      params: { assetKinds: [alert] }
+    waivable: true
+    source: Platform operability standard
+    needs:
+      - kind: ObservabilityAsset
+        scope: touched-components
+        question: "What alerts or dashboards exist for ${record}?"
+
+  - id: story-has-acceptance-criteria
+    title: Every story has acceptance criteria
+    description: Catches d13.
+    layer: constitution
+    lens: story
+    appliesTo: { artifacts: [stories] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: story-has-acceptance-criteria
+    waivable: false
+    source: Story quality bar
+
+  - id: design-has-rollback
+    title: The design says how to roll back
+    layer: team
+    lens: delivery
+    appliesTo: { artifacts: [design] }
+    severity: risk
+    check:
+      type: ai
+      prompt: Read the design's rollout section. Report a finding if it does not say how each repo's change is rolled back, in what order, and what happens to data written in between. Quote the passage you relied on.
+    waivable: false
+    source: Team practice

package/dist/fixtures/forge/metarepo/org-pack/dialects/forge.yaml

@@ -0,0 +1,111 @@
+# The Forge dialect: teaches the scanner the invented in-house Forge framework.
+# Contract C2. Hand-written sample; the rule engine that runs it arrives in M1.
+schemaVersion: 1
+name: forge
+version: 0.1.0
+description: Forge services declare endpoints, clients and events with annotations, and name themselves in forge.yaml.
+extends: []
+appliesTo:
+  repoTypes: [forge-service]
+  marker: forge.yaml
+layout:
+  sourceRoots: [src/main/java]
+  configFiles: [src/main/resources/application.yml]
+rules:
+  - id: forge-endpoint
+    description: A method annotated @ForgeEndpoint serves a REST endpoint of the service named in forge.yaml.
+    match:
+      annotation: ForgeEndpoint
+      target: method
+      files: ["src/main/java/**/*.java"]
+    emit:
+      kind: Endpoint
+      id: "${yaml:forge.yaml#service}.${attr.method | lower}-${member.name | slug}"
+      fields:
+        component: "${yaml:forge.yaml#service}"
+        endpointType: rest
+        method: "${attr.method | upper}"
+        pathOrTopic: "${attr.path}"
+        normalizedPath: "${attr.path | normalizePath}"
+        auth: "${attr.auth | default('none')}"
+      evidence: { source: code, side: callee }
+    confidence: verified
+
+  - id: forge-client-call
+    description: A method annotated @ForgeCall in a @ForgeClient interface calls another service directly (not through the gateway).
+    match:
+      annotation: ForgeCall
+      target: method
+      files: ["src/main/java/**/*.java"]
+    emit:
+      kind: Interface
+      fields:
+        from: "${yaml:forge.yaml#service}"
+        to: "${annotation.ForgeClient.service}"
+        via: direct
+        method: "${attr.method | upper}"
+        normalizedPath: "${attr.path | normalizePath}"
+        sync: sync
+      evidence: { source: code, side: caller }
+    confidence: inferred
+
+  - id: forge-publish
+    description: A method annotated @ForgePublish publishes to a topic; the consumer is resolved later from topic configs.
+    match:
+      annotation: ForgePublish
+      target: method
+      files: ["src/main/java/**/*.java"]
+    emit:
+      kind: Unresolved
+      id: "${yaml:forge.yaml#service}.publish.${attr.topic | slug}"
+      fields:
+        unresolvedKind: event-publish
+        raw: "${attr.topic}"
+        owner: "${yaml:forge.yaml#service}"
+      evidence: { source: code, side: caller }
+    confidence: inferred
+
+  - id: forge-subscribe
+    description: A method annotated @ForgeSubscribe consumes a topic; the producer is resolved later from topic configs.
+    match:
+      annotation: ForgeSubscribe
+      target: method
+      files: ["src/main/java/**/*.java"]
+    emit:
+      kind: Unresolved
+      id: "${yaml:forge.yaml#service}.subscribe.${attr.topic | slug}"
+      fields:
+        unresolvedKind: event-subscribe
+        raw: "${attr.topic}"
+        owner: "${yaml:forge.yaml#service}"
+      evidence: { source: code, side: callee }
+    confidence: inferred
+
+tests:
+  - name: endpoints and the direct vendor call in forge-ledger
+    fixture: ../../../repos/forge-ledger
+    expect:
+      - kind: Endpoint
+        id: ledger-api.get-balance
+        method: GET
+        pathOrTopic: /accounts/{id}/balance
+        normalizedPath: /accounts/{}/balance
+        auth: oauth2
+      - kind: Endpoint
+        id: ledger-api.post-transfer
+        method: POST
+        pathOrTopic: /transfers
+      - kind: Interface
+        id: if-e7344c9455608119
+        from: ledger-api
+        to: northwind-pay
+        via: direct
+        method: POST
+        normalizedPath: /v2/payments
+    absent: [ledger-api.get-accounts]
+  - name: a service with no forge.yaml produces nothing
+    files:
+      src/main/java/x/A.java: |
+        @ForgeEndpoint(method = "GET", path = "/a")
+        public void a() {}
+    expect: []

package/dist/fixtures/forge/metarepo/org-pack/gates.yaml

@@ -0,0 +1,22 @@
+schemaVersion: 1
+gates:
+  - id: design
+    phase: design
+    approvers: [architect]
+    checklists: [forge-architecture]
+    checks: [{ check: openspec-validate }]
+  - id: plan
+    phase: plan
+    approvers: [team-lead]
+    checklists: [forge-architecture]
+    checks: [{ check: openspec-validate }]
+  - id: build
+    phase: build
+    approvers: [developer]
+    checks: [{ check: tests-pass }, { check: coverage, params: { minPercent: 80 } }]
+  - id: release
+    phase: release
+    approvers: [delivery-lead, sre]
+    minApprovals: 2
+    checklists: [forge-architecture]
+    checks: [{ check: snow-requests-closed }]

package/dist/fixtures/forge/metarepo/org-pack/pack.yaml

@@ -0,0 +1,11 @@
+# The Forge org pack (fixture). Contract C6. change-types.yaml and test-strategy.yaml are
+# left out on purpose: the built-in defaults apply until a team writes its own.
+schemaVersion: 1
+name: forge
+version: 0.1.0
+owner: team-platform
+reviewWindowDays: 90
+freshness:
+  Setting: 180
+  ObservabilityAsset: 180
+  Pattern: 365

package/dist/fixtures/forge/metarepo/org-pack/patterns/A.EB.PUB.yaml

@@ -0,0 +1,12 @@
+schemaVersion: 1
+code: A.EB.PUB
+name: Asynchronous publish to the event bus
+definition: A service publishes an event to a topic on the event bus.
+interaction: async
+route: event-bus
+targetType: product
+controls: [Schema in the registry, dead-letter topic]
+detection: { via: [event-bus], sync: async, hints: [kafka.send, "@ForgePublish"] }
+source: inputs/wiki/integration-patterns.md
+version: 1.0.0
+status: confirmed

package/dist/fixtures/forge/metarepo/org-pack/patterns/D.JDBC.yaml

@@ -0,0 +1,12 @@
+schemaVersion: 1
+code: D.JDBC
+name: Direct database access
+definition: A component reads or writes another component's database directly.
+interaction: data-access
+route: jdbc
+targetType: data-store
+controls: [Read-only account, owner approval]
+detection: { hints: [JdbcTemplate, DataSource] }
+source: inputs/wiki/integration-patterns.md
+version: 1.0.0
+status: to-review

package/dist/fixtures/forge/metarepo/org-pack/patterns/S.DIR.BFF.yaml

@@ -0,0 +1,12 @@
+schemaVersion: 1
+code: S.DIR.BFF
+name: Synchronous, direct from a UI to its own BFF
+definition: A browser application calling its own backend-for-frontend directly.
+interaction: sync
+route: direct
+targetType: product
+controls: [Session auth]
+detection: { via: [direct], sync: sync, sameSystem: true, hints: [fetch, axios] }
+source: inputs/wiki/integration-patterns.md
+version: 1.0.0
+status: confirmed

package/dist/fixtures/forge/metarepo/org-pack/patterns/S.GW.SOR.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 1
+code: S.GW.SOR
+name: Synchronous via the gateway to a system of record
+definition: A synchronous call that passes through the gateway to an internal system of record.
+interaction: sync
+route: gateway
+targetType: product
+controls: [OAuth2 at the gateway, timeout under 3 s, circuit breaker]
+resilience: { timeoutMs: 3000, circuitBreaker: true }
+detection: { via: [gateway], sync: sync, targetBoundary: product }
+source: inputs/wiki/integration-patterns.md
+version: 1.0.0
+status: confirmed

package/dist/fixtures/forge/metarepo/org-pack/patterns/S.GW.VND.yaml

@@ -0,0 +1,14 @@
+schemaVersion: 1
+code: S.GW.VND
+name: Synchronous via the gateway to a vendor
+definition: A synchronous call to an external vendor that passes through the gateway.
+interaction: sync
+route: gateway
+targetType: vendor
+controls: [OAuth2 or mTLS at the gateway, timeout, retry with idempotency key]
+resilience: { retries: 2 }
+detection: { via: [gateway], sync: sync, targetBoundary: vendor }
+checklist: [vendor-calls-through-gateway, vendor-timeouts-set]
+source: inputs/wiki/integration-patterns.md
+version: 1.0.0
+status: confirmed

package/dist/fixtures/forge/metarepo/org-pack/process/change-templates/feature.md

@@ -0,0 +1,37 @@
+---
+id: feature
+name: New feature (Forge)
+changeType: feature
+description: The Forge platform's brief for a new feature. Replaces the built-in feature template.
+---
+# {{title}}
+
+<!-- Brief for {{id}} ({{type}}), started by {{by}} on {{date}}. Replace every comment with your own words; the proposal is drafted from this file. -->
+
+## Problem
+
+<!-- Who has the problem, what it costs them today, and why now. -->
+
+## Outcome
+
+<!-- What is true when this is done, in the customer's words. -->
+
+## Scope
+
+<!-- In scope, and what is out of scope. -->
+
+## Ledger impact
+
+<!-- Does this change balances, transfers or entries in Ledger? Say how, or write "None". -->
+
+## Partners
+
+<!-- Does Northwind Pay or another partner need to change anything? Say what, or write "None". -->
+
+## Success measures
+
+<!-- How we will know it worked. -->
+
+## Open questions
+
+<!-- Anything you don't know yet, and who might. -->

package/dist/fixtures/forge/metarepo/org-pack/process/skills/add-forge-endpoint/SKILL.md

@@ -0,0 +1,17 @@
+---
+id: add-forge-endpoint
+name: Add an endpoint to a Forge service
+description: How to add a REST endpoint to a service built on the Forge framework, with its OpenAPI entry and tests.
+appliesTo:
+  repoTypes: [forge-service]
+  artifacts: [tasks]
+owner: team-ledger
+source: inputs/wiki/ledger-solution-spec.md
+status: active
+reviewedAt: 2026-10-01
+---
+
+1. Add a method annotated `@ForgeEndpoint(method, path, auth)` to the service's endpoints class.
+2. Add the operation to `api/<service>-openapi.yaml` with the same method and path.
+3. Write a test that calls the endpoint and checks the response and the error cases.
+4. If the endpoint is public, raise a gateway route request (process/snow/gateway-route).

package/dist/fixtures/forge/metarepo/org-pack/process/snow/firewall-rule.yaml

@@ -0,0 +1,14 @@
+schemaVersion: 1
+id: firewall-rule
+name: Network firewall rule
+requestType: Network firewall rule
+fields:
+  - { name: Source app, required: true, from: "${record}" }
+  - { name: Destination host, required: true }
+  - { name: Port, required: true }
+  - { name: Protocol, required: true }
+  - { name: Business justification, required: true }
+approvers: [network team]
+leadTimeDays: 10
+triggers:
+  - { kind: Interface, change: planned-new, where: { via: direct } }

package/dist/fixtures/forge/metarepo/org-pack/process/snow/gateway-route.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 1
+id: gateway-route
+name: New gateway proxy
+requestType: Gateway proxy deployment
+fields:
+  - { name: Proxy name, required: true, from: "${record}" }
+  - { name: Base path, required: true }
+  - { name: Target, required: true }
+approvers: [gateway team]
+leadTimeDays: 5
+triggers:
+  - { kind: GatewayRoute, change: planned-new }
+alsoNeeds: [firewall-rule]

package/dist/fixtures/forge/metarepo/org-pack/profiles/forge/profile.yaml

@@ -0,0 +1,12 @@
+schemaVersion: 1
+platform: forge
+name: Forge payments platform
+systems:
+  - { id: portal, name: Portal, boundary: product, owner: team-portal, aliases: [Portal UI, Portal BFF] }
+  - { id: ledger, name: Ledger, boundary: product, owner: team-ledger, aliases: [Ledger Platform] }
+  - { id: reports, name: Reports, boundary: product, owner: team-reports, aliases: [Reports Job] }
+  - { id: audit, name: Audit, boundary: internal }
+  - { id: northwind-pay, name: Northwind Pay, boundary: vendor }
+environments: [dev, test, prod]
+legend: { new: [New], modify: [Modify, Changed], retire: [Retire] }
+gates: [design, release]

package/dist/fixtures/forge/metarepo/org-pack/profiles/forge/repos.manifest.yaml

@@ -0,0 +1,44 @@
+# The Forge platform's repos. Hand-written; matches fixtures/forge/repos.
+schemaVersion: 1
+platform: forge
+repos:
+  - id: forge-portal-ui
+    url: https://git.example.com/forge/forge-portal-ui.git
+    type: spa
+    owner: team-portal
+    component: portal-ui
+    system: portal
+  - id: forge-portal-bff
+    url: https://git.example.com/forge/forge-portal-bff.git
+    type: spring-boot
+    owner: team-portal
+    component: portal-bff
+    system: portal
+  - id: forge-ledger
+    url: https://git.example.com/forge/forge-ledger.git
+    type: forge-service
+    owner: team-ledger
+    component: ledger-api
+    system: ledger
+    dialects: [forge]
+  - id: forge-reports-job
+    url: https://git.example.com/forge/forge-reports-job.git
+    type: spring-batch
+    owner: team-reports
+    component: reports-job
+    system: reports
+  - id: forge-gateway
+    url: https://git.example.com/forge/forge-gateway.git
+    type: gateway
+    owner: team-platform
+    hosts: [gateway.forge.example]
+    sparse: [proxies/ledger-v1]
+  - id: forge-events
+    url: https://git.example.com/forge/forge-events.git
+    type: event-config
+    owner: team-platform
+  - id: forge-infra
+    url: https://git.example.com/forge/forge-infra.git
+    defaultBranch: main
+    type: infra
+    owner: team-platform

package/dist/fixtures/forge/metarepo/org-pack/roles.yaml

@@ -0,0 +1,14 @@
+schemaVersion: 1
+enabledOptional: [data-architect, sre]
+mappings:
+  - { group: "Forge Architects", role: architect }
+  - { group: "Forge Ledger Team", role: developer }
+  - { group: "Forge Platform", role: platform-lead }
+approvals:
+  release-go-no-go: { roles: [delivery-lead] }
+  waiver: { roles: [architect], groups: ["Forge Architects"] }
+  snow-submission: { roles: [delivery-lead] }
+  org-pack-change: { roles: [platform-lead] }
+separation:
+  - actions: ["author:design", "approve:design"]
+    reason: The author of a design can't approve it.

package/dist/fixtures/forge/metarepo/org-pack/runtime.yaml

@@ -0,0 +1,14 @@
+schemaVersion: 1
+assistants: { allowed: [copilot, claude-code], default: copilot }
+editors: [vscode, intellij]
+modes: { allowed: [hand-off, headless-claude-code], default: hand-off }
+autonomy:
+  default: draft
+  capPerRepo: { forge-gateway: plan-only, forge-infra: plan-only }
+budgets: { defaultTokens: 150000 }
+retention: { runsDays: 30 }
+adapters:
+  workTracker: { type: mock }
+  serviceDesk: { type: mock }
+  gitHost: { type: mock }
+  notify: { type: mock }

package/dist/fixtures/forge/metarepo/org-pack/sources.yaml

@@ -0,0 +1,3 @@
+schemaVersion: 1
+wikis:
+  - { id: forge-wiki, type: markdown-folder, location: ../../inputs/wiki, owner: team-platform }

package/dist/fixtures/forge/repos/forge-events/topics/payments.initiated.yaml

@@ -0,0 +1,4 @@
+topic: payments.initiated
+producers: [portal-bff]
+consumers: [ledger-api]
+schema: schemas/payment-initiated.avsc

package/dist/fixtures/forge/repos/forge-events/topics/transfers.completed.yaml

@@ -0,0 +1,4 @@
+topic: transfers.completed
+producers: [ledger-api]
+consumers: [reports-job]
+schema: schemas/transfer-completed.avsc

package/dist/fixtures/forge/repos/forge-gateway/proxies/ledger-v1/apiproxy/ledger-v1.xml

@@ -0,0 +1,3 @@
+<APIProxy name="ledger-v1">
+  <Description>Ledger API, version 1</Description>
+</APIProxy>

package/dist/fixtures/forge/repos/forge-gateway/proxies/ledger-v1/apiproxy/policies/SpikeArrest.xml

@@ -0,0 +1,3 @@
+<SpikeArrest name="SpikeArrest">
+  <Rate>100ps</Rate>
+</SpikeArrest>

package/dist/fixtures/forge/repos/forge-gateway/proxies/ledger-v1/apiproxy/policies/VerifyOAuth.xml

@@ -0,0 +1,4 @@
+<OAuthV2 name="VerifyOAuth">
+  <Operation>VerifyAccessToken</Operation>
+  <Scope>ledger.read ledger.write</Scope>
+</OAuthV2>

package/dist/fixtures/forge/repos/forge-gateway/proxies/ledger-v1/apiproxy/proxies/default.xml

@@ -0,0 +1,14 @@
+<ProxyEndpoint name="default">
+  <PreFlow>
+    <Request>
+      <Step><Name>VerifyOAuth</Name></Step>
+      <Step><Name>SpikeArrest</Name></Step>
+    </Request>
+  </PreFlow>
+  <HTTPProxyConnection>
+    <BasePath>/ledger/v1</BasePath>
+  </HTTPProxyConnection>
+  <RouteRule name="default">
+    <TargetEndpoint>ledger</TargetEndpoint>
+  </RouteRule>
+</ProxyEndpoint>

package/dist/fixtures/forge/repos/forge-gateway/proxies/ledger-v1/apiproxy/targets/ledger.xml

@@ -0,0 +1,5 @@
+<TargetEndpoint name="ledger">
+  <HTTPTargetConnection>
+    <URL>http://ledger-api.forge.internal</URL>
+  </HTTPTargetConnection>
+</TargetEndpoint>

package/dist/fixtures/forge/repos/forge-infra/alerts/ledger-api.yaml

@@ -0,0 +1,5 @@
+# Alert definitions kept as code. reports-job has none (seeded gap).
+alerts:
+  - name: Ledger API error rate
+    component: ledger-api
+    expr: rate(http_errors_total{service="ledger-api"}[5m]) > 0.05

package/dist/fixtures/forge/repos/forge-infra/k8s/ledger-api.yaml

@@ -0,0 +1,15 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: ledger-api
+  namespace: prod
+spec:
+  replicas: 3
+  template:
+    spec:
+      containers:
+        - name: ledger-api
+          resources:
+            limits:
+              cpu: "1"
+              memory: 1Gi

package/dist/fixtures/forge/repos/forge-infra/k8s/portal-bff.yaml

@@ -0,0 +1,7 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: portal-bff
+  namespace: prod
+spec:
+  replicas: 2

package/dist/fixtures/forge/repos/forge-infra/terraform/ledger-db.tf

@@ -0,0 +1,9 @@
+resource "google_sql_database_instance" "ledger_db" {
+  name             = "ledger-db"
+  database_version = "POSTGRES_15"
+  settings {
+    backup_configuration {
+      enabled = true
+    }
+  }
+}

package/dist/fixtures/forge/repos/forge-ledger/api/ledger-openapi.yaml

@@ -0,0 +1,31 @@
+openapi: 3.0.3
+info:
+  title: Ledger API
+  version: 1.0.0
+paths:
+  /accounts/{id}/balance:
+    get:
+      operationId: getBalance
+      security:
+        - oauth2: [ledger.read]
+      responses:
+        "200":
+          description: Balance
+  /transfers:
+    post:
+      operationId: createTransfer
+      security:
+        - oauth2: [ledger.write]
+      responses:
+        "201":
+          description: Created
+components:
+  securitySchemes:
+    oauth2:
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: https://auth.forge.example/token
+          scopes:
+            ledger.read: read balances
+            ledger.write: create transfers

package/dist/fixtures/forge/repos/forge-ledger/forge.yaml

@@ -0,0 +1,4 @@
+# Forge service descriptor (the invented in-house framework)
+service: ledger-api
+system: ledger
+framework: forge

package/dist/fixtures/forge/repos/forge-ledger/src/main/java/forge/ledger/LedgerEndpoints.java

@@ -0,0 +1,13 @@
+package forge.ledger;
+
+import forge.framework.*;
+
+@ForgeService(name = "ledger-api")
+public class LedgerEndpoints {
+
+  @ForgeEndpoint(method = "GET", path = "/accounts/{id}/balance", auth = "oauth2")
+  public Balance balance(String id) { return null; }
+
+  @ForgeEndpoint(method = "POST", path = "/transfers", auth = "oauth2")
+  public TransferResult transfer(TransferRequest request) { return null; }
+}