Reference › Commands › Requirements

Reference › Commands

Requirements

The commands for requirements: baselines, sign-off, issues, standards, specifications and diagrams.

Commands: archec baseline · archec approve · archec approvals · archec issues · archec status · archec cert · archec qualify · archec polarion · archec reqif · archec doc · archec diagram

On this page: More on these commands

Command What it does
archec baseline <main.arche> [--name v1.0] [--sign [--key ~/.ssh/id_ed25519]] Freeze the requirements (baselines/<name>.json); the linter then marks the links to a reworded one as suspect. --sign: an SSH signature beside it (<name>.json.sig, ssh-keygen -Y sign, namespace arche-baseline) with --key, else ARCHE_SIGNING_KEY, else git's user.signingkey when gpg.format is ssh.
archec baseline <main.arche> --verify [name] Each baseline's signature (or one) against reviews/allowed_signers (git's allowed-signers format: qa@example.com ssh-ed25519 AAAA…). Exit 1 on a bad signature or a signer not listed.
archec approve [main.arche] <id…> --as <name> [--role <role>] [--code] Sign-off: records in reviews/approvals.yaml who approved each element (a requirement, a case, a test plan, Car.brakes…), in which role, when, and a fingerprint of what it said — a requirement's wording as a baseline keeps it (a status or an owner changing does not undo it), another element's declaration without its comments and layout (a part's with its definition). One line per approval, sorted, for git. Approving again replaces that person's approval. --as defaults to git's user.name; the model to main.arche here. --code: a part's code instead (Pump.ctrl): a fingerprint of each file its source names, stale when one changes; archec debt counts the files still as approved as signed off (comprehension debt).
archec approvals [main.arche] [--stale] [--json] The approvals, each current, stale (the element changed since: approve it again) or gone. --stale: only those, exit 1 when there is one. archec cert shows who approved each requirement (a stale approval is a gap) and the baselines' signatures; archec ci --require-approval fails while a requirement has no current approval.
archec changes <main.arche> [--since v1.0] [--json] Requirements added, removed and changed since a baseline (the newest by default), and the suspect links.
archec issues sync [main.arche] [-o arche-out | --results test-results.json] [--only cases|requirements] [--dry-run] An issue in Jira (REST v3), GitHub or GitLab for each case the last run says failed (.archec/test-results.json, as archec test writes it) and each requirement that is not verified — nothing verifies it, its cases failed, or none of them ran. The issue's key is written on the element, in its place among the properties: issue "CAR-128" (acme/car#7 on GitHub and GitLab). An element that has one gets its issue updated; one whose problem is gone gets a comment, and on GitHub and GitLab its issue closed (a Jira workflow is the project's own). The tracker is in issues.yaml beside the model — tracker: jira|github|gitlab, url, project (the Jira key, owner/repo, the GitLab path), issue-type, labels — or --tracker, --url, --project; the token in the environment: JIRA_EMAIL + JIRA_API_TOKEN or JIRA_TOKEN, GITHUB_TOKEN, GITLAB_TOKEN. It sends model text out (the ids, names and texts of those elements), only when this command runs; --dry-run prints the requests (the token left out), sends nothing and writes nothing. Offline by default: archec config allow issues lets it reach the tracker (ai-engineering.md).
archec issues list [main.arche] [--json] Every requirement, plan and case with an issue.
archec polarion <workitems.json> [--project main.arche] [-o out.arche] [--config polarion.yaml] [--document "Name=ID"…] [--module text…] [--id puid] A Polarion project's work items, from a JSON export of its REST API, as requirements — any project: the standard fields known, a custom field recognised by its name or said in polarion.yaml, anything else kept as attr. A link between them in a derives role (parent, satisfies, refines…) is derives, the others attr polarion-links. Importing.
archec polarion pull [main.arche] [-o out.arche] [--save workitems.json] [--url u] [--polarion-project P] [--query q] [--dry-run] The same, read from the server named in polarion.yaml (every page of the query), the token POLARION_TOKEN from the environment; the requirements are written to out: — pulling again rewrites them. --dry-run: the request, not sent. Offline by default: archec config allow polarion lets it reach the server (ai-engineering.md).
archec reqif <main.arche> [-o out.reqif] [--document D] The requirements as ReqIF 1.2 (DOORS, Polarion, Jama…).
archec reqif <in.reqif> [-o out.arche] A ReqIF file's requirements in arche-lang.
archec doc <main.arche> [-o spec.tex|spec.html|spec.md] [--html|--md] [--no-diagrams] The specification: LaTeX, one self-contained web page, or Markdown. The page draws each view (a viewpoint with include lines) and plays each scenario on its system's blocks (SVG, no script); the Markdown has them as Mermaid. --no-diagrams leaves them out. --provenance adds a chapter on who wrote the code (see provenance).
archec doc <main.arche> --template <file.docx|file.odt> [-o out.docx] Your own Word (.docx, .dotx) or LibreOffice (.odt, .ott) document, its placeholders filled with the model: {{ requirement REQ-1 .text }}, loops that repeat table rows ({{#each requirements where tag=safety}}…{{/each}}), {{#if}}, {{ count … }}, and {{ diagram Car }} for a system's block diagram (SVG, with a PNG for older Word). A placeholder Word cut into pieces is read whole. One that cannot be filled is marked in the document and printed; exit 1 then. See template documents; the output defaults to <template>-filled.docx.
archec diagram <main.arche> [view] [--format mermaid|d2|svg] [-o file] [--md] [--auto] [--list] [--all -o dir] [--max-links N] A diagram as text other tools draw, or as a picture: a system or a component (Car, Car.adcu) as a flowchart, a state machine (Car.adcu.states) as a state diagram, a scenario (emergency-stop, one sequence: emergency-stop.detect) as a sequence diagram, a view (braking, a viewpoint with include lines) as the blocks it picks. Mermaid by default (GitHub draws it in a README or a pull request; --md fences it), D2, or SVG laid out by ELK as the editor lays it out — a block keeps the place it was given (at, a canvas line, or main.layout.json beside the model, where the editor keeps the places dragged in a view), --auto lays everything out. The format also follows -o's extension (.mmd, .d2, .svg). --play (with SVG) plays a scenario on its system's block diagram: each step lights its two blocks and the link between them, the message moving along it, a step every 1.6 s, in SMIL — no script, so it plays where an image plays. --list lists the diagrams, --all -o dir writes each one. --overlay provenance colours each block by who wrote its code, --overlay debt by its comprehension debt (see provenance). --max-links N: a block diagram draws its N heaviest links, among those whose label says a weight ("12 imports", "3 calls"; the others are all drawn) — each block's heaviest first, so none is left alone — and says "+K weaker links not drawn"; 30 by default for a model archec recover wrote (its system's prop recovered), none otherwise; --max-links 0 draws all. Exit 2 when the diagram does not exist.
archec qualify [--use check,gen-c|all] [--config qualify.yaml] [--asil A-D] [--dal A-E] [--standard iso26262|do330|both] [--results results.json | --no-run] [-o dir] [--html] [--repo dir] [--strict] [--list] The tool-qualification kit for the archec features a safety project relies on, from the self-model (examples/arche-lang: the use cases, the requirements on archec that refine them, the test cases that verify those), a run of those tests (each test's result, the version, the git commit, the hashes of dist/, the environment) and the docs' known limits: the ISO 26262-8 §11 tool classification (TI, TD, TCL per use case) and qualification report, the DO-330 Tool Operational Requirements and their verification cases and results, a configuration index, the known problems; Markdown, --html too. --list lists the use cases. TI2 and TD3 unless the config says otherwise, with your reasons. Exit 1 when a test failed (--strict: or a requirement is not shown). It supports a qualification; it does not certify archec. See qualification.
archec status [main.arche] [--req <ID>]… [--json] [--lenient] Each requirement: its text, what satisfies it (parts, functions, states, chains), where it is built (the genmaps of archec gen: files and line ranges), and every piece of evidence archec test, verify, timing, replay and live recorded in .arche/evidence/ — its verdict, kind, place and age, or out of date with what changed since (Thermostat.update changed, fw.bin changed). A requirement with no evidence: nothing proves it. A summary line at the end. Exit 1 when one fails, is out of date or unproved; --lenient: only when one fails. --json: the report. Above the evidence, the highest rung of the test ladder it reached (highest rung renode (sim ✓, renode ✓, board –)), once a rung above the simulator has evidence; a fix line for a case that proves a fix. See what proves each requirement.
archec status [main.arche] --build [<trace>…] [--json] The build a board runs. Alone: the model's build, build <fingerprint> <commit> — what firmware generated with --trace says in its first trace line (arche-trace 0 build <fingerprint> <commit>). With traces: whether the firmware that wrote them is this model's build. Exit 0 when it is, 1 when the board runs an older build (rebuild and flash), 2 when a trace does not say.
archec cert <main.arche> [--standard iso26262|do178c] [-o file.md] [--strict] The trace matrix a safety standard asks for, in Markdown: the safety goals with their ASIL (from their hazards), the requirements with their ASIL or DAL, what they derive from, what satisfies and verifies them, the elements and the level they need; then the gaps. The levels are checked in archec check too: a requirement keeps the level of what it derives from or decomposes it (asil "B(D)", adding up to the parent on independent elements), an element is at the level of what it satisfies. --strict: exit 1 on a gap.

More on these commands#

Sign-off is kept in the repository: archec approve REQ-1 Car.brakes --as "A. Martin" --role safety writes one line per approval to reviews/approvals.yaml — the element, a fingerprint of what it says, who, when. When the element changes, its approval is stale (archec approvals --stale); archec cert shows who approved each requirement, and archec ci --require-approval fails while one is missing. archec baseline --sign signs a baseline with an SSH key (ssh-keygen -Y sign, as git does), checked by archec baseline --verify against reviews/allowed_signers.

archec issues sync opens an issue in Jira, GitHub or GitLab for each failing case and each unverified requirement, and writes its key on the element (issue "CAR-128"); the next run updates it, or comments and closes it once the problem is gone. The tracker is named in issues.yaml, the token comes from the environment, and --dry-run prints the requests without sending them.

archec diagram main.arche <view> writes any diagram the editor shows — a system, a component, a state machine, a scenario, a view — as Mermaid (--md fences it, for a README or a pull request, where GitHub draws it), D2, or SVG laid out by ELK. A viewpoint with include/exclude lines is a view of its own, a query over the model (include * -> adcu, exclude kind sensor): the diagram stays right as the model changes, and a term that matches nothing is a warning. --all -o docs/diagrams writes them all. archec diagram main.arche emergency-stop --format svg --play plays a scenario on its system's blocks, step by step, as an SVG with no script; archec doc --html puts every view and played scenario in the page.