# SSP narrative doctrine — by-who, inheritance, and status vocabulary

> **Shared platform corpus** — `halo-platform/` is vendored byte-identical across the plugins that carry it; a consistency check enforces identity. Do not hand-edit a vendored copy — edit the canonical copy (see `halo-platform/README.md`) and re-run the corpus sync.

The one doctrine both the SSP authoring/review side and the Halo read/render side must agree on: who implements a control, how inheritance is claimed, and the status vocabulary. Authoring guidance (section structure, narrative patterns, worked examples) and read-side derivation heuristics (Halo CF walks) live in their owning skills; this file is the shared semantic core they both cite.

## 1. The "by whom" taxonomy

Every control / KSI / practice implementation claim carries exactly one of:

| Value | Meaning |
|---|---|
| **by the system** | Automated, technical; runs without human intervention. |
| **by the organization** | Procedural, policy, human-driven. |
| **by the system and the organization** | Combined: automated enforcement plus a procedural overlay — be explicit about which part is which. |
| **inherited from `<provider>`** | An upstream provider fulfills the control, with CRM citation (§ 2). |
| **partially inherited from `<provider>`** | Provider fulfills part; the system fulfills the remainder — per-portion narrative. |

**Decision rule.** "If the system has zero operators awake at 3 AM, does this control still satisfy itself?" Yes, automatically → by the system. No, a human must act → by the organization. Mixed → by the system and the organization.

**Anti-pattern — claiming "by the system" for procedural enforcement.** WRONG: "The system enforces quarterly account reviews" — the review is human-driven; the system may only remind. RIGHT: "Quarterly reviews are performed by the organization. The ISSO runs the inventory report; the system owner certifies within 5 business days. The system supports the review by automatically flagging inactive accounts." An assessor seeing "by the system" expects an automated enforcement point and will issue a finding when the configuration doesn't exist.

**Never default when ambiguous.** When source data does not unambiguously signal one value, emit the field as null/absent and flag it for human resolution. A wrong by-who is worse than a flagged absent one — in particular, never default to "by the organization" because it feels safer.

## 2. Inheritance documentation rules

Inherited controls are explicit claims that another system fulfills the control; the assessor validates them against the upstream provider's Customer Responsibility Matrix (CRM).

1. **Name the provider with the specific offering.** Not "AWS" — "AWS Commercial, EKS managed control plane" or "Azure Government, Azure SQL Database". Providers have many authorized offerings with different boundaries; an unqualified name cannot be validated.
2. **State the provider's authorization** ("FedRAMP Moderate Authorized", "DoD IL5 Authorized").
3. **Cite the specific CRM item ID** (e.g. `AWS-CRM-AU-2-01`) — the assessor's validation key.
4. **Distinguish full from partial.** Full: status "Inherited". Partial: per-portion narrative; status reflects the system-implemented portion.
5. **State what the system inherits the requirement to DO.** Many "inherited" controls are shared: the provider supplies the surface; the customer must configure it correctly — name those obligations.
6. **Never claim inheritance without the CRM citation.** If the CRM reference is missing, write the control as system-implemented and flag it for owner follow-up.

**Structured shape (read/render side).** Per-control `inheritance` = `{type, provider, crm_reference}` with `type` ∈ {`full`, `partial`, `none`}. `provider` and `crm_reference` come from explicitly stored fields only — never inferred from context; absent values emit as null and are flagged.

**Anti-pattern.** WRONG: "Inherited from AWS." RIGHT: "Infrastructure-layer audit-event generation is partially inherited from AWS Commercial (FedRAMP Moderate Authorized) per CRM `AWS-CRM-AU-2-01`. CloudTrail and VPC Flow Logs provide the underlying surface. The system inherits the requirement to enable CloudTrail in all production accounts, configure destinations to customer-owned S3 buckets with 12-month retention, and forward to the SIEM. Application-layer events are emitted by the system per policy."

## 3. Implementation-status vocabulary (SAR-aligned)

| Status | Meaning |
|---|---|
| **Implemented** | Fully met today; evidence cited. |
| **Partially Implemented** | Mechanism in place but does not meet the full objective; the narrative explicitly cites the gap. |
| **Planned** | Mechanism not in place; narrative cites planned mechanism, owner, and target date. |
| **Alternative Implementation** | Non-standard mechanism meets the intent; cite mechanism AND rationale. |
| **Not Applicable** | Does not apply; cite the reason; tailoring rationale documented. |

The status must match the narrative: a narrative that describes a gap cannot carry "Implemented". If nothing can be cited as evidence, the status is NOT "Implemented". "Not Assessed" (where a tenant records it) is a deliberate state, never a fallback for missing data — missing data emits as null/absent and is flagged.
