Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion spec/functional/FR-030-relations-subcommand.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ cause; a run that emits a complete report and then fails `--strict` exits 1.
| FR-030-AC-19 | Two `--repo` flags with one identity exit 3 naming the identity (quire-rs FR-085-AC-9), and a `--repo` value that is not `<ORG/REPO>=<DIR>` exits 3 naming the value. | Test |
| FR-030-AC-20 | `quire validate --okf --repo o/a=<A> --repo o/b=<B> --module $M` over a fixture where a classified requirement in `o/a` mitigates a hazard in `o/b` carries no finding bearing the fixture relation's own `check` token for it, and with the `o/b` flag removed carries that finding, naming the member identity `o/a`. | Test |
| FR-030-AC-21 | `quire validate --repo ...` without `--okf` exits 3 naming the missing flag. | Test |
| FR-030-AC-22 | The CLI's executable source contains no category-specific behavior and constructs no regulated-data facts (no branching on, matching of, or building of hazard, threat, safety-classification or regulated-data category values); domain words appearing only in comments do not fail this criterion. The report is delegated to quire-rs. | Inspection |
| FR-030-AC-22 | The CLI's default `relations`, `--design`, and `--flow` modes contain no category-specific behavior and construct no regulated-data facts (no branching on, matching of, or building of hazard, threat, safety-classification or regulated-data category values); domain words appearing only in comments do not fail this criterion. The explicit `--health-data-flows` projection is a scoped exception; it derives only that output from FR-084 report facts and does not alter the other modes. | Inspection |
| FR-030-AC-23 | `quire validate --okf --repo o/a=<A> --scope <DIR>` exits 3 naming both flags, and `quire validate <DIR> --okf --repo o/a=<A>` (a positional bundle directory) exits 3 naming the positional argument and `--repo`. | Test |
| FR-030-AC-24 | `quire validate --okf --repo o/a=<A> --repo o/b=<B> --module $M` over a fixture where the module declares an `exclude: ['spec/fixtures/**']` glob on a trace target, with a broken fixture under `spec/fixtures/` in both members: the glob excludes the fixture in `o/a` and in `o/b` when it resolves against each member's own `<DIR>`, and without the glob each member reports its own finding, so each member's declarations resolve against its own `<DIR>`, not `<DIR>/spec`. | Test |
| FR-030-AC-25 | `quire relations --repo o/a=<A> --repo o/b=<B>` without `--module`, where `<A>` and `<B>` each hold a `manifest.yaml` declaring a differently named relation, reports only the relation of the first `--repo` member, in either order. | Test |
Expand Down
11 changes: 6 additions & 5 deletions spec/functional/FR-044-relations-flow-mode.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,11 @@ the flow report of quire-rs [FR-096](ix://agent-ix/quire-rs/spec/functional/FR-0
the facts they were evaluated over, keyed by the archetype names those rules declare, and one denial
for each subject a rule denies. The rules, their
evaluation, the facts, the denials, their order and the `quire.flow-report/v1` payload belong to
quire-rs. The CLI is a pass-through: it resolves roots, applies path safety, calls the engine, and
renders what the engine returns ([StR-004](../stakeholder/StR-004-thin-boundary-over-quire-rs.md)).
It holds no domain rule, and no archetype, edge verb, field, category, trust level, sink kind or
remediation name: which rules exist comes from the loaded modules' `traceability.flow_rules`.
quire-rs. Under `--flow`, the CLI is a pass-through: it resolves roots, applies path safety, calls the
engine, and renders what the engine returns ([StR-004](../stakeholder/StR-004-thin-boundary-over-quire-rs.md)).
That mode holds no domain rule, and no archetype, edge verb, field, category, trust level, sink kind or
remediation name: which rules exist comes from the loaded modules' `traceability.flow_rules`. The
separate `--health-data-flows` projection does not change this pass-through contract.

```
quire relations (--scope <DIR> | --repo <ORG/REPO>=<DIR>...) [--module <PATH>]... --flow [--json] [--strict]
Expand Down Expand Up @@ -104,7 +105,7 @@ produced.
| FR-044-AC-12 | `--repo o/a=<A> --repo o/b=<B> --flow` over a fixture whose connection in `o/a` crosses a boundary in `o/b` reports the denial using the `o/b` boundary; with the `o/b` flag omitted the `crosses` edge has no target and contributes nothing, so the report holds no denial and both `--flow` and `--flow --strict` exit 0. | Test |
| FR-044-AC-13 | With `--severity trace:health-across-untrusted-boundary=warning`, `quire validate` over the AC-1 fixture reports the denial as a warning and exits 0, while `quire relations --flow --json` over it still lists the denial. | Test |
| FR-044-AC-14 | Over a fixture whose archetype, edge verb, field, category, trust-level and remediation names are unrelated to data flow, `--flow` renders the complete engine report in both output forms. | Test |
| FR-044-AC-15 | The CLI source delegates evaluation to quire-rs: it holds no rule, edge-matching, condition, denial or sorting logic and no archetype, verb, field, category or remediation name. | Inspection |
| FR-044-AC-15 | The `--flow` CLI path delegates evaluation to quire-rs: it holds no rule, edge-matching, condition, denial or sorting logic and no archetype, verb, field, category or remediation name. The separate `--health-data-flows` projection does not alter the `--flow` payload. | Inspection |
| FR-044-AC-16 | A module set declaring `flow_rules` and no `required_relations` exits 0 under `--flow` and renders the report; the same module set without `--flow` follows FR-030. Default `quire relations --json` over a module set declaring `flow_rules` carries the engine's flow section unaltered, and its denials do not change the default run's exit status. | Test |

## Dependencies
Expand Down
131 changes: 131 additions & 0 deletions spec/functional/FR-046-health-data-flows-subcommand.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
---
id: FR-046
title: "quire relations health-data-flows mode"
type: FR
relationships:
- target: "ix://agent-ix/quire-cli/spec/functional/FR-030"
type: "extends"
- target: "ix://agent-ix/quire-cli/spec/functional/FR-044"
type: "references"
- target: "ix://agent-ix/quire-rs/spec/functional/FR-084"
type: "references"
- target: "ix://agent-ix/quire-rs/spec/functional/FR-096"
type: "references"
- target: "ix://agent-ix/spec-clauses-us-health/FR-005"
type: "references"
- target: "ix://agent-ix/spec-objects-architecture/FR-007"
type: "references"
---
# FR-046: quire relations health-data-flows mode

## Description

The CLI SHALL expose a `health-data-flows` record through
`quire relations --health-data-flows`, so a consumer can obtain health-classified
connection facts from the declared architecture corpus. The CLI SHALL build the
health-specific projection from the generic relation facts in quire-rs
[FR-084](ix://agent-ix/quire-rs/spec/functional/FR-084); it SHALL NOT modify or
specialize the engine report. The engine report supplies only author-declared
model facts. The CLI does not determine whether a flow is legally permissible.

## Inputs

- The corpus root selected by `--scope` or the ordered corpus selected by `--repo`, as defined by [FR-030](./FR-030-relations-subcommand.md).
- Optional `--module` paths supplying `traceability.required_relations` and their selected `record_keys`.

## Outputs

- A complete JSON envelope with schema id `quire.health-data-flows/v1`, canonical output metadata, a deterministically ordered `flows` array, and a deterministically ordered `gaps` array.

## Behavior

- `quire relations --health-data-flows` SHALL accept `--scope`, repeated `--repo`, repeated `--module`, `--json`, and `--strict` with the meanings in [FR-030](./FR-030-relations-subcommand.md).
- The mode SHALL use the generic `relations` section from the quire-rs FR-084 report.
- The mode SHALL NOT require `traceability.flow_rules` or a flow-rule denial.
- The mode SHALL read connection endpoint values only from `sourceEnd` and `targetEnd` selected by the loaded connection relation's `record_keys`.
- The mode SHALL read health categories only from the related classification's selected `regulatedCategories` record value.
- The mode SHALL read crossings only from related trust-boundary entries and their selected `trust_level` record value.
- The mode SHALL ignore the optional `flow` section appended under quire-rs FR-096, leaving it unaltered for `--flow` callers.
- When `--json` is present, stdout SHALL contain only the complete CLI-projected document.
- With `--json`, the envelope SHALL carry keys in this order: `schema`, `output`, `flows`, `gaps`.
- The `schema` value SHALL equal `quire.health-data-flows/v1`.
- `output` SHALL be exactly `{"name":"health-data-flows","kind":"record","description":"Health-data flow records; PLAT-1756 in the Data-Flow Model project owns the producer definition."}`.
- The CLI SHALL emit the envelope, `output`, every flow, crossing, gap, missing-reference object, `ModelDocument`, and `DeclaredReference` as closed objects with no additional keys.
- A `ModelDocument` value SHALL have exactly `repo`, `id`, `archetype`, and `path`, in that order.
- The `repo` field in `ModelDocument` SHALL be a string containing the `<ORG/REPO>` identity or `null` for `--scope`.
- The `id`, `archetype`, and `path` fields in `ModelDocument` SHALL be strings.
- The `path` field in `ModelDocument` SHALL be relative to that corpus member's root.
- A `DeclaredReference` value SHALL have exactly `repo`, `id`, `archetype`, and `declared_by`, in that order.
- The `repo` field in `DeclaredReference` SHALL be a string containing the target member identity or `null` for `--scope`.
- The `id` and `archetype` fields in `DeclaredReference` SHALL be strings.
- The `declared_by` field in `DeclaredReference` SHALL be a `ModelDocument` for the artifact whose relation or record field authored the reference.
- Each `flows` item SHALL have exactly `connection`, `source`, `destination`, `classifications`, and `crossings`, in that order.
- The `connection` field in a flow SHALL be a `ModelDocument`.
- The `source` and `destination` fields in a flow SHALL be `DeclaredReference` values.
- The `classifications` field in a flow SHALL be an array of `ModelDocument` values.
- The `crossings` field in a flow SHALL be an array of objects with exactly `boundary` followed by `trust_level`.
- The `boundary` field in a crossing SHALL be a `ModelDocument`.
- The `trust_level` field in a crossing SHALL be a string.
- Each complete flow SHALL represent one connection whose related classification record states `regulatedCategories` containing `health`.
- The `source` and `destination` references in a flow SHALL come from the connection's declared `sourceEnd.type` and `targetEnd.type` record values.
- The `crossings` array in a flow SHALL include every resolved related trust boundary and its declared `trust_level` value.
- Each `gaps` item SHALL have exactly `connection` followed by `missing`.
- The `connection` field in a gap SHALL be a `ModelDocument`.
- The `missing` field in a gap SHALL be a non-empty array.
- Each missing-reference item SHALL have exactly `field` followed by `reference`.
- The `field` value in a missing-reference item SHALL be a string equal to one of `source`, `destination`, `crossing`, or `trust_level`.
- The `reference` value in a missing-reference item SHALL be a `DeclaredReference` or `null` when the corresponding reference identifier is absent.
- The CLI SHALL emit a gap for a health-classified connection when an endpoint record value is absent, an explicitly declared crossing is dangling, or a resolved boundary lacks `trust_level`.
- A connection with no declared crossing SHALL have no crossing entry.
- A connection with no declared crossing SHALL NOT be treated as a missing boundary.
- The CLI SHALL NOT emit a complete flow entry for a connection with any missing endpoint or boundary fact.
- The CLI SHALL NOT infer, substitute, or default a missing identifier or value.
- A connection is a health flow only when a related, author-declared classification record includes `health` in `regulatedCategories`.
- Other classifications SHALL not be promoted to health flows.
- The CLI SHALL NOT derive classifications from source code, schema content, flow-rule outcomes, or legal criteria.
- Complete flow entries SHALL sort by connection `repo` then `id`.
- Classification arrays SHALL sort by target `repo` then `id`.
- Crossing arrays SHALL sort by boundary `repo` then `id`.
- Gaps SHALL sort by connection `repo` then `id`.
- Each `missing` array SHALL sort by `field`, then target `repo` and `id`.
- The `flows`, `gaps`, `classifications`, and `crossings` arrays SHALL always be present, including when empty.
- The `missing` array SHALL be present and non-empty in every gap.
- When sorting repository identities, the CLI SHALL sort `null` before any string identity.
- When sorting strings and identifiers, the CLI SHALL sort them lexically.
- The envelope SHALL contain no timestamps, host paths, or run-specific values.
- Human output SHALL provide one line per complete flow.
- Human output SHALL provide one line per gap.
- A report containing gaps SHALL still be emitted completely.
- By default, gaps SHALL not change the exit status.
- With `--strict`, the CLI SHALL emit the complete report and exit 1 when `gaps` is non-empty.
- With `--strict`, the CLI SHALL emit the complete report and exit 0 when `gaps` is empty.
- Flow-report denials SHALL not affect this exit rule.
- Relation verification status SHALL not affect this exit rule.
- Invalid corpus or module input follows [FR-030](./FR-030-relations-subcommand.md).
- The mode SHALL conflict with `--relation`, `--design`, and `--flow`, naming both conflicting modes and writing no report to stdout.
- The existing `--flow` output SHALL remain unchanged.
- The default `relations` output SHALL remain unchanged.
- The CLI SHALL obtain the generic relation report from quire-rs and build this health projection from its `document`, `linked`, `dangling`, and selected `record` values.
- The CLI SHALL NOT read source files outside the report.
- The CLI SHALL NOT infer missing facts.
- The CLI SHALL NOT decide permissibility.

## Acceptance Criteria

| ID | Criteria | Verification |
|----|----------|--------------|
| FR-046-AC-1 | `quire relations --scope <DIR> --module $M --health-data-flows --json` over a fixture module with `required_relations` for connection-to-classification and connection-to-trust-boundary facts, and `record_keys` selecting `sourceEnd`, `targetEnd`, `regulatedCategories`, and `trust_level`, emits a complete JSON envelope. The fixture model has one health-classified connection with source and destination record values and one declared boundary crossing. | Test |
| FR-046-AC-2 | The AC-1 envelope's `schema`, `output`, `flows`, `gaps`, `ModelDocument`, `DeclaredReference`, flow, crossing, and gap keys have the exact names, order, types, nullability, and closed shapes specified in this requirement; each reference carries repository identity and a source artifact path or `declared_by` document. | Test |
| FR-046-AC-3 | A health-classified connection with a missing source value, missing destination value, dangling crossing, or boundary without `trust_level` emits a gap naming the connection and missing reference, emits no complete entry for that connection, and substitutes no identifier or value. A connection with no declared crossing emits no boundary gap. | Test |
| FR-046-AC-4 | A connection carrying a declared category other than `health` is absent from the complete flow entries and gaps, even when another category is regulated. | Test |
| FR-046-AC-5 | Two runs over the same corpus produce byte-identical JSON. With multiple repositories, references retain each `--repo` identity and records, crossings, and gaps follow the specified order. | Test |
| FR-046-AC-6 | The emitted metadata's name, kind, and description exactly match the `health-data-flows` row in US pack FR-005, and the pack's catalog test accepts those values. | Test |
| FR-046-AC-7 | A module set with the required `required_relations` and record keys but no `flow_rules` can produce a record; a corpus with no health-classified connections succeeds with empty `flows` and `gaps`. | Test |
| FR-046-AC-8 | With gaps, default mode emits the full report and exits 0; with `--strict`, it emits the full report and exits 1. With no gaps, both modes emit the full report and exit 0, regardless of generic relation verification status or flow-report denials. | Test |
| FR-046-AC-9 | A request combining `--health-data-flows` with `--relation`, `--design`, or `--flow` exits 3, names the conflicting modes, and writes no report to stdout; requests in existing relations modes retain their prior outputs. | Test |
| FR-046-AC-10 | The CLI derives health selection and record structure only from the generic FR-084 relation report's `document`, `linked`, `dangling`, and selected `record` values; it reads no source files and does not alter the report used by `--flow`. | Inspection |

## Dependencies

- **Upstream**: [FR-030](./FR-030-relations-subcommand.md), [FR-044](./FR-044-relations-flow-mode.md), quire-rs [FR-084](ix://agent-ix/quire-rs/spec/functional/FR-084) for generic relation facts, architecture [FR-007](ix://agent-ix/spec-objects-architecture/FR-007), and the `health-data-flows` output metadata in US pack [FR-005](ix://agent-ix/spec-clauses-us-health/FR-005). The existing `connection-carries-classification` relation SHALL select `sourceEnd` and `targetEnd` in addition to `regulatedCategories`; the `connection-crosses-trust-boundary` relation SHALL select `trust_level`. Updating these `record_keys` is part of PLAT-1756 implementation and needs no new engine requirement. Quire-rs [FR-096](ix://agent-ix/quire-rs/spec/functional/FR-096) is referenced only to distinguish its optional flow section; this mode does not require `flow_rules`.
- **Consumer**: the US Health-Law Compliance Pack consumes this record and validates its metadata against its output catalog; the CLI does not discharge or evaluate HIPAA clauses.
1 change: 1 addition & 0 deletions spec/functional/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,3 +50,4 @@ description: "Index of artifacts in this directory."
* [FR-043: quire matrix design column and design gate](./FR-043-matrix-design-column.md)
* [FR-044: quire relations flow mode](./FR-044-relations-flow-mode.md)
* [FR-045: quire trace and symbols report the formalizes relation](./FR-045-trace-formalizes-output.md)
* [FR-046: quire relations health-data-flows mode](./FR-046-health-data-flows-subcommand.md)
Loading