@afokapu/atdd-bun 0.1.0

package/planner-nodes/nodes/planner.plan.spec-is-schema-valid.convention.yaml

@@ -0,0 +1,61 @@
+schema_version: 1.0.0
+rule_id: planner.plan.spec-is-schema-valid
+kind: policy
+status: active
+name: Plan unit specs are schema-valid
+statement: A hand-authored plan unit spec is validated against its artifact schema
+  — well-formedness at Compose, completeness at Ratify — so the by-construction guarantee
+  atdd author makes is kept at the one layer where the spec is written by hand.
+terms:
+- term_id: well_formedness_at_compose
+  text: Compose checks only the values a spec actually carries (pattern, enum, type,
+    additionalProperties). Those are wrong the instant they are written, and refusing
+    them there is what planner.plan.session-lifecycle already asks of Compose ("candidate
+    decomposition convention-shaped").
+- term_id: completeness_at_ratify
+  text: required, minItems, minLength and minProperties are checked only at Ratify,
+    on kept units, before the lock. Compose is a drafting loop — add_unit upserts by
+    ref so a spec can be re-stated as it fills in — so an unfinished spec is a draft
+    there and a defect only once the operator asserts the set may be authored.
+- term_id: enforced_kinds
+  text: A kind whose schema describes the artifacts atdd actually authors RAISES.
+    Measured over this repo's plan/ tree, wagon (41/41), train (21/21), interlocking
+    (8/8) and the embedded acceptance shape all validate, so all four enforce.
+- term_id: advisory_kinds
+  text: A kind whose schema has drifted from the artifacts atdd authors REPORTS and
+    never blocks; the findings ride on the unit so they survive compaction and resurface
+    at Ratify. feature (134/188 failing) and wmbt (294/468 failing) are advisory —
+    wmbt.schema.json says in its own $comment that it is not a file gate. A repo promotes
+    a kind with plan.spec_validation.enforce in .atdd/config.yaml.
+- term_id: every_authorable_kind_is_governed
+  text: 'No authorable kind may be silently ungoverned. A kind whose artifact has
+    no schema is checked by its own writer''s validator instead, and a kind that is
+    checked by nothing must say so rather than return clean. `contract` is the case
+    that forced this: a contract IS a JSON schema, so it has no meta-schema to validate
+    against, and omitting it from the schema table made `check_unit_spec` report
+    nothing for all three rules `validate_contract` enforces across 14 registered
+    contracts (#2013). Silence that reads as approval is the defect this whole rule
+    exists to prevent.'
+- term_id: atomicity
+  text: The Ratify pass runs before locked is set, so a failure leaves the session
+    unlocked — the same contract the interlocking, verb-object and artifact-naming
+    gates keep.
+implementation:
+  type: validator
+  ref: test_plan_unit_spec_schema::test_compose_refuses_a_malformed_enforced_spec
+metadata:
+  severity: 4
+  disposition: strict
+validation:
+  family: presence
+  template: conditional_requirement
+  variant: planner_plan_spec_is_schema_valid
+  phase: CONFIRM
+  enforcement: confirm-blocking
+  subject_kind: plan-session
+  failure_evidence:
+  - session_id
+  - unit_ref
+  - unit_kind
+  - schema_file
+  - failed_field

package/planner-nodes/nodes/planner.relationship.no-orphan-nodes.convention.yaml

@@ -0,0 +1,32 @@
+schema_version: 1.1.0
+rule_id: planner.relationship.no-orphan-nodes
+kind: rule
+status: active
+name: Every convention node is referenced in the relationship graph
+statement: Every convention node (any *.convention.yaml carrying a rule_id, test fixtures excluded) must appear as a source_ref or target_ref of at least one edge in the relationship graph (src/atdd/coach/graph/relationships.yaml). A node referenced by no edge is an orphan and is refused — the graph must cover every node, not just have no dangling edges.
+source:
+  legacy_path: src/atdd/planner/conventions/relationship.convention.yaml
+  legacy_section: rules
+  extraction_mode: high_fidelity
+  legacy_rule_id: planner.relationship.no-orphan-nodes
+content:
+  fix_hint: Author at least one relationship edge with the orphan node as source_ref or target_ref in src/atdd/coach/graph/relationships.yaml (use `atdd author relationship`), choosing a real relationship type/foundation to a semantically related node.
+  exceptions:
+    - Nodes under test fixtures (paths containing tests/fixtures) and the demo.* namespace are excluded.
+operational_guidance: Pairs with the existing forward check (edges may not reference a missing node) to make relationship-graph integrity bidirectional — no dangling edges AND no orphan nodes.
+metadata:
+  aliases:
+    - PLANNER-RELATIONSHIP-NO-ORPHAN-NODES-001
+  severity: 3
+  disposition: strict
+  introduced_in: 3.119.0
+parity:
+  source_fragments_preserved: true
+terms:
+  - term_id: orphan_node
+    text: a convention node whose rule_id is referenced by no source_ref or target_ref in any relationship-graph edge.
+  - term_id: relationship_graph
+    text: the directed convention-node graph at src/atdd/coach/graph/relationships.yaml whose edges connect node rule_ids.
+implementation:
+  type: validator
+  ref: conventions/coverage/test_no_orphan_nodes::test_fault_injection_legacy_parity_both_catch

package/planner-nodes/nodes/planner.smoke.feedback-loop-close-the-loop.convention.yaml

@@ -0,0 +1,39 @@
+schema_version: 1.0.0
+rule_id: planner.smoke.feedback-loop-close-the-loop
+kind: rule
+status: active
+name: Feedback-loop features must close the loop in SMOKE
+statement: 'A feature marked `kind: feedback-loop` must have at least one SMOKE acceptance
+  whose acceptance block declares a close_the_loop: field carrying both consumer_reacted
+  and drift_resolved.'
+rationale: 'Producer-only smoke assertions (artifact existence, schema validation)
+  are insufficient for feedback-loop features: they produce false-positive green CI
+  while the consumer end of the loop is never exercised. Motivating incident: #825.'
+terms:
+- term_id: close_the_loop_block
+  text: The SMOKE acceptance field that proves the loop closed. Requires both consumer_reacted
+    (the consumer-side assertion the test makes) and drift_resolved (the convergence
+    assertion).
+- term_id: suppression
+  text: "Inline hatch on the feature YAML kind: line \u2014 'kind: feedback-loop \
+    \ # atdd:suppress(planner.smoke.feedback-loop-close-the-loop) UNTIL=YYYY-MM-DD'\
+    \ \u2014 dated, so the debt expires."
+implementation:
+  type: validator
+  ref: conventions/presence/test_feedback_loop_close_the_loop::test_feedback_loop_convention_fault
+source:
+  legacy_path: src/atdd/tester/conventions/smoke.convention.yaml
+  legacy_section: feedback_loop_rules
+  legacy_rule_id: planner.smoke.feedback-loop-close-the-loop
+  extraction_mode: high_fidelity
+content:
+  summary: A feedback-loop feature whose SMOKE acceptances only assert the producer
+    side leaves the consumer end unexercised while CI stays green.
+  fix_hint: 'Add (or extend) a SMOKE acceptance on the feature primary WMBT with a
+    close_the_loop: block declaring consumer_reacted and drift_resolved. The test
+    must assert the consumer actually received the correction (not a fake send-history),
+    and that re-running the producer yields 0 new corrections for the same drift.'
+metadata:
+  severity: 3
+  disposition: suppress-and-clean
+  introduced_in: 3.79.0

package/planner-nodes/nodes/planner.smoke.synthetic-fixture-bypass.convention.yaml

@@ -0,0 +1,44 @@
+schema_version: 1.0.0
+rule_id: planner.smoke.synthetic-fixture-bypass
+kind: anti_pattern
+status: active
+name: SMOKE must drive the real entry point, not a synthetic fixture
+statement: A SMOKE-phase test must not drive a synthetic subprocess stub (FakeMultiplexer,
+  or subprocess.Popen of a cat/sleep/python stub) as the primary production wiring;
+  it must drive the real CLI entry point.
+rationale: 'The real-entry-point mandate. Lived incident #854: a Popen crash (missing
+  shell=True on the adapter command tuple) was invisible because the E003-SMOKE tests
+  used a Python stub that never exercised the real command-construction path. Issues
+  #860/#862.'
+terms:
+- term_id: banned_fixtures
+  text: FakeMultiplexer (bypasses real surface dispatch); Popen(['cat',...]) (exercises
+    the pty wrapper, not the agent command); Popen(['sleep',...]) (proves process
+    lifecycle, not agent behaviour); Popen(['python','-c',...]) (bypasses adapter
+    command construction); _SYNTHETIC_AGENT (embedded script constant replacing the
+    real adapter command).
+- term_id: real_entry_points
+  text: "atdd spawn, atdd coach, and the rendered launch prompt \u2014 the surfaces\
+    \ that exercise real adapter command construction and the cmux-native launch path."
+- term_id: suppression
+  text: "Inline hatch: '# atdd:suppress(planner.smoke.synthetic-fixture-bypass) UNTIL=YYYY-MM-DD'\
+    \ \u2014 dated, so the debt expires."
+implementation:
+  type: validator
+  ref: conventions/policy/test_smoke_synthetic_fixture_bypass::test_fault_injection_legacy_parity
+source:
+  legacy_path: src/atdd/tester/conventions/smoke.convention.yaml
+  legacy_section: synthetic_fixture_anti_patterns
+  legacy_rule_id: planner.smoke.synthetic-fixture-bypass
+  extraction_mode: high_fidelity
+content:
+  summary: A SMOKE test driving a synthetic stub proves the harness works, not the
+    product. It is green precisely where the real wiring is untested.
+  fix_hint: Replace the synthetic fixture with the real CLI entry point (subprocess.run([sys.executable,
+    -m, atdd.cli, spawn, ...]) or the invoke_atdd_spawn helper), driving the real
+    cmux-native launch path. Write agent scripts to tmp_path files; do not embed them
+    as string constants.
+metadata:
+  severity: 3
+  disposition: suppress-and-clean
+  introduced_in: 3.83.0

package/planner-nodes/nodes/planner.steps.architecture-routing.convention.yaml

@@ -0,0 +1,109 @@
+schema_version: 1.1.0
+rule_id: planner.steps.architecture-routing
+kind: pattern
+status: active
+name: 'Steps: Architecture Routing'
+statement: Each JTBD step declares its primary architecture layer(s) and a canonical
+  call sequence across presentation, application, domain, and integration, giving
+  a routable mapping from step to architecture.
+implementation:
+  type: none
+source:
+  legacy_path: src/atdd/planner/conventions/steps.convention.yaml
+  legacy_section: architecture-routing
+  extraction_mode: high_fidelity
+content:
+  summary: Binding steps to layers and call sequences keeps the JTBD taxonomy minimal
+    yet routable, so a step can be mechanically placed into the layered architecture.
+  examples:
+  - resolve routes application.event → application.use_case → domain.policy → integration.call_external
+    → integration.persist
+  - conclude routes application.use_case → domain.validate → integration.persist →
+    integration.archive
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: true
+  fix_hint_preserved: true
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: layers_by_step
+  text: The primary architecture layer(s) each step lands in.
+  values:
+    define:
+    - domain
+    locate:
+    - application
+    prepare:
+    - application
+    confirm:
+    - application
+    execute:
+    - domain
+    - application
+    monitor:
+    - presentation
+    modify:
+    - application
+    resolve:
+    - application
+    conclude:
+    - integration
+    - application
+- term_id: sequence_by_step
+  text: The canonical ordered call sequence across layers for each step, written as
+    layer.operation tokens.
+  values:
+    define:
+    - presentation.command
+    - application.use_case
+    - domain.create
+    - integration.persist
+    locate:
+    - application.query
+    - integration.read
+    - application.aggregate
+    - presentation.display
+    prepare:
+    - application.use_case
+    - domain.validate
+    - integration.read
+    - application.stage
+    confirm:
+    - application.query
+    - integration.read
+    - domain.validate
+    - application.decide
+    execute:
+    - presentation.command
+    - application.use_case
+    - domain.mutate
+    - integration.persist
+    monitor:
+    - presentation.query
+    - application.query
+    - integration.read
+    - application.aggregate
+    - presentation.display
+    modify:
+    - presentation.command
+    - application.use_case
+    - domain.mutate
+    - integration.persist
+    resolve:
+    - application.event
+    - application.use_case
+    - domain.policy
+    - integration.call_external
+    - integration.persist
+    conclude:
+    - application.use_case
+    - domain.validate
+    - integration.persist
+    - integration.archive
+  examples:
+    positive:
+    - define → layers [domain], sequence [presentation.command, application.use_case,
+      domain.create, integration.persist]
+    - monitor → layers [presentation], sequence [presentation.query, application.query,
+      integration.read, application.aggregate, presentation.display]

package/planner-nodes/nodes/planner.steps.jtbd-taxonomy.convention.yaml

@@ -0,0 +1,227 @@
+schema_version: 1.1.0
+rule_id: planner.steps.jtbd-taxonomy
+kind: pattern
+status: active
+name: 'Steps: Jtbd Taxonomy'
+statement: Every job decomposes into an ordered sequence of nine JTBD steps — define,
+  locate, prepare, confirm, execute, monitor, modify, resolve, conclude — each with
+  a fixed purpose, guiding question, and expected outputs.
+implementation:
+  type: none
+source:
+  legacy_path: src/atdd/planner/conventions/steps.convention.yaml
+  legacy_section: jtbd-taxonomy
+  extraction_mode: high_fidelity
+content:
+  summary: The nine steps give a stable, exhaustive vocabulary for framing work so
+    that any job-to-be-done can be located in the lifecycle and decomposed consistently
+    across planners.
+  examples:
+  - Define a duel as a synchronous PvP match between two teams
+  - Conclude the duel by updating Elo and archiving the match summary
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: true
+  fix_hint_preserved: true
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: ordered_steps
+  text: The nine ordered JTBD steps, each carrying its purpose, guiding question,
+    one canonical example, and expected outputs.
+  values:
+    define:
+      order: 1
+      purpose: Frame the work and set boundaries
+      question: What must be defined upfront before anything else can proceed?
+      example: Define a duel as a synchronous PvP match between two teams
+      outputs:
+      - Clear objectives
+      - Success metrics
+      - Constraint boundaries
+    locate:
+      order: 2
+      purpose: Identify and access required inputs or resources
+      question: What must be found or accessed to do the job?
+      example: Locate peers across devices within 100ms latency
+      outputs:
+      - Resource inventory
+      - Access patterns
+      - Dependency map
+    prepare:
+      order: 3
+      purpose: Make the environment/resources ready without starting execution
+      question: How must the executor prepare before acting?
+      example: Prepare the duel lobby and match players before countdown
+      outputs:
+      - Prepared resources
+      - Validated inputs
+      - Ready state confirmation
+    confirm:
+      order: 4
+      purpose: Ensure preconditions and synchronization before moving forward
+      question: What must be verified or agreed upon to continue?
+      example: Confirm readiness from both teams before duel starts
+      outputs:
+      - Precondition checklist
+      - Permission verification
+      - Go/no-go decision
+    execute:
+      order: 5
+      purpose: Carry out the core action that changes state
+      question: What must the executor do to perform the job itself?
+      example: Execute player move and apply it locally in ≤2ms
+      outputs:
+      - Completed core job
+      - State changes
+      - Performance metrics
+    monitor:
+      order: 6
+      purpose: Observe progress, quality, or risks to enable correction
+      question: What must be tracked during execution to ensure success?
+      example: Monitor state divergence and resync if thresholds are exceeded
+      outputs:
+      - Progress indicators
+      - Performance data
+      - Anomaly reports
+    modify:
+      order: 7
+      purpose: Proactively adjust or optimize during normal operation
+      question: What might need to be changed for better outcomes?
+      example: Modify scoring rules mid-season if the meta shifts
+      outputs:
+      - Adjustments made
+      - Optimization results
+      - Updated configurations
+    resolve:
+      order: 8
+      purpose: Reactive problem-solving and exception handling
+      question: What problems must be addressed when things go wrong?
+      example: Resolve a disconnection by substituting a bot
+      outputs:
+      - Problem resolutions
+      - Recovery procedures
+      - Workaround documentation
+    conclude:
+      order: 9
+      purpose: Close the loop and capture results
+      question: What must be done to finish the job and capture results?
+      example: Conclude the duel by updating Elo and archiving the match summary
+      outputs:
+      - Completion confirmation
+      - Results captured
+      - Final documentation
+  examples:
+    positive:
+    - Define a duel as a synchronous PvP match between two teams
+    - Locate peers across devices within 100ms latency
+    - Prepare the duel lobby and match players before countdown
+    - Confirm readiness from both teams before duel starts
+    - Execute player move and apply it locally in ≤2ms
+    - Monitor state divergence and resync if thresholds are exceeded
+    - Modify scoring rules mid-season if the meta shifts
+    - Resolve a disconnection by substituting a bot
+    - Conclude the duel by updating Elo and archiving the match summary
+- term_id: key_terms
+  text: The leading and supporting verbs that signal each step, used to classify a
+    job step from its phrasing.
+  values:
+    define:
+    - Define
+    - Plan
+    - Select
+    - Determine
+    - rule
+    - policy
+    - constraint
+    - specification
+    - invariant
+    - requirement
+    locate:
+    - Locate
+    - Gather
+    - Access
+    - Retrieve
+    - find
+    - search
+    - fetch
+    - query
+    - lookup
+    - discover
+    prepare:
+    - Prepare
+    - Set up
+    - Organize
+    - Examine
+    - setup
+    - configure
+    - initialize
+    - stage
+    - arrange
+    - organize
+    confirm:
+    - Confirm
+    - Validate
+    - Prioritize
+    - Decide
+    - validate
+    - verify
+    - check
+    - ensure
+    - authorize
+    - approve
+    execute:
+    - Execute
+    - Perform
+    - Transact
+    - Administer
+    - perform
+    - process
+    - calculate
+    - transform
+    - create
+    - generate
+    monitor:
+    - Monitor
+    - Verify
+    - Track
+    - Check
+    - display
+    - show
+    - track
+    - observe
+    - report
+    - visualize
+    modify:
+    - Modify
+    - Update
+    - Adjust
+    - Maintain
+    - adjust
+    - update
+    - correct
+    - patch
+    - tune
+    - amend
+    resolve:
+    - Resolve
+    - Troubleshoot
+    - Fix
+    - Handle
+    - error
+    - exception
+    - retry
+    - recover
+    - fallback
+    - compensate
+    conclude:
+    - Conclude
+    - Store
+    - Finish
+    - Close
+    - complete
+    - finish
+    - archive
+    - cleanup
+    - close
+    - record

package/planner-nodes/nodes/planner.steps.linguistic-patterns.convention.yaml

@@ -0,0 +1,81 @@
+schema_version: 1.1.0
+rule_id: planner.steps.linguistic-patterns
+kind: pattern
+status: active
+name: 'Steps: Linguistic Patterns'
+statement: Each JTBD step is recognized and phrased through a fixed set of slotted
+  linguistic templates that bind the step's verb to its objects and constraints.
+implementation:
+  type: none
+source:
+  legacy_path: src/atdd/planner/conventions/steps.convention.yaml
+  legacy_section: linguistic-patterns
+  extraction_mode: high_fidelity
+content:
+  summary: Templated phrasings make step classification and acceptance authoring deterministic
+    — the same surface grammar always maps to the same step.
+  examples:
+  - Execute {action} within {constraint}
+  - Resolve {issue} using {method}
+parity:
+  source_fragments_preserved: true
+  examples_preserved: true
+  implementation_preserved: true
+  fix_hint_preserved: true
+  reviewed_at: '2026-06-16'
+terms:
+- term_id: patterns_by_step
+  text: Per-step linguistic templates with slot placeholders for objects, constraints,
+    and outcomes.
+  values:
+    define:
+    - Define {object} as {specification}
+    - Plan {approach} for {outcome}
+    - Select {option} from {alternatives}
+    - Determine {criteria} for {decision}
+    locate:
+    - Locate {resource} within {constraint}
+    - Gather {inputs} from {sources}
+    - Access {data} via {method}
+    - Retrieve {information} in {timeframe}
+    prepare:
+    - Prepare {environment} for {activity}
+    - Set up {infrastructure} with {configuration}
+    - Organize {resources} by {criteria}
+    - Examine {inputs} for {validation}
+    confirm:
+    - Confirm {precondition} before {action}
+    - Validate {input} against {criteria}
+    - Prioritize {items} by {importance}
+    - Decide {path} based on {conditions}
+    execute:
+    - Execute {action} within {constraint}
+    - Perform {operation} on {target}
+    - Transact {change} to {system}
+    - Administer {process} per {protocol}
+    monitor:
+    - Monitor {metric} for {threshold}
+    - Verify {state} remains {condition}
+    - Track {progress} against {target}
+    - Check {status} every {interval}
+    modify:
+    - Modify {parameter} when {condition}
+    - Update {configuration} to {value}
+    - Adjust {setting} for {optimization}
+    - Maintain {state} within {bounds}
+    resolve:
+    - Resolve {issue} using {method}
+    - Troubleshoot {problem} via {diagnosis}
+    - Fix {error} within {timeframe}
+    - Handle {exception} with {fallback}
+    conclude:
+    - Conclude {job} with {summary}
+    - Store {results} in {location}
+    - Finish {process} by {action}
+    - Close {session} after {cleanup}
+  examples:
+    positive:
+    - Define {object} as {specification}
+    - Monitor {metric} for {threshold}
+    negative:
+    - Do the thing with the stuff

package/planner-nodes/nodes/planner.steps.sequence.convention.yaml

@@ -0,0 +1,17 @@
+schema_version: 1.0.0
+rule_id: planner.steps.sequence
+kind: rule
+status: active
+statement: Steps are ordered and numbered, and each declares its pre-conditions and
+  its outputs.
+rationale: Ordered, numbered steps with pre-conditions and outputs make a wagon procedure
+  reproducible and checkable.
+terms:
+- term_id: step
+  text: a numbered unit of a wagon procedure
+- term_id: preconditions_and_outputs
+  text: what a step requires before running and produces after
+metadata:
+  severity: 2
+  disposition: documentation-only
+  introduced_in: 1.67.0

package/planner-nodes/nodes/planner.subject.invariants.convention.yaml

@@ -0,0 +1,34 @@
+schema_version: 1.0.0
+rule_id: planner.subject.invariants
+kind: constraint
+status: active
+name: Subject invariants
+statement: A subject is a durable noun object registered in plan/_subjects.yaml before
+  any train is typed under it; subjects are unique-by-subject and typed trains are
+  unique-by-subject+slug.
+terms:
+- term_id: durable_noun
+  text: a subject is kebab-case and noun-led (not a verb, an actor, a theme, a route,
+    a category, an owner, or a program name) — the durable object of a train's change
+- term_id: registered_before_first_train
+  text: the subject exists in the plan/_subjects.yaml registry before any train:<subject>:<slug>
+    is typed under it
+- term_id: unique_identity
+  text: registry entries are unique-by-subject and typed trains are unique-by-subject+slug
+implementation:
+  type: validator
+  ref: test_subject_invariants::test_repo_subject_registry_satisfies_invariants
+metadata:
+  severity: 4
+  disposition: strict
+validation:
+  family: coherence
+  template: registry_entries_coherent
+  variant: planner_subject_invariants
+  phase: CONFIRM
+  enforcement: confirm-blocking
+  subject_kind: subject
+  failure_evidence:
+  - subject
+  - slug
+  - registry_status

package/planner-nodes/nodes/planner.theme.definition.convention.yaml

@@ -0,0 +1,23 @@
+schema_version: 1.1.0
+rule_id: planner.theme.definition
+kind: family
+status: active
+name: Repository-owned theme namespace
+statement: A theme is a repository-defined kebab-case namespace for plan artifacts. The only
+  reserved entry is index 0, which MUST be commons; repositories declare every other theme
+  in plan/_themes.yaml. Theme membership and identity-prefix consistency are enforceable.
+terms:
+- term_id: semantic_anchor
+  label: Advisory semantic anchor
+  text: a definitional node that gives the artifact a stable meaning but is not itself
+    bound to a validator; it is transitively protected by the enforceable constraint/rule
+    nodes that require it.
+- term_id: theme
+  label: Repository-owned theme
+  text: theme -> {kebab-case namespace, registry membership, identity prefix}.
+  values:
+    registry: plan/_themes.yaml
+    reserved_zero: commons
+    format: ^[a-z][a-z0-9-]*$
+    membership: every declared theme is a value in the repository registry
+    identity_prefix: the first segment of an artifact or contract identity equals its theme