---
name: cleverthis-guidelines
description: |
  Complete, exhaustive reference for every rule, regulation, directive, and guideline
  governing CleverThis projects and the CleverThis Corporation. Covers both the
  CleverThis Operations Code (C.O.C.) company-wide policies and the project-specific
  CONTRIBUTING.md guidelines.

  Use this skill whenever you need to know: how to write a commit, how to create or
  update an issue, how to submit a pull request, how to write tests, how code should
  be structured, what labels to apply, how triaging works, what security practices
  apply, how confidentiality levels work, how sprints and DSDM work, how branch
  names are formed, how CI/CD works, how the TDD bug fix workflow operates with its
  exact tag rules, which directory code belongs in,   or any other procedural or regulatory question about working at or
  contributing to CleverThis.

  Covers: commit format and quality rules, pull request requirements and merge
  criteria, BDD testing (project uses Behave for unit and Robot Framework for
  integration), coverage threshold (97% project-specific), static type checking
  (project uses Pyright), task runner commands (project uses nox), CI/CD pipeline
  (all jobs + required gates), issue hierarchy (Issue→Epic→Legendary), label
  system (State/Priority/MoSCoW/Type/), ticket lifecycle, sprint structure
  (2-week, 1st and 15th), DSDM triaging, MoSCoW prioritization, point estimation
  (poker points), branch naming conventions (feature/mN-, bugfix/mN-, tdd/mN-),
  TDD bug fix workflow with exact tag validation rules (assertion failure type
  requirement), file organization (src/ test/ docs/ config/ scripts/ examples/),
  documentation traceability rules (no line numbers, logical module path +
  commit hash), code style principles, SOLID patterns, error handling rules,
  security policies (gopass, Yubikey, encryption), confidentiality levels
  (Restricted/Secret/Trade Secret/Confidential/Public), organizational structure,
  boards (ELB/OCRB), committees (12 committees), FOSS policies, open standards
  mandate,   backwards compatibility policy, and definition of done.

  All tooling references are framed as project-specific examples. The rules
  themselves apply universally; specific tools (nox, Pyright, ruff, Behave,
  Robot Framework) are the current project's choices for a Python codebase, with
  equivalents for other language ecosystems noted throughout.
references:
  - commits
  - pull-requests
  - testing
  - issue-tracking
  - sprints
  - code-style
  - security
  - information
  - organizational
  - project-tools
  - open-source
---

# CleverThis Guidelines Skill

Complete reference for **every rule, regulation, and guideline** governing CleverThis
projects and company operations. Drawn from the **CleverThis Operations Code (C.O.C. v0.4)**
and the project-specific **CONTRIBUTING.md**.

> **Precedence**: Bylaws > Operations Code > CONTRIBUTING.md (project-specific). When this
> project's CONTRIBUTING.md overrides C.O.C. defaults, both values are documented.

---

## ⚡ Quick Command Reference

> **Language / tooling note:** The commands below are the **project-specific** examples
> using Python and nox. The underlying principle applies to any language: **always use
> the project's designated task runner** — never invoke linters, type checkers, or test
> frameworks directly. Common equivalents by ecosystem:
>
> | Concern | Python *(this project)* | JavaScript / TypeScript | Java / Kotlin | Go |
> |---------|------------------------|------------------------|---------------|----|
> | Task runner | `nox` | `npm run` / `pnpm run` | Gradle / Maven | `make` / `mage` |
> | Linter | ruff | ESLint / Biome | Checkstyle / Detekt | golangci-lint |
> | Formatter | ruff format | Prettier | google-java-format | gofmt |
> | Type checker | Pyright | tsc (strict) | javac / kotlinc | built-in |
> | Unit tests (BDD) | Behave | jest-cucumber / vitest | Cucumber-JVM | godog |
> | Integration tests | Robot Framework | Playwright / Cypress | Selenium | `go test` (tagged) |
> | Coverage | Slipcover | Istanbul / c8 | JaCoCo | `go test -cover` |
> | Security scan | bandit + semgrep | npm audit + semgrep | SpotBugs | gosec |
> | Benchmarks | ASV | Benchmark.js | JMH | `go test -bench` |
> | Build / package | hatch build | npm pack / vite build | `./gradlew build` | `go build` |
> | Docs | MkDocs | VitePress / Docusaurus | Javadoc | pkg.go.dev |

```bash
# Run ALL quality gates (must pass before any PR) — Python/nox:
nox

# Core quality sessions:
nox -s lint              # linting + format check (ruff)
nox -s format            # auto-format code (ruff)
nox -s format -- --check # check formatting only, no changes — CI mode
nox -s typecheck         # static type checking (Pyright, strict, no suppressions)
nox -s security_scan     # security scan (bandit + semgrep + vulture)
nox -s dead_code         # dead code detection (vulture)

# Test sessions:
nox -s unit_tests        # BDD unit tests (Behave — features/)
nox -s integration_tests # integration tests (Robot Framework via pabot — robot/)
nox -s e2e_tests         # end-to-end tests with real external credentials
nox -s coverage_report   # coverage report (Slipcover — must be ≥ 97%)
nox -s benchmark         # performance benchmarks (Airspeed Velocity)
nox -s benchmark_regression  # benchmark regression check (PRs only)

# Analysis sessions:
nox -s complexity        # code complexity (Radon — nightly quality sweep)

# Build / docs sessions:
nox -s docs              # build documentation (MkDocs)
nox -s build             # build distributable (wheel)

# Dev environment setup:
scripts/setup-dev.sh     # installs pre-commit hooks

# Conventional commit message helper (works for any language project):
npm install -g commitizen@2.8.6 cz-customizable@4.0.0
git cz                   # interactive commit — replaces git commit

# Release (triggers CI release.yml workflow):
git tag v1.2.3 && git push origin v1.2.3
```

---

## 🧭 Master Decision Trees

### "What am I about to do?"

```
What are you about to do?
│
├─ Write or commit code
│   ├─ Before writing → "Am I about to write code?" tree below
│   ├─ Before committing → "Am I about to commit?" tree below
│   └─ About to push → run the task runner first (e.g. nox), verify all gates pass
│
├─ Create or update an issue/ticket
│   ├─ New issue → "Am I creating an issue?" tree below
│   ├─ Updating labels → "What label do I apply?" tree below
│   └─ Moving state → "What state should this ticket be?" tree below
│
├─ Decide ticket type (Issue vs Epic vs Legendary)
│   └─ → "Should this be an Issue, Epic, or Legendary?" tree below
│
├─ Check if a ticket is well-scoped
│   └─ → "Is this ticket well-scoped?" tree below
│
├─ Submit a Pull Request (PR / MR)
│   └─ → "Am I submitting a PR?" tree below
│
├─ Review someone else's code
│   └─ → "Am I reviewing a PR?" tree below
│
├─ Choose a branch name
│   └─ → "What branch name should I use?" tree below
│
├─ Work within a sprint
│   ├─ Sprint planning → "Am I in sprint planning?" tree below
│   ├─ Daily standup → references/sprints/README.md (Sprint Ceremonies section)
│   ├─ Triaging → "Am I triaging tickets?" tree below
│   ├─ Point estimation → "Am I estimating points?" tree below
│   └─ Sprint review → references/sprints/README.md (Sprint Ceremonies section)
│
├─ Write or update documentation
│   ├─ Authoring a doc → "Am I writing or updating documentation?" tree below
│   ├─ Confidentiality stamp → "What confidentiality level applies?" tree below
│   └─ Sharing a doc → "Am I authoring a document?" tree below
│
├─ Handle security (passwords, keys, hardware)
│   └─ → "Am I handling credentials or security hardware?" tree below
│
├─ Work with open source
│   └─ → "Am I working with FOSS?" tree below
│
├─ Fix a bug
│   └─ → "Am I fixing a bug?" tree below (mandatory TDD workflow)
│
├─ Write a TDD test for a bug
│   └─ → "Am I writing a TDD issue-capture test?" tree below
│
├─ Check which directory a file belongs in
│   └─ → "Which directory should this file go in?" tree below
│
├─ Set up the development environment
│   └─ → "Am I setting up my development environment?" tree below
│
├─ Investigate a CI failure
│   └─ → "Am I looking at a CI failure?" tree below
│
├─ Release a new version
│   └─ → "Am I releasing a new version?" tree below
│
└─ Make an architectural decision
    └─ → "Am I making an architectural decision?" tree below
```

---

## 🔄 Situation-Specific Decision Trees

### "Am I about to write code?"

```
Before writing any code:
│
├─ SPECIFICATION FIRST (mandatory step)
│   ├─ Open docs/specification/ (see docs/specification/index.md)
│   ├─ Read ALL sections relevant to your task
│   ├─ Understand the intended architecture and design
│   └─ If code ≠ specification → ALWAYS align code to specification
│       ⚠️ Never adjust specification to match incorrect code
│
├─ Does a ticket exist for this work?
│   ├─ NO → Create an issue first (see "Am I creating an issue?")
│   └─ YES → continue
│
├─ Is the ticket in State/Verified or State/In progress?
│   ├─ State/Unverified → wait for maintainer triage, do not start
│   ├─ State/Verified → move to State/In progress, assign yourself
│   └─ State/In progress → you're clear to work
│
├─ Which directory does my code belong in?
│   └─ → "Which directory should this file go in?" tree
│
├─ Is this a bug fix?
│   ├─ YES → MANDATORY: TDD workflow applies (see "Am I fixing a bug?")
│   └─ NO → continue
│
├─ Code style checklist (before writing):
│   ├─ Write tests BEFORE implementation (test-first, no exceptions)
│   ├─ Use the language's type system fully — no inline suppression of type errors:
│   │   ├─ Python → full type annotations on all functions, variables, and returns
│   │   ├─ TypeScript → strict mode enabled; avoid `any`
│   │   ├─ Java / C# / Kotlin → rely on compiler types; use generics appropriately
│   │   └─ No type-suppression comments regardless of language
│   │       (Python: # type: ignore  |  TS: // @ts-ignore  |  Java: @SuppressWarnings)
│   ├─ Production source only in src/ — no mocks or test data there
│   ├─ Are you using SOLID principles? (see references/code-style/)
│   └─ File under 500 lines? (break into modules if approaching limit)
│
└─ Dependency / import declaration rules:
    ├─ Declare all imports/dependencies at the top of the file (language-idiomatic)
    ├─ Never scatter them throughout code or bury them inside functions or blocks
    ├─ Prefer specific imports over wildcard or whole-module imports:
    │   ├─ Python:     from module import ClassName   (not import *)
    │   ├─ Java:       explicit class imports          (not import java.util.*)
    │   └─ TypeScript: import { Foo } from './foo'    (named imports)
    └─ Exception: type-only imports for circular-dependency avoidance
        ├─ Python:     if TYPE_CHECKING: block
        └─ TypeScript: import type { Foo } from './foo'
```

### "Am I about to commit?"

```
Before every commit:
│
├─ Have all tests been written for this change?
│   └─ NO → Write tests first (test-first development)
│
├─ Run quality gates (use the task runner — see "What task runner session should I run?"):
│   ├─ Lint session            → must be green  (e.g. nox -s lint)
│   ├─ Type check session      → must be green, no inline suppressions  (e.g. nox -s typecheck)
│   ├─ Unit test session       → must be green  (e.g. nox -s unit_tests)
│   └─ Coverage session        → must be ≥ 97%  (e.g. nox -s coverage_report)
│
├─ Self-review the diff:
│   ├─ Only intended changes staged? (use git add -p)
│   ├─ No debug statements / temporary code?
│   ├─ No secrets or credentials hardcoded?
│   ├─ Tests included in same commit as the change?
│   ├─ Documentation updated in same commit?
│   └─ Changelog updated? (one entry per commit)
│
├─ Is this commit atomic?
│   ├─ One logical change only (not two bugs, not feature + refactor)
│   ├─ Can be reverted without breaking anything else?
│   ├─ No cosmetic changes mixed with functional changes?
│   └─ No half-done work? (only commit complete, tested work)
│
├─ Commit message format:
│   ├─ Format: <type>(<scope>): <description>
│   ├─ Types: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert
│   ├─ First line: 50-72 chars, imperative mood, no period at end
│   ├─ Blank line, then body: what was done and WHY
│   └─ Footer: ISSUES CLOSED: #N (required)
│
├─ Does commit message first line match the issue's Metadata section?
│   └─ YES → use EXACTLY that text (copy-paste, do not paraphrase)
│
└─ Pre-commit hooks:
    ├─ Hooks run automatically on git commit (if setup-dev.sh was run)
    ├─ Commitizen validates message format at commit-msg stage
    └─ Rejected commit = fix the problem, do NOT use --no-verify
```

### "Am I submitting a PR (Pull Request / Merge Request)?"

```
PR submission checklist (ALL must be true):
│
├─ CODE QUALITY
│   ├─ Task runner full suite passes with zero failures  (e.g. nox)
│   ├─ Coverage ≥ 97%  (e.g. nox -s coverage_report)
│   ├─ No inline type-checking suppressions anywhere
│   │   (Python: # type: ignore  |  TypeScript: // @ts-ignore  |  Java: @SuppressWarnings)
│   └─ All pre-commit hooks pass
│
├─ COMMIT STRUCTURE
│   ├─ Each commit is atomic (one logical change)
│   ├─ Each commit builds and passes tests independently
│   ├─ Each commit message follows Conventional Changelog format
│   ├─ Each commit footer includes ISSUES CLOSED: #N or Refs: #N
│   ├─ First line of each commit matches issue Metadata if prescribed
│   └─ One changelog entry per commit has been added
│
├─ PR DESCRIPTION
│   ├─ Detailed summary of what changed and WHY
│   ├─ Closing keyword for every linked issue (Closes #N, Fixes #N)
│   └─ Dependency link: PR must BLOCK the issue (issue DEPENDS ON PR)
│       ⚠️ Critical direction: PR→blocks→issue, NOT issue→blocks→PR
│       Wrong direction creates unresolvable deadlock in Forgejo
│
├─ LABELS AND METADATA
│   ├─ Exactly one Type/ label (Type/Bug, Type/Feature, Type/Task, etc.)
│   ├─ Assigned to correct milestone (same as linked issue)
│   └─ Associated with a single Epic (one Epic per PR, no multi-Epic PRs)
│
├─ ISSUE STATE
│   └─ Move linked issue(s) to State/In review
│
├─ CHANGELOG
│   └─ Updated with one new entry per commit in this PR
│
├─ CONTRIBUTORS.md
│   └─ Your name listed (if not already there)
│
├─ VERSION BUMP (when applicable)
│   ├─ New functionality → bump MINOR
│   ├─ Bug fix in released version → bump PATCH
│   ├─ Breaking API change → bump MAJOR
│   └─ Refactoring / docs / test improvements → usually NO bump
│
└─ AFTER SUBMISSION
    ├─ Watch CI — fix any failures immediately
    ├─ Respond to review comments constructively
    ├─ Address all requested changes, then re-request review
    └─ After merge: move linked issue(s) to State/Completed
```

### "Am I reviewing a PR?"

```
Code review responsibilities:
│
├─ ELIGIBILITY (project-specific rules override C.O.C.)
│   ├─ Minimum 1 approving review required (project override: not C.O.C.'s 2)
│   ├─ Self-approval IS permitted (including automated bot PRs)
│   ├─ Approval types: formal "APPROVED" review OR comment with LGTM/✅
│   └─ No open "Request Changes" reviews at merge time
│
├─ CI STATUS CHECK
│   ├─ All required CI jobs must be green before merge
│   ├─ Required: lint, typecheck, security, unit_tests, coverage
│   ├─ The status-check job is the single branch-protection gate
│   └─ See "Am I looking at a CI failure?" tree for failure diagnosis
│
├─ WHAT TO CHECK
│   ├─ Correctness: does it satisfy acceptance criteria of linked issue?
│   ├─ Readability: clear names, easy to follow, no magic numbers?
│   ├─ Performance: no unnecessary inefficiencies or N+1 problems?
│   ├─ Security: no vulnerabilities, secrets, or unsafe patterns?
│   ├─ Style: follows project coding standards (linter, type checker)?
│   ├─ Tests: adequate coverage? edge cases covered? error paths tested?
│   ├─ Coverage: does coverage remain ≥ 97%?
│   └─ Documentation: updated alongside code changes?
│
├─ COMMIT QUALITY CHECK
│   ├─ Each commit atomic and self-contained?
│   ├─ Each commit message follows Conventional Changelog?
│   ├─ Each commit references an issue?
│   └─ Changelog has one entry per commit?
│
├─ IF REQUESTING CHANGES
│   ├─ Document findings in Merge Request discussion
│   ├─ Be specific and constructive, not vague
│   └─ Author must address every comment in writing
│
├─ MERGING (if you have merge authority)
│   ├─ All CI required checks green (status-check job passes)
│   ├─ At least 1 approval present, no dissenting reviews
│   ├─ PR linked to exactly one Epic
│   ├─ Changelog updated
│   └─ Project owner can override any requirement (documented exception)
│
└─ URGENT/HIGH-RISK MRs
    └─ Architectural refactors → require additional CQAC reviewer
```

### "Am I creating an issue?"

```
Issue creation requirements:
│
├─ WHAT TYPE IS THIS ISSUE?
│   ├─ Defect in existing functionality → Type/Bug
│   │   ├─ Also create a companion Type/Testing (TDD) issue immediately
│   │   ├─ Bug issues are always Priority/Critical + MoSCoW/Must Have
│   │   └─ Follow mandatory TDD bug fix workflow
│   ├─ New functionality → Type/Feature
│   ├─ Technical work (refactor, infra, deps) → Type/Task
│   ├─ Test-only work or TDD capture → Type/Testing
│   ├─ Group of related issues → Type/Epic
│   └─ Group of related Epics → Type/Legendary
│
├─ HIERARCHY PLACEMENT
│   ├─ Regular issue → MUST link to at least one parent Epic
│   ├─ Epic → MUST link to at least one parent Legendary
│   └─ Legendary → no parent (root node)
│   ⚠️ No orphan issues. No skip-level parenting (issue cannot be child of Legendary)
│
├─ TITLE
│   ├─ Specific and descriptive ("Fix null pointer when parsing empty config file")
│   └─ NOT vague ("Fix bug", "Improve performance")
│
├─ MANDATORY LABELS
│   ├─ State/Unverified (all new issues start here)
│   ├─ Type/ label (see above)
│   └─ Priority/Backlog (default until triaged)
│   ⚠️ Do NOT set MoSCoW/ labels — project owner only
│
├─ DESCRIPTION SECTIONS REQUIRED
│   ├─ ## Metadata (at the top)
│   │   ├─ Commit Message: feat(scope): exact message for this issue's commit
│   │   └─ Branch: feature/m3-my-feature (branch name to use)
│   ├─ Background and context (why does this exist?)
│   ├─ Current behavior (for bugs: repro steps, errors, logs)
│   ├─ Expected behavior / definition of "done"
│   ├─ Acceptance criteria (testable, binary yes/no conditions)
│   ├─ Supporting information (links, screenshots, references)
│   ├─ ## Subtasks (checkbox list of discrete steps)
│   └─ ## Definition of Done (explicit closure conditions)
│
├─ MILESTONE
│   ├─ Unverified: optional
│   └─ Any active state (Verified, In Progress, etc.): MANDATORY
│
├─ BRANCH/TAG (Ref field)
│   ├─ Development issues: must match branch from Metadata section
│   └─ Non-development: may be blank
│
├─ ISSUE QUALITY CRITERIA (must meet ALL 11)
│   ├─ Atomicity: smallest meaningful unit of work
│   ├─ Single Commit: one issue = one commit
│   ├─ Single Responsibility: one concern only
│   ├─ Assignability: one developer can own it without synchronization
│   ├─ Verifiability: clear binary verification criterion
│   ├─ Self-Containment: all context in the issue + parent Epic
│   ├─ Implementation Independence: ideally independent (or deps documented)
│   ├─ Subtask Decomposition: checkbox list unless trivially simple
│   ├─ Leaf Node: no child tickets (promote to Epic if decomposition needed)
│   ├─ Mandatory Parent: belongs to at least one Epic
│   └─ Finite Completion: done when single commit merged, no reopening
│
└─ PARENT LINKING
    ├─ Open child issue → add parent under "blocks"
    ├─ OR open parent → add child under "depends on"
    └─ NEVER reference parent by number in description body text
```

### "What label do I apply to this issue?"

```
Label system (all issues must have one label from each applicable scope):
│
├─ STATE LABELS (State/) — exactly one required at all times
│   ├─ State/Unverified → just created, not yet reviewed by maintainer
│   ├─ State/Verified → maintainer confirmed valid, ready to work
│   ├─ State/In progress → someone is actively working on it
│   ├─ State/Paused → work stopped (usually blocked); add Blocked label too
│   ├─ State/In review → PR submitted, awaiting peer review
│   ├─ State/Completed → PR merged, all work done
│   └─ State/Wont Do → deliberate decision not to address; comment required
│   Special: Duplicate → mark and link to original before closing
│
├─ TYPE LABELS (Type/) — exactly one required
│   ├─ Type/Bug → defect in existing functionality
│   ├─ Type/Feature → new capability or user story
│   ├─ Type/Task → technical/admin work (refactor, deps, docs, infra)
│   ├─ Type/Testing → TDD issue-capture test or standalone test work
│   ├─ Type/Epic → large body of work composed of multiple issues
│   └─ Type/Legendary → strategic pillar composed of multiple Epics
│
├─ PRIORITY LABELS (Priority/) — required for all non-Epic, non-Legendary
│   ├─ Priority/Critical → immediate; outages, data loss, security vulns
│   ├─ Priority/High → current or next cycle
│   ├─ Priority/Medium → valid, not urgent
│   ├─ Priority/Low → nice to have, time-insensitive
│   └─ Priority/Backlog → default; not yet pulled into a sprint
│   Note: Bugs are always Priority/Critical (no exceptions)
│
├─ MoSCoW LABELS (MoSCoW/) — set by project owner ONLY
│   ├─ MoSCoW/Must Have → milestone cannot complete without it
│   ├─ MoSCoW/Should Have → important but not blocking milestone
│   └─ MoSCoW/Could Have → nice to have if time permits
│   Note: No "Won't Have" label — use State/Wont Do instead
│
└─ SPECIAL LABELS
    ├─ Blocked → cannot proceed (must also link blocking issue)
    └─ Signed-off: → formal sign-off during review process
    Note: Signed-off:Owner, Signed-off:scrum master, Signed-off:Tech Lead required
    to close Epics and Legendaries
```

### "What state should this ticket be in?"

```
Ticket lifecycle transitions:
│
├─ Just created by anyone → State/Unverified (always)
│
├─ During sprint planning, maintainer reviews unverified:
│   ├─ Valid and actionable → State/Verified (maintainer only)
│   ├─ Will not address → State/Wont Do (comment required explaining why)
│   └─ Already exists → Duplicate (link to original, close)
│
├─ Contributor starts working on a verified issue:
│   └─ → State/In progress (assign yourself simultaneously)
│
├─ Work blocked by dependency:
│   ├─ → State/Paused
│   ├─ → Add Blocked label
│   ├─ → Link to blocking issue in comment
│   └─ Once blocker resolved: remove Blocked, → State/In progress
│
├─ Implementation complete, PR submitted:
│   └─ → State/In review
│
├─ PR merged, all requirements met:
│   └─ → State/Completed (then close the ticket)
│
└─ At any point, maintainer decides to drop it:
    └─ → State/Wont Do (comment explaining decision required)

⚠️ Rules:
- Never close without first marking Wont Do, Duplicate, or Completed
- Never close without peer review process satisfied
- Epics/Legendaries: need Signed-off labels from owner + scrum master + tech leads
- Contributors do NOT move their own issues out of State/Unverified
```

### "Is my work done? (Definition of Done)"

```
Work is DONE only when ALL of the following are true:
│
├─ IMPLEMENTATION
│   ├─ Feature/fix fully implemented and tested
│   ├─ No placeholder code or stub implementations
│   └─ All subtasks in the issue checklist are checked off
│
├─ TESTS (MANDATORY)
│   ├─ BDD scenarios written BEFORE implementation  (project uses Behave;
│   │   other frameworks: Cucumber, SpecFlow, pytest-bdd, rspec, godog)
│   ├─ Unit tests cover all non-trivial logic paths
│   ├─ Integration tests updated/added if component interfaces changed
│   ├─ Task runner unit test session → green  (e.g. nox -s unit_tests)
│   ├─ Task runner integration test session → green  (e.g. nox -s integration_tests)
│   └─ Task runner coverage session → ≥ 97%  (e.g. nox -s coverage_report)
│
├─ CODE QUALITY
│   ├─ Task runner lint session → green, no suppressions  (e.g. nox -s lint)
│   ├─ Task runner type check session → green, no inline suppressions  (e.g. nox -s typecheck)
│   ├─ Task runner security scan session → green  (e.g. nox -s security_scan)
│   ├─ Task runner dead code session → no new dead code  (e.g. nox -s dead_code)
│   └─ Task runner full default suite → all green  (e.g. nox)
│
├─ COMMIT AND PR
│   ├─ Atomic commit with correct Conventional Changelog format
│   ├─ Commit message first line matches issue Metadata exactly
│   ├─ ISSUES CLOSED: #N in commit footer
│   ├─ PR submitted with detailed description
│   ├─ PR has closing keyword (Closes #N)
│   ├─ PR dependency direction correct (PR blocks issue, not vice versa)
│   ├─ PR assigned to correct milestone
│   ├─ PR has exactly one Type/ label
│   └─ PR associated with exactly one Epic
│
├─ DOCUMENTATION
│   ├─ Documentation updated alongside code in same commit
│   ├─ References use logical module path — never line numbers
│   │   ├─ Python:     mypackage.services.plan_service.PlanService.execute
│   │   ├─ Java:       com.example.services.PlanService.execute
│   │   ├─ TypeScript: services/planService.PlanService.execute
│   │   └─ Go:         github.com/example/services.(*PlanService).Execute
│   ├─ Changelog has one new entry for this commit
│   └─ CONTRIBUTORS.md updated if first contribution
│
├─ REVIEW
│   ├─ At least 1 approval received (self-approval permitted)
│   ├─ No open "Request Changes" reviews
│   └─ PR merged to master
│
└─ ISSUE STATE
    └─ Issue moved to State/Completed and closed
```

### "Am I triaging tickets?"

```
Triaging process (performed during sprint planning):
│
├─ STAGE 1: Unverified ticket review
│   ├─ For each State/Unverified ticket, decide:
│   │   ├─ Valid and actionable → move to State/Verified
│   │   ├─ Will not be done → State/Wont Do (add brief explanation why)
│   │   └─ Duplicate of existing → mark Duplicate, link original, close
│   └─ Rules:
│       ├─ Must happen at least once per sprint (at sprint planning start)
│       ├─ All triage decisions logged in task management system
│       └─ Tickets can only be assigned to CURRENT sprint (no pre-planning)
│
├─ STAGE 2: Epic and Legendary preparation
│   ├─ Project owner creates/updates Epics and Legendaries
│   ├─ Tech lead and scrum master review for completeness
│   ├─ Epics/Legendaries: never given a point value
│   └─ Only verified Epics/Legendaries eligible for sprint assignment
│
├─ STAGE 3: Assign Epics/Legendaries to sprint
│   ├─ Scrum master proposes; team must collectively agree
│   ├─ Priority/deadline drives ordering
│   └─ Carried-over items must be re-reviewed for validity
│
├─ STAGE 4: Break Epics into actionable tickets
│   ├─ Tech lead decomposes verified Epics into issues
│   ├─ All new child tickets: State/Unverified, Priority/Backlog
│   ├─ Each child ticket must list parent Epic as dependency
│   ├─ Remain unassigned until work begins
│   └─ Tickets must be completable within one sprint (≤ 2 weeks)
│
├─ STAGE 5: Point estimation (see dedicated tree below)
│
├─ STAGE 6: Owner approval and sprint population
│   ├─ Project owner reviews all child tickets for an Epic
│   ├─ On approval: Epic moves from State/Verified → State/In progress
│   ├─ Team collectively determines sprint capacity (not one person)
│   ├─ When added to sprint: Priority/Backlog → Priority/Critical|High|Medium|Low
│   ├─ New sprint tickets: remain unassigned until work begins
│   └─ Sprint at capacity: no additions without removing something else
│
└─ Requirements across ALL triaging stages:
    ├─ No ticket assigned to individual until work actively started
    ├─ No pre-planning of future sprints (current sprint only)
    └─ All decisions recorded in task management system
```

### "Am I estimating points?"

```
Point estimation rules (poker-style, silent voting):
│
├─ BEFORE ESTIMATION
│   ├─ Ticket must be in State/Verified (no estimation on unverified)
│   ├─ Ticket text must be complete enough to estimate WITHOUT explanation
│   └─ If ticket is incomplete → pause, author must update ticket first
│
├─ THE ESTIMATION PROCESS
│   1. Scrum master confirms ticket readiness
│   2. Everyone reads ticket silently and mentally decides a value
│   3. Scrum master confirms all participants have a number
│   4. Round-robin reveal: each person states ONLY their number
│   5. If unanimous → record that value, done
│   6. If not unanimous:
│      → Lowest and highest estimators give brief factual explanations
│      → No rebuttals, no extended debate at this point
│      → Silent re-vote (same process)
│   7. Repeat until consensus or unanimity
│   8. If persistent major disagreement → ticket is incomplete
│      → Author updates ticket → restart estimation
│
├─ CRITICAL RULES
│   ├─ NO hints or suggestions before the first reveal
│   ├─ NO explaining your reasoning before others reveal
│   ├─ Violations → reset the estimation round
│   ├─ Point values = effort for a PROFICIENT EXPERT (no learning curve)
│   ├─ Personal skill level does NOT affect the point value
│   └─ Only stated number allowed on reveal (no qualifiers or caveats)
│
├─ AFTER CONSENSUS
│   ├─ Scrum master records agreed value in task management system
│   └─ No rationale needed in the ticket
│
└─ RE-ESTIMATION
    ├─ Allowed if requirements shift substantially
    ├─ Allowed if new dependencies discovered
    └─ Same silent vote + reveal process applies
```

### "Am I in sprint planning?"

```
Sprint planning workshop (held at start of each sprint):
│
├─ WHEN
│   ├─ Sprints start: 1st and 15th of every month
│   ├─ If end date on weekend/holiday → sprint closes next working day
│   └─ Sprint duration: exactly 2 weeks (no extensions without ELB approval)
│
├─ THREE PHASES
│   ├─ Phase 1: Triage (review unverified, verify or reject)
│   ├─ Phase 2: Point estimation (for all newly verified tickets)
│   └─ Phase 3: Sprint commitment (select capacity-matched tickets)
│
├─ RULES FOR SPRINT COMMITMENT
│   ├─ Total points must not exceed team's projected capacity
│   ├─ Over-commitment prohibited without project owner + scrum master approval
│   ├─ Ticket enters sprint only if:
│   │   ├─ State/Verified for accuracy and completeness
│   │   ├─ Has MoSCoW/ label (set by project owner)
│   │   └─ Has point value (unless Epic or Legendary)
│   ├─ Mid-sprint scope changes: unanimous team + scrum master agreement required
│   └─ All sprint tickets added to the sprint project in Forgejo
│
├─ MoSCoW RULES
│   ├─ Project owner sets ALL MoSCoW labels (contributors CANNOT set these)
│   ├─ Each ticket: exactly one MoSCoW label before entering sprint
│   ├─ Review Must Have tickets with project owner by day 2 of sprint
│   ├─ Should Have/Could Have can enter sprint only if Must Haves on track
│   └─ MoSCoW labels are dynamic — revisit each sprint planning session
│
└─ SPRINT REVIEW (end of sprint)
    ├─ Must occur before next sprint's planning
    ├─ Live demonstration of key deliverables (Must Have + critical path)
    ├─ Demonstrations: working code/environments, not speculative features
    ├─ Unresolved tickets: document decision to carry over or not
    ├─ Feedback from stakeholders → new tickets → triaged next sprint
    └─ Owner Review: every other sprint (after sprint work done + peer-reviewed)
```

### "Am I writing tests?"

```
Testing requirements (MANDATORY at all levels):
│
├─ TEST-FIRST DEVELOPMENT
│   ├─ Write tests BEFORE implementation (no exceptions)
│   ├─ Tests go in same commit as the implementation they test
│   └─ Never commit implementation without its tests
│
├─ UNIT TESTS — BDD / Gherkin  (project uses Behave)
│   ├─ All unit-level tests must follow Behavior-Driven Development (BDD)
│   ├─ Framework: project uses Behave; other options: Cucumber, SpecFlow, pytest-bdd, rspec, godog
│   ├─ Test format: human-readable Gherkin feature files + step definitions
│   ├─ Location: designated unit test directory  (project: features/)
│   ├─ Mock/fake location: mock subdirectory within test dir  (project: features/mocks/)
│   ├─ DO NOT write xUnit-style tests (raw assertions without BDD structure)
│   ├─ Step files: group by feature, add to existing files before creating new
│   ├─ Name step files after their feature  (Python example: foo_steps.py for foo.feature)
│   ├─ Never commit placeholder steps (all steps must be fully implemented)
│   ├─ Mocks/fakes/stubs: allowed ONLY in unit tests, in the designated mock location
│   ├─ Run via: task runner unit test session  (e.g. nox -s unit_tests)
│   └─ Coverage threshold: ≥ 97%  (e.g. nox -s coverage_report)
│
├─ INTEGRATION TESTS  (project uses Robot Framework)
│   ├─ Framework: keyword-driven integration tests  (project: Robot Framework via pabot)
│   ├─ Other frameworks: Playwright, Cypress, Selenium, `go test` (integration tag)
│   ├─ Location: integration test directory  (project: robot/)
│   ├─ Run via: task runner integration test session  (e.g. nox -s integration_tests)
│   ├─ Exercise real services, endpoints, dependencies
│   ├─ NO mocking in integration tests (strictly prohibited)
│   ├─ Mocks acceptable ONLY for truly impractical external dependencies
│   └─ Must be updated when component interfaces change
│
├─ END-TO-END TESTS  (project uses Robot Framework with real credentials)
│   ├─ Run via: task runner e2e session  (e.g. nox -s e2e_tests)
│   ├─ Requires real external service credentials (separate from integration tests)
│   └─ Tests the complete system with real providers end-to-end
│
├─ PERFORMANCE BENCHMARKS
│   ├─ Write benchmarks for performance-sensitive code
│   │   (project: ASV — Airspeed Velocity; others: JMH, Benchmark.js, `go test -bench`)
│   ├─ Run via: task runner benchmark session  (e.g. nox -s benchmark)
│   └─ PRs: regression check via task runner  (e.g. nox -s benchmark_regression)
│
├─ COVERAGE REQUIREMENTS
│   ├─ Minimum: ≥ 97% (project-specific; C.O.C. baseline is 85%)
│   ├─ Measured independently for unit AND integration suites
│   ├─ PR blocked automatically if below threshold
│   ├─ Only project owner can grant exception (must be documented)
│   └─ Any coverage exclusions: explicit project owner approval required
│
├─ WHAT MUST HAVE TESTS
│   ├─ Every non-trivial function, method, or class (regardless of project coverage %)
│   ├─ Both normal operation AND error/exception paths
│   ├─ All newly introduced behavior (not just line coverage)
│   └─ Regression tests for every bug fix (via TDD workflow)
│
├─ MOCK PLACEMENT (strict)
│   ├─ Mocks/fakes/stubs/fixtures: designated mock directory ONLY  (project: features/mocks/)
│   ├─ NEVER in production source directory (src/) or scripts/
│   ├─ Production code must not contain if-testing guards or test-only code paths
│   └─ Use dependency injection to substitute test doubles
│
├─ TDD BUG FIX TAGS (see also "Am I writing a TDD issue-capture test?")
│   ├─ Required tags: @tdd_issue + @tdd_issue_N + @tdd_expected_fail
│   ├─ @tdd_expected_fail inverts result: failing assertion = CI passes
│   └─ Must use the language's assertion failure type — NOT runtime exceptions
│       (Python: AssertionError  |  Java: AssertionError  |  JS: assert.AssertionError)
│
└─ RUNNING TESTS
    ├─ Always use the task runner — never invoke frameworks directly
    │   Python/nox: never call `behave`, `robot`, or `pytest` directly — use `nox`
    │   Node.js: never call `jest` directly — use `npm run test`
    │   Java: never call `junit` directly — use `./gradlew test`
    ├─ If a task runner session is missing → add it to the task runner config FIRST
    └─ Test failure during development → immediately becomes blocking task
```

### "Am I writing a commit message?"

```
Conventional Changelog commit message format:
│
├─ STRUCTURE
│   Line 1:  <type>(<scope>): <description>
│   Line 2:  (blank line)
│   Line 3+: Body — what was done and WHY (free-form, as long as needed)
│   Last:    ISSUES CLOSED: #N   (or Refs: #N if not closing)
│
├─ TYPE (required)
│   ├─ feat     → new feature (triggers MINOR version bump)
│   ├─ fix      → bug fix (triggers PATCH version bump)
│   ├─ docs     → documentation only
│   ├─ style    → formatting, whitespace (no logic change)
│   ├─ refactor → code restructuring without behavior change
│   ├─ test     → adding or updating tests
│   ├─ chore    → build process, dependency updates, tooling
│   ├─ perf     → performance improvement
│   ├─ ci       → CI/CD configuration
│   ├─ build    → build system changes
│   └─ revert   → reverting a previous commit
│
├─ SCOPE (required, lowercase, e.g. cli, api, auth, tests)
│
├─ DESCRIPTION (required)
│   ├─ Imperative mood: "add feature" not "added feature"
│   ├─ No period at end
│   └─ 50-72 characters max for first line
│
├─ EXAMPLES
│   feat(cli): add tool and validation commands
│
│   fix(auth): resolve null pointer on empty config
│
│   chore(Commitizen): make repository Commitizen friendly
│
│   Added standard Commitizen configuration files to the repo.
│
│   ISSUES CLOSED: #31
│
├─ IF ISSUE HAS PRESCRIBED COMMIT MESSAGE
│   └─ Use EXACTLY the text from ## Metadata section (copy-paste, verbatim)
│
└─ TOOLS
    ├─ Commitizen: git cz (interactive, recommended — works for any language project)
    ├─ npm install -g commitizen@2.8.6 cz-customizable@4.0.0
    └─ Pre-commit hook validates format automatically
```

### "Am I fixing a bug?"

```
Mandatory Bug Fix TDD Workflow:
│
├─ STEP 1: Create TDD issue (before writing ANY code)
│   ├─ Type: Type/Testing
│   ├─ Title: "TDD: <description of bug from bug issue>"
│   ├─ The bug issue DEPENDS ON this TDD issue (bug blocks on TDD)
│   └─ Priority/Critical + MoSCoW/Must Have
│
├─ STEP 2: Write the failing test
│   ├─ Branch naming: tdd/mN-<name> (N = milestone number)
│   │   e.g.: tdd/m3-shacl-crash
│   ├─ Write a BDD scenario that captures the buggy behavior  (project uses Behave)
│   ├─ Tag the test with ALL THREE tags (see Tag Validation Rules below):
│   │   ├─ @tdd_issue
│   │   ├─ @tdd_issue_N (N = bug issue number, e.g. @tdd_issue_123)
│   │   └─ @tdd_expected_fail  ← CRITICAL: inverts pass/fail in CI
│   ├─ The test MUST fail when run normally (it proves the bug exists)
│   └─ ⚠️ Use the language's assertion failure type ONLY — NOT runtime exceptions:
│       Python:     use `assert` or `raise AssertionError(...)` — not ValueError/RuntimeError
│       Java:       throw new AssertionError(...)  — not RuntimeException
│       JavaScript: throw new assert.AssertionError(...)  — not Error or TypeError
│
├─ STEP 3: Merge the TDD test PR
│   ├─ CI passes because @tdd_expected_fail inverts the result
│   ├─ Reviewer verifies test quality and correct tagging
│   ├─ Merge to master through normal PR process
│   └─ Close the TDD issue
│
├─ STEP 4: Implement the fix
│   ├─ Branch naming: bugfix/mN-<name> (SAME suffix as tdd/ branch!)
│   │   e.g.: bugfix/m3-shacl-crash  (matches tdd/m3-shacl-crash)
│   ├─ Implement the fix
│   ├─ REMOVE @tdd_expected_fail tag (leave @tdd_issue and @tdd_issue_N)
│   ├─ Test must now PASS normally
│   └─ Open PR: "Closes #<bug_issue_number>"
│
├─ STEP 5: CI verification
│   ├─ CI checks that @tdd_expected_fail is ABSENT (quality gate)
│   ├─ CI also checks that @tdd_issue_N test EXISTS for bug #N
│   │   ⚠️ If no @tdd_issue_N test in codebase → PR is BLOCKED
│   ├─ Test now runs normally and must pass
│   └─ Coverage must still be ≥ 97%
│
├─ STEP 6: Merge and close
│   ├─ Merge bug fix PR through normal process
│   ├─ Close the bug issue
│   └─ Test stays permanently in codebase as regression guard
│
├─ TAG VALIDATION RULES (enforced by CI)
│   ├─ @tdd_issue_N present → @tdd_issue MUST also be present
│   ├─ @tdd_expected_fail present → @tdd_issue AND @tdd_issue_N MUST be present
│   ├─ Expected-fail steps MUST fail via the language's assertion type (not runtime exceptions)
│   ├─ Bug fix PR closing #N → @tdd_expected_fail MUST be removed from @tdd_issue_N
│   └─ Bug fix PR closing #N → @tdd_issue_N test MUST exist in codebase
│
└─ ASSIGNEE PREFERENCE (not mandatory)
    ├─ Ideally TDD issue and bug fix issue assigned to DIFFERENT developers
    └─ One proves the bug exists, another proves they fixed it
```

### "Am I authoring a document?"

```
Document authoring requirements:
│
├─ EVERY document must have a confidentiality stamp on the title page
│   ├─ No stamp = non-distributable to ANYONE under any circumstances
│   └─ Get your manager to review and approve the classification level
│
├─ WHAT STAMP LEVEL?
│   ├─ Restricted → executive management only (ELB approval for exceptions)
│   ├─ Secret → C-level and above (ELB approval for exceptions)
│   ├─ Trade Secret → named authorized group ONLY (not even C-level by default)
│   ├─ Confidential → all company personnel (ELB approval for exceptions)
│   └─ Public → distributable inside and outside company, no NDA needed
│
├─ COPYRIGHT NOTICE (required on all company documents)
│   └─ "© [YEAR] CleverThis, Inc. This material is protected by U.S., and
│       International copyright laws. Reproduction and distribution of this
│       material is prohibited without prior written consent of the copyright
│       holder."
│   ⚠️ Copyright holder = CleverThis, Inc. (not the author's name)
│
├─ CITATION FORMAT
│   ├─ IEEE style citations for all company documents
│   └─ Exception: journals that require their own citation format
│
├─ LANGUAGE
│   ├─ All written work: English only
│   └─ Meetings: any language acceptable, UNLESS recorded (then English)
│
├─ SCIENTIFIC PAPERS
│   ├─ Must include CleverThis copyright notice
│   ├─ CTO must be listed as an author
│   └─ CTO must be consulted throughout study and writing
│
├─ DIAGRAMS
│   ├─ Use only TDAC-approved tools: Kroki, CleverTempl
│   ├─ All diagrams must comply with TDAC style guidelines
│   ├─ Diagrams must have confidentiality stamps aligned with document
│   └─ Store in centralized repositories per TDAC policies
│
└─ TYPESETTING
    ├─ Use TTAC-approved tools: LaTeX, Typst, Markdown
    └─ All corporate documents must use TTAC templates
```

### "What confidentiality level applies?"

```
Confidentiality classification decision:
│
├─ Can this information be shared publicly?
│   ├─ YES, no NDA needed, can post online → PUBLIC
│   └─ NO → continue
│
├─ Can this be shared with ALL company personnel?
│   ├─ YES (internal matters, general company info) → CONFIDENTIAL
│   └─ NO → continue
│
├─ Is this accessible only to a specific named group?
│   ├─ YES (compartmentalized IP, trade secrets) → TRADE SECRET
│   │   ├─ Access list must be explicitly named on title page
│   │   ├─ C-level and executives do NOT automatically have access
│   │   └─ Modifying access list: ELB written approval required
│   └─ NO → continue
│
├─ Can this be shared with C-level and above?
│   ├─ YES → SECRET
│   └─ NO → continue (must be executive-only)
│       └─ → RESTRICTED (executive management only)
│
└─ For each level, ELB can grant exceptions in writing:
    ├─ Restricted: executive management default, ELB can expand to others
    ├─ Secret: C-level default, ELB can expand to Board or contractors
    ├─ Trade Secret: named group only, ELB can modify named list
    └─ Confidential: all personnel default, ELB can expand externally
```

### "Am I handling credentials or security hardware?"

```
Security rules (non-negotiable):
│
├─ PASSWORDS AND CREDENTIALS
│   ├─ Password manager: gopass ONLY (no exceptions, no third-party tools)
│   ├─ Protected by: Yubikey hardware token
│   ├─ NEVER write passwords in plain text (no spreadsheets, notes, diaries)
│   ├─ NEVER reuse passwords across systems
│   ├─ NEVER share passwords (even with supervisors or IT staff)
│   ├─ Team secrets: team-shared gopass repository folder
│   ├─ Suspected compromise → immediately change + notify EP
│   └─ Short/guessable passwords → prohibited (use random, long passphrases)
│
├─ YUBIKEY HARDWARE TOKENS
│   ├─ Everyone with access to sensitive systems → Yubikey required
│   ├─ Must be registered and enabled with company systems
│   ├─ Must be clearly labeled/serial-numbered to identify owner
│   ├─ Physical possession mandatory during working hours
│   ├─ NEVER lend or share your Yubikey
│   ├─ Lost/damaged/compromised → immediately notify EP + IT security lead
│   └─ Passwords/PINs for Yubikey: follow all password management rules
│
├─ ENCRYPTION
│   ├─ Confidential/Restricted/Secret/Trade Secret → must be encrypted
│   │   when on portable devices or transmitted outside internal networks
│   ├─ Only EP-approved encryption algorithms permitted
│   ├─ Private key sharing: prohibited except under emergency procedures
│   ├─ Periodic key rotation and revocation: required
│   └─ Digital signatures on high-level documents: approved tools only
│
├─ CODE SIGNING
│   ├─ All authenticated commits → must have digital signature
│   ├─ Signature tied to hardware security token (Yubikey)
│   └─ Before sending sensitive files externally → confirm encryption
│
└─ HARDCODING CREDENTIALS
    ├─ NEVER hardcode secrets in code, configuration, or documentation
    ├─ Use environment variables or secrets management systems
    └─ Violation = security breach, report immediately
```

### "Am I working with FOSS (Free and Open Source Software)?"

```
FOSS governance rules:
│
├─ USING A FOSS LIBRARY
│   ├─ Review license for compatibility with CleverThis requirements
│   ├─ If uncertain → request OOC (Open-source Oversight Committee) review
│   └─ Compatible license required before incorporating
│
├─ CONTRIBUTING TO EXTERNAL FOSS PROJECT
│   ├─ Must follow documented approval process
│   ├─ Verify: no conflicts with existing IP or confidentiality agreements
│   └─ Must comply with TCRC (Technical Community Relations) guidelines
│
├─ CREATING A NEW FOSS PROJECT
│   ├─ Register with OOC (document scope, repos, license, maintenance plan)
│   ├─ Include: open source license file (GPL, MIT, Apache, etc.)
│   ├─ Include: README, contributor guidelines, license files
│   ├─ Host on both internal (Forgejo) AND external (GitHub/GitLab) platforms
│   └─ Mirror must be kept synchronized and functional
│
├─ RELEASING PROPRIETARY CODE AS FOSS
│   ├─ Requires explicit approval from EP or EVP AND OOC
│   └─ Verify: IP rights, confidentiality, contractual obligations intact
│
├─ DISCOVERING LICENSE NON-COMPLIANCE
│   ├─ Report to OOC immediately
│   └─ Submit remediation plan to ELB immediately
│
└─ COMMUNITY ENGAGEMENT
    ├─ Prioritize education and support over marketing
    ├─ Maintain authenticity and professionalism
    ├─ Sensitive topics: pre-approval from ELB required
    └─ All presentations: must align with CleverThis branding
```

### "Am I making an architectural decision?"

```
Architectural Decision Record (ADR) process:
│
├─ Is this a change to the project architecture or design?
│   ├─ NO → no ADR needed, proceed with implementation
│   └─ YES → ADR process required BEFORE implementation
│
├─ ADR process:
│   ├─ Capture proposed change in an ADR document
│   ├─ Submit for review and approval
│   ├─ Once approved → incorporate into specification (docs/specification/)
│   └─ Implementation ONLY after specification is updated
│
├─ Source of truth priority:
│   ├─ docs/specification/ is AUTHORITATIVE (see docs/specification/index.md)
│   ├─ When code ≠ specification → align code to specification
│   └─ Never adjust specification to match incorrect code
│
├─ AOC (Architectural Oversight Committee) involvement:
│   ├─ Projects > $50,000 budget OR > 12 months timeline → AOC must review
│   ├─ All architectural designs must include UML or equivalent diagrams
│   └─ Requirements documents due at least 1 sprint before review meeting
│
└─ Tools for architecture diagrams:
    ├─ Approved: Kroki, Umlet
    └─ Approved formats: PlantUML, Mermaid
```

### "Am I escalating an issue?"

```
Escalation paths:
│
├─ TECHNICAL DISPUTE (code quality, architecture)
│   ├─ First: resolve between parties directly
│   ├─ If unresolved: escalate to project owner
│   ├─ Architectural disputes: → AOC (Architectural Oversight Committee)
│   └─ All unresolved: → ELB (Executive Liaison Board)
│
├─ CODE QUALITY STANDARDS DISPUTE
│   └─ → CQAC (Code Quality Assurance Committee)
│
├─ WIKI / DOCUMENTATION DISPUTE
│   ├─ Must be resolved within one sprint
│   └─ If unresolved within sprint: → ELB
│
├─ ETHICAL CONCERN
│   ├─ Report confidentially to EMEC (Ethics Management & Enforcement Committee)
│   └─ EMEC mediates, recommendations signed off by ELB
│
├─ OPERATIONS CODE VIOLATION
│   └─ → OCRB (Operations Code Review Board)
│
├─ SECURITY INCIDENT
│   ├─ Immediately notify relevant supervisor or security liaison
│   ├─ Compromised password/key → change immediately + notify EP
│   └─ Lost Yubikey → immediately notify EP + IT security lead
│
├─ PERSONNEL ISSUE
│   ├─ Promotions/demotions/disciplinary → ELB has final authority
│   └─ Review outcome appeals → request clarification from ELB
│
└─ OPERATIONS CODE CHANGE PROPOSAL
    ├─ Submit to OCRB (all personnel eligible)
    ├─ External proposals: must be endorsed by C-level executive
    ├─ OCRB vote → EP/EVP approval → official release
    └─ Emergency: C-level endorsement required, OCRB has 24-hour window
```

---

## 🆕 Additional Decision Trees

### "What branch name should I use?"

```
Branch naming conventions (milestone number N is required in prefix):
│
├─ WHAT TYPE OF WORK IS THIS?
│   │
│   ├─ New feature or user story
│   │   └─ feature/mN-<descriptive-name>
│   │       e.g. feature/m3-tool-cli
│   │            feature/m5-plan-lifecycle
│   │
│   ├─ Bug fix (implementation of fix)
│   │   └─ bugfix/mN-<descriptive-name>
│   │       e.g. bugfix/m3-shacl-crash
│   │       ⚠️ Suffix MUST match the companion tdd/ branch name
│   │
│   ├─ TDD issue-capture test (proves bug exists)
│   │   └─ tdd/mN-<descriptive-name>
│   │       e.g. tdd/m3-shacl-crash
│   │       ⚠️ Suffix MUST match the companion bugfix/ branch name
│   │
│   ├─ Chore / refactor / infrastructure / dependency update
│   │   └─ feature/mN-<descriptive-name>  (use feature/ prefix)
│   │       e.g. feature/m4-upgrade-dependencies
│   │
│   └─ Documentation-only change
│       └─ feature/mN-<descriptive-name>
│           e.g. feature/m2-contributing-guide
│
├─ RULES
│   ├─ Always include milestone number: mN (e.g. m3, m12)
│   ├─ Name in kebab-case (lowercase, hyphens, no spaces)
│   ├─ Name must be descriptive and match the issue it implements
│   ├─ TDD and bug fix branches share the same descriptive suffix (traceability)
│   └─ Branch must match the Branch field in the issue's ## Metadata section
│
└─ EXAMPLE PAIR (bug workflow)
    ├─ Bug #123: SHACL validation crashes on empty graph
    ├─ TDD branch: tdd/m3-shacl-crash
    └─ Fix branch: bugfix/m3-shacl-crash
```

### "Am I writing or updating documentation?"

```
Documentation standards (all code-related docs):
│
├─ IS THIS NEW OR UPDATED DOCUMENTATION?
│   ├─ New doc: check if a canonical location already exists for this type
│   │   ├─ Existing doc exists → update it (never create a duplicate)
│   │   └─ No existing doc → create in the canonical location for its type
│   └─ Updated doc: find the single canonical location and update there
│
├─ TRACEABILITY RULES (enforced)
│   ├─ Reference code by LOGICAL LOCATION only (language-appropriate format):
│   │   ├─ Python example: mypackage.services.plan_service.PlanService.execute
│   │   ├─ Java example:   com.example.services.PlanService.execute
│   │   └─ TypeScript:     services/planService.PlanService.execute
│   ├─ Include commit hash at time of writing
│   │   └─ e.g. (see commit a3f92b1)
│   ├─ ⚠️ NEVER reference by line number  (e.g. file.py:142 or file.go:87)
│   │   Line numbers shift with every edit and become misleading immediately
│   └─ When names are refactored later, commit hash traces original location
│
├─ CONTINUOUS DOCUMENTATION
│   ├─ Update documentation IN THE SAME COMMIT as the code change
│   ├─ Discoveries, decisions, and workarounds → document immediately
│   ├─ Do not defer documentation to a "later" commit — it never happens
│   └─ Work is NOT done until all affected documentation is updated
│
├─ SINGLE DOCUMENTATION SURFACE
│   ├─ Each type of doc has ONE canonical location
│   ├─ Do not scatter related notes across multiple files
│   ├─ If a doc exists for a purpose, update it (don't create alongside it)
│   └─ Avoid duplicate or parallel documentation for the same content
│
├─ SPECIFICATION vs. CODE
│   ├─ docs/specification/ is THE authoritative source of truth (see docs/specification/index.md)
│   ├─ Before any task: review relevant specification sections
│   ├─ When code ≠ spec → code is wrong, align code to spec
│   └─ Spec changes: go through ADR process, not ad-hoc edits
│
├─ CODE DOCUMENTATION (docstrings / doc comments)
│   ├─ All public functions, classes, methods → docstrings/doc comments required
│   ├─ Non-obvious logic → inline comments explaining WHY (not what)
│   ├─ Avoid comments that merely restate the code
│   └─ Keep comments current when code changes
│
├─ DOCS DIRECTORY (docs/)
│   ├─ All markdown files must be written for the project's doc tool  (project: MkDocs)
│   ├─ Build with: task runner docs session  (e.g. nox -s docs)
│   └─ API docs, architecture overviews, user guides → all in docs/
│
└─ CHANGELOG
    ├─ One new entry per commit (in same commit)
    └─ Describes the change from the user's perspective
```

### "What task runner session should I run?"

```
Complete task runner guide  (this project uses nox — Python):
│
├─ BEFORE COMMITTING (run all of these):
│   ├─ Lint session            → linting  (nox -s lint)
│   ├─ Format check session    → formatting only, no changes  (nox -s format -- --check)
│   ├─ Type check session      → static type checking  (nox -s typecheck)
│   ├─ Unit test session       → BDD tests  (nox -s unit_tests)
│   └─ Coverage session        → verify ≥ 97%  (nox -s coverage_report)
│
├─ BEFORE SUBMITTING A PR (additionally run):
│   ├─ Full default suite       → ALL sessions  (nox)
│   ├─ Security scan session    → (nox -s security_scan)
│   ├─ Unused code session      → (nox -s dead_code)
│   └─ Integration test session → (nox -s integration_tests)
│
├─ SPECIFIC SITUATIONS:
│   ├─ Auto-fix formatting:         Format session  (nox -s format)
│   ├─ End-to-end tests:            E2E session — needs real credentials  (nox -s e2e_tests)
│   ├─ Performance benchmarks:      Benchmark session  (nox -s benchmark)
│   ├─ Benchmark regression:        Benchmark regression session  (nox -s benchmark_regression)
│   ├─ Code complexity analysis:    Complexity session  (nox -s complexity)
│   ├─ Build documentation:         Docs session  (nox -s docs)
│   ├─ Build distributable:         Build session  (nox -s build)
│   └─ Run everything:              Full default suite  (nox)
│
├─ CI JOBS AND THEIR SESSIONS  (project-specific mapping):
│   ├─ lint job              → nox -s lint  +  nox -s format -- --check
│   ├─ typecheck job         → nox -s typecheck
│   ├─ security job          → nox -s security_scan  +  nox -s dead_code
│   ├─ quality job           → nox -s complexity
│   ├─ unit_tests job        → nox -s unit_tests
│   ├─ integration_tests job → nox -s integration_tests
│   ├─ e2e_tests job         → nox -s e2e_tests
│   ├─ coverage job          → nox -s coverage_report  (fail-under 97%)
│   ├─ benchmark-regression  → nox -s benchmark_regression
│   ├─ benchmark-publish     → nox -s benchmark  (publish variant, push to master/develop only)
│   ├─ build job             → nox -s build
│   └─ docker job            → Docker build + smoke test
│
├─ REQUIRED FOR MERGE (status-check gate):
│   ├─ lint ✓
│   ├─ typecheck ✓
│   ├─ security ✓
│   ├─ unit_tests ✓
│   └─ coverage ✓
│   (integration_tests, e2e_tests, benchmark-regression are informational only)
│
├─ UNIVERSAL RULES (apply to any language, not just Python/nox):
│   ├─ ALWAYS use the task runner — never invoke test/lint/type-check tools directly
│   │   Python/nox:    never call `behave`, `robot`, `pyright`, or `ruff` directly
│   │   Node.js:       never call `jest`, `eslint`, or `tsc` directly — use `npm run <script>`
│   │   Java/Gradle:   never call JUnit directly — use `./gradlew test`
│   │   Go:            `go test` is idiomatic, but complex projects wrap it in `make` / `mage`
│   ├─ If a session/script is missing → add it to the task runner config BEFORE using it
│   └─ Test failure → immediately becomes blocking task; fix before moving on
│
└─ NIGHTLY QUALITY SESSIONS  (nightly-quality.yml — not part of standard CI):
    └─ nox -s complexity   (Radon code complexity analysis)
```

### "Am I looking at a CI failure?"

```
Diagnosing and fixing CI failures:
│
├─ WHERE TO LOOK
│   ├─ 1. Open the PR → scroll to "Checks" section at the bottom
│   ├─ 2. Each job appears as a separate named check
│   ├─ 3. Click a failed job → view its full log
│   └─ 4. The status-check job summarizes all required results
│
├─ WHICH JOBS ARE REQUIRED FOR MERGE?
│   ├─ lint       → linting + format check  (Python/nox: nox -s lint, nox -s format -- --check)
│   ├─ typecheck  → static type checking    (Python/nox: nox -s typecheck)
│   ├─ security   → security scan + dead code  (Python/nox: nox -s security_scan, nox -s dead_code)
│   ├─ unit_tests → BDD unit tests          (Python/nox: nox -s unit_tests)
│   └─ coverage   → coverage ≥ 97%          (Python/nox: nox -s coverage_report)
│   Other jobs (integration_tests, e2e_tests, benchmark-regression) are informational
│
├─ DIAGNOSING SPECIFIC FAILURES:
│   │
│   ├─ lint failure
│   │   ├─ Run the lint session to see exact violations  (e.g. nox -s lint)
│   │   ├─ Auto-fix where possible  (e.g. nox -s format)
│   │   └─ Remaining violations → fix manually
│   │
│   ├─ typecheck failure
│   │   ├─ Run the type check session to see errors  (e.g. nox -s typecheck)
│   │   ├─ Fix ALL type errors — never add inline type suppression comments:
│   │   │   Python: # type: ignore  |  TypeScript: // @ts-ignore  |  Java: @SuppressWarnings
│   │   └─ Never disable the type checker in configuration files
│   │
│   ├─ security failure
│   │   ├─ Run the security scan session  (e.g. nox -s security_scan)
│   │   ├─ Run the dead code session  (e.g. nox -s dead_code)
│   │   ├─ Fix or suppress findings with proper justification comments
│   │   └─ High-severity findings → must be fixed, not suppressed
│   │
│   ├─ unit_tests failure
│   │   ├─ Run the unit test session to see failing scenarios  (e.g. nox -s unit_tests)
│   │   ├─ Fix the failing step or the code it exercises
│   │   └─ ⚠️ @tdd_expected_fail failure means bug was fixed without removing the tag
│   │
│   ├─ coverage failure
│   │   ├─ Run the coverage session  (e.g. nox -s coverage_report)
│   │   ├─ Look for "COVERAGE OK" or "COVERAGE FAILED" in the output
│   │   ├─ Look at coverage report for uncovered lines
│   │   ├─ Add tests for uncovered paths
│   │   └─ Exception: project owner approval required for any coverage exclusion
│   │
│   └─ TDD tag gate failure (in unit_tests or a dedicated CI gate)
│       ├─ "@tdd_expected_fail still present on @tdd_issue_N" → remove the tag
│       └─ "no @tdd_issue_N test found for bug #N" → TDD step was skipped
│
├─ AFTER FIXING
│   ├─ Run the affected task runner session locally to confirm the fix
│   ├─ Run the full task runner suite to ensure no regressions  (e.g. nox)
│   └─ Push the fix — CI re-runs automatically
│
└─ NEVER:
    ├─ Skip failing checks by force-pushing without fixing them
    ├─ Use inline type suppression comments to silence the type checker
    │   (Python: # type: ignore  |  TypeScript: // @ts-ignore  |  Java: @SuppressWarnings)
    └─ Use --no-verify to bypass pre-commit hooks
```

### "Which directory should this file go in?"

```
File organization — every file has a canonical home:
│
├─ /src/<package>/
│   ├─ Production source code ONLY
│   │   Example: src/myapp/ for a Python project named "myapp"
│   │            src/main/java/com/example/ for a Java project
│   │            src/ for a TypeScript project
│   ├─ Source packages, modules, and components for the target language
│   ├─ ⚠️ MUST NOT contain: tests, mocks, test data, documentation, examples
│   └─ If you're tempted to put test/mock code here → put it in the test mock directory
│
├─ /features/   (project's BDD unit test directory — project uses Behave)
│   ├─ BDD unit tests ONLY — Gherkin *.feature files + step definitions
│   ├─ steps/ subdirectory — step definition files
│   └─ /features/mocks/ → ALL mocks, fakes, stubs, test doubles for this project
│       ⚠️ This is the ONLY place mocks are allowed in this project
│   Note: other frameworks/languages may name this spec/, test/, tests/unit/, or __tests__/
│
├─ /robot/   (project's integration and e2e test directory — project uses Robot Framework)
│   ├─ Integration and end-to-end tests ONLY — .robot and .resource files
│   └─ ⚠️ No mocks allowed here (real services only)
│   Note: other projects may name this tests/integration/, e2e/, cypress/, or test/e2e/
│
├─ /docs/
│   ├─ Documentation and markdown files  (project: MkDocs format)
│   ├─ docs/specification/ → THE authoritative architecture specification (see docs/specification/index.md)
│   └─ API docs, user guides, architecture docs, changelog
│
├─ /config/
│   └─ Configuration files (not the project manifest — that stays in root)
│
├─ /scripts/
│   ├─ Utility shell/automation scripts  (e.g. setup-dev.sh)
│   └─ ⚠️ MUST NOT contain: mock code, test data, production source
│
├─ /examples/
│   └─ Example code demonstrating project usage
│
├─ /k8s/
│   └─ Kubernetes Helm chart for server deployment
│
├─ ROOT LEVEL (project root only — keep clean)
│   ├─ Project manifest / build config:
│   │   Python: pyproject.toml  |  Node.js: package.json  |  Java: build.gradle / pom.xml
│   ├─ Task runner config:
│   │   Python/nox: noxfile.py  |  Node.js: scripts in package.json  |  make: Makefile
│   ├─ Pre-commit hooks config  (e.g. .pre-commit-config.yaml)
│   ├─ Test framework / runner config  (e.g. robot.cfg, jest.config.js, pytest.ini)
│   ├─ README, CONTRIBUTING, LICENSE, CHANGELOG, CONTRIBUTORS.md
│   ├─ CI/CD workflow definitions  (e.g. .forgejo/, .github/)
│   └─ Other widely recognized root-level convention files
│   ⚠️ NO arbitrary files in root — if it doesn't conventionally live there,
│       put it in an appropriate subdirectory
│
└─ DECISION HEURISTIC
    ├─ Is it production code?               → /src/<package>/
    ├─ Is it a BDD scenario or step?        → /features/ (or project's BDD test dir)
    ├─ Is it a mock/fake/stub?              → /features/mocks/ (or project's mock location)
    ├─ Is it an integration/e2e test?       → /robot/ (or project's integration test dir)
    ├─ Is it documentation?                 → /docs/
    ├─ Is it a config file?                 → /config/
    ├─ Is it a utility script?              → /scripts/
    ├─ Is it example code?                  → /examples/
    └─ Is it a Kubernetes resource?         → /k8s/
```

### "Am I setting up my development environment?"

```
Development environment setup (new contributor checklist):
│
├─ STEP 1: Clone the repository
│   └─ git clone <repo-url>
│
├─ STEP 2: Run the setup script
│   ├─ scripts/setup-dev.sh
│   └─ This installs pre-commit hooks that run automatically on every commit
│
├─ STEP 3: Verify the setup
│   ├─ Run the full task runner suite  (Python/nox: nox)
│   └─ All sessions must be green before you start work
│
├─ STEP 4: Install Commitizen (recommended — works for any language project)
│   ├─ npm install -g commitizen@2.8.6 cz-customizable@4.0.0
│   └─ Use: git cz  (instead of git commit — guides you through message format)
│
├─ STEP 5: Read key documents
│   ├─ CONTRIBUTING.md → all project rules (top priority)
│   ├─ docs/specification/ → architecture and design decisions (see docs/specification/index.md)
│   └─ This skill file → procedural decision trees
│
├─ VERIFICATION CHECKLIST  (examples use Python/nox)
│   ├─ Lint session → green?              (nox -s lint)
│   ├─ Type check session → green?        (nox -s typecheck)
│   ├─ Unit test session → green?         (nox -s unit_tests)
│   ├─ Coverage session → ≥ 97%?          (nox -s coverage_report)
│   ├─ Pre-commit hooks installed?         (git commit should trigger hooks)
│   └─ git cz available if Commitizen installed?
│
└─ WHAT TOOLS ARE USED  (this project — Python ecosystem)
    ├─ Hatch        → Python project management  (hatch env create, hatch build)
    ├─ nox          → task automation  (ALWAYS use nox, never invoke tools directly)
    ├─ pyproject.toml → all project configuration  (single-source truth)
    ├─ Behave       → BDD unit tests  (Gherkin feature files + step definitions)
    ├─ Robot Framework + pabot → integration and e2e tests
    ├─ Pyright      → static type checking  (strict, no suppressions ever)
    ├─ ruff         → linting and formatting
    ├─ Slipcover    → test coverage measurement  (fail-under 97%)
    ├─ Commitizen   → interactive commit message generation
    └─ pre-commit   → automated quality hooks

    General principle (any language): use modern, idiomatic tooling for your
    ecosystem. Avoid legacy approaches (raw Makefiles, ad-hoc shell wrappers).
    All tooling should be from the current ecosystem and used as designed.
```

### "Should this be an Issue, Epic, or Legendary?"

```
Ticket type hierarchy decision:
│
├─ CAN IT BE DONE IN ONE COMMIT?
│   ├─ YES AND it's a single concern → ISSUE (atomic work unit)
│   │   ├─ Maps to exactly 1 commit
│   │   ├─ One developer can own it completely
│   │   └─ Must belong to at least one parent Epic
│   └─ NO → not an Issue, continue
│
├─ IS IT A GROUP OF RELATED ISSUES with a demonstrable capability?
│   ├─ YES → EPIC
│   │   ├─ Must contain at least 2 child issues
│   │   ├─ Produces a demonstrable outcome (not just "code was written")
│   │   ├─ Has own acceptance criteria beyond "all children closed"
│   │   ├─ Must belong to a parent Legendary
│   │   └─ Typically aligns with a single milestone
│   └─ NO → not an Epic, continue
│
├─ IS IT A MAJOR STRATEGIC PILLAR spanning multiple milestones?
│   ├─ YES → LEGENDARY
│   │   ├─ Must contain at least 2 child Epics
│   │   ├─ Spans multiple milestones naturally
│   │   ├─ Has articulated terminal condition (when is it fully realized?)
│   │   ├─ No parent ticket (root node)
│   │   └─ Progress measured by Epic completion, not issue counts
│   └─ NO → something is wrong; reconsider scope
│
├─ PROMOTION / DEMOTION RULES
│   ├─ Issue grows beyond 1 commit → promote to Epic, break into issues
│   ├─ Epic collapses to 1 issue → demote (absorb issue into another Epic)
│   └─ Legendary left with 1 Epic → absorb into another Legendary
│
└─ QUICK TESTS
    ├─ "Can I describe it in one commit message?" → Issue
    ├─ "Will I show stakeholders a working capability when done?" → Epic
    ├─ "Does it represent a major dimension of what makes the project succeed?" → Legendary
    └─ "Does it need 'and' to describe two separate things?" → split into two tickets
```

### "Is this ticket well-scoped? (Issue quality criteria)"

```
11-point issue quality checklist (ALL must pass):
│
├─ 1. ATOMICITY
│   ├─ Smallest meaningful unit of work? (not smaller, not larger)
│   └─ If describing it requires "and" between unrelated actions → split
│
├─ 2. SINGLE COMMIT
│   ├─ Maps to exactly one commit?
│   └─ One commit = one issue (no multi-commit issues)
│
├─ 3. SINGLE RESPONSIBILITY
│   ├─ Addresses exactly one concern?
│   └─ One bug fix / one function / one refactor / one doc update
│
├─ 4. ASSIGNABILITY
│   ├─ One developer can own it completely?
│   └─ No required synchronization with other in-flight work?
│
├─ 5. VERIFIABILITY
│   ├─ Has a clear, binary verification criterion?
│   └─ Any reviewer can independently verify pass/fail?
│
├─ 6. SELF-CONTAINMENT
│   ├─ All context in the issue + parent Epic?
│   └─ Developer can begin without seeking clarification?
│
├─ 7. IMPLEMENTATION INDEPENDENCE
│   ├─ Can ideally be implemented without blocking on other issues?
│   └─ If ordering dependencies exist → explicitly documented via linking?
│
├─ 8. SUBTASK DECOMPOSITION
│   ├─ Checkbox list of discrete steps in ## Subtasks section?
│   └─ Exception: only if so trivial that decomposition would be absurd
│
├─ 9. LEAF NODE
│   ├─ Has NO child tickets?
│   └─ If decomposition needed → promote to Epic, break into issues
│
├─ 10. MANDATORY PARENT
│   ├─ Linked to at least one parent Epic?
│   └─ No orphan issues (issues without parent Epics are rejected)
│
└─ 11. FINITE COMPLETION
    ├─ Done when commit is merged and criteria pass?
    ├─ No ongoing/recurring obligation?
    └─ No reopening permitted → new issue if follow-up needed
```

### "Am I releasing a new version?"

```
Release process:
│
├─ WHEN TO RELEASE
│   ├─ New functionality → bump MINOR (e.g. v1.5.0 → v1.6.0)
│   ├─ Bug fix in released version → bump PATCH (e.g. v1.6.0 → v1.6.1)
│   ├─ Breaking API change → bump MAJOR (e.g. v1.x.x → v2.0.0)
│   └─ Refactoring / docs / tests → usually no version bump
│
├─ STEP 1: Verify everything is ready
│   ├─ Full task runner suite → all green  (e.g. nox)
│   ├─ Changelog updated with all changes since last release
│   ├─ Version number bumped in the project manifest
│   │   (Python: pyproject.toml  |  Node.js: package.json  |  Java: build.gradle)
│   └─ All required CI checks passing on master
│
├─ STEP 2: Create and push the version tag
│   ├─ git tag v1.2.3    (format: v + semantic version number)
│   └─ git push origin v1.2.3
│
├─ STEP 3: release.yml workflow runs automatically
│   ├─ Builds distributable artifact  (Python/nox: nox -s build → wheel)
│   ├─ Builds Docker image tagged with version + "latest"
│   ├─ Pushes Docker image to container registry
│   └─ Creates Forgejo release with artifact as downloadable file
│
├─ REQUIRED REPOSITORY SECRETS (must exist for release to succeed)
│   ├─ CONTAINER_REGISTRY → Docker registry URL
│   ├─ CONTAINER_REGISTRY_USER → Registry auth username
│   ├─ CONTAINER_REGISTRY_PASSWORD → Registry auth password
│   ├─ FORGEJO_TOKEN → API token for creating releases
│   └─ FORGEJO_URL → Forgejo instance URL
│
└─ VERSION FORMAT
    ├─ v<MAJOR>.<MINOR>.<PATCH>
    ├─ e.g. v1.2.0, v1.2.1, v2.0.0
    └─ Must follow Clever Semantic Versioning (W3C Semantic Versioning)
```

### "Am I writing a TDD issue-capture test?"

```
TDD issue-capture test requirements (detailed tag rules):
│
├─ WHEN TO WRITE THIS
│   ├─ A new Type/Bug issue exists
│   ├─ A companion Type/Testing "TDD: <bug description>" issue was created
│   └─ You are working on the TDD issue (not the bug fix itself)
│
├─ BRANCH
│   └─ tdd/mN-<descriptive-name>  (e.g. tdd/m3-shacl-crash)
│
├─ THE TEST ITSELF
│   ├─ Framework: BDD with Gherkin  (project uses Behave — adapt for your BDD framework)
│   ├─ Scenario must capture the buggy behavior:
│   │   └─ Given the conditions that trigger the bug
│   │   └─ When the action that causes the bug is performed
│   │   └─ Then the assertion that SHOULD pass but currently FAILS
│   └─ The assertion must fail when the bug is present (proving the bug)
│
├─ REQUIRED TAGS (all three are mandatory):
│   │
│   ├─ @tdd_issue
│   │   ├─ Generic filter tag — on ALL TDD issue tests
│   │   ├─ Used to list, filter, and count TDD tests across codebase
│   │   └─ PERMANENT — never removed
│   │
│   ├─ @tdd_issue_N   (N = the bug issue number, e.g. @tdd_issue_123)
│   │   ├─ Links this test to the specific bug issue
│   │   ├─ CI checks for this tag when a bug fix PR closes issue #N
│   │   └─ PERMANENT — never removed (serves as regression reference)
│   │
│   └─ @tdd_expected_fail
│       ├─ Behavioral switch: inverts pass/fail in CI
│       ├─ Test PASSES CI when the underlying assertion FAILS (bug present)
│       ├─ Test FAILS CI when the underlying assertion PASSES (bug fixed
│       │    without removing this tag — catches premature success)
│       └─ TEMPORARY — MUST be removed by the bug fix developer
│
├─ ASSERTION TYPE REQUIREMENT (critical — applies to any language)
│   ├─ Steps that signal "bug still present" MUST fail via the language's
│   │   assertion failure type — NOT via runtime or infrastructure exceptions
│   ├─ Python (this project):
│   │   ├─ Use: assert some_condition, "message"
│   │   └─ Use: raise AssertionError("bug still present")
│   │   ⚠️ Do NOT use: ValueError, RuntimeError, OSError, or other non-assertion exceptions
│   ├─ Java:          throw new AssertionError(...)  — not RuntimeException
│   ├─ JavaScript/TS: throw new assert.AssertionError(...)  — not Error or TypeError
│   └─ The rule is universal: assertion failures are inverted by the TDD hook;
│       runtime/infrastructure exceptions are NOT inverted and will break the suite
│
├─ TAG VALIDATION RULES (CI enforces all of these):
│   ├─ @tdd_issue_N present → @tdd_issue MUST also be present
│   ├─ @tdd_expected_fail present → @tdd_issue AND @tdd_issue_N MUST be present
│   └─ Missing any required tag → CI rejects the test
│
├─ EXAMPLE — before bug fix (Python/Behave):
│   @tdd_issue @tdd_issue_123 @tdd_expected_fail
│   Scenario: Bug #123 - SHACL validation rejects valid graph
│     Given a valid resource graph
│     When SHACL validation is applied
│     Then the validation should succeed   ← this assertion fails (bug present)
│
├─ EXAMPLE — after bug fix (developer removes @tdd_expected_fail):
│   @tdd_issue @tdd_issue_123
│   Scenario: Bug #123 - SHACL validation rejects valid graph
│     Given a valid resource graph
│     When SHACL validation is applied
│     Then the validation should succeed   ← now passes (bug fixed)
│
└─ MERGING THE TDD PR
    ├─ CI passes because @tdd_expected_fail inverts the result
    ├─ Reviewer checks: test quality, correct tagging, correct assertion type usage
    ├─ Merge to master (normal PR process)
    └─ Close the TDD issue; bug issue remains open (depends on bug fix PR)
```

---

## 📏 Key Numbers Reference

| Rule | Value | Source |
|------|-------|--------|
| Test coverage minimum | **97%** | CONTRIBUTING.md (overrides C.O.C. 85%) |
| PR approvals minimum | **1** (self-approval allowed; formal or comment) | CONTRIBUTING.md (overrides C.O.C. 2) |
| C.O.C. PR approvals baseline | **2** (no self-approval) | C.O.C. (project overrides to 1) |
| Max file size | **500 lines** | CONTRIBUTING.md |
| Sprint duration | **2 weeks** | C.O.C. |
| Sprint starts | **1st and 15th of month** | C.O.C. |
| Daily standup max | **15 minutes** | C.O.C. |
| Minimum ticket task size | **15 minutes** | C.O.C. |
| Owner Review frequency | **Every other sprint** | C.O.C. |
| Personnel reviews | **Biannually (every 6 months)** | C.O.C. |
| Probationary reviews | **Monthly** | C.O.C. |
| Operations Code review | **Biannual** | C.O.C. |
| OCRB vote majority | **Simple majority (all members, not just present)** | C.O.C. |
| OCRB quorum | **>50% of board members** | C.O.C. |
| Committee quorum | **>50% of committee members** | C.O.C. |
| Blocked issue resolution | **Report to ELB if unresolved >1 sprint** | C.O.C. |
| AOC review threshold | **$50K budget or 12-month timeline** | C.O.C. |
| C.O.C. baseline coverage | **85%** | C.O.C. (this project uses 97%) |
| MR auto-reports retention | **1 year** | C.O.C. |
| CI trigger (ci.yml) | **Push to master/develop; PRs to master/develop*** | CONTRIBUTING.md |
| Nightly quality sweep | **Daily midnight UTC** (nightly-quality.yml) | CONTRIBUTING.md |
| Release trigger | **Push v* tag** (e.g. v1.2.3) | CONTRIBUTING.md |
| Required CI jobs for merge | **lint, typecheck, security, unit_tests, coverage** | CONTRIBUTING.md |
| Issue ↔ PR dependency direction | **PR blocks issue; issue depends on PR** | CONTRIBUTING.md |
| Epic minimum children | **2 child issues** | CONTRIBUTING.md |
| Legendary minimum children | **2 child Epics** | CONTRIBUTING.md |
| TDD assertion failure type | **Language assertion type only** (Python: AssertionError; not runtime exceptions) | CONTRIBUTING.md |

---

## 📂 Reference Index

| Category | Files | Covers |
|----------|-------|--------|
| `references/commits/` | README | Conventional Changelog, atomic commits, pre-commit hooks |
| `references/pull-requests/` | README | PR checklist, review process, merge criteria |
| `references/testing/` | README | BDD/Behave (unit), Robot Framework (integration), 97% threshold, TDD, mock placement |
| `references/issue-tracking/` | README | Full issue guide, label system, ticket states, dependencies |
| `references/sprints/` | README | Sprint structure, 6-stage triaging, poker points, MoSCoW |
| `references/code-style/` | README | SOLID, programming patterns, error handling, static type checking |
| `references/security/` | README | gopass, Yubikey rules, encryption policy, code signing |
| `references/information/` | README | Stamp levels, document authoring, traceability, email conventions |
| `references/organizational/` | README | C.O.C. org structure, ELB, OCRB, 12 committees, reviews |
| `references/project-tools/` | README | task runner sessions (nox), CI pipeline (all jobs), release process, Hatch |
| `references/open-source/` | README | FOSS governance, open standards mandate, POSIX |
