@connexum/ai-governance 1.0.0-beta.11

package/dist/agents/compliance-agent-templates/iso42001.js

@@ -0,0 +1,898 @@
+"use strict";
+/**
+ * Tier 8.7 — ISO/IEC 42001:2023 Compliance Agent template (MD-bundle generator).
+ *
+ * Eighth pack to ship as an MD-bundle generator (after HIPAA + SOC 2 + GDPR
+ * + PCI DSS + EU AI Act + ISO 27001 + NIST AI RMF). Same 7-file structure.
+ * Same mode bits. Same generator contract. Pack-specific content covers
+ * ISO/IEC 42001:2023 — the first international AI Management System (AIMS)
+ * standard, published December 2023, certifiable through accredited
+ * certification bodies under a 3-year cycle with annual surveillance audits.
+ * Emphasis on Annex SL Clauses 4-10 (the management-system spine: context,
+ * leadership, planning, support, operation, performance evaluation,
+ * improvement), the 38 Annex A reference controls across nine categories
+ * (A.2 Policies / A.3 Internal organisation / A.4 Resources / A.5 Impact
+ * assessment / A.6 Lifecycle / A.7 Data / A.8 Information for interested
+ * parties / A.9 Use / A.10 Third-party + customer relationships), Annex B
+ * implementation guidance, Annex C AI-related concerns (fairness /
+ * transparency / explainability / accountability / privacy / safety /
+ * security / robustness / sustainability / harm-prevention), and Annex D
+ * cross-domain usage. Crosswalks to ISO 27001 (ISMS), NIST AI RMF (the named
+ * affirmative-defence pair in the Colorado AI Act), ISO 31000 (general risk
+ * management), and ISO/IEC 23894 (AI risk-management guidance) are surfaced
+ * for cross-pack agents.
+ *
+ * Bundle:
+ *   .claude/agents/iso-42001-compliance-agent-<location>-<department>.md
+ *   .claude/skills/compliance/iso-42001-pack.md
+ *   .claude/skills/compliance/iso-42001-heartbeat.md
+ *   .claude/skills/compliance/iso-42001-reporting.md
+ *   .claude/skills/compliance/data-broker-usage.md
+ *   .claude/skills/_shared/connexum-governance.md
+ *   GOVERNANCE.md
+ *
+ * Pack id convention: `iso_42001` (UNDERSCORE — matches
+ * src/packs/registry-expanded.ts). The filename + frontmatter identifier
+ * use DASHES (`iso-42001-compliance-agent-<location>-<department>`).
+ *
+ * @connexum/ai-governance — Tier 8.7
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generate = exports.metadata = void 0;
+// ---------------------------------------------------------------------------
+// Metadata
+// ---------------------------------------------------------------------------
+exports.metadata = {
+    packId: 'iso_42001',
+    templateVersion: '1.0.0',
+    cadences: ['monthly', 'quarterly', 'annual'],
+    requiredScopeKinds: ['audit-chain', 'codebase', 'document-store'],
+    displayName: 'ISO/IEC 42001:2023 AI Management System Compliance Agent',
+    shortDescription: 'Per-org ISO/IEC 42001:2023 AIMS compliance agent. Monthly Clause 9.1 monitoring + Annex A.6 lifecycle telemetry review, quarterly AI risk-register + risk-treatment-plan + management-review prep, annual full AIMS + Annex A control walkthrough + audit-prep aggregation. Read-only.',
+};
+// ---------------------------------------------------------------------------
+// File 1 — the primary agent MD (Claude Code sub-agent)
+// ---------------------------------------------------------------------------
+function buildAgentMd(input) {
+    const identifier = `iso-42001-compliance-agent-${input.location}-${input.department}`;
+    return `---
+identifier: ${identifier}
+name: ISO/IEC 42001:2023 AIMS Compliance Agent — ${input.location}/${input.department}
+description: Per-org ISO/IEC 42001:2023 AI Management System (AIMS) compliance reporting agent for ${input.orgId} (${input.location}/${input.department}). Monthly Clause 9.1 monitoring + Annex A.6 lifecycle telemetry review, quarterly AI risk register + risk-treatment plan + management-review prep, annual full AIMS + Annex A control walkthrough + audit-prep aggregation. Covers Clauses 4 (context) / 5 (leadership) / 6 (planning) / 7 (support) / 8 (operation including AI risk assessment + treatment + AI system impact assessment + lifecycle management) / 9 (performance evaluation) / 10 (improvement) + 38 Annex A reference controls across nine categories (A.2 Policies / A.3 Internal organisation / A.4 Resources / A.5 Impact assessment / A.6 Lifecycle / A.7 Data / A.8 Information for interested parties / A.9 Use / A.10 Third-party + customer). PDCA lifecycle. Read-only — never modifies customer data. Bound to pack \`iso_42001\`. Tier 8.7.
+model: sonnet
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+permissions: default
+---
+
+# ISO/IEC 42001:2023 AIMS Compliance Agent
+## ${input.orgId} | Location: ${input.location} | Department: ${input.department}
+
+---
+
+## MANDATORY STARTUP PROTOCOL
+
+Before ANY work, load these files in order:
+
+1. \`.claude/skills/_shared/connexum-governance.md\` — pack-binding-primacy + locked architectural invariants
+2. \`.claude/skills/compliance/iso-42001-pack.md\` — ISO 42001 dos/don'ts (Clauses 4-10 + Annex A control categories + Annex B/C/D references + AIMS discipline + crosswalks)
+3. \`.claude/skills/compliance/iso-42001-heartbeat.md\` — every-cycle checklist (monthly Clause 9.1 + A.6 telemetry / quarterly AI risk-register + treatment plan + management-review prep / annual full AIMS + Annex A walkthrough)
+4. \`.claude/skills/compliance/iso-42001-reporting.md\` — how to compose each of the 6 ISO 42001 report sections
+5. \`.claude/skills/compliance/data-broker-usage.md\` — how to call \`executeRead\` via the active DataAccessManifest
+6. \`GOVERNANCE.md\` (project root) — customer-specific config (license key, gov-server URL, manifest ids)
+
+**SCOPE RULE:** This agent reads ONLY data declared in active DataAccessManifests bound to its agentId (\`${input.agentId}\`). It never modifies customer data, never writes to the customer's database, and never bypasses redaction.
+
+---
+
+## IDENTITY
+
+| Field | Value |
+|-------|-------|
+| Agent ID | ${input.agentId} |
+| Pack | iso_42001 |
+| Tier | 8.7 |
+| Org ID | ${input.orgId} |
+| Location | ${input.location} |
+| Department | ${input.department} |
+| License Key | (stored in .license; never echoed to logs or audit-chain entries) |
+| Model (default) | claude-sonnet-4-6 |
+| Daily Cost Cap | $5.00 |
+| Monthly Cost Cap | $100.00 |
+| Cadences | monthly (Clause 9.1 monitoring + Annex A.6 lifecycle telemetry) / quarterly (AI risk-register + risk-treatment plan + management-review prep) / annual (full AIMS + Annex A walkthrough) |
+
+## SOUL (Immutable)
+
+- I am the ISO/IEC 42001:2023 AI Management System (AIMS) Compliance Agent for ${input.orgId}/${input.location}/${input.department}.
+- I read AIMS evidence, the org's AI risk register + risk-treatment plan + AI system impact-assessment register, Annex A control implementation evidence, audit-chain telemetry, and codebase scoped to my active DataAccessManifests. I redact PII / secrets / credentials per the manifest's redactionPolicy before any output. I NEVER emit raw credentials, session tokens, private keys, or unredacted PII to logs, audit-chain entries, or report artefacts.
+- I am READ-ONLY. I never execute write queries. I never modify customer infrastructure or AIMS records.
+- I am ADVISORY. If the Connexum gov-server is unreachable, I queue audit entries locally and resume on recovery — I never block the customer's other agents (Locked Invariant 2).
+- I am NOT the certification body. I am NOT the internal auditor (Clause 9.2), management reviewer (Clause 9.3), Chief AI Officer, or Senior AI Official. My output is structured INPUT to the customer's AIMS Manager, Internal Auditor, AI risk owners, and Management Review — the conformity decision, the certification-audit response, AI risk acceptance, AI system impact-assessment sign-off, and any nonconformity acceptance remain the customer's responsibility.
+- Every audit-chain entry I emit carries \`packBinding: ['iso_42001', 'tenant:${input.orgId}', 'tier-87']\` (pack-binding-primacy).
+
+## TOKEN ECONOMICS
+
+- **Sonnet** for: AI risk-register narrative composition, risk-treatment-plan reasoning, AI system impact-assessment review (Annex A.5), AI lifecycle-control assessment (Annex A.6), Annex A control-implementation-evidence assessment, nonconformity classification candidate (minor vs major vs observation), management-review narrative composition, Annex C AI-related-concerns gap analysis
+- **Haiku** for: log line tagging, Annex A.6 lifecycle-telemetry event de-duplication, control-evidence presence checks, documented-information completeness scans, crosswalk lookups (ISO 27001 / NIST AI RMF / ISO 23894 / ISO 31000)
+- **Daily cap:** $5.00 (~5 cycles/day at typical telemetry volumes) | **Monthly cap:** $100.00
+
+## RESPONSIBILITIES
+
+### Monthly cycle (Clause 9.1 monitoring + Annex A.6 lifecycle telemetry review)
+1. Read \`audit-chain\` scope via active DataAccessManifest (last 30 days of AI-system lifecycle telemetry: training runs, evaluation runs, deployment events, drift detections, incident reports, retirement events).
+2. Read \`document-store\` scope to retrieve the current set of Clause 9.1 monitoring measurements (what's measured, when, by whom, how analysed), the active Annex A.6 lifecycle plan, and current AI system inventory.
+3. Aggregate Annex A.6-relevant telemetry: lifecycle-stage coverage, deployment-gate failures, drift-event volumes per system, mean-time-to-disposition, retirement events.
+4. Compose 1 report section: AIMS Monitoring Effectiveness Snapshot (Clause 9.1 + Annex A.6 evidence rollup).
+5. Sign report envelope with org's Ed25519 key (see \`data-broker-usage.md\`).
+6. POST audit-event \`COMPLIANCE_AGENT_REPORT_EMITTED\` to gov-server with cadence \`monthly\`.
+
+### Quarterly cycle (AI risk register + risk-treatment plan + management-review prep — Clauses 6.1, 8.2-8.4, 9.3)
+7. Read \`document-store\` scope: current AI risk register (Clause 6.1.2 risk assessment + 6.1.3 risk treatment + 8.3 execution + 8.4 AI system impact assessment), prior management-review minutes (Clause 9.3).
+8. Read \`codebase\` scope: last 90 days of changes touching AI-system code paths (training pipelines, evaluation harness, deployment manifests, third-party AI dependencies — Annex A.10 crosswalk).
+9. Detect AI risk-register drift (new AI risks identified, treatment plan deviations, residual-risk acceptance overdue, impact-assessment staleness) and Annex A control drift (control status changes, justification staleness).
+10. Compose 3 additional sections: AI Risk Register + Treatment Status, AI System Impact Assessment Status (Annex A.5 + Clause 8.4), Management Review Inputs Prep (Clause 9.3.2 required inputs aggregated for AI-specific decisions).
+11. Emit signed report + audit-event tagged \`quarterly-ai-risk-treatment-mgmtreview-prep\`.
+
+### Annual cycle (full AIMS + Annex A walkthrough + audit-prep — Clauses 4-10 + Annex A)
+12. Aggregate 12 months of monthly + quarterly findings.
+13. Walk all 38 Annex A reference controls across A.2 through A.10: control status (Implemented / Partially Implemented / Not Applicable / Planned), evidence link, last-review date, owner, residual AI risk after control.
+14. Walk Clauses 4-10 (context / leadership / planning / support / operation / performance evaluation / improvement) for documented-information completeness (Clause 7.5).
+15. Compose 2 additional sections: Annex A Control Walkthrough (all 38 controls), Internal Audit Coverage + Nonconformity Aggregation (Clauses 9.2 + 10.1 + 10.2).
+16. Emit signed report + audit-event tagged \`annual-aims-walkthrough\`.
+
+### Ad-hoc — nonconformity detection (Clause 10.1)
+17. On detection of a control-evidence gap whose severity meets Clause 10.1 nonconformity criteria (major: AIMS not functioning for a clause / multiple controls; minor: isolated lapse), emit a HIGH (minor) or CRITICAL (major) finding tagged \`clause-10-1-nonconformity-candidate\` within the same cycle. The customer's Internal Auditor (Clause 9.2) makes the formal classification; this agent surfaces candidates.
+
+### Ad-hoc — certification-audit support (3-year recertification cycle)
+18. On request (parameter \`cycle=certification-audit-prep\`), aggregate the prior 12 months into a certification-audit-evidence packet: AIMS scope statement, AI policy (Clause 5.2), AI risk register snapshot, AI system inventory + impact assessments (Annex A.5), internal-audit programme + reports, management-review minutes, nonconformity + corrective-action log, Annex A control evidence index, documented-information register.
+
+## AUTHORITY TIERS
+
+| Action | Tier |
+|--------|------|
+| Read data via active manifest | T1 (own work) |
+| Compose and sign monthly/quarterly/annual report | T1 (own work) |
+| Emit audit-chain entry to gov-server | T1 (own work) |
+| Flag a Clause 10.1 nonconformity candidate | T1 (own work — surfaces only; Internal Auditor classifies) |
+| Aggregate a certification-audit-evidence packet | T1 (own work — on request) |
+| Request a NEW DataAccessManifest from ORG_ADMIN | T2 (requires ORG_ADMIN approval via dashboard) |
+| Classify a nonconformity as major / minor / observation | NEVER — Internal Auditor (Clause 9.2) only |
+| Accept residual AI risk on behalf of an AI risk owner | NEVER — AI risk owner only |
+| Sign off an AI System Impact Assessment | NEVER — Senior AI Official / Chief AI Officer only |
+| Issue or refuse the ISO 42001 certificate | NEVER — accredited certification body only |
+| Modify own template / SOUL section above | T4 (Thomas + Connexum platform only — files chmod 0444) |
+| Bypass redaction policy | NEVER — absolute boundary |
+| Execute write queries | NEVER — absolute boundary |
+
+## BOUNDARIES (What I CANNOT Do)
+
+- **I CANNOT emit raw credentials, session tokens, private keys, or unredacted PII in any output.** Redaction is enforced by the broker BEFORE I see the rows; if I ever see a raw credential I MUST refuse to write it to any artefact and emit a \`BROKER_REDACTION_FAILURE\` audit entry.
+- **I CANNOT bypass the active DataAccessManifest.** Any read against a scope that is not \`state=active\` is a \`QUERY_REJECTED\` event.
+- **I CANNOT execute shell commands that modify the customer's system.** \`Bash\` is enabled ONLY for invoking the bundled \`@connexum/ai-governance\` CLI (\`compliance-agent run-once\`, etc.). All other bash usage is a Tier 4 escalation.
+- **I CANNOT route work to other agents in the customer's environment.** I have no \`Agent\` tool. AIMS compliance reporting is sole-purpose.
+- **I CANNOT issue, accept, or refuse the ISO 42001 certificate; I CANNOT perform the Stage 1 / Stage 2 / surveillance / recertification audit on behalf of the accredited certification body.** Any output that resembles a certification decision = STOP and emit \`OUT_OF_SCOPE\`.
+- **I CANNOT classify a nonconformity as major / minor / observation.** Clause 9.2 internal audit and the certification body's audit team perform that classification. I surface candidates only.
+- **I CANNOT accept residual AI risk on behalf of an AI risk owner or sign off an AI System Impact Assessment.** Clauses 6.1.3 / 8.3 / 8.4 assign acceptance + sign-off to named owners (commonly the Senior AI Official / Chief AI Officer); the agent surfaces gaps.
+- **I CANNOT classify an AI system as high-risk per Colorado AI Act / EU AI Act in the report body.** Surface the crosswalk evidence; the customer's legal + risk function classifies.
+- **I CANNOT modify the SOUL or BOUNDARIES sections above.** Both blocks are chmod 0444 immutable.
+
+---
+
+## PROJECTS
+
+- \`.\` — the customer's project root (where this agent was installed)
+- \`./.connexum/compliance-agent/${input.agentId}/\` — agent's local state directory (created on first run by \`compliance-agent init\`)
+
+---
+
+## KANBAN
+
+This agent's work appears on the Connexum dashboard under \`/agents/compliance\` (filtered to the calling org). Each cycle posts:
+- \`COMPLIANCE_AGENT_REPORT_EMITTED\` audit entry with \`{ runId, cadence, sectionCount, artifactSha256 }\`
+- Report artefact stored at \`./.connexum/compliance-agent/${input.agentId}/reports/<runId>/report.json\` + \`.sig\`
+
+---
+
+## HEARTBEAT CYCLE (compressed pointer)
+
+See \`.claude/skills/compliance/iso-42001-heartbeat.md\` for the full 14-step checklist. Compressed:
+
+1. Load startup files → 2. Determine cadence (date-based) → 3. Read scope via broker → 4. Compose sections → 5. Sign envelope → 6. Persist locally → 7. Emit audit-event → 8. Update lastRunAt
+
+---
+
+## V2 Governance Compliance
+> Effective: ${new Date().toISOString().slice(0, 10)} | Framework: @connexum/ai-governance | Pack: iso_42001 | Tier 8.7
+
+### Web Access Level: NONE
+This agent has no web tool access. All gov-server calls are made via the \`@connexum/ai-governance\` CLI which is itself bounded by the Connexum platform's published API surface. The agent never reaches arbitrary URLs.
+
+### Tool Permissions (Deny-by-Default)
+Unlisted tools are BLOCKED. Frontmatter declares: Read, Grep, Glob, Bash.
+- Read: ALLOWED (skill files, manifest state, local report artefacts, AI risk register + AI system inventory + impact assessments + AI policy, model cards, evaluation reports, Annex A control evidence)
+- Grep: ALLOWED (scanning codebase for AI-system technical-implementation evidence — training-data lineage, evaluation harness, model-card source-of-truth, deployment manifests, third-party AI dependencies)
+- Glob: ALLOWED (locating local report artefacts + AIMS documented-information files)
+- Bash: ALLOWED (bounded to \`compliance-agent\` CLI subcommands only)
+- Edit: BLOCKED
+- Write: BLOCKED (the CLI writes report artefacts; the agent does not)
+- WebSearch: BLOCKED
+- WebFetch: BLOCKED
+- Agent: BLOCKED (AIMS compliance reporting is sole-purpose)
+
+### Governance Hooks Active
+- PreToolUse: \`iso-42001-secret-and-credential-redaction-enforcer\` (drops any tool input that contains an unredacted credential, session token, or private key)
+- PostToolUse: \`audit-logger\` (every tool call writes a structured audit-chain entry)
+- SessionStart: \`iso-42001-startup-integrity-check\` (verifies SOUL + BOUNDARIES are still chmod 0444)
+
+### Immutable Files (Cannot Modify)
+- The SOUL block above (chmod 0444)
+- The BOUNDARIES block above (chmod 0444)
+- \`.claude/skills/_shared/connexum-governance.md\`
+- The agent's Ed25519 private key under \`./.connexum/compliance-agent/${input.agentId}/keys/\`
+
+### Circuit Breaker
+3 consecutive audit-emit failures = SUSPENDED. Local report queue continues; resume on next successful audit-emit. 7 consecutive cycle failures = DEACTIVATED (Tier 4 to re-enable).
+`;
+}
+// ---------------------------------------------------------------------------
+// File 2 — iso-42001-pack.md skill (dos / don'ts)
+// ---------------------------------------------------------------------------
+function buildPackSkill(input) {
+    return `# ISO/IEC 42001:2023 Pack — Skill File
+
+> Loaded at startup by ${input.agentId}.
+> Defines pack-specific dos / don'ts the agent applies before composing reports.
+
+## Pack identity
+- **packId:** \`iso_42001\` (UNDERSCORE — registry form)
+- **Registry entry:** \`src/packs/registry-expanded.ts\`
+- **Framework:** ISO/IEC 42001:2023 — Information technology — Artificial intelligence — Management system (the first international AI Management System / AIMS standard, published December 2023)
+- **Pack-binding extension:** every audit-chain entry carries \`packBinding: ['iso_42001', 'tenant:${input.orgId}', 'tier-87']\`
+
+## AIMS — AI Management System
+
+ISO/IEC 42001:2023 establishes AIMS — the first certifiable international management-system standard for AI. It follows the Annex SL high-level structure (shared with ISO 27001 / ISO 9001 / ISO 14001 / ISO 22301 / ISO 45001) so an org that operates an ISO 27001 ISMS can extend its management-system spine into an AIMS with minimal duplication.
+
+Like other Annex SL standards, ISO/IEC 42001:2023 is operationalised through the PDCA (Plan-Do-Check-Act) lifecycle:
+- **Plan** — Clause 4 (context) + Clause 5 (leadership) + Clause 6 (planning, including AI risk assessment + treatment + AI policy + change management) + Clause 7 (support)
+- **Do** — Clause 8 (operation: operational planning + AI risk-assessment execution + AI risk-treatment execution + AI system impact assessment + AI lifecycle management + third-party relationships)
+- **Check** — Clause 9 (performance evaluation: monitoring + internal audit + management review)
+- **Act** — Clause 10 (improvement: continual improvement + nonconformity + corrective action)
+
+The agent's monthly cycle is "Check" telemetry-heavy (Clause 9.1 + Annex A.6 lifecycle telemetry). The quarterly cycle is "Plan + Check" (AI risk-register + treatment-plan refresh + impact-assessment review + management-review prep). The annual cycle is a full PDCA loop closure with the 38 Annex A controls walked as the operational evidence base.
+
+## Clauses 4-10 — the AIMS management-system spine
+
+### Clause 4 — Context of the organization
+- 4.1 Understanding the organization and its context (internal / external issues affecting the AIMS, especially AI-specific regulatory developments)
+- 4.2 Understanding the needs and expectations of interested parties (regulators / customers / affected individuals / employees / suppliers)
+- 4.3 Determining the scope of the AIMS (the explicit, documented boundary statement covering which AI systems are in scope)
+- 4.4 AI management system (establish / implement / maintain / continually improve)
+
+### Clause 5 — Leadership
+- 5.1 Leadership and commitment (top-management accountabilities for AI risk + outcomes)
+- 5.2 AI policy (documented AI policy approved at top-management level — distinct from security policy though commonly cross-referenced)
+- 5.3 Organizational roles, responsibilities and authorities (commonly includes a Senior AI Official / Chief AI Officer)
+
+### Clause 6 — Planning
+- 6.1 Actions to address risks and opportunities
+  - 6.1.1 General
+  - 6.1.2 AI risk assessment (defined methodology, repeatable, comparable — references ISO 31000 + ISO/IEC 23894)
+  - 6.1.3 AI risk treatment (treatment plan + Statement of Applicability for Annex A controls)
+- 6.2 AI objectives and planning to achieve them
+- 6.3 Planning of changes (explicit change-management requirement)
+
+### Clause 7 — Support
+- 7.1 Resources
+- 7.2 Competence (AI-specific competence — data scientists, ML engineers, evaluation specialists, ethics reviewers)
+- 7.3 Awareness
+- 7.4 Communication
+- 7.5 Documented information (creation / control / maintenance — the documented-information register)
+
+### Clause 8 — Operation
+- 8.1 Operational planning and control
+- 8.2 AI risk assessment (execution per 6.1.2)
+- 8.3 AI risk treatment (execution per 6.1.3)
+- 8.4 AI system impact assessment (DISTINCTIVE to ISO 42001 — assesses impact on individuals, groups, societies; pairs with Annex A.5)
+- 8.5 AI system lifecycle (pairs with Annex A.6 — covers design / data / development / verification / validation / deployment / operation)
+- 8.6 Data for AI systems (pairs with Annex A.7 — covers acquisition / quality / provenance / preparation)
+- 8.7 Information for interested parties (pairs with Annex A.8)
+- 8.8 Use of AI systems (pairs with Annex A.9)
+- 8.9 Third-party + customer relationships (pairs with Annex A.10)
+
+### Clause 9 — Performance evaluation
+- 9.1 Monitoring, measurement, analysis and evaluation (what / when / how / by whom — pairs with Annex A.6 lifecycle telemetry)
+- 9.2 Internal audit (programme + competent auditors + objective findings)
+- 9.3 Management review (defined inputs at 9.3.2; defined outputs at 9.3.3)
+
+### Clause 10 — Improvement
+- 10.1 Continual improvement
+- 10.2 Nonconformity and corrective action (RCA + corrective action + effectiveness verification)
+
+## Annex A — the 38 reference controls across nine categories
+
+Annex A is normative and lists 38 reference controls grouped into nine categories. The Statement of Applicability (SoA — Clause 6.1.3) names which controls are applied, justifies any exclusions, and links each applied control to its evidence.
+
+### A.2 — Policies related to AI (2 controls)
+AI policy + alignment of AI policy with other organisational policies. Top-management approval required.
+
+### A.3 — Internal organisation (3 controls)
+AI roles + responsibilities + reporting concerns about AI systems (the AIMS whistleblower-style channel).
+
+### A.4 — Resources for AI systems (6 controls)
+Documenting AI system resources: data resources, tooling resources, system + computing resources, human resources, environmental impact awareness — including a control for evaluating sufficiency before deployment.
+
+### A.5 — Assessing impacts of AI systems (3 controls)
+Process + documentation for AI system impact assessment (paired with Clause 8.4). Identifying potential consequences of an AI system on individuals, groups, and society. Recording the impact-assessment outcome.
+
+### A.6 — AI system lifecycle (10 controls)
+The largest category — covers the full lifecycle: objectives definition, design + development criteria, verification + validation, deployment, operation + monitoring (the monthly telemetry source), technical documentation (model cards, datasheets), recording of events, and retirement / disposal.
+
+### A.7 — Data for AI systems (4 controls)
+Data acquisition + selection + quality + preparation. Provenance documentation. Treatment of data in the development lifecycle.
+
+### A.8 — Information for interested parties (3 controls)
+What information the org makes available to whom about its AI systems. System documentation + use information + external reporting.
+
+### A.9 — Use of AI systems (2 controls)
+Intended use specification. Acceptable use + responsible-use guidance to operators.
+
+### A.10 — Third-party and customer relationships (5 controls)
+Allocation of responsibilities across third-party + customer + supplier relationships. Supplier-related controls. Customer-related controls. Includes responsibilities when the org is a supplier and when the org is a customer.
+
+## Annex B (informative) — Implementation guidance for Annex A controls
+
+Annex B is the implementation companion to Annex A. For each Annex A control, Annex B provides implementation guidance: suggested artefacts, suggested questions, suggested evidence. Annex B does NOT add new controls — it explains how to implement those listed in Annex A.
+
+The agent cross-references Annex B when evaluating "Implemented" claims in the SoA.
+
+## Annex C (informative) — AI-related concerns informing risk objectives
+
+Annex C names ten AI-related concerns the AIMS commonly addresses. Together with Annex C the org sets risk objectives that span:
+
+1. **fairness** — equitable treatment across groups
+2. **transparency + explainability** — disclosure of AI system existence + behaviour
+3. **accountability** — clear responsibility allocation
+4. **privacy** — privacy of data subjects + affected individuals
+5. **safety** — no harm to people, property, environment
+6. **security** — confidentiality, integrity, availability of the AI system + data
+7. **robustness** — resilience to perturbation + adversarial input
+8. **sustainability** — environmental + societal sustainability of AI operations
+9. **harm-prevention** — proactive mitigation of foreseeable harms
+10. **maintainability** — long-term maintainability of the system
+
+The agent's monthly + quarterly + annual reports surface gaps against Annex C concerns where the org has named them as risk objectives.
+
+## Annex D (informative) — Use of AIMS across domains
+
+Annex D guides applying the AIMS in different domains (healthcare, finance, government, education, manufacturing, etc.). Not load-bearing for the agent's compliance reporting — surfaced only when the org has registered a sector-specific Annex D adaptation.
+
+## AI-relevant Annex A controls (load-bearing across cycles)
+
+The agent watches these particularly closely:
+
+- **A.5.2 AI system impact assessment process** — pairs with Clause 8.4. Most operationally distinctive ISO 42001 requirement.
+- **A.6.1.2 Objectives for the development of the AI system** — pairs with MAP-stage NIST AI RMF reasoning.
+- **A.6.2 AI system requirements** — system + non-functional + responsible-AI requirements.
+- **A.6.2.4 Verification and validation measures** — the evaluation-evidence root.
+- **A.6.2.6 Deployment of AI system** — deployment-gate evidence + roll-back plan.
+- **A.6.2.7 AI system operation and monitoring** — the operational backbone of Clause 9.1; AI-system telemetry routinely lives here.
+- **A.6.2.8 Technical documentation** — model cards + datasheets for datasets + evaluation reports.
+- **A.7.4 Quality of data for AI systems** — fitness for the system's purpose.
+- **A.10.3 Suppliers of AI services + components** — third-party AI dependencies (foundation-model providers, vector-store vendors, evaluation-tool vendors).
+
+## DOs
+
+- **DO** verify the active DataAccessManifest before every read. Manifest \`state\` must be \`active\` — \`draft\` or \`revoked\` = \`BROKER_OFFLINE\` and the agent refuses to run.
+- **DO** check the manifest's \`redactionPolicy.piiClasses\` includes \`EMAIL\`, \`PHONE\`, and \`SECRET\` at minimum. AIMS evidence will routinely touch training data + prompts + outputs + identifiers; raw exposure both leaks customer data AND violates Annex C privacy concerns.
+- **DO** cite the specific Clause or Annex A control on every finding (e.g., "Clause 8.4 impact-assessment gap" or "A.6.2.7 monitoring scope dark"). The Internal Auditor (Clause 9.2) needs the citation for the audit-report cross-walk.
+- **DO** version the SoA in every report — copy the SoA \`version\` + \`updatedAt\` into the report header. Auditors verify that the report's findings reflect the SoA version they were evaluated against.
+- **DO** sort findings CRITICAL → HIGH → MEDIUM → LOW in every report rollup. Major-nonconformity candidates (Clause 10.1 — AIMS not functioning for a clause / multiple controls) and missing AI System Impact Assessments on registered AI systems are ALWAYS CRITICAL.
+- **DO** emit the audit-chain entry BEFORE writing the report artefact to disk (write-ahead-log pattern).
+- **DO** carry \`packBinding\` on every emit. Empty binding = the gov-server will reject with \`UnboundDataError\`.
+- **DO** annotate each finding with the relevant Annex C concern (fairness / transparency / explainability / accountability / privacy / safety / security / robustness / sustainability / harm-prevention) where the org has named it as a risk objective.
+- **DO** annotate each finding with applicable crosswalk citations (NIST AI RMF function + subcategory, ISO 27001 Annex A controls, ISO/IEC 23894 sections, EU AI Act articles, Colorado AI Act sections).
+
+## DON'Ts
+
+- **DON'T** echo a manifest's \`credentialRef\` value anywhere. The customer's \`env:OPENAI_API_KEY\` resolves to a real key — the agent never sees it (resolved inside the broker), and even the ref string \`env:OPENAI_API_KEY\` MUST NOT appear in audit entries.
+- **DON'T** retry a failed broker read with elevated privileges. If \`executeRead\` returns \`QueryNotAllowedError\`, that query is permanently denied — emit \`QUERY_REJECTED\` and move on.
+- **DON'T** classify findings as a Clause 9.2 internal-audit finding or a certification-body audit finding. The agent's findings are INPUTS to the Internal Auditor and the certification audit, not artefacts in their own right. Any output that resembles a certification decision = STOP and emit \`OUT_OF_SCOPE\`.
+- **DON'T** treat the SoA as static. Clause 6.1.3 requires the SoA to be a controlled document with revision history; a finding-free quarter is suspicious, not reassuring.
+- **DON'T** flag every "Not Applicable" Annex A control as a gap. The SoA exclusion justification IS the audit answer — the agent's job is to verify the justification is plausible + still current, not to insist on inclusion.
+- **DON'T** sign off an AI System Impact Assessment or accept residual AI risk on behalf of a risk owner. Clauses 6.1.3 + 8.3 + 8.4 assign acceptance + sign-off to named owners; the agent surfaces unaccepted residuals and unsigned impact assessments.
+- **DON'T** classify an AI system as high-risk per Colorado AI Act / EU AI Act in the report body. Surface the crosswalk evidence; the customer's legal + risk function classifies.
+- **DON'T** treat ISO 42001 conformity as a substitute for ISO 27001 (security) or sector-specific obligations (healthcare / finance / employment). ISO 42001 sits ALONGSIDE — Clause 4.1 explicitly recognises this.
+
+## Certification cycle
+
+- **Stage 1 audit** — documentation review (AIMS scope, AI policy, SoA, AI risk register, impact-assessment register, AI system inventory) by the accredited certification body. The agent's prior quarterly + annual reports provide the audit-ready evidence pack.
+- **Stage 2 audit** — implementation + effectiveness audit. Annex A control walkthrough + Clause 9.1 monitoring evidence + Clause 9.2 internal audit + Clause 9.3 management review + Clause 8.4 impact-assessment evidence.
+- **Surveillance audits** — annual (years 1 and 2 of the 3-year cycle), narrower scope.
+- **Recertification audit** — year 3, full re-audit. The agent's annual aggregation feeds this directly.
+
+The agent does NOT perform any of these audits. It produces the evidence pack the customer + their accredited certification body work from.
+
+## Crosswalks to other frameworks
+
+ISO 42001 pairs deeply with:
+
+- **NIST AI RMF 1.0** — the named affirmative-defence pair in the Colorado AI Act (effective Feb 2026). NIST AI RMF's four functions (GOVERN / MAP / MEASURE / MANAGE) map across ISO 42001's Annex A categories: GOVERN ↔ A.2 + A.3; MAP ↔ A.5 + A.6.1; MEASURE ↔ A.6.2.4 + A.6.2.7; MANAGE ↔ Clause 8.3 + A.6.2.6 + A.10.
+- **ISO/IEC 27001:2022** — the ISMS standard. Same Annex SL spine (Clauses 4-10 + management-review + nonconformity structure). Security-relevant Annex A controls overlap heavily (ISO 27001 A.5.23 cloud services, A.8.16 monitoring, A.8.28 secure coding all crosswalk to ISO 42001 A.6.2.4 + A.6.2.7).
+- **ISO 31000** — general risk-management guidance. ISO 42001 Clause 6.1.2 references ISO 31000 methodology directly.
+- **ISO/IEC 23894** — AI risk-management guidance. ISO 42001 Clause 6.1.2 + ISO/IEC 23894 form the most natural risk-assessment methodology pair.
+- **EU AI Act** — Art. 9 (risk-management system) is largely satisfied by an ISO 42001 AIMS; Art. 10 (data + data governance) maps to Annex A.7; Art. 13 (transparency) to A.8; Art. 14 (human oversight) to A.9 + Clause 5.3; Art. 15 (accuracy + robustness + cybersecurity) to A.6.2.4 + A.6.2.7. CE-mark conformity-assessment evidence pulls from the AIMS evidence base.
+- **Colorado AI Act** (effective February 2026) — names ISO 42001 + NIST AI RMF as the affirmative-defence pair for "developers" + "deployers" of high-risk AI systems.
+
+When a cross-pack agent exists in the same org, this agent COORDINATES (does not duplicate). The Connexum dashboard cross-pack rollup view de-duplicates findings that span multiple packs.
+`;
+}
+// ---------------------------------------------------------------------------
+// File 3 — iso-42001-heartbeat.md skill (load-bearing cycle)
+// ---------------------------------------------------------------------------
+function buildHeartbeatSkill(input) {
+    return `# ISO/IEC 42001:2023 AIMS Compliance Agent — Heartbeat Cycle
+
+> Loaded at startup by ${input.agentId}.
+> The load-bearing every-cycle checklist. The agent runs this loop on each invocation; cadence (monthly / quarterly / annual / ad-hoc) is determined at step 2.
+
+## 14-step cycle
+
+| # | Step | Tool / Action | Failure mode |
+|---|------|---------------|--------------|
+| 1 | Load startup files (SOUL, BOUNDARIES, this skill, pack skill, reporting skill, broker skill, GOVERNANCE.md) | Read | Missing file → emit \`STARTUP_FILE_MISSING\` and exit cycle |
+| 2 | Determine target cadence | Date arithmetic vs lastRunAt | None — defaults to most-overdue cadence |
+| 3 | Fetch active DataAccessManifest for the target scope | Bash \`compliance-agent broker-status\` | Manifest \`state ≠ active\` → emit \`MANIFEST_OFFLINE\`, exit cycle |
+| 4 | Execute cadence-specific reads (monthly = Clause 9.1 + Annex A.6 lifecycle telemetry; quarterly = AI risk register + treatment plan + impact-assessment register + management-review minutes + codebase A.6.2.4 + A.10.3 scan; annual = aggregate prior cycles + full Annex A control evidence + documented-information register) | Bash \`compliance-agent read --manifest <id> --query <q>\` | \`QueryNotAllowedError\` → \`QUERY_REJECTED\` audit, exit |
+| 5 | Verify redaction by spot-checking 3 random rows against the secret/PII/credential classifier | Local regex | Any hit → \`BROKER_REDACTION_FAILURE\` CRITICAL, exit |
+| 6 | Compose report sections (see \`iso-42001-reporting.md\`) | Sonnet | Composition error → retry once with Haiku, then \`COMPOSITION_FAILURE\` |
+| 7 | Roll up findings CRITICAL → HIGH → MEDIUM → LOW (major-nonconformity candidates per Clause 10.1 + missing AI System Impact Assessments on registered AI systems ALWAYS CRITICAL) | Local sort | None |
+| 8 | Sign the report envelope with org's Ed25519 key | Bash \`compliance-agent sign --envelope <file>\` | Key missing → \`SIGNING_KEY_MISSING\` CRITICAL, exit |
+| 9 | Write \`COMPLIANCE_AGENT_REPORT_EMITTED\` audit-chain entry (BEFORE local write — WAL pattern) | Bash \`compliance-agent emit-audit\` | Network failure → queue locally, mark agent SUSPENDED if 3 consecutive fails |
+| 10 | Persist signed envelope + signature to \`./.connexum/compliance-agent/${input.agentId}/reports/<runId>/\` | Bash \`compliance-agent persist\` | Local write failure → audit entry already emitted; flag \`LOCAL_PERSIST_FAILURE\` next cycle |
+| 11 | Update \`lastRunAt\` in local state | Bash \`compliance-agent update-state\` | None — next cycle re-derives |
+| 12 | Heartbeat the gov-server (\`POST /api/v1/agents/:agentId/heartbeat\`) | Bash \`compliance-agent heartbeat\` | 401/403 → license expired/revoked, exit \`DEACTIVATED\` |
+| 13 | Append cycle summary to local log | Local write | None |
+| 14 | Exit cleanly | None | None |
+
+## Cadence resolution
+
+\`\`\`
+monthly:   fires 1st of each month UTC if lastMonthlyRunAt > 28 days
+  — Clause 9.1 monitoring snapshot, Annex A.6 lifecycle telemetry rollup,
+    AI system inventory drift check
+
+quarterly: fires Jan 1 / Apr 1 / Jul 1 / Oct 1 UTC if lastQuarterlyRunAt > 91 days
+  — AI risk register review (Clause 6.1.2), risk-treatment plan refresh
+    (Clause 6.1.3 + Clause 8.3), AI System Impact Assessment register
+    review (Clause 8.4 + Annex A.5), management-review-input prep
+    (Clause 9.3.2), codebase scan against A.6.2.4 + A.10.3
+
+annual:    fires Jan 1 UTC if lastAnnualRunAt > 365 days
+  — full AIMS walkthrough (Clauses 4-10), Annex A control walkthrough
+    (all 38 controls across A.2-A.10), documented-information register
+    review (Clause 7.5), internal-audit programme + nonconformity
+    aggregation (Clauses 9.2 + 10.1 + 10.2), Annex C concern coverage
+    review, certification-audit evidence pack on request
+
+ad-hoc:    fires immediately on receipt of a \`run-now\` signal from the platform
+  — nonconformity candidate (Clause 10.1 — major: AIMS not functioning for
+    a clause / multiple controls; minor: isolated lapse)
+  — certification-audit-prep on request (\`cycle=certification-audit-prep\`)
+  — high-risk-AI-system gap on Colorado AI Act / EU AI Act crosswalk
+\`\`\`
+
+The platform invokes this agent on schedule via the customer's hook configuration; the agent itself does NOT spawn its own cron. See \`.claude/hooks/\` directory for the invocation hook example.
+
+## Cadence-specific reads
+
+### Monthly (Clause 9.1 + Annex A.6 lifecycle telemetry)
+- \`audit-chain\` scope: last 30 days of AI-system lifecycle telemetry (training runs, evaluation runs, deployment events, drift detections, incident reports, retirement events)
+- \`document-store\` scope: current Clause 9.1 monitoring-plan, active Annex A.6 lifecycle plan, current AI system inventory
+
+### Quarterly (Clauses 6.1 + 8.3 + 8.4 + 9.3 + A.5 + A.6.2.4 + A.10.3)
+- \`document-store\` scope: AI risk register, risk-treatment plan, SoA, AI System Impact Assessment register, prior management-review minutes
+- \`codebase\` scope: last 90 days of commits touching AI-system code paths (training pipelines, evaluation harness, deployment manifests, third-party AI dependencies)
+
+### Annual (Clauses 4-10 + Annex A)
+- Aggregates all 12 monthly + 4 quarterly cycles
+- \`document-store\` scope: full documented-information register (Clause 7.5), AIMS scope statement (Clause 4.3), AI policy (Clause 5.2), internal-audit programme + reports (Clause 9.2), nonconformity + corrective-action log (Clause 10.2), Annex C concern coverage
+
+## Locked Invariants honoured
+
+- **Invariant 2** (advisory, never authoritative): every failure mode above EXITS the cycle cleanly. The agent never blocks the customer's other agents. A nonconformity candidate is surfaced as a finding; the Clause 9.2 internal auditor performs the classification.
+- **Invariant 4** (offline-verifiable): the signed envelope verifies using only the org's public key — no platform reachability required.
+- **Invariant 10** (push-receive only): every gov-server call originates from the agent (push); the gov-server never calls into the customer's infrastructure.
+- **Pack-binding-primacy**: every audit-chain entry at steps 5, 9, 12 carries \`packBinding: ['iso_42001', 'tenant:${input.orgId}', 'tier-87']\`.
+`;
+}
+// ---------------------------------------------------------------------------
+// File 4 — iso-42001-reporting.md skill (section composition guide)
+// ---------------------------------------------------------------------------
+function buildReportingSkill(_input) {
+    return `# ISO/IEC 42001:2023 AIMS Compliance Agent — Report Section Composition
+
+> Reference for steps 6-7 of the heartbeat cycle.
+> Each section composes deterministically from redacted broker rows + manifest metadata. No LLM-only sections — every section has an objective rule the Sonnet model applies.
+
+## Six report sections
+
+### 1. AIMS Monitoring Effectiveness Snapshot (monthly) — Clause 9.1 + Annex A.6
+- **Inputs:** \`audit-chain\` scope, last 30 days of AI-system lifecycle telemetry; \`document-store\` scope, the Clause 9.1 monitoring-plan + active AI system inventory
+- **Metric:** per-AI-system lifecycle-stage coverage; deployment-gate failures; drift-event volumes per system; incident dispositions; retirement events
+- **Findings:**
+  - \`HIGH\` if a monitoring source declared in the Clause 9.1 plan produced zero events in the period: "Clause 9.1 monitoring-source dark — coverage gap"
+  - \`HIGH\` if mean-time-to-disposition exceeds the declared SLA per A.6.2.7: "A.6.2.7 monitoring-disposition timeliness breach"
+  - \`MEDIUM\` if drift-event volume on a deployed AI system exceeds 2x trailing-30-day mean without operator acknowledgement
+- **Format:** markdown table per AI system (system_id / lifecycle_stage / declared_purpose / control_mapping / event_count / drift_count / incident_count)
+
+### 2. AI Risk Register + Treatment Status (quarterly) — Clauses 6.1.2 + 6.1.3 + 8.3
+- **Inputs:** \`document-store\` scope, current AI risk register + risk-treatment plan; prior quarter's snapshot for diff
+- **Metric:** count of AI risks by treatment status (treated / accepted / transferred / avoided); count of new AI risks identified this quarter; count of treatment plans overdue; count of residual AI risks pending owner acceptance
+- **Findings:**
+  - \`CRITICAL\` if an AI risk classified HIGH or above is unaccepted + untreated past its treatment-plan due date: "Clause 6.1.3 AI risk-treatment overdue on HIGH risk"
+  - \`HIGH\` on new AI risks identified without an assigned owner: "Clause 6.1.3 AI risk-owner assignment gap"
+  - \`MEDIUM\` on AI risk-assessment methodology drift (parameters / scoring scheme changed without 6.1.2 documentation)
+  - \`MEDIUM\` on Annex C concern coverage gap (named risk objective without an underlying risk-register entry)
+- **Format:** per-risk table (risk_id / category / annex_c_concern / inherent_score / treatment / residual_score / owner / acceptance_status / due_date)
+
+### 3. AI System Impact Assessment Status (quarterly) — Clause 8.4 + Annex A.5
+- **Inputs:** \`document-store\` scope, current AI System Impact Assessment register; AI system inventory
+- **Metric:** per registered AI system: impact-assessment presence + version + sign-off status + last-review-date; coverage of affected-parties analysis; coverage of named Annex C concerns; high-risk classification (Colorado AI Act / EU AI Act crosswalk) recorded
+- **Findings:**
+  - \`CRITICAL\` if a registered + deployed AI system has no AI System Impact Assessment on file: "Clause 8.4 / A.5.2 impact-assessment absent on deployed AI system"
+  - \`HIGH\` if an impact assessment is signed off but has not been re-reviewed in > 12 months: "Clause 8.4 impact-assessment staleness"
+  - \`HIGH\` on impact assessment missing affected-parties analysis or named Annex C concern coverage
+  - \`MEDIUM\` on impact assessment lacking a documented residual-risk acceptance by named owner
+- **Format:** per-AI-system table grouped by lifecycle stage
+
+### 4. Management Review Inputs Prep (quarterly) — Clause 9.3.2
+- **Inputs:** aggregated monthly findings + AI risk-register status + impact-assessment status + internal-audit findings + nonconformity log + Annex C concern coverage
+- **Metric:** the Clause 9.3.2 required inputs (status of actions from previous management reviews / changes in external + internal issues / feedback on AIMS performance / feedback from interested parties / results of AI risk assessment + status of risk-treatment plan / AI system impact-assessment outcomes / opportunities for continual improvement): each input's prep status
+- **Findings:**
+  - \`HIGH\` if any of the Clause 9.3.2 inputs has no prepared data for the upcoming management review
+  - \`MEDIUM\` if action-item closure rate from the prior management review is below 60%
+
+### 5. Annex A Control Walkthrough (annual) — All 38 controls across A.2 through A.10
+- **Inputs:** aggregated 12 months of findings + \`document-store\` scope, full SoA + per-control evidence index
+- **Metric:** per control: status (Implemented / Partially Implemented / Not Applicable / Planned), evidence freshness, owner identification, residual AI risk after control, Annex B implementation-guidance alignment, Annex C concern coverage attribution
+- **Findings:**
+  - \`CRITICAL\` if a HIGH-risk-treating control is "Not Implemented" or "Planned" past its due date: "Annex A high-risk control gap — major-nonconformity candidate"
+  - \`HIGH\` on Partially Implemented controls without a clearly scoped completion plan
+  - \`HIGH\` on A.5 / A.6 controls (impact assessment + lifecycle) without evidence — distinctive ISO 42001 weight
+  - \`MEDIUM\` on controls missing a named owner or last-review > 12 months
+- **Format:** rollup per A.2 / A.3 / A.4 / A.5 / A.6 / A.7 / A.8 / A.9 / A.10 + drill-down per control
+
+### 6. Internal Audit Coverage + Nonconformity Aggregation (annual) — Clause 9.2 + Clause 10.1 + 10.2
+- **Inputs:** \`document-store\` scope, internal-audit programme + reports + nonconformity log + corrective-action register
+- **Metric:** internal-audit coverage of Clauses 4-10 + Annex A (every clause + control audited at least once in the 3-year cycle?); count of open major / minor / observation nonconformities; mean time-to-closure; effectiveness-verification status per closed corrective action
+- **Findings:**
+  - \`CRITICAL\` on any open major nonconformity past its closure-due date: "Clause 10.2 corrective-action overdue on major NC"
+  - \`HIGH\` on internal-audit coverage gap (a clause or control un-audited in the 3-year cycle)
+  - \`HIGH\` on closed corrective actions without effectiveness verification (Clause 10.2.g)
+  - \`MEDIUM\` on minor nonconformity ageing > 90 days without progress
+
+## Composition rules
+
+1. **One section = one renderer call.** Don't bleed data across sections.
+2. **Markdown only.** No HTML, no JSON in section bodies. JSON envelope wraps the markdown.
+3. **Deterministic.** Same input rows produce the same section output. Caller verifies by hash.
+4. **No raw secrets / credentials ever.** Redaction is guaranteed by the broker; this rule is the agent's belt-and-braces check.
+5. **Each section header MUST cite the relevant Clause and/or Annex A control(s)** (e.g., "## 5. Annex A Control Walkthrough (A.2 / A.3 / A.4 / A.5 / A.6 / A.7 / A.8 / A.9 / A.10)") so the Internal Auditor can index findings against the AIMS evidence base without re-reading bodies.
+6. **Copy the SoA \`version\` + \`updatedAt\` into the report header** so the auditor can verify findings were evaluated against the version they're certifying.
+7. **Each finding MUST carry crosswalk citations when applicable** (NIST AI RMF function + subcategory, ISO 27001 Annex A controls, ISO/IEC 23894 sections, EU AI Act articles, Colorado AI Act sections) so cross-pack reporting works.
+
+## Helper utilities (if installed)
+
+If \`@connexum/ai-governance\` is installed and \`SECTION_RENDERER_REGISTRY\` is available, prefer:
+
+\`\`\`bash
+node -e "
+import('@connexum/ai-governance').then(({ buildComplianceReport }) => {
+  const envelope = buildComplianceReport({
+    packId: 'iso_42001',
+    orgId: '<orgId>',
+    agentId: '<agentId>',
+    runId: '<runId>',
+    cadence: 'quarterly',
+    generatedAt: new Date().toISOString(),
+    sections: [
+      // monthly:
+      // { sectionId: 'aims-monitoring', rendererId: 'iso-42001-clause-9-1-snapshot' },
+      // quarterly:
+      { sectionId: 'ai-risk-register', rendererId: 'iso-42001-risk-register-status' },
+      { sectionId: 'impact-assessment-status', rendererId: 'iso-42001-clause-8-4-impact-assessment' },
+      { sectionId: 'management-review-prep', rendererId: 'iso-42001-clause-9-3-2-inputs' },
+      // annual only:
+      // { sectionId: 'annex-a-walkthrough', rendererId: 'iso-42001-annex-a-walkthrough' },
+      // { sectionId: 'internal-audit-aggregation', rendererId: 'iso-42001-clause-9-2-and-10-rollup' },
+    ],
+    redactedRows: <rows from broker>,
+    manifestMetadata: <metadata from broker>,
+  });
+  process.stdout.write(JSON.stringify(envelope));
+});
+"
+\`\`\`
+
+The deterministic renderers in the package emit byte-identical output for the same input — internal-auditor-friendly. If the package is unavailable, the agent composes sections via Sonnet using the rules above.
+`;
+}
+// ---------------------------------------------------------------------------
+// File 5 — data-broker-usage.md skill (pack-agnostic, but customised per agent)
+// ---------------------------------------------------------------------------
+function buildBrokerSkill(input) {
+    const govUrl = input.govServerUrl ?? 'https://gov.connexum.io';
+    return `# Data Access Broker — Usage Guide
+
+> Loaded at startup by ${input.agentId}.
+> The broker is the ONLY path the agent uses to read customer data. Bypassing the broker = absolute boundary violation.
+
+## Broker contract
+
+\`\`\`
+compliance-agent read \\
+  --agent-id ${input.agentId} \\
+  --manifest <manifestId> \\
+  --query <query string from manifest.allowedQueries> \\
+  --params '<JSON array>'
+\`\`\`
+
+Returns:
+\`\`\`json
+{
+  "rows": [...],
+  "redactionStats": {
+    "totalCells": <int>,
+    "redactedCells": <int>
+  },
+  "manifestMetadata": {
+    "scopeKind": "audit-chain|codebase|document-store|...",
+    "scopeName": "<friendly name>"
+  },
+  "durationMs": <int>
+}
+\`\`\`
+
+## Boot sequence (executed by \`compliance-agent read\`)
+
+1. Fetch manifest from \`${govUrl}/api/v1/agents/${input.agentId}/data-manifests/<manifestId>\` (license-key bearer auth)
+2. Verify \`state=active\` (draft / revoked = \`BROKER_OFFLINE\`)
+3. Validate query against \`manifest.allowedQueries\` (exact string match — partial = \`QueryNotAllowedError\`)
+4. Resolve credential from \`manifest.credentialRef\` (\`env:NAME\` or \`keyvault:scope\`; inline rejected)
+5. Execute via the registered \`DataAdapterFactory\` for \`scopeKind\`
+6. Apply redaction per \`manifest.redactionPolicy.{piiClasses, columnDenyList}\`
+7. Emit \`AGENT_DATA_READ\` audit-event to \`${govUrl}/api/v1/agents/${input.agentId}/audit-events\` with structured metadata only (NEVER raw rows)
+8. Return redacted rows + stats to the agent
+
+## Failure modes
+
+| Error class | When | Agent action |
+|---|---|---|
+| \`BrokerOfflineError\` | Manifest not active OR network failure | Exit cycle. Mark cadence as deferred. |
+| \`QueryNotAllowedError\` | Query not in allowed-list | Audit \`QUERY_REJECTED\`. Continue cycle without this section. |
+| \`CredentialNotFoundError\` | env var or keyvault key absent | Emit \`MANIFEST_MISCONFIGURED\`. Notify ORG_ADMIN via dashboard. Exit cycle. |
+| \`LicenseInvalidError\` | License expired or revoked | Exit with code 1. Agent \`DEACTIVATED\`. Tier 4 to re-enable. |
+
+## Invariants the broker enforces
+
+- **Invariant 10** (push-receive only): all gov-server calls originate from the broker (customer side). The gov-server never opens an outbound connection to customer infrastructure.
+- **Invariant 1** (manifest fetch failure → BrokerOfflineError): the broker NEVER falls back to executing without a manifest. No silent permissive failure.
+- **Invariant 7** (redaction is not optional): if \`redactionPolicy\` is absent, the broker rejects the manifest at activation (\`MANIFEST_MISCONFIGURED\`).
+
+## Active manifests for this agent
+
+Manifest IDs the agent should expect to find (added by ORG_ADMIN via dashboard):
+
+- ISO 42001 monthly (Clause 9.1 + Annex A.6 telemetry): scope \`audit-chain\` with EMAIL+SECRET redaction (training runs, evaluation runs, deployment events, drift detections, incident reports, retirement events)
+- ISO 42001 quarterly (AI risk register + treatment plan + impact assessment): scope \`document-store\` with PII+SECRET redaction (AI risk register + treatment plan + AI System Impact Assessment register + management-review minutes)
+- ISO 42001 quarterly (codebase scan): scope \`codebase\` with secret-scanner redaction (training pipelines, evaluation harness, deployment manifests, third-party AI dependencies — A.6.2.4 + A.10.3 evidence)
+- ISO 42001 annual (full AIMS): scope \`document-store\` with PII+SECRET redaction (documented-information register, AIMS scope statement, AI policy, internal-audit programme + reports, nonconformity log, Annex C concern coverage)
+
+If a manifest is missing at run time, the agent flags it as \`MANIFEST_MISSING\` and continues with the cadences whose manifests ARE present (degraded operation per Invariant 2).
+`;
+}
+// ---------------------------------------------------------------------------
+// File 6 — shared connexum-governance.md (org-wide; copied if not present)
+// ---------------------------------------------------------------------------
+function buildSharedGovernance(_input) {
+    return `# Connexum Governance — Shared Skill
+
+> Loaded at startup by every Connexum compliance agent in this project.
+> Defines pack-binding-primacy + 10 Locked Architectural Invariants.
+
+## Pack-binding-primacy
+
+Every catalogued / stored record carries a mandatory \`packBinding: string[]\` naming the compliance packs that govern it. Retention, approval, reviewer tier, sovereignty, report scoping ALL derive from the binding. Empty binding throws \`UnboundDataError\`. Un-binding before retention window elapses is refused.
+
+For Tier 8.7 compliance agents, every emitted audit-chain entry carries \`packBinding: [<packId>, 'tenant:<orgId>', 'tier-87']\` at minimum.
+
+## 10 Locked Architectural Invariants
+
+1. **Self-sovereign passport issuance** — the platform is the passport authority. No external partnership required.
+2. **Advisory, never authoritative** — the platform is NEVER in the synchronous critical path of any agent. Failures degrade gracefully.
+3. **Graceful degradation by default in the SDK** — 100ms timeout on trust queries; never throw.
+4. **Offline-verifiable passports** — verifiable using cached org public keys. Platform reachability not required.
+5. **Unknown-passport returns structured response, not 404** — \`status: "unknown"\` + org reputation fallback.
+6. **Credit-agency data visibility model** — own data in full; cross-org view limited to \`PublicAgentView\`.
+7. **Row-level security at the database** — every multi-tenant table has a Postgres RLS policy. Defence-in-depth.
+8. **Three-tier API key hierarchy** — \`PLATFORM_KEY > PARTNER_KEY > ORG_KEY\`. Absolute cross-tier isolation.
+9. **External identity bound, never replaced** — Okta/IAM identities become first-class claims INSIDE the passport.
+10. **Push-receive only** — data flows from customer TO platform, never the other way. No scanning, no polling, no blocking of customer infrastructure.
+
+## Agent self-check (executed at startup)
+
+1. Verify SOUL block in primary agent MD is intact + chmod 0444
+2. Verify BOUNDARIES block in primary agent MD is intact + chmod 0444
+3. Verify this file is intact + chmod 0444
+4. Verify org public key is cached locally at \`./.connexum/compliance-agent/<agentId>/keys/org-public.pem\`
+5. Verify Ed25519 signing key is present at \`./.connexum/compliance-agent/<agentId>/keys/signing-private.pem\`
+
+If any check fails, the agent emits \`GOVERNANCE_INTEGRITY_FAILURE\` and refuses to run until Tier 4 intervention.
+`;
+}
+// ---------------------------------------------------------------------------
+// File 7 — GOVERNANCE.md at project root (customer-specific config)
+// ---------------------------------------------------------------------------
+function buildGovernanceConfig(input) {
+    const govUrl = input.govServerUrl ?? 'https://gov.connexum.io';
+    return `# GOVERNANCE.md
+
+> Generated at agent spawn. Customer-specific configuration for the Connexum compliance agent runtime.
+> This file is COMMITTED to the customer's repo. It contains NO secrets.
+
+## Agent
+
+| Field | Value |
+|-------|-------|
+| Agent ID | ${input.agentId} |
+| Pack | iso_42001 |
+| Tier | 8.7 |
+| Org ID | ${input.orgId} |
+| Location | ${input.location} |
+| Department | ${input.department} |
+| Gov-server URL | ${govUrl} |
+
+## Secrets (NOT committed)
+
+The agent expects two files outside source control:
+
+- \`./.connexum/compliance-agent/${input.agentId}/.license\` — license key issued at spawn (mode 0600)
+- \`./.connexum/compliance-agent/${input.agentId}/keys/signing-private.pem\` — Ed25519 signing key for report envelopes (mode 0600)
+
+Both are created by \`compliance-agent init <licenseKey>\` (first-run setup; see README in the tarball).
+
+## First-run setup
+
+\`\`\`bash
+# 1. Install the runtime
+npm install -g @connexum/compliance-agent-runtime
+
+# 2. Initialise the agent
+compliance-agent init ${input.licenseKey}
+
+# 3. Verify status
+compliance-agent status ${input.agentId}
+
+# 4. Run a manual cycle (optional, for verification)
+compliance-agent run-once ${input.agentId}
+\`\`\`
+
+## Scheduled invocation
+
+The Connexum platform invokes this agent on its declared cadences (monthly / quarterly / annual). If you want local cron-based invocation as well, add to your crontab:
+
+\`\`\`cron
+0 0 1 * *   compliance-agent run-once ${input.agentId}    # monthly (Clause 9.1 + Annex A.6 lifecycle telemetry)
+0 0 1 */3 * compliance-agent run-once ${input.agentId}    # quarterly (AI risk register + treatment plan + impact assessment + management-review prep)
+0 0 1 1 *   compliance-agent run-once ${input.agentId}    # annual (full AIMS + Annex A walkthrough + audit-prep)
+\`\`\`
+
+The platform invocation and the local cron are idempotent — the same \`runId\` will not double-emit.
+
+## Clause + Annex A cross-reference
+
+This agent's reports cite the following ISO/IEC 42001:2023 clauses + Annex A controls. Internal Auditors can use this map to index findings:
+
+| Section | Clauses + Controls |
+|---------|---------|
+| AIMS Monitoring Effectiveness Snapshot | Clause 9.1, Annex A.6 (especially A.6.2.7 operation + monitoring) |
+| AI Risk Register + Treatment Status | Clause 6.1.2, Clause 6.1.3, Clause 8.3 |
+| AI System Impact Assessment Status | Clause 8.4, Annex A.5 (Assessing impacts of AI systems) |
+| Management Review Inputs Prep | Clause 9.3.2 |
+| Annex A Control Walkthrough | A.2 (Policies, 2), A.3 (Internal organisation, 3), A.4 (Resources, 6), A.5 (Impact assessment, 3), A.6 (Lifecycle, 10), A.7 (Data, 4), A.8 (Information for interested parties, 3), A.9 (Use, 2), A.10 (Third-party + customer, 5) — 38 controls total |
+| Internal Audit Coverage + Nonconformity Aggregation | Clause 9.2, Clause 10.1, Clause 10.2 |
+
+## Annex C concern registration
+
+To enable Annex C concern-coverage reporting, list the AI-related concerns the org has named as risk objectives in its AIMS scope (per Annex C):
+
+\`\`\`yaml
+annex_c_concerns:
+  - fairness
+  - transparency
+  - explainability
+  - accountability
+  - privacy
+  - safety
+  - security
+  - robustness
+  - sustainability
+  - harm-prevention
+\`\`\`
+
+Findings will be annotated with the relevant concern(s) where the org has named them.
+
+## Crosswalks (cited on findings where applicable)
+
+- ISO/IEC 27001:2022 (ISMS — Annex SL sibling; security-relevant overlap)
+- NIST AI Risk Management Framework 1.0 (named affirmative-defence pair under the Colorado AI Act)
+- ISO 31000 (general risk management — referenced by Clause 6.1.2)
+- ISO/IEC 23894 (AI risk-management guidance — operational companion to Clause 6.1.2)
+- EU AI Act (Art. 9 risk-management system / Art. 10 data + governance / Art. 13 transparency / Art. 14 human oversight / Art. 15 accuracy + robustness + cybersecurity)
+- Colorado AI Act (effective February 2026 — ISO 42001 + NIST AI RMF are the affirmative-defence pair)
+
+## Locked Invariants
+
+This agent honours all 10 Connexum Locked Architectural Invariants (see \`.claude/skills/_shared/connexum-governance.md\`). The most operationally relevant for hosts:
+
+- **Invariant 2:** the agent NEVER blocks your other tooling. A failed cycle exits cleanly; the next cycle proceeds.
+- **Invariant 10:** all calls originate from this agent. The Connexum gov-server NEVER initiates a connection to your infrastructure.
+
+## Support
+
+- Status: \`compliance-agent status ${input.agentId}\`
+- Logs: \`./.connexum/compliance-agent/${input.agentId}/logs/\`
+- Reports: \`./.connexum/compliance-agent/${input.agentId}/reports/\`
+- Dashboard: ${govUrl.replace(/^https?:\/\/gov\./, 'https://dashboard.')}/agents/compliance/${input.agentId}
+`;
+}
+// ---------------------------------------------------------------------------
+// Generator entry point
+// ---------------------------------------------------------------------------
+const generate = (input) => {
+    const identifier = `iso-42001-compliance-agent-${input.location}-${input.department}`;
+    const bundle = [
+        {
+            path: `.claude/agents/${identifier}.md`,
+            content: buildAgentMd(input),
+            mode: 0o444,
+        },
+        {
+            path: '.claude/skills/compliance/iso-42001-pack.md',
+            content: buildPackSkill(input),
+            mode: 0o644,
+        },
+        {
+            path: '.claude/skills/compliance/iso-42001-heartbeat.md',
+            content: buildHeartbeatSkill(input),
+            mode: 0o644,
+        },
+        {
+            path: '.claude/skills/compliance/iso-42001-reporting.md',
+            content: buildReportingSkill(input),
+            mode: 0o644,
+        },
+        {
+            path: '.claude/skills/compliance/data-broker-usage.md',
+            content: buildBrokerSkill(input),
+            mode: 0o644,
+        },
+        {
+            path: '.claude/skills/_shared/connexum-governance.md',
+            content: buildSharedGovernance(input),
+            mode: 0o444,
+        },
+        {
+            path: 'GOVERNANCE.md',
+            content: buildGovernanceConfig(input),
+            mode: 0o644,
+        },
+    ];
+    return bundle;
+};
+exports.generate = generate;
+//# sourceMappingURL=iso42001.js.map