Skip to content

Tenka Concepts

"Tenka" (天下) refers metaphorically to the vision of a colossal project — literally "all under heaven" or "everything under the sky." In Daimyo, Tenka is the domain for modeling project requirements through User Stories and Acceptance Criteria, and tracking their validation status.

While rules and katas provide the "what" and "how" of development standards, Tenka provides the "why" and "when is it done" of the project's functional goals.

User Stories

A User Story describes a desired capability from the perspective of a user.

Scope-local ID Format: MUST follow US<us_num> (e.g., US101).

Format: "As a(n) <who>, I want <what>, so that <why>."

Tags (Optional): User stories can include tags for additional metadata (e.g., tags: [Functional, Core]).

Acceptance Criteria (AC)

Acceptance Criteria define the specific conditions that must be met for a user story to be considered complete.

Immutability: ACs are immutable. Once a requirement is established, existing ACs SHOULD NOT be modified. To change a requirement, deactivate the old AC (using active: false) and introduce a new one.

Scope-local ID Format: MUST follow AC<us_num>.<ac_num> (e.g., AC101.1).

Format: "Given <precondition>, when <action>, then <outcome>."

Tags (Optional): Acceptance criteria can include tags for additional metadata (e.g., tags: ["OWASP A03:2021"]).

Tenka YAML Format (tenka.yml)

User stories and ACs are defined in a tenka.yml file within a scope directory:

tenka:
  US123:
    who: Administrator
    what: a user management facility
    why: I can manage users and permissions
    acs:
      AC123.1:
        given: a new username
        when: inserting the user
        then: the user is added to the database
        active: false  # ACs can be deactivated
      AC123.3:
        given: a new username and 2FA is enabled
        when: inserting the user
        then: the user is added and a 2FA setup is triggered
      AC123.2:
        then: permission changes are logged to the audit trail
  US456:
    who: Developer
    what: automated API documentation
    why: consumers can understand the interface
    active: false  # Stories can be deactivated

history:
  - timestamp: "2026-05-20T10:00:00Z"
    reason: "Updated user creation to require 2FA"
    obsolete_acs:
      - AC123.1
    added_acs:
      - AC123.3

Requirement Change History

Daimyo tracks the evolution of requirements through the history block in tenka.yml. This ensures that all changes to acceptance criteria are traceable and version-controlled.

History Entry Fields:

  • timestamp: ISO 8601 timestamp of when the change was made.
  • reason: Human-readable description of why the requirement changed.
  • obsolete_acs: List of AC IDs that are no longer active as a result of this change.
  • added_acs: List of new AC IDs introduced by this change.

Querying History:

You can query the requirement change history using:

  • CLI: daimyo tenka get-history
  • MCP: get_tenka_history tool

Both tools support filtering by date, changes since the last fulfillment, or changes since the last git commit.

Fulfillment (tenka.fulfillment.yml)

TenkaFulfillment tracks the validation of acceptance criteria. Unlike rules, katas, and stories, fulfillment data is local-only and is never inherited across scope boundaries. It represents the actual state of the project in a specific workspace.

Daimyo supports aggregating fulfillment data from multiple files within a scope directory: - tenka.fulfillment.yml: The main fulfillment file (base layer). - tenka.fulfillment.*.yml: Sidecar files (e.g., tenka.fulfillment.manual.yml).

Sidecar files allow you to organize fulfillment data more effectively, for example by committing manual validations to git while keeping automated results (which may change frequently and contain local paths) gitignored.

Merging Strategy: When loading fulfillment data for a scope: 1. tenka.fulfillment.yml is loaded as the base layer. 2. All tenka.fulfillment.*.yml sidecar files are discovered and merged in alphabetical order by filename. 3. Auto Validations: Deduplicated by (ac_ref, source, name). The entry with the latest timestamp wins. 4. Manual Validations: All entries from all files are accumulated without deduplication.

Validation Types:

  • Auto (auto): Automated test results (source file, test name, message).
  • Manual (manual): Human verification results (verdict).

Fulfillment entries can be managed through: - CLI: daimyo tenka import-results (for automated reports) and daimyo tenka validate-ac (for manual verdicts). - MCP: import_test_results and validate_acceptance_criterion tools.

YAML Format (tenka.fulfillment.yml):

tenka_fulfillment:
  AC123.1:
    - type: auto
      passed: true
      source: tests/unit/test_users.py
      name: test_user_insertion
      timestamp: "2026-05-15T10:00:00Z"
  AC123.2:
    - type: manual
      passed: false
      verdict: Audit logs are missing the 'actor_id' field.
      timestamp: "2026-05-15T11:30:00Z"

Merging Strategy

When scope inheritance resolves a merged scope:

  • USs only in parent: inherited verbatim.
  • USs only in child: added as-is.
  • USs in both: child fields (who, what, why, active) replace parent fields.
  • AC Merging: Child ACs override parent ACs by the same ID. Parent ACs not redefined in the child are retained (selective override).

Domain Model

Tenka            → UserStory      → AcceptanceCriterion
TenkaFulfillment → ACFulfillment  → Validation (Auto/Manual)