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

package/dist/packages/naysayer/constitution/constitution.yaml

@@ -0,0 +1,286 @@
+# Atticus's built-in constitution. Contract C3.
+#
+# These rules apply to every change, at every gate where their artifacts are due. They are
+# never waivable, a team or org pack can only tighten them, and a pack that drops or loosens
+# one is refused. They are data, so the critic's code holds no policy of its own: each rule
+# names a built-in deterministic check and the catalog facts it needs.
+#
+# Each rule answers one of the four questions the critic asks of every draft (ADR 0124 addendum,
+# Part 4): is it true to the code, is it complete, is it safe to build, can it ship. `question` says
+# which; `lens` keeps the role lens the rule was first written for, so a pack that tightens it with
+# that lens still matches. The two rules added with the questions are written for theirs; the
+# timeout and rollback checks added with them are the starter review's (starter/review.yaml), the
+# organisation's to change (the product owner's decision of 2026-10-24).
+schemaVersion: 1
+name: constitution
+version: 1.0.0
+description: Rules every change meets, whatever the organisation or team configures.
+rules:
+  - id: constitution.interface-approved-pattern
+    title: Every interface names an approved integration pattern
+    description: A hop without a pattern, or with a code that isn't a confirmed pattern in the registry, can't be checked for its controls.
+    layer: constitution
+    lens: architecture
+    question: safe
+    appliesTo: { artifacts: [interfaces] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: interface-pattern-approved
+      params: { statuses: [confirmed] }
+    waivable: false
+    source: Atticus constitution
+    needs: []
+
+  - id: constitution.interface-ends-in-catalog
+    title: No planned interface to a system missing from the catalog
+    description: A caller or callee the catalog doesn't know is either a typo or an unknown system nobody has looked at.
+    layer: constitution
+    lens: architecture
+    question: "true"
+    appliesTo: { artifacts: [interfaces, catalog] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: interface-ends-in-catalog
+    waivable: false
+    source: Atticus constitution
+    needs: []
+
+  - id: constitution.interface-ids-in-catalog
+    title: Existing interfaces keep their catalog id
+    description: A row naming an interface id must match the catalog; a row for a new hop says new and planned-new.
+    layer: constitution
+    lens: architecture
+    question: "true"
+    appliesTo: { artifacts: [interfaces, catalog] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: interface-ids-in-catalog
+    waivable: false
+    source: Atticus constitution
+    needs: []
+
+  - id: constitution.hop-resilience-stated
+    title: Every planned call states the timeouts and retries its pattern requires
+    description: The pattern's controls say which resilience settings a hop needs; each must be in the catalog or stated in interfaces.md or design.md.
+    layer: constitution
+    lens: architecture
+    question: safe
+    appliesTo: { artifacts: [interfaces, design, catalog] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: settings-present
+      params: { fromPattern: true }
+    waivable: false
+    source: Atticus constitution
+    needs:
+      - kind: Setting
+        field: settingKind
+        scope: touched-components
+        question: "What timeout, retry and circuit-breaker settings does ${record} use for its calls?"
+
+  - id: constitution.touched-components-known
+    title: Every touched component has a known owner, repo and interface
+    description: A component known only from a caller can't be checked; its owner is asked.
+    layer: constitution
+    lens: architecture
+    question: "true"
+    appliesTo: { artifacts: [catalog] }
+    severity: risk
+    check:
+      type: deterministic
+      check: knowledge-check
+      params: { check: component-source-known }
+    waivable: false
+    source: Atticus constitution
+    needs:
+      - kind: System
+        field: owner
+        scope: touched-systems
+        question: "Who owns ${record}?"
+      - kind: Component
+        field: repo
+        scope: touched-components
+        question: "Which repo holds the code of ${record}?"
+
+  - id: constitution.data-doc-present
+    title: data.md exists when a data store is touched
+    layer: constitution
+    lens: architecture
+    question: complete
+    appliesTo: { artifacts: [data, catalog] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: data-doc-present
+    waivable: false
+    source: Atticus constitution
+    needs: []
+
+  - id: constitution.data-change-has-migration
+    title: Every data change names its migration
+    layer: constitution
+    lens: architecture
+    question: ship
+    appliesTo: { artifacts: [data] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: data-migration-named
+    waivable: false
+    source: Atticus constitution
+    needs: []
+
+  - id: constitution.data-columns-classified
+    title: Every new column is classified, and personal data is classified as personal
+    layer: constitution
+    lens: architecture
+    question: safe
+    appliesTo: { artifacts: [data] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: data-columns-classified
+    waivable: false
+    source: Atticus constitution
+    needs: []
+
+  - id: constitution.data-retention-stated
+    title: Every new table says how long its rows are kept
+    layer: constitution
+    lens: architecture
+    question: safe
+    appliesTo: { artifacts: [data, catalog] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: data-retention-stated
+    waivable: false
+    source: Atticus constitution
+    needs:
+      - kind: Table
+        field: retention
+        scope: touched-data-stores
+        question: "How long are rows of ${record} kept, and when are they deleted?"
+
+  - id: constitution.story-acceptance-criteria
+    title: Every story has acceptance criteria
+    layer: constitution
+    lens: story
+    question: complete
+    appliesTo: { artifacts: [stories] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: story-has-acceptance-criteria
+    waivable: false
+    source: Atticus constitution
+    needs: []
+
+  - id: constitution.spec-scenarios-present
+    title: Every requirement has a scenario
+    layer: constitution
+    lens: business
+    question: complete
+    appliesTo: { artifacts: [specs] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: spec-scenarios-present
+    waivable: false
+    source: Atticus constitution
+    needs: []
+
+  # Retired with the four questions (ADR 0124 addendum, Part 4): a service-desk request is a
+  # person's manual step. atticus plan drafts snow.md from the triggers this check reads, and
+  # atticus release plan lists each draft as a request to file, with its required fields still
+  # missing. The check stays for an org pack that wants it as a rule of its own.
+  - id: constitution.snow-drafts-present
+    title: A service-desk draft exists for each firewall or gateway change
+    description: Request templates in the org pack say which catalog changes need a request; each needs a draft in snow.md with its required fields filled.
+    layer: constitution
+    lens: release
+    question: ship
+    appliesTo: { artifacts: [snow, interfaces] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: snow-drafts-present
+    waivable: false
+    source: Atticus constitution
+    needs: []
+    status: retired
+
+  - id: constitution.no-embedded-instructions
+    title: Artifacts hold no instructions aimed at AI agents
+    description: Ingested content is data, never instructions; text that tries to steer a reviewer or an agent is removed before review.
+    layer: constitution
+    lens: delivery
+    question: safe
+    appliesTo:
+      {
+        artifacts:
+          [brief, proposal, specs, interfaces, mappings, data, design, ux, stories, tasks, snow],
+      }
+    severity: blocking
+    check:
+      type: deterministic
+      check: no-embedded-instructions
+    waivable: false
+    source: Atticus constitution
+    needs: []
+
+  # ---- added with the four questions (ADR 0124 addendum, Part 4): code answers what code can.
+  # Never waivable (the product owner's decision of 2026-10-24); a person may still dismiss a
+  # finding as not relevant, with a reason.
+
+  - id: constitution.public-entry-auth
+    title: Every entry another system calls says how it authenticates
+    description: An entry point the change adds or changes that another system or the gateway calls needs an auth fact (the Endpoint's or the Interface's auth, or a gateway route that checks scopes). None known is asked of the owner; none at all blocks.
+    layer: constitution
+    lens: safe
+    question: safe
+    appliesTo: { artifacts: [interfaces, catalog] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: public-entry-auth
+    waivable: false
+    source: Atticus constitution
+    needs: []
+
+  - id: constitution.breaking-delta-consumers
+    title: A breaking change to an operation plans for every consumer the catalog knows
+    description: A retired operation breaks its callers; a changed one breaks them when a caller must change (a judgment, ADR 0117, asked of a person when nobody has made it). Each consumer the catalog knows and the change doesn't plan for is named.
+    layer: constitution
+    lens: safe
+    question: safe
+    appliesTo: { artifacts: [interfaces, catalog] }
+    severity: blocking
+    check:
+      type: deterministic
+      check: breaking-delta-consumers
+    waivable: false
+    source: Atticus constitution
+    needs: []
+
+  # ADR 0124 addendum A-callers: who a gateway route lets in. A route whose files name no consumer,
+  # that no person declared a caller of and that no call the catalog holds goes through is asked
+  # about, never passed in silence; a risk, so a person answers it rather than the gate blocking.
+  - id: constitution.route-callers-known
+    title: Every gateway route a change touches has a known caller
+    description: A gateway route that carries an operation the change modifies or retires names its consumers in its files, has a caller a person declared in the org pack's profile, or has a call the catalog holds going through it. When none of these says who calls it, who does is asked of the callee's owner.
+    layer: constitution
+    lens: architecture
+    question: complete
+    appliesTo: { artifacts: [interfaces, catalog] }
+    severity: risk
+    check:
+      type: deterministic
+      check: route-callers-known
+    waivable: false
+    source: Atticus constitution
+    needs: []

package/dist/packages/naysayer/starter/review.yaml

@@ -0,0 +1,256 @@
+# Built-in default written out by Atticus: the starter review (ADR 0120). Change it through a
+# pull request; delete the file to turn the starter review off (atticus upgrade won't add it back).
+#
+# Most are AI rules: the critic's lenses apply them to every draft a stage writes (ADR 0115) and
+# at each gate's critic round, judging what the draft means against the estate and the brief. The
+# last three are code checks (a call's timeout, a store write's rollback step, a note's cite) that run before any
+# lens, with no model.
+# This is the organisation's configuration, not the constitution: change a prompt or a severity,
+# make a blocking rule not waivable, retire a rule (status: retired) or delete it, and add your own.
+# A rule runs from the first gate where its artifacts are due (brief: define; design, data and
+# interfaces: design; stories and tasks: plan; the catalog: every gate), and again at each later
+# gate. Contract C3.
+#
+# Each rule asks part of one of the critic's four questions (ADR 0124 addendum, Part 4): is it true
+# to the code, is it complete, is it safe to build, can it ship. `question` says which, and that
+# question's lens applies it, to the change types that ask it (a type lists its questions). `lens`
+# names the role lens an AI rule was written for: a change type that still lists the old lens
+# names takes the rule when it lists that lens.
+schemaVersion: 1
+name: review
+version: 1.0.0
+description: The starter review. AI rules for the critic's true, complete, safe and ship lenses, from the define gate to the plan gate, and three code checks of the true, safe and ship questions.
+rules:
+  # ---- define: the feature placement, against the brief and the estate
+  - id: review.brief-outcomes-placed
+    title: Every outcome the brief states is placed
+    lens: business
+    question: complete
+    layer: org
+    appliesTo: { artifacts: [brief] }
+    severity: blocking
+    check:
+      type: ai
+      prompt: >-
+        List each outcome the brief states: what the change must achieve, and for whom. For each
+        one, find where the draft under review delivers it: the feature placement (feature.md and
+        feature.yaml) at the define gate, the target flows at design, the stories at plan. Report
+        each outcome the draft leaves out or delivers only in part, citing the brief's line for
+        that outcome and quoting it. Don't report what the brief puts out of scope.
+    waivable: true
+    source: Atticus starter review
+
+  - id: review.changed-flow-not-read
+    title: A flow the change alters isn't marked only read
+    lens: architecture
+    question: "true"
+    layer: org
+    appliesTo: { artifacts: [brief] }
+    severity: blocking
+    check:
+      type: ai
+      prompt: >-
+        For each flow the draft marks as only read, check against the estate and the brief whether
+        the change has to alter that flow's steps: a new step, a step that now sends, stores or
+        checks something new, or a step that must behave differently. Report each such flow,
+        citing and quoting the line that marks it read, and name the step that has to change. A
+        flow the change uses exactly as it is today is rightly marked read.
+    waivable: true
+    source: Atticus starter review
+
+  - id: review.assumed-capability-named
+    title: A capability the brief assumes but nothing in the estate does is named as a gap
+    lens: architecture
+    question: "true"
+    layer: org
+    appliesTo: { artifacts: [brief] }
+    severity: blocking
+    check:
+      type: ai
+      prompt: >-
+        Find each thing the brief takes for granted the systems already do, such as sending
+        notifications, keeping a new kind of record or calling an outside service. Look in the
+        estate for a flow, component or interface that does it today. When nothing in the estate
+        does it and the draft treats it as already there, instead of adding it as new work or
+        asking about it, report it, citing and quoting the line of the brief or the draft that
+        assumes it. Use kind knowledge-gap when only a person can say whether it exists.
+    waivable: true
+    source: Atticus starter review
+
+  # ---- design: the target flows and the data changes
+  - id: review.outcome-has-target-steps
+    title: Every outcome has the target-flow steps that deliver it
+    lens: architecture
+    question: complete
+    layer: org
+    appliesTo: { artifacts: [design] }
+    severity: blocking
+    check:
+      type: ai
+      prompt: >-
+        For each outcome the brief states, find the steps of the target flows (the design and the
+        target-flows files) that deliver it. Report an outcome no step delivers, or one whose steps
+        stop short because it needs a check, a stored value or a reply that no step has, citing and
+        quoting the brief's line for that outcome. If no brief is among the documents, report
+        nothing for this rule.
+    waivable: true
+    source: Atticus starter review
+
+  - id: review.shown-data-has-a-source
+    title: Data a step returns or shows comes from somewhere
+    lens: architecture
+    question: "true"
+    layer: org
+    appliesTo: { artifacts: [design, data] }
+    severity: blocking
+    check:
+      type: ai
+      prompt: >-
+        For each value a step of the target flows returns, shows to a person or sends on, find
+        where it comes from: a step that receives it, reads it from or writes it to a table, gets
+        it from another call, or works it out. Report a value that nothing in the target flows or
+        the estate gives, citing and quoting the step that returns or shows it, and say which step
+        would have to give it.
+    waivable: true
+    source: Atticus starter review
+
+  - id: review.new-column-complete
+    title: A new column has its classification and its migration
+    lens: architecture
+    question: safe
+    layer: org
+    appliesTo: { artifacts: [data, design] }
+    severity: blocking
+    check:
+      type: ai
+      prompt: >-
+        For each new or changed column in the data changes or the target flows, check that it has
+        a data classification and a migration that adds or changes it, and that the classification
+        fits what the column holds: a name, a contact detail, an account number or anything else
+        about a person is never public. Report a column that lacks either, or whose classification
+        understates what it holds, citing and quoting the column's line.
+    waivable: true
+    source: Atticus starter review
+
+  - id: review.hop-pattern-fits
+    title: Each integration hop follows an approved pattern that fits it
+    lens: architecture
+    question: safe
+    layer: org
+    appliesTo: { artifacts: [interfaces, design] }
+    severity: risk
+    check:
+      type: ai
+      prompt: >-
+        For each call, message or file transfer between systems that the change adds or changes,
+        check that the approved integration pattern it names fits what the hop does: a hop the
+        caller must not wait on isn't a synchronous call, a hop that must not be lost isn't fire
+        and forget, and a hop that carries personal data uses a pattern whose controls allow it.
+        Report a hop whose pattern doesn't fit, citing and quoting the hop's line and saying which
+        approved pattern would.
+    waivable: false
+    source: Atticus starter review
+
+  # ---- plan: the stories, their criteria and the requests
+  - id: review.outcome-has-story
+    title: Each outcome has a story
+    lens: story
+    question: complete
+    layer: org
+    appliesTo: { artifacts: [stories] }
+    severity: blocking
+    check:
+      type: ai
+      prompt: >-
+        For each outcome the brief states, find the story or stories that deliver it. Report an
+        outcome no story delivers, citing and quoting the brief's line for that outcome. If no
+        brief is among the documents, report nothing for this rule.
+    waivable: true
+    source: Atticus starter review
+
+  - id: review.criteria-testable
+    title: Each story's criteria are testable and name the data they check
+    lens: story
+    question: complete
+    layer: org
+    appliesTo: { artifacts: [stories] }
+    severity: risk
+    check:
+      type: ai
+      prompt: >-
+        Read each acceptance criterion of each story and task. Report a criterion a tester couldn't
+        turn into a test: one without a situation, an action and a result, or one whose result is a
+        vague word such as works, correctly, quickly or easily. Report also a criterion that doesn't
+        name the data it checks: the field, record, message or value whose state shows it passed.
+        Cite and quote the criterion's line.
+    waivable: false
+    source: Atticus starter review
+
+  - id: review.requests-raised-in-time
+    title: Requests and approvals are raised before the phase that needs them
+    lens: delivery
+    question: ship
+    layer: org
+    appliesTo: { artifacts: [tasks] }
+    severity: risk
+    check:
+      type: ai
+      prompt: >-
+        Read what the change needs from outside the team: the needs, and the request tasks in the
+        tasks and requests files, such as service-desk requests, access, approvals and sign-offs,
+        each with its lead time. For each one, check that a task raises it before the phase or the
+        task that depends on it, early enough for its lead time. Report a need no task raises, or
+        one raised too late for the work that waits on it, citing and quoting the line of the need
+        or the task.
+    waivable: false
+    source: Atticus starter review
+
+  # ---- code checks of the four questions (ADR 0124 addendum, Part 4; the product owner's decision
+  # of 2026-10-24): what code can answer before a model is asked, kept here rather than in the
+  # constitution so the organisation can change them. Each finding is a risk, which a person may
+  # dismiss with a reason; raise a rule to blocking to make it hold the gate (and waivable or not),
+  # retire it (status: retired) or delete it.
+  - id: review.call-timeout-stated
+    title: Every synchronous call the change plans has a timeout
+    description: A call with no timeout waits as long as the callee does. The fact is a timeout Setting for the caller and callee in the catalog, or a timeout stated for the call in interfaces.md or design.md; a pattern that requires more is the resilience rule's.
+    lens: safe
+    question: safe
+    layer: org
+    appliesTo: { artifacts: [interfaces, design, catalog] }
+    severity: risk
+    check:
+      type: deterministic
+      check: call-timeout-stated
+    waivable: false
+    source: Atticus starter review
+    needs: []
+
+  - id: review.store-write-rollback
+    title: Every store write has a rollback step
+    description: A table the change writes or alters (data.md, or a write step of a target flow) is named, or its migration is, under the rollback heading of design.md.
+    lens: ship
+    question: ship
+    layer: org
+    appliesTo: { artifacts: [data, design, catalog] }
+    severity: risk
+    check:
+      type: deterministic
+      check: store-write-rollback
+    waivable: false
+    source: Atticus starter review
+    needs: []
+
+  - id: review.note-cites-on-line
+    title: A criterion from an attached note quotes the note's line
+    description: A story criterion that says it comes from a file a person attached to the change (From inputs/<file>:<line>) quotes words that are on that line of what was read from the file, a file attached and not held out of AI steps (ADR 0113 addendum).
+    lens: "true"
+    question: "true"
+    layer: org
+    appliesTo: { artifacts: [stories] }
+    severity: risk
+    check:
+      type: deterministic
+      check: note-cites-on-line
+    waivable: false
+    source: Atticus starter review
+    needs: []