arckit-cli 6.1.1__py3-none-any.whl

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/c4-layout-science.md

@@ -0,0 +1,280 @@
+# C4 Layout Science Guide
+
+> **Guide Origin**: Official | **ArcKit Version**: [VERSION]
+
+A research-backed guide to creating readable C4 architecture diagrams with minimal edge crossings and clear visual hierarchy. This guide covers the graph drawing theory behind layout engines, practical declaration ordering strategies, quality targets from empirical research, and a structured validation checklist.
+
+For the full reference used by the `/arckit:diagram` command, see `plugins/arckit-claude/skills/mermaid-syntax/references/c4-layout-science.md`.
+
+---
+
+## Graph Drawing Theory
+
+### The Sugiyama Algorithm
+
+Mermaid's layout engine uses Dagre, which implements the **Sugiyama hierarchical layout algorithm** — the most widely-used method for drawing directed graphs in layers. Understanding how this algorithm works explains why certain authoring choices produce better diagrams.
+
+The algorithm proceeds in four stages:
+
+**Stage 1: Cycle Removal**
+The algorithm temporarily reverses edges that create cycles in the graph. This ensures the graph can be processed as a directed acyclic graph (DAG). Reversed edges are restored with their original direction after layout is complete.
+
+**Stage 2: Layer Assignment**
+Each node is assigned to a horizontal or vertical layer (rank). Nodes that depend on other nodes are placed in later layers, creating the top-to-bottom or left-to-right hierarchy. Long edges that span multiple layers are broken into segments with invisible intermediate nodes.
+
+**Stage 3: Crossing Minimisation**
+This is the critical stage where declaration order matters. The algorithm reorders nodes within each layer to minimise the number of edge crossings. The most common technique is the **barycentric method**: for each node, compute the average position of its connected neighbours in the adjacent layer, then sort nodes by this average.
+
+The barycentric method is a local optimisation heuristic — it improves an initial ordering but does not guarantee a global optimum. This means the initial order (determined by the order nodes appear in the source code) significantly affects the final result. A good starting order produces fewer crossings.
+
+**Stage 4: Coordinate Assignment**
+Final x/y coordinates are calculated for each node, respecting minimum spacing, edge routing, and the layer assignments from Stage 2.
+
+### Why This Matters for Architecture Diagrams
+
+When you write a Mermaid or PlantUML diagram, you are providing the initial ordering for Stage 3. If your declaration order already matches the intended visual layout, the crossing minimisation heuristic starts from a near-optimal position and produces a clean diagram. If elements are declared in random order, the heuristic starts from a poor position and may converge to a layout with unnecessary crossings.
+
+---
+
+## Declaration Ordering
+
+### The Tier-Based Strategy
+
+For architecture diagrams, the most effective declaration strategy is **tier-based ordering**: declare elements in the order they should appear visually, following the natural data flow of the system.
+
+For a `flowchart LR` (left-to-right) diagram:
+
+| Order | Tier | Examples | Position |
+|-------|------|----------|----------|
+| 1 | Actors | Citizens, administrators, operators | Leftmost |
+| 2 | Presentation | Web applications, mobile apps, portals | Left |
+| 3 | API | API gateways, load balancers, BFF services | Centre-left |
+| 4 | Service | Business logic, orchestrators, workers | Centre |
+| 5 | Data | Databases, caches, queues, object stores | Centre-right |
+| 6 | External systems | Third-party APIs, GOV.UK services, banks | Rightmost |
+
+For a `flowchart TB` (top-to-bottom) diagram, the same tiers apply vertically: actors at the top, external systems at the bottom.
+
+### Three Rules
+
+1. **Declare ALL elements before ANY relationships.** The layout engine positions nodes as it encounters them. If a relationship references an undeclared node, the engine creates it at that point, often in a suboptimal position.
+
+2. **Within each tier, declare elements in the order you want them to appear.** For a horizontal layout, declare left-to-right. For a vertical layout, declare top-to-bottom.
+
+3. **Group related elements with `subgraph`.** This constrains the layout engine to keep grouped elements together, reinforcing the visual hierarchy.
+
+### C4-Specific Ordering
+
+For C4 native syntax (`C4Context`, `C4Container`), the recommended declaration order is:
+
+1. `Person(...)` — all actors
+2. `System(...)` — the system being described
+3. `System_Boundary(...)` — system boundaries containing:
+   - `Container(...)` — in tier order within the boundary
+   - `ContainerDb(...)` — databases
+   - `ContainerQueue(...)` — queues (PlantUML only)
+4. `System_Ext(...)` — all external systems
+5. `Rel(...)` — all relationships last
+
+---
+
+## Edge Crossing Targets
+
+### The Research
+
+Purchase et al. conducted empirical studies measuring how different graph aesthetics affect human comprehension. Their key finding: **edge crossings are the strongest negative predictor of diagram comprehension**, significantly more impactful than:
+
+- Node overlap
+- Edge bends
+- Symmetry violations
+- Minimum angle between edges
+
+Participants shown diagrams with fewer crossings understood them faster, answered questions about them more accurately, and rated them as more readable.
+
+### Practical Targets
+
+Based on this research and practical experience with architecture diagrams:
+
+| Complexity | Element Count | Target Crossings | Notes |
+|-----------|--------------|-----------------|-------|
+| Simple | 6 or fewer | 0 | Easily achievable with tier-based ordering |
+| Medium | 7-12 | Fewer than 3 | Requires careful ordering; subgraphs help |
+| Complex | More than 12 | Fewer than 5 | May need diagram splitting or PlantUML hints |
+
+### Counting Crossings
+
+When evaluating a rendered diagram:
+
+- Count each point where two edges intersect (not at a node)
+- Self-loops and edges to/from the same subgraph boundary do not count
+- Edges that run parallel closely but do not intersect do not count
+- If you cannot count crossings easily, the diagram is too complex — split it
+
+---
+
+## Visual Hierarchy
+
+### The Gestalt Proximity Principle
+
+The Gestalt principle of proximity states that elements placed close together are perceived as belonging to the same group. In architecture diagrams, this principle supports two practices:
+
+1. **Use `subgraph` blocks** to visually group related elements. Mermaid draws a visible boundary around subgraph contents, creating an immediate visual grouping.
+
+2. **Nest subgraphs** to represent hierarchical containment. For example, a system boundary containing multiple subsystem boundaries containing individual containers.
+
+### Applying Visual Hierarchy in C4
+
+| C4 Level | Visual Treatment | How to Achieve |
+|----------|-----------------|----------------|
+| Context | System boundary is the largest visual element | Single `subgraph` or `System_Boundary` containing all internal elements |
+| Container | Containers grouped by architectural tier | Nested `subgraph` blocks for presentation, service, and data tiers |
+| Component | Components grouped by responsibility | `subgraph` blocks for handlers, services, repositories |
+| Deployment | Infrastructure zones (VPC, subnets, regions) | Deeply nested `subgraph` blocks matching network topology |
+
+### Boundary Styling
+
+Use dashed borders for trust boundaries and solid borders for system boundaries:
+
+```mermaid
+%% Trust boundary (dashed)
+subgraph TrustBoundary["DMZ"]
+    style TrustBoundary stroke:#1168BD,stroke-dasharray:5 5,fill:none
+end
+
+%% System boundary (solid)
+subgraph SystemBoundary["Payment Gateway"]
+    style SystemBoundary stroke:#1168BD,stroke-width:2px,fill:#E8F0FE
+end
+```
+
+---
+
+## Validation Checklist
+
+After generating any architecture diagram, evaluate it against these six criteria:
+
+| # | Criterion | Target | How to Evaluate |
+|---|-----------|--------|----------------|
+| 1 | **Edge crossings** | 0 for simple, fewer than 3 for medium, fewer than 5 for complex | Count intersection points of edges (not at nodes) |
+| 2 | **Visual hierarchy** | System boundary is the most prominent visual element | Check that the main system boundary is immediately identifiable |
+| 3 | **Grouping** | Related elements are proximate | Verify that architecturally-related elements appear visually close |
+| 4 | **Flow direction** | Consistent left-to-right or top-to-bottom | Check that the primary data flow follows one consistent direction |
+| 5 | **Relationship traceability** | Each line can be followed from source to target | Trace each edge visually — if any edge is ambiguous, the diagram needs improvement |
+| 6 | **Abstraction level** | One C4 level per diagram | Verify that the diagram does not mix context-level and container-level elements |
+
+### Quality Gate Integration
+
+The `/arckit:diagram` command includes a **Step 5b: Diagram Quality Gate** that automatically evaluates generated diagrams against these criteria and reports results in a structured table. Any failing criterion triggers an iterative refinement cycle.
+
+---
+
+## Iterative Refinement
+
+When a diagram fails one or more validation criteria, follow this systematic process:
+
+### Step 1: Reorder Declarations
+
+The most common fix. Rearrange element declarations to match the intended tier layout:
+
+- Actors first (leftmost or topmost)
+- Internal elements in data-flow order
+- External systems last (rightmost or bottommost)
+
+This alone resolves most edge crossing issues.
+
+### Step 2: Add Subgraph Grouping
+
+Group related elements using `subgraph` blocks:
+
+```mermaid
+subgraph Services["Business Services"]
+    PaymentService["Payment Service"]
+    NotificationService["Notification Service"]
+    AuditService["Audit Service"]
+end
+```
+
+This constrains the layout engine to keep grouped elements together, reducing crossings between unrelated edges.
+
+### Step 3: Reorder Within Subgraphs
+
+The same tier-ordering principle applies within each subgraph. If elements within a group produce crossings, reorder their declarations.
+
+### Step 4: Change Orientation
+
+Try switching between `flowchart LR` and `flowchart TB`. Some architectures produce fewer crossings in one orientation than the other:
+
+- **Horizontal (LR)** works well for data-flow architectures (request flows left to right)
+- **Vertical (TB)** works well for hierarchical architectures (users at top, infrastructure at bottom)
+
+### Step 5: Use PlantUML Directional Hints
+
+If Mermaid cannot achieve acceptable results, switch to PlantUML with the C4-PlantUML library and use directional hints:
+
+| Hint | Effect |
+|------|--------|
+| `Rel_Down(a, b, ...)` | Places a above b |
+| `Rel_Right(a, b, ...)` | Places a left of b |
+| `Lay_Right(a, b)` | Forces a left of b (invisible) |
+| `Lay_Down(a, b)` | Forces a above b (invisible) |
+
+### Step 6: Split the Diagram
+
+If the element count exceeds 15 or crossings remain above the target after all other refinements, split the diagram at a natural boundary:
+
+- **System boundary** — separate context from internal structure
+- **Trust boundary** — separate public-facing from internal components
+- **Domain boundary** — separate bounded contexts
+- **Deployment boundary** — separate cloud regions or availability zones
+
+### Step 7: Document Trade-Offs
+
+If a crossing or layout imperfection cannot be eliminated without sacrificing clarity elsewhere, document it explicitly in the diagram's architecture decisions section.
+
+---
+
+## Format Selection Guide
+
+Choose the right format based on diagram complexity and requirements:
+
+| Scenario | Format | Reason |
+|----------|--------|--------|
+| Simple C4 (12 or fewer elements) | Mermaid `C4Context` / `C4Container` | Native C4 syntax, renders in GitHub markdown and VS Code |
+| Complex C4 (more than 12 elements) | PlantUML with C4-PlantUML | Directional hints (`Rel_Right`, `Lay_Down`) for precise crossing control |
+| Deployment diagrams | Mermaid `flowchart` | `subgraph` nesting maps naturally to infrastructure zones (VPC, subnets, AZs) |
+| Sequence diagrams | Mermaid `sequenceDiagram` | Native support for request/response flows, alt/opt blocks, participant ordering |
+| Data flow diagrams | Mermaid `flowchart` | PII annotations, data classification labels, retention metadata in node labels |
+| Wardley Maps | Online Wardley Mapping (OWM) | Specialised positioning by evolution and value chain; not achievable in Mermaid |
+
+### Rendering Environments
+
+| Environment | Mermaid Support | PlantUML Support |
+|-------------|----------------|-----------------|
+| GitHub markdown | Native rendering | Requires image embedding |
+| VS Code | Mermaid Preview extension | PlantUML extension |
+| mermaid.live | Full interactive editor | N/A |
+| PlantUML Server | N/A | Full rendering |
+| Confluence | Mermaid plugin (varies) | PlantUML plugin |
+| PDF export | Via Mermaid CLI (`mmdc`) | Via PlantUML JAR |
+
+---
+
+## References
+
+1. **Purchase, H.C., Cohen, R.F., and James, M.I.** (1997). "An Experimental Study of the Basis for Graph Drawing Aesthetics." *Journal of Visual Languages and Computing*, 8(1), 32-50.
+
+2. **Purchase, H.C.** (2002). "Metrics for Graph Drawing Aesthetics." *Journal of Visual Languages and Computing*, 13(5), 501-516. Establishes that edge crossings have the strongest negative effect on comprehension.
+
+3. **Sugiyama, K., Tagawa, S., and Toda, M.** (1981). "Methods for Visual Understanding of Hierarchical System Structures." *IEEE Transactions on Systems, Man, and Cybernetics*, 11(2), 109-125. The foundational algorithm for layered graph drawing.
+
+4. **Brown, S.** The C4 Model for Visualising Software Architecture. [https://c4model.com](https://c4model.com). Defines the four abstraction levels (Context, Container, Component, Code) and standard visual notation.
+
+5. **Wertheimer, M.** (1923). "Untersuchungen zur Lehre von der Gestalt II." *Psychologische Forschung*, 4(1), 301-350. Establishes the proximity principle used to justify subgraph grouping.
+
+6. **Mermaid Documentation** — Flowchart Syntax. [https://mermaid.js.org/syntax/flowchart.html](https://mermaid.js.org/syntax/flowchart.html).
+
+7. **C4-PlantUML** — PlantUML macros for C4 diagrams. [https://github.com/plantuml-stdlib/C4-PlantUML](https://github.com/plantuml-stdlib/C4-PlantUML).
+
+---
+
+*This guide is part of the ArcKit documentation. For the reference used by the diagram command, see `plugins/arckit-claude/skills/mermaid-syntax/references/c4-layout-science.md`. For the diagram command itself, see `/arckit:diagram`.*

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/ca-aia.md

@@ -0,0 +1,81 @@
+# Canada Algorithmic Impact Assessment Playbook
+
+> **Guide Origin**: Community | **ArcKit Version**: [VERSION]
+
+`/arckit:ca-aia` generates a Canada Algorithmic Impact Assessment under the TBS *Directive on Automated Decision-Making*. It scores the system against the six-dimension questionnaire (Project, System, Algorithm, Decision, Impact, Data), computes the Impact Level (I, II, III, or IV), and applies the Directive's mandated mitigations for that Level — peer review tier, bilingual transparency notice, human-in-the-loop design, quality assurance plan, and a recourse mechanism for affected individuals.
+
+The AIA is mandatory for any federal automated decision-making system that produces administrative decisions about individuals or businesses. The computed Level gates the system: Level III/IV systems require external peer review and pre-launch publication 30 days ahead of go-live, and the AIA itself is published on the Open Government portal by default. AIDA (Bill C-27) was stalled in Parliament, so the TBS Directive remains the federal public-sector floor for algorithmic accountability.
+
+---
+
+## Inputs
+
+| Artefact | Purpose |
+|----------|---------|
+| Requirements (`ARC-<id>-REQ-v1.0.md`) | Decisions automated, NFR-AI / NFR-DEC requirements covering bias, contestability, override |
+| Data requirements (`ARC-<id>-DR-v1.0.md`) | Training-data lineage and decision boundary inputs |
+| Data model (`ARC-<id>-DMOD-v1.0.md`) | Entity-level data structures feeding the model |
+| Privacy Impact Assessment (`ARC-<id>-PIA-v1.0.md`) | Lawful authority and personal-information posture; AIA depth must match PIA depth |
+
+---
+
+## Command
+
+```bash
+/arckit:ca-aia <project ID or service description>
+```
+
+Output: `projects/<id>/ARC-<id>-AIA-v1.0.md`
+
+---
+
+## Assessment Structure
+
+| Section | Contents |
+|---------|----------|
+| Document Control | Canadian classification (UNCLASSIFIED / Protected A–C / CONFIDENTIAL / SECRET / TOP SECRET) |
+| Revision History | Version, date, author, changes, approvals |
+| Executive Summary | Computed Impact Level, headline mitigations, residual risk posture |
+| System Description | Purpose, decisions automated, training-data lineage, vendor / model provenance, stewardship |
+| Levels I–IV Questionnaire Scoring | Six-dimension scoring tables (Project, System, Algorithm, Decision, Impact, Data) and computed Level |
+| Per-Level Mitigation Requirements | Peer review, transparency notice, human-in-the-loop, QA, recourse — by Level |
+| Algorithmic Risks Register | Bias, drift, proxies, contestability, fairness, severity with residual rating |
+| Training-Data Provenance | Per-dataset source, licence, refresh cadence, drift trigger, steward |
+| Disclosure Plan | Audience, channel, cadence, bilingual flag |
+| Reassessment Triggers | Material-change triggers and periodic-reassessment cadence |
+| Open Items | Pending peer-review nominations, publication, recourse, downstream artefacts |
+| External References | Document Register, Citations, Unreferenced |
+
+---
+
+## When to run
+
+- Any new automated decision-making system that touches individuals or businesses, before service launch.
+- Vendor selection of an ML / AI tool that will be used in administrative decisions — the AIA validates Level and feeds procurement evaluation.
+- Substantive change to training data, model architecture, decision boundary, or operating environment of a live system.
+- Periodic reassessment — annual default, accelerated for Level III/IV systems.
+
+---
+
+## Common pitfalls
+
+- **Self-declaring Level I to skip peer review.** The questionnaire output is the source of truth, not an architect's intuition. Reviewers will check the score-to-level mapping against the Directive's threshold matrix and a downward bias is a Directive breach.
+- **Missing the 30-day pre-launch notification window.** Level III and IV systems require pre-launch publication 30 days before go-live and external peer review with realistic lead time. Booking these late forces a launch slip or a Directive non-conformance.
+- **Treating the AIA as a launch artefact rather than a continuous compliance asset.** The Directive requires reassessment on material change to data, model, decision boundary, or operating environment, plus periodic reassessment. A static AIA produced once at launch is non-compliant over the system's lifecycle.
+- **Conflating internal-productivity AI with decision-making AI.** Internal copilots that do not produce administrative decisions about individuals fall outside the Directive; running an AIA against them dilutes review capacity. Run the AIA where the Directive bites — automated administrative decisions — and pair internal-productivity AI with a separate posture (cross-reference `uae-ai-autonomy-tier` for a tiered model).
+
+---
+
+## Handoffs
+
+- **`risk`** — AIA findings (bias, drift, contestability, fairness gaps) feed the operational risk register. Each algorithmic risk row in the AIA should map to a project-level risk entry with owner and review cadence.
+- **`adr`** — Material AIA outcomes warrant Architecture Decision Records. Vendor selection of an ML model, autonomy tier (full automation vs decision-support vs human-only), and recourse-mechanism design are all ADR-worthy decisions with options analysis.
+- **`ca-pia`** — Personal-information feeding the algorithmic system inherits the PIA controls. The AIA depth must match the PIA depth: a Level III/IV AIA against a thin PIA is a red flag, and vice versa.
+
+---
+
+## Statutory currency
+
+The TBS *Directive on Automated Decision-Making* evolves on a published cadence; verify the current version on the TBS policy site before relying on threshold or mitigation cites. AIDA (Bill C-27) was stalled in Parliament, so the federal public-sector floor for algorithmic accountability remains the TBS Directive — not statutory AI legislation. The *Algorithmic Impact Assessment Tool* questionnaire is open-source and versioned on the Open Government portal; cite the specific release used to score the system.
+
+The Directive is operational, not aspirational: the Treasury Board Secretariat tracks compliance through the AIA publications listed on the Open Government portal and through the policy suite's regular reviews. Architects should treat the published AIA as the single authoritative version of the assessment; severance of Protected B/C content for the public copy is acceptable, but withholding the whole assessment is not. Where a national-security exemption is claimed, document the exemption rationale and cross-reference `ca-soia` rather than silently dropping the publication step.

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/ca-atip.md

@@ -0,0 +1,79 @@
+# Canada ATIP Reconciliation Playbook
+
+> **Guide Origin**: Community | **ArcKit Version**: [VERSION]
+
+`/arckit:ca-atip` generates a Canada federal ATIP (Access to Information / Privacy Act) Reconciliation under the Access to Information Act (R.S.C., 1985, c. A-1) and the Privacy Act (R.S.C., 1985, c. P-21). It produces an information holdings inventory categorised Public / Protected / Classified, an exemption mapping per holding under the ATI Act (§13, §14, §15, §16 and §16.1–§16.6, §19, §21, §23, §24), a Privacy Act §4–§8 use and disclosure register with §8(2)(a)–(m) routine-use letters individually analysed, a severance design with field-level rules and an audit log schema, the §7 30-day request workflow with §9 extension and §27 consultation handling, and the annual report mapping for OIC, OPC and TBS InfoSource.
+
+ATIP reconciliation sits between the Privacy Impact Assessment and the data model. The PIA establishes lawful authority and the personal-information inventory; the data model carries the field-level structure and classification flags. ATIP reconciles the two against the disclosure regime — proving that every disclosure has a Privacy Act §8 basis, every redaction has an ATI Act exemption head, and every hybrid public/protected view has explicit severance rules with a per-field audit trail. Public/protected hybrid systems (e.g. registers carrying both a transparency view and an investigative back-end) are the most common pattern and the most common defect: if you cannot answer "what is suppressed in the public view, under which exemption, and how is the redaction logged?", you are not ATIP-ready.
+
+---
+
+## Inputs
+
+| Artefact | Purpose |
+|----------|---------|
+| Requirements (`ARC-<id>-REQ-v1.0.md`) | Disclosure scenarios, programme description, third-party touchpoints |
+| Data requirements (`ARC-<id>-DR-v1.0.md`) | Per-element sensitivity flags and disclosure recipients |
+| Data model (`ARC-<id>-DMOD-v1.0.md`) | Field-level structure that the severance rules act on |
+| Privacy Impact Assessment (`ARC-<id>-PIA-v1.0.md`) | Authoritative source for the §4–§8 register and PIB references |
+
+---
+
+## Command
+
+```bash
+/arckit:ca-atip <project ID or service description>
+```
+
+Output: `projects/<id>/ARC-<id>-ATIP-v1.0.md`
+
+---
+
+## Assessment Structure
+
+| Section | Contents |
+|---------|----------|
+| Document Control | Canadian classification (UNCLASSIFIED / Protected A–C / CONFIDENTIAL / SECRET / TOP SECRET) |
+| Revision History | Version, date, author, changes, approvals |
+| Executive Summary | Holdings posture, headline exemptions, §8(2) letters in play, severance summary |
+| Information Holdings Inventory | Per-holding category Public/Protected/Classified, PIB ref, owner, lifecycle |
+| Access to Information Act Mapping | Exemption section per holding (§13, §14, §15, §16/§16.1–§16.6, §19, §21, §23, §24) with justification |
+| Privacy Act §4–§8 Register | Collection (§4, §5/§5(2)(3)), use (§7/§7(a)), disclosure (§8 with §8(2)(a)–(m) individually) |
+| Severance Design | Field-level rules table, audit log schema, re-identification risk register |
+| ATIP Request Workflow | §7 30-day clock, §9 extensions, §27 consultation; SLA per step; extension justification template |
+| Annual Report Mapping | OIC, OPC, TBS InfoSource feeds and reporting cadences |
+| Open Issues | Unresolved exemption rationales, missing PIBs, pending consultations, severance `<TBC>` |
+| External References | Document Register, Citations, Unreferenced |
+
+---
+
+## When to run
+
+- After the PIA is drafted — the PIA's personal-information inventory is the authoritative source for the §4–§8 register here, and re-deriving it would create drift.
+- Before launch — severance design, third-party consultation lists, and PIB updates must be signed off before the public register opens.
+- After a substantial change to information holdings (new dataset, new disclosure recipient, new processor, new jurisdiction).
+- After a change in disclosure recipients or routine-use letters — adding or removing a §8(2) letter is a substantial change.
+
+---
+
+## Common pitfalls
+
+- **Treating §19 as automatic.** §19 (personal information) is not a blanket exemption. Privacy Act §8(2) routine-use disclosures may still apply, including §8(2)(a) consistent use, §8(2)(b) consent, and §8(2)(m) public-interest disclosure with notice to the OPC. Test §19 against §8(2)(a)–(m) before invoking.
+- **Missing the 30-day clock.** §7 of the ATI Act starts the clock at receipt of the request (and any required fee). §9 extensions require written notice with reasons and a stated timeline before the clock expires. Failure exposes the institution to OIC complaints under §30 and Federal Court review under §41.
+- **Under-modelling re-identification.** Hybrid public/protected systems can leak through cumulative disclosures, metadata gaps, and small-cell aggregates. Build a re-identification risk register; do not assert "anonymised" without a k-anonymity threshold or differential-privacy parameter.
+- **Forgetting PIB updates.** Personal Information Bank registration in TBS InfoSource is required under §13 of the Privacy Act. New holdings or changed purposes require a PIB update; an unregistered or stale PIB undermines the §12 access right and is a §30 complaint waiting to happen.
+- **Asserting §16 or §15 without identifying the head.** Each section has multiple heads (§16(1)(a) ongoing investigation, §16(1)(b) techniques, §16(1)(c) injurious-to-enforcement; §15 international affairs vs defence vs national security). Reviewers and the OIC expect the specific head, not the bare section number.
+- **Aggregating dissimilar §8(2) disclosures.** Each §8(2)(a)–(m) routine-use letter must match the actual disclosure scenario. Do not group disclosures to different recipients or for different purposes under one letter.
+
+---
+
+## Handoffs
+
+- **`data-model`** — Severance rules in this artefact feed back into the data model's classification flags, role-based access controls, and field-level masking. Update the data model with a `severance:` annotation per field that maps to the rules in the Severance Design section so the runtime enforcement is auditable against the policy.
+- **`ca-pia`** — The PIA is the upstream artefact and the authoritative source for the §4–§8 register here. If a §8(2) letter is added or a recipient changes during ATIP reconciliation, push the change back into the PIA rather than letting the two artefacts drift.
+
+---
+
+## Statutory currency
+
+The Access to Information Act was substantially amended by the Access to Information Modernization Act (Bill C-58, 2019), which introduced proactive publication obligations under Part 2 and expanded the OIC's order-making powers. Post-2019 jurisprudence is still being settled — cite carefully and check Federal Court / FCA decisions current at the date of generation. The Privacy Act is comparatively stable but is itself under reform consideration; cite the current consolidated text and verify against the Justice Laws Website. Record the verification date in the Document Register. Provincial access and privacy regimes (FIPPA in Ontario, Loi sur l'accès in Quebec, BC FIPPA, etc.) layer on top where the programme involves provincial or private-sector partners and are out of scope for this federal reconciliation.

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/ca-charter.md

@@ -0,0 +1,81 @@
+# Canada Charter Rights Design Review Playbook
+
+> **Guide Origin**: Community | **ArcKit Version**: [VERSION]
+
+`/arckit:ca-charter` generates a Canada Charter Rights Design Review for a federal system that materially engages Charter-protected interests. It identifies which sections of the Canadian Charter of Rights and Freedoms are engaged (default for FITAA-class apps: s.2(b), s.2(d), s.7, s.8, s.15), runs the *Oakes* four-step proportionality test against each engaged right, registers risks and mitigations with residual posture, and captures the DOJ counsel sign-off block.
+
+Charter review is mandatory for any federal system that limits a Charter-protected interest. *R v Oakes* structures the analysis: any limit must be prescribed by law and demonstrably justified through (1) a pressing and substantial objective, (2) a rational connection between the means and the objective, (3) minimal impairment of the right, and (4) proportional effects. The artefact this command produces is a design-stage instrument — DOJ counsel sign-off remains a delivery gate, not a sign-off formality.
+
+---
+
+## Inputs
+
+| Artefact | Purpose |
+|----------|---------|
+| Requirements (`ARC-<id>-REQ-v1.0.md`) | Engagement surface — speech, association, liberty, search, equality requirements |
+| Stakeholders (`ARC-<id>-STKE-v1.0.md`) | Subject populations, advocacy / journalism / diaspora stakeholders, protected-ground populations |
+| Privacy Impact Assessment (`ARC-<id>-PIA-v1.0.md`) | s.8 reasonable-expectation-of-privacy analysis grounded in personal-information categories |
+| FITAA Compliance Assessment (`ARC-<id>-FITAA-v1.0.md`) | s.2 expression and association engagement — Charter review is a mandatory companion to FITAA |
+
+---
+
+## Command
+
+```bash
+/arckit:ca-charter <project ID or service description>
+```
+
+Output: `projects/<id>/ARC-<id>-CHRT-v1.0.md`
+
+---
+
+## Assessment Structure
+
+| Section | Contents |
+|---------|----------|
+| Document Control | Canadian classification (UNCLASSIFIED / Protected A–C / CONFIDENTIAL / SECRET / TOP SECRET) |
+| Revision History | Version, date, author, changes, approvals |
+| Executive Summary | Engaged Charter sections, headline risks per right, residual posture, DOJ counsel sign-off status |
+| Charter Engagement Surface | Per-section engagement decision with reasoning; default-engaged for FITAA-class apps: s.2(b), s.2(d), s.7, s.8, s.15 |
+| s.2 Analysis | Sub-section tables for 2(a) conscience and religion, 2(b) expression, 2(c) peaceful assembly, 2(d) association |
+| s.7 Analysis | Engagement, deprivation, procedural safeguard, residual; principles of fundamental justice per *Carter* |
+| s.8 Analysis | Reasonable-expectation-of-privacy analysis per *Hunter v Southam* and *R v Spencer*; warrant or production-order interface |
+| s.15 Analysis | Protected grounds, differential impact, substantive-equality test, residual |
+| Oakes Proportionality Analysis | Four-step test (pressing-and-substantial, rational connection, minimal impairment, proportional effects) for each engaged right |
+| Mitigation Register | Charter risk, mitigation, owner, status, residual |
+| DOJ Counsel Sign-Off Block | Departmental Justice counsel and DOJ HQ constitutional advisor where the risk warrants; date and conditions |
+| External References | Document Register, Citations, Unreferenced |
+
+---
+
+## When to run
+
+- A federal system introduces or modifies a registration scheme, surveillance capability, or automated decision-making process that touches Charter-protected interests.
+- A FITAA-class app is being designed — Charter §2 expression and association analysis is unconditional after `/arckit:ca-fitaa`.
+- A programme will collect, retain, or disclose personal information in a way that engages s.8 reasonable expectation of privacy — typically after the PIA has scoped the personal-information inventory.
+- Pre-launch — before service-design sign-off and before any external-facing release of the system or its register.
+- On material change — to data, decision boundary, disclosure regime, or operating environment that re-opens any of the engaged rights.
+
+---
+
+## Common pitfalls
+
+- **Skipping Oakes steps.** Every engaged right requires the full four-step test (pressing-and-substantial, rational connection, minimal impairment, proportional effects). Partial proportionality analysis is the most common review failure and a reliable rejection trigger at DOJ review.
+- **Treating s.15 as formal equality.** The substantive-equality test asks whether the design creates or perpetuates disadvantage for a protected group, not whether everyone is treated identically. A facially neutral design that lands harder on a protected group is a s.15 problem regardless of intent.
+- **Under-citing technology-specific jurisprudence.** *R v Spencer* expanded s.8 to digital subscriber identifiers, and the s.8 jurisprudence continues to develop around metadata, cell-tower data, and platform-mediated communications. A Charter review that cites only *Hunter v Southam* without the modern digital line is incomplete.
+- **Sidelining DOJ counsel.** Anything beyond a routine internal-tooling review requires departmental Justice counsel sign-off; constitutional matters route to DOJ HQ constitutional advisors. A Charter design review without named counsel sign-off is a draft, not an artefact.
+- **Conflating engagement with limitation.** A Charter section can be engaged without being limited; the proportionality analysis only runs where the design imposes a limit. The engagement surface and the Oakes analysis are separate questions and must be answered separately.
+
+---
+
+## Handoffs
+
+- **`ca-fitaa`** — Charter §2 expression and association analysis is a mandatory companion to FITAA; the FITAA artefact references this review and the public-vs-protected severance design feeds the s.2 mitigation register. If `/arckit:ca-fitaa` has been run, `/arckit:ca-charter` is not optional.
+- **`ca-pia`** — §8 search-and-seizure analysis is grounded in the personal-information categories captured in the Privacy Impact Assessment. The PIA inventory drives the reasonable-expectation-of-privacy analysis; do not duplicate, link.
+- **`risk`** — Residual Charter risks per right feed the operational risk register with appropriate severity. Carry the Mitigation Register entries forward with the same risk identifiers so the residual posture is traceable.
+
+---
+
+## Statutory currency
+
+Charter jurisprudence is fast-moving in digital contexts. Cite the most recent SCC decisions on s.8 (digital privacy, metadata, cell-tower data), s.7 (procedural-fairness in administrative regimes touching liberty), s.15 (substantive-equality methodology), and s.1 (proportionality refinements) at the time of generation, and record the verification date in the Document Register. Section numbers are stable; the binding effect of jurisprudence is not. Treat any pre-2020 case as load-bearing only after checking subsequent SCC treatment, and re-verify before publication.

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/ca-cloud-residency.md

@@ -0,0 +1,91 @@
+# Canada Sovereign Cloud Residency Playbook
+
+> **Guide Origin**: Community | **ArcKit Version**: [VERSION]
+
+`/arckit:ca-cloud-residency` generates a sovereign cloud residency assessment for a Canadian federal information system. The artefact reconciles the system-level Protected categorisation with the *Government of Canada Cloud Adoption Strategy* and the TBS *Direction on the Secure Use of Commercial Cloud Services*, then produces a sovereign-options matrix across AWS Canada, Azure Canada, and Google Cloud Canada. It records the foreign-government access exposure (US CLOUD Act, FISA-702 / EO-12333 reach for US-incorporated CSPs), captures the SSC cloud-brokering inheritance picture, and documents the exit and portability plan with a published dry-run cadence.
+
+The Protected B threshold is the load-bearing line in this artefact. At Protected B and above the *Direction on the Secure Use of Commercial Cloud Services* tightens the residency envelope, and the choice of region, sub-processor inventory, encryption-key custody, and identity trust root all become assurance-relevant. The assessment is rationale-driven: every sovereign-option choice and every CLOUD-Act risk acceptance must be named, justified, and approved — sovereignty is a posture, not a checkbox.
+
+This command does not replace the formal cloud authorisation packages (CSP-level CSEAP submission, departmental ATO, SSC inheritance memos). It produces the residency-decision artefact that sits alongside those packages: the document that captures *why this region, this CSP, this exit plan, this CLOUD-Act risk acceptance*, anchored to the categorisation and the data-class drivers. Reviewers — security authority, departmental privacy office, ATIP coordinator, CIO branch — read it to understand the residency choices before they read the SoA or the PIA.
+
+---
+
+## Inputs
+
+| Artefact | Purpose |
+|----------|---------|
+| Requirements (`ARC-<id>-REQ-v1.0.md`) | NFR-AVL availability targets, NFR-LOC residency requirements, NFR-SEC data-handling expectations |
+| ITSG-33 SoA (`ARC-<id>-ITSG-v1.0.md`) | System-level categorisation and chosen control profile (PBMM-Cloud, Secret-High) — drives the residency envelope |
+| Data requirements (`ARC-<id>-DR-v1.0.md`) | Per-element sensitivity, including any Indigenous-data or personal-information flags |
+
+---
+
+## Command
+
+```bash
+/arckit:ca-cloud-residency <project ID or service description>
+```
+
+Output: `projects/<id>/ARC-<id>-CACR-v1.0.md`
+
+---
+
+## Assessment Structure
+
+| Section | Contents |
+|---------|----------|
+| Document Control | Canadian classification (UNCLASSIFIED / Protected A–C / CONFIDENTIAL / SECRET / TOP SECRET) |
+| Revision History | Version, date, author, changes, approvals |
+| Executive Summary | Categorisation, recommended sovereign cloud option, CLOUD-Act exposure posture, exit cadence |
+| Workload Categorisation | C / I / A scoring (or pull from ITSG SoA) and the resulting Protected level |
+| Residency Requirement Statement | At rest, in transit, in processing; backup and DR location; policy and data-class constraints |
+| Sovereign Cloud Options Matrix | AWS Canada, Azure Canada, Google Cloud Canada with regions, Protected B status, CLOUD-Act exposure, cost band, managed-services gaps |
+| GC Cloud Brokering Service Path | SSC role, departmental role, inheritance of ATO components |
+| Foreign Subprocessor Analysis | CSP supply-chain residency and named sub-processor jurisdictions |
+| Exit / Portability Plan | Bulk-export plan, state replication, format portability, dry-run cadence |
+| Cross-Border Transfer Analysis | Transfers, lawful authority cited, justification, CLOUD-Act exposure even for in-Canada workloads |
+| Operational Topology | Regions, AZs, network paths, encryption-in-transit, peering, key custody |
+| Open Items | Pending Protected B authorisations, unresolved sub-processor flags, exit-rehearsal schedule |
+| External References | Document Register, Citations, Unreferenced |
+
+The Shared Responsibility Matrix (within Operational Topology) crosswalks every residency-relevant control across CSP / SSC / departmental ownership, so reviewers can see who answers to TBS for which control surface.
+
+---
+
+## When to run
+
+- Pre-deployment cloud strategy — generate the assessment before the cloud target is locked in, not after.
+- Categorisation upgrade — any move from Protected A to Protected B, or Protected B to Protected C / SECRET, reshapes the eligible region set; re-run.
+- CSP migration — moving between hyperscalers (or onto an SSC-brokered offering) requires a fresh sovereign-options matrix and a refreshed CLOUD-Act risk acceptance.
+- ATO renewal — re-run on the published re-authorisation cycle; sub-processor inventories drift continuously and the verification dates expire.
+- New managed-service adoption — when a workload picks up a managed observability, ML, or analytics service that brings its own sub-processor reach, re-run the foreign-subprocessor analysis.
+- New CSP region or sovereign offering — Canadian cloud supply matures incrementally (e.g. AWS `ca-west-1` Calgary going GA, Azure regional expansions, GCP additional Toronto capacity). Re-run when a candidate region reaches the federal authorisation envelope, in case it changes the recommendation.
+- Sub-processor change notice — most CSPs publish sub-processor lists with a notice cadence; treat any addition of a non-Canadian-jurisdiction sub-processor as a trigger for a focused re-assessment of the affected workloads.
+
+---
+
+## Common pitfalls
+
+- **Treating a Canadian region as full sovereignty.** A US-incorporated CSP with `ca-central-1` or Canada Central is still subject to the US CLOUD Act for the data it processes. The region addresses operational residency; it does not neutralise the legal-conflict exposure.
+- **Ignoring CLOUD Act on US-incorporated CSPs.** The risk acceptance must be named — recorded in an ADR, signed off by an accountable person, and visible to the authorising official. Silent acceptance fails on inspection.
+- **Under-budgeting exit cost.** Bulk-egress fees, format-portability gaps, and operational-runbook coupling all add up. An exit budget that has not been tested by a dry-run is fiction; rehearse annually at minimum.
+- **Assuming SSC brokering cancels departmental ATO obligations.** SSC publishes inherited ATO components but the departmental Authorising Official still issues the system ATO. Treat the inherited envelope as scaffolding, not a transfer.
+- **Federating identity to a foreign tenant.** A workload whose IAM trust root sits in a foreign-hosted IdP is not residency-clean even if the data is in Canada. The identity plane is a residency surface.
+- **Treating sub-processor lists as static.** CSPs update their sub-processor lists on their own cycle. Record the verification date and re-check at ATO renewal.
+- **Conflating Canadian region with Canadian sovereign cloud.** AWS Canada, Azure Canada, and Google Cloud Canada are Canadian-region offerings of US-incorporated CSPs, not sovereign clouds in the sense some other jurisdictions use the term. Where a workload requires a sovereignty posture beyond what an in-Canada region of a US CSP can deliver, escalate to the security authority — the eligible-options set narrows materially.
+- **Forgetting the backup region.** Disaster-recovery secondaries often quietly land in a foreign region under default cloud-provider patterns. Pin the DR target to a second Canadian region (or an in-Canada AZ topology) and verify the actual replication path against the residency requirement.
+
+---
+
+## Handoffs
+
+- **`adr`** — Sovereign-cloud option choices (which region, which CSP, which encryption-key custody model) and CLOUD-Act risk acceptances are material architectural decisions. Each warrants an ADR with options analysed, the chosen path justified, and the named accepter recorded against the residual risk.
+- **`ca-itsg-33`** — The cloud control-profile selection (PBMM-Cloud for the typical federal Protected B cloud-hosted baseline; Secret-High for higher-categorised workloads) is grounded in the ITSG-33 categorisation. Run `ca-itsg-33` before this assessment where possible — the categorisation flows in. Where this assessment is run first to inform a cloud decision, hand the categorisation forward to the SoA and reconcile both artefacts at the same review. Tailoring decisions in the SoA (key-custody parameters, network-segmentation parameters, audit retention) often have direct cloud-residency implications and should be revisited together.
+
+---
+
+## Statutory currency
+
+The TBS *Direction on the Secure Use of Commercial Cloud Services* updates regularly as TBS guidance evolves and as new sovereign-cloud offerings reach federal authorisation. CSE sovereign-cloud guidance moves with regional supply maturity — Protected B authorisations, new Canadian regions (e.g. AWS `ca-west-1`), and new sovereign offerings (e.g. provider-specific sovereign clouds for Canada) all reshape the eligible-options set. Re-verify against the TBS and CSE primary sources at the verification date recorded in the Document Register, and treat any sub-processor list as time-bounded.
+
+The CMVP active-modules list, the CSP-published sub-processor inventories, and the SSC cloud-brokering catalogue all churn on shorter cycles than the TBS Direction. Stamp the verification date against each table cell that reflects an external source, and surface anything that has gone stale at the next review gate. A residency assessment that has not been re-verified in the last review cycle is, for inspection purposes, not current — even if the underlying environment has not changed.