diff --git a/spec/functional/FR-030-relations-subcommand.md b/spec/functional/FR-030-relations-subcommand.md index a199da2..548daad 100644 --- a/spec/functional/FR-030-relations-subcommand.md +++ b/spec/functional/FR-030-relations-subcommand.md @@ -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 `=` exits 3 naming the value. | Test | | FR-030-AC-20 | `quire validate --okf --repo o/a= --repo o/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= --scope ` exits 3 naming both flags, and `quire validate --okf --repo o/a=` (a positional bundle directory) exits 3 naming the positional argument and `--repo`. | Test | | FR-030-AC-24 | `quire validate --okf --repo o/a= --repo o/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 ``, and without the glob each member reports its own finding, so each member's declarations resolve against its own ``, not `/spec`. | Test | | FR-030-AC-25 | `quire relations --repo o/a= --repo o/b=` without `--module`, where `` and `` each hold a `manifest.yaml` declaring a differently named relation, reports only the relation of the first `--repo` member, in either order. | Test | diff --git a/spec/functional/FR-044-relations-flow-mode.md b/spec/functional/FR-044-relations-flow-mode.md index e8cbe69..9d54ee9 100644 --- a/spec/functional/FR-044-relations-flow-mode.md +++ b/spec/functional/FR-044-relations-flow-mode.md @@ -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 | --repo =...) [--module ]... --flow [--json] [--strict] @@ -104,7 +105,7 @@ produced. | FR-044-AC-12 | `--repo o/a= --repo o/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 diff --git a/spec/functional/FR-046-health-data-flows-subcommand.md b/spec/functional/FR-046-health-data-flows-subcommand.md new file mode 100644 index 0000000..ddc4b75 --- /dev/null +++ b/spec/functional/FR-046-health-data-flows-subcommand.md @@ -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 `` 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 --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. diff --git a/spec/functional/index.md b/spec/functional/index.md index 9e02772..b91cb83 100644 --- a/spec/functional/index.md +++ b/spec/functional/index.md @@ -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)