How to use Concord

Review the specifications affected by a change, select checks from the Git diff, and trace the results back to the relevant specifications. The workflow below uses a repository with search and detail APIs.

From changes to verification

Install Concord and run it from the root of the target Git repository. Configure runners and commands in concord.toml, and define requirements, contracts, properties, and relations under concord/.

  1. Update the definitions

    Identify the requirements, contracts, and properties that need to change. For example, revise the search API property when its visibility rules change, and record the relevant implementation and checks in the Relation.

  2. Check the definitions

    Check YAML syntax, IDs and references, and concord.toml settings. Fix errors in diagnostics first, then review warnings such as unapproved definitions or missing verification obligations.

    concord check
  3. Update tests and implementation

    Review the expected behavior and add or update tests. Then update the implementation to satisfy them. Update the Relation if its implementation or test references change.

  4. Review which checks are selected

    Use main as the comparison base. Review the tests and registered commands selected for the current Git diff and why Concord chose them. Read selected_files and selected_commands for the targets, and decisions and command_decisions for the reasons. If Concord expands verification to a full run, such as after a definition or shared configuration change, check mode and fallback_reasons.

    concord plan --base main --json
  5. Run verification

    Use the same comparison base. Concord selects and runs tests and registered commands for the current diff. Read status, passed, failed, and skipped for test outcomes, and command_results[] for registered commands. A noop run executes no checks.

    concord verify --base main --json
  6. Inspect failures and selection reasons

    Locate the failure in the verify output, then pass the test or command ID to explain. It reads the most recently saved plan, so inspect it before running a new plan.

    cases[].test_id
    Find the case with status failed in cases[] and use its test_id. If test_id is absent and both file and name match a plan.tests[] entry in the same output, use that entry's id.
    command_results[]
    Find the failed registered command in command_results[] and read its id, exit code, and logs. For individual failures in tools such as Playwright, also read the runner's report.
    concord explain TEST_ID

    For a test ID, explain shows selection reasons and related Relations, Contracts, and Properties. For a command ID, it shows the command's selection reason. Read verification outcomes in verify output, then use the Relation's implementations and obligations to see which code, tests, or specifications need attention.

Repository layout

Track concord.toml and the YAML files under concord/ in Git. Keep local results out of version control by adding /.concord/ to the repository's .gitignore.

View examples
my-repository/
├── concord.toml
├── concord/
│   ├── requirements/
│   ├── contracts/
│   ├── properties/
│   └── relations/
├── src/
├── tests/
└── .concord/