arckit-cli 6.1.1__py3-none-any.whl

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/security-hooks.md

@@ -0,0 +1,200 @@
+# Security Hooks Guide
+
+> **Guide Origin**: Official | **ArcKit Version**: [VERSION]
+
+ArcKit includes three security hooks that provide layered protection against accidental secret exposure during Claude Code sessions. These hooks run automatically and require no manual configuration.
+
+## Three-Layer Protection Model
+
+The security hooks implement defence in depth with three complementary layers:
+
+| Layer | Hook | Hook Type | Trigger | Purpose |
+|-------|------|-----------|---------|---------|
+| 1 | `secret-detection.py` | UserPromptSubmit | Every user message | Catches secrets pasted into prompts |
+| 2 | `file-protection.py` | PreToolUse (Edit\|Write) | File edit/write operations | Blocks writes to sensitive file paths |
+| 3 | `secret-file-scanner.py` | PreToolUse (Edit\|Write) | File edit/write operations | Scans content being written for embedded secrets |
+
+### How the layers work together
+
+1. **Layer 1 — Prompt scanning**: Before your message reaches the model, `secret-detection.py` scans the prompt text for known secret patterns (API keys, tokens, passwords, connection strings). If a secret is detected, the message is blocked before it is sent.
+
+2. **Layer 2 — Path protection**: When Claude attempts to edit or write a file, `file-protection.py` checks whether the target file path is sensitive (environment files, credential stores, private keys, lock files). Protected files are blocked regardless of content.
+
+3. **Layer 3 — Content scanning**: For files that pass the path check, `secret-file-scanner.py` examines the actual content being written for secret patterns. This catches cases where a secret is embedded in an otherwise safe file path.
+
+## What Each Hook Detects
+
+### secret-detection.py (Prompt Scanner)
+
+Scans user prompts for:
+
+- **Key-value secrets**: `pwd=`, `api_key=`, `auth_token=`, `api_secret=`
+- **Provider-specific tokens**: OpenAI (`sk-`), Anthropic (`sk-ant-`), GitHub (`ghp_`, `gho_`, `ghs_`), AWS (`AKIA`), Notion (`ntn_`), Atlassian (`ATATT`), Slack (`xox`), Google (`AIza`)
+- **Bearer tokens**: `bearer <value>`
+- **Connection strings**: `mongodb://`, `postgres://`, `mysql://`, `redis://` with credentials
+- **PEM private keys**: `-----BEGIN ... KEY-----` headers
+- **High-entropy credentials**: Long base64-like strings assigned to key/secret variables
+
+**Example block:**
+
+```text
+$ echo '{"userPrompt": "Use this key sk-ant-abc123def456ghi789"}' \
+    | python3 plugins/arckit-claude/hooks/secret-detection.py
+# Output: {"decision": "block", "reason": "Warning: Potential secrets detected: ..."}
+```
+
+### file-protection.py (Path Guard)
+
+Blocks writes to:
+
+- **Environment files**: `.env`, `.env.local`, `.env.production`, `.env.development`
+- **Lock files**: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Gemfile.lock`, `poetry.lock`, `Cargo.lock`
+- **Version control**: `.git/`
+- **Credential directories**: `.aws/`, `.ssh/`, `.gnupg/`
+- **Secret files**: `credentials`, `credentials.json`, `secrets.json`, `secrets.yaml`, `secrets.yml`, `.secrets`
+- **Private keys**: `*.pem`, `*.key`, `*.p12`, `*.pfx`, `id_rsa`, `id_ed25519`, `id_ecdsa`
+- **Auth config files**: `.npmrc`, `.pypirc`, `.netrc`
+- **Files with sensitive keywords**: filenames containing terms like "credential", "api-key", etc.
+
+**Example block:**
+
+```text
+$ echo '{"tool_name": "Write", "tool_input": {"file_path": ".env", "content": "DB_HOST=localhost"}}' \
+    | python3 plugins/arckit-claude/hooks/file-protection.py
+# Output: {"decision": "block", "reason": "Protected: Protected file: .env\nFile: .env\n..."}
+```
+
+### secret-file-scanner.py (Content Scanner)
+
+Scans the content of files being written or edited using the same pattern library as `secret-detection.py`. This catches secrets that might be embedded in source code, configuration files, or documentation.
+
+**Example block:**
+
+```text
+$ echo '{"tool_name": "Write", "tool_input": {"file_path": "config.py", "content": "db_host=localhost"}}' \
+    | python3 plugins/arckit-claude/hooks/secret-file-scanner.py
+# Output: no output (safe content passes through)
+```
+
+## Adding Exceptions
+
+### File protection exceptions
+
+To allow edits to files that would normally be blocked by `file-protection.py`, you have three options:
+
+**1. Add to `ALLOWED_EXCEPTIONS`** — for specific filenames that are legitimate security tools:
+
+```python
+ALLOWED_EXCEPTIONS = [
+    ".secrets.baseline",
+    ".pre-commit-config.yaml",
+    "secret-detection.py",
+    "secret-file-scanner.py",
+    "your-new-exception.py",  # Add here
+]
+```
+
+**2. Add to `ALLOWED_DIRECTORIES`** — for directories containing documentation or tool files that discuss secrets:
+
+```python
+ALLOWED_DIRECTORIES = [
+    "plugins/arckit-claude/commands/",
+    "plugins/arckit-claude/templates/",
+    "plugins/arckit-claude/agents/",
+    "plugins/arckit-claude/hooks/",
+    "docs/",
+    ".arckit/templates/",
+    "your-project/docs/",  # Add here
+]
+```
+
+### Content scanner skip patterns
+
+To prevent `secret-file-scanner.py` from scanning certain files (e.g., documentation that legitimately discusses secret formats), add a regex to `SKIP_PATTERNS`:
+
+```python
+SKIP_PATTERNS = [
+    r"\.pre-commit-config\.yaml$",
+    r"secret-detection\.py$",
+    r"secret-file-scanner\.py$",
+    r"file-protection\.py$",
+    r"\.secrets\.baseline$",
+    r"plugins/arckit-claude/commands/.*\.md$",
+    r"plugins/arckit-claude/templates/.*\.md$",
+    r"docs/.*\.md$",
+    r"CHANGELOG\.md$",
+    r"README\.md$",
+    r"your-custom-pattern\.md$",  # Add here
+]
+```
+
+## Restricting web access for research agents
+
+ArcKit's web-research agents (`research`, `datascout`, `aws-research`, `azure-research`, `gcp-research`, `gov-*`, `grants`) use `WebFetch`. For a regulated or OFFICIAL-SENSITIVE deployment you may want to confine that traffic to an approved set of domains. As of Claude Code v2.1.162, explicit `WebFetch(domain:...)` permission rules **take precedence over the built-in preapproved-host auto-allow** (previously the preapproved hosts leaked through), so a deny/allow policy now actually holds.
+
+Add rules to `.claude/settings.json` (or org managed settings for fleet-wide enforcement — see [Fleet & Version Governance](enterprise-scale.md#fleet--version-governance-managed-settings)):
+
+```json
+{
+  "permissions": {
+    "deny": ["WebFetch"],
+    "allow": [
+      "WebFetch(domain:*.gov.uk)",
+      "WebFetch(domain:*.service.gov.uk)",
+      "WebFetch(domain:docs.aws.amazon.com)"
+    ]
+  }
+}
+```
+
+This is a Claude Code permission policy, not an ArcKit hook — ArcKit ships no domain restrictions by default, leaving the choice to the deployment.
+
+## Testing
+
+You can test each hook by piping JSON to stdin. All hooks handle empty input gracefully.
+
+### Test file protection blocks .env writes
+
+```bash
+echo '{"tool_name": "Write", "tool_input": {"file_path": ".env", "content": "VALUE=abc"}}' \
+    | python3 plugins/arckit-claude/hooks/file-protection.py
+```
+
+Expected: `{"decision": "block", ...}`
+
+### Test secret detection blocks API keys in prompts
+
+```bash
+echo '{"userPrompt": "Use this key sk-ant-abc123def456ghi789"}' \
+    | python3 plugins/arckit-claude/hooks/secret-detection.py
+```
+
+Expected: `{"decision": "block", ...}`
+
+### Test secret file scanner blocks secrets in content
+
+```bash
+echo '{"tool_name": "Write", "tool_input": {"file_path": "test.md", "content": "pwd=hunter2"}}' \
+    | python3 plugins/arckit-claude/hooks/secret-file-scanner.py
+```
+
+Expected: `{"decision": "block", ...}`
+
+### Test that allowed files pass through
+
+```bash
+echo '{"tool_name": "Write", "tool_input": {"file_path": "plugins/arckit-claude/commands/research.md", "content": "Use API key format: sk-xxx"}}' \
+    | python3 plugins/arckit-claude/hooks/secret-file-scanner.py
+```
+
+Expected: no output (exit code 0, file is in a skip pattern)
+
+### Test that empty input does not crash
+
+```bash
+echo '' | python3 plugins/arckit-claude/hooks/file-protection.py
+echo '' | python3 plugins/arckit-claude/hooks/secret-detection.py
+echo '' | python3 plugins/arckit-claude/hooks/secret-file-scanner.py
+```
+
+Expected: no output or `{}` (exit code 0 for all)

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/security.md

@@ -0,0 +1,62 @@
+# G-Cloud Security Assertions Guide
+
+> **Guide Origin**: Community | **ArcKit Version**: [VERSION]
+
+`/arckit:security` generates NCSC Cloud Security Principles assertions and evidence for a G-Cloud
+service. It links the service design, SDD, and supplier profile to security controls, evidence,
+residual risks, and buyer-facing security statements.
+
+---
+
+## Command
+
+```bash
+/arckit:security <service project or service name>
+```
+
+Output:
+
+```text
+projects/<NNN>-<service-name>/ARC-<NNN>-SECA-v1.0.md
+```
+
+---
+
+## When to Use
+
+- After the service design and SDD are drafted.
+- Before pricing and review, so security claims are evidence-backed.
+- When a buyer will ask for data protection, access control, encryption, monitoring, incident,
+  resilience, or supply-chain evidence.
+- When ISO, Cyber Essentials, penetration test, or hosting-location evidence must be tied to the
+  service.
+
+---
+
+## Inputs
+
+| Input | Purpose |
+|-------|---------|
+| Supplier profile (`SUPP`) | Shared certifications, data centres, insurance, and contacts |
+| Service design (`SVCD`) | Service scope and architecture assumptions |
+| Service Definition Document (`SDD`) | Buyer-facing claims to validate |
+| Security evidence | Certificates, policies, pen-test summaries, diagrams, and control records |
+
+---
+
+## Review Checklist
+
+- Assertions are mapped to the NCSC Cloud Security Principles.
+- Each material security claim has a source or an explicit evidence gap.
+- Data location, access control, encryption, backup, incident, and monitoring statements align with
+  the SDD.
+- Residual risks are visible and can be fed into `/arckit:risk`.
+- Sensitive evidence is referenced appropriately rather than pasted into public documents.
+
+---
+
+## Related Commands
+
+- `/arckit:secure` - General secure-by-design assessment.
+- `/arckit:dfd` - Data flow and trust-boundary analysis.
+- `/arckit:review` - Final G-Cloud readiness check.

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/service-assessment.md

@@ -0,0 +1,47 @@
+# GDS Service Assessment Guide
+
+> **Guide Origin**: Official | **ArcKit Version**: [VERSION]
+
+`/arckit:service-assessment` packages evidence for Discovery→Alpha, Alpha→Beta, and Beta→Live assessments against the 14-point Service Standard.
+
+---
+
+## Command
+
+```bash
+/arckit:service-assessment PHASE=<alpha|beta|live> DATE=<YYYY-MM-DD optional>
+```
+
+Output: `projects/<id>/ARC-<id>-SVCASS-v1.0.md`.
+
+---
+
+## Evidence Mapping (Summary)
+
+| Service Standard Area | ArcKit Sources | Notes |
+|-----------------------|----------------|-------|
+| Understand users & solve the whole problem (Points 1–3) | Stakeholder analysis, requirements, Wardley Maps | Ensure latest research notes attached |
+| Simple, accessible service (Points 4–5) | Requirements (WCAG), `/arckit:secure` outputs, journey maps | Include accessibility testing evidence |
+| Team & delivery approach (Points 6–8) | Project plan, backlog, retrospectives, vendor governance | Highlight multidisciplinary team and agile cadence |
+| Security, privacy, performance (Points 9–10,14) | `/arckit:secure`, `/arckit:dpia`, `/arckit:servicenow`, NFRs | Provide incident response and monitoring plans |
+| Technology & openness (Points 11–13) | `/arckit:research`, `/arckit:tcop`, design reviews, repos | Reference open-source/code-reuse commitments |
+
+---
+
+## Prep Checklist
+
+- Evidence heatmap reviewed; gaps assigned owners.
+- Show-and-tell deck created (use summary of prep doc).
+- Service metrics dashboard ready (alpha/beta) or plan to publish (live).
+- Accessibility and security testing signed off.
+- Service manual guidance referenced for each point.
+- Assessment logistics: presenter list, dry run scheduled, Q&A roles agreed.
+
+---
+
+## Assessment Day Tips
+
+- Keep walkthrough to 30 minutes; leave 90+ minutes for Q&A.
+- Use real artefacts (screenshots, repo links) rather than talking points.
+- Note assessor actions live and add to backlog within 24 hours.
+- Update the prep doc with outcomes (Green/Amber/Red, conditions, owners).

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/service-design.md

@@ -0,0 +1,71 @@
+# G-Cloud Service Design Guide
+
+> **Guide Origin**: Community | **ArcKit Version**: [VERSION]
+
+`/arckit:service-design` creates a per-service design document for a UK G-Cloud Digital Marketplace
+offering. In the G-Cloud supplier overlay, each service is its own ArcKit project under
+`projects/<NNN>-<service-name>/`.
+
+---
+
+## Command
+
+```bash
+/arckit:service-design <service name, lot, and context>
+```
+
+Output:
+
+```text
+projects/<NNN>-<service-name>/ARC-<NNN>-SVCD-v1.0.md
+```
+
+---
+
+## When to Use
+
+- To create a new cloud hosting, cloud software, or cloud support service listing.
+- To capture service name, description, lot, buyer segments, features, benefits, onboarding, and
+  support model before drafting the SDD.
+- To ground pricing, security assertions, and competitor review in a single service definition.
+
+---
+
+## Inputs
+
+| Input | Purpose |
+|-------|---------|
+| Service name | Creates or locates the service project |
+| G-Cloud lot | Selects Lot 1, Lot 2, or Lot 3 guidance |
+| Supplier profile | Reuses company, certification, and contact evidence |
+| Service URL or existing listing | Supports citation-backed service facts |
+
+---
+
+## Workflow
+
+1. Run `/arckit:supplier-profile` first when supplier-wide evidence is not yet captured.
+2. Run `/arckit:service-design` for the service name and target lot.
+3. Review the generated `SVCD` document for marketplace limits and claim accuracy.
+4. Generate the relevant SDD with `/arckit:sdd-lot1`, `/arckit:sdd-lot2`, or
+   `/arckit:sdd-lot3`.
+5. Generate pricing and security evidence, then review the submission.
+
+---
+
+## Review Checklist
+
+- The service name and short description fit Digital Marketplace limits.
+- Features and benefits are buyer-focused and evidence-backed.
+- The selected lot matches the service model.
+- Support, onboarding, offboarding, data, security, and pricing assumptions are explicit.
+- The service design is internally consistent with the supplier profile.
+
+---
+
+## Related Commands
+
+- `/arckit:sdd-lot1` - Draft a Lot 1 Service Definition Document.
+- `/arckit:sdd-lot2` - Draft a Lot 2 Service Definition Document.
+- `/arckit:sdd-lot3` - Draft a Lot 3 Service Definition Document.
+- `/arckit:pricing` - Generate the pricing document.

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/servicenow.md

@@ -0,0 +1,152 @@
+# ServiceNow Service Design Playbook
+
+> **Guide Origin**: Official | **ArcKit Version**: [VERSION]
+
+`/arckit:servicenow` creates a comprehensive ServiceNow service design covering CMDB, SLAs, incident management, change control, and ITSM integration.
+
+---
+
+## Inputs
+
+| Artefact | Purpose |
+|----------|---------|
+| Requirements (`ARC-<id>-REQ-v1.0.md`) | SLA targets from NFRs |
+| Architecture diagrams | Components for CMDB population |
+| Operational readiness | Support model and escalation paths |
+| Stakeholder drivers | Business criticality and service expectations |
+
+---
+
+## Command
+
+```bash
+/arckit:servicenow Create ServiceNow service design for <service>
+```
+
+Output: `projects/<id>/ARC-<id>-SNOW-v1.0.md`
+
+---
+
+## Service Design Structure
+
+| Section | Contents |
+|---------|----------|
+| Service Overview | Service definition, criticality, ownership |
+| CMDB Design | CI classes, relationships, discovery, data quality |
+| Service Portfolio | Service catalog entry, request items, bundles |
+| Incident Management | Categories, priorities, SLAs, escalation, major incident |
+| Problem Management | Root cause analysis, known errors, problem review |
+| Change Management | Change types, CAB process, approvals, windows |
+| Service Level Management | SLAs, OLAs, UCs, reporting |
+| Knowledge Management | Article structure, approval workflow, review cycle |
+| Service Request Management | Request catalog, fulfillment workflows, approvals |
+| Asset Management | Hardware/software assets, lifecycle, contracts |
+| Event Management | Alert integration, correlation, auto-remediation |
+| Reporting & Dashboards | KPIs, dashboards, executive reporting |
+| Integration Architecture | External system integrations, APIs, data flows |
+| Automation | Flow Designer, IntegrationHub, auto-assignment |
+| UK Government Considerations | Cross-government ITSM, NCSC alignment |
+
+---
+
+## CMDB CI Classes
+
+| CI Class | Examples | Relationships |
+|----------|----------|---------------|
+| Business Service | "Customer Portal" | Depends on Technical Services |
+| Technical Service | "API Gateway" | Runs on Applications |
+| Application | "Portal Frontend" | Runs on Servers/Containers |
+| Server | "web-server-01" | Hosted on Hardware/Cloud |
+| Database | "PostgreSQL Cluster" | Stores data for Applications |
+| Network Device | "Load Balancer" | Connects to Servers |
+
+---
+
+## Incident Priority Matrix
+
+| Impact / Urgency | High | Medium | Low |
+|------------------|------|--------|-----|
+| **High** | P1 (Critical) | P2 (High) | P3 (Moderate) |
+| **Medium** | P2 (High) | P3 (Moderate) | P4 (Low) |
+| **Low** | P3 (Moderate) | P4 (Low) | P5 (Planning) |
+
+---
+
+## SLA Response/Resolution Targets
+
+| Priority | Response | Resolution | Support Hours |
+|----------|----------|------------|---------------|
+| P1 | 15 minutes | 4 hours | 24/7 |
+| P2 | 30 minutes | 8 hours | 24/7 |
+| P3 | 4 hours | 24 hours | Business hours |
+| P4 | 8 hours | 72 hours | Business hours |
+| P5 | 24 hours | 2 weeks | Business hours |
+
+---
+
+## Change Types
+
+| Change Type | Approval | Lead Time | Example |
+|-------------|----------|-----------|---------|
+| Standard | Pre-approved | Immediate | Password reset, minor config |
+| Normal | CAB | 5 days | New feature deployment |
+| Emergency | Emergency CAB | Immediate | Critical security patch |
+
+---
+
+## One-Page Workflow
+
+| Phase | Key Activities | ArcKit Commands |
+|-------|----------------|-----------------|
+| Discovery | Define service and requirements | `/arckit:requirements`, `/arckit:stakeholders` |
+| Architecture | Design components and dependencies | `/arckit:diagram`, `/arckit:hld-review` |
+| Operations | Create operational readiness | `/arckit:operationalize` |
+| ITSM Design | Create ServiceNow design | `/arckit:servicenow` |
+| Implementation | Configure ServiceNow, populate CMDB | `/arckit:backlog` |
+
+---
+
+## Integration Points
+
+| System | Integration Type | Purpose |
+|--------|------------------|---------|
+| Monitoring (Prometheus, Datadog) | Event Management | Auto-create incidents from alerts |
+| CI/CD (Jenkins, GitHub Actions) | Change Management | Auto-create change records |
+| Cloud Provider (AWS, Azure) | Discovery | Auto-populate CMDB |
+| Identity Provider (Azure AD) | User Management | SSO, group sync |
+| Communication (Slack, Teams) | Notifications | Incident updates, approvals |
+
+---
+
+## Review Checklist
+
+- CMDB design covers all architecture components.
+- CI relationships reflect actual dependencies.
+- SLAs align with NFRs and business expectations.
+- Incident categories match service components.
+- Change management process appropriate for service criticality.
+- Knowledge base structure defined with review cycle.
+- Integrations defined for monitoring, CI/CD, and discovery.
+- Automation opportunities identified (auto-assignment, auto-remediation).
+
+---
+
+## Key Metrics
+
+| Metric | Description | Target |
+|--------|-------------|--------|
+| CMDB Accuracy | % of CIs with correct data | >95% |
+| SLA Achievement | % of incidents meeting SLA | >95% |
+| First Contact Resolution | % resolved at L1 | >70% |
+| Change Success Rate | % of changes without incidents | >95% |
+| MTTR | Mean time to resolve incidents | Trending down |
+
+---
+
+## Key Principles
+
+1. **CMDB as Source of Truth**: All service relationships mapped and maintained.
+2. **ITIL Alignment**: Follow ITIL v4 practices for service management.
+3. **Automation First**: Automate ticket creation, routing, and remediation.
+4. **Continuous Improvement**: Regular service reviews and CSI initiatives.
+5. **Integration**: Connect ServiceNow to monitoring, CI/CD, and cloud platforms.

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/session-memory.md

@@ -0,0 +1,100 @@
+# Session Memory
+
+ArcKit includes automated session capture that records what happened during each Claude Code session. This complements Claude Code's built-in auto-memory by tracking the *actual work done* (git commits, artifact types) rather than relying on what Claude decides to remember.
+
+## How It Works
+
+```text
+Session N ends
+  └── session-learner.mjs (Stop hook) analyses recent git commits
+       └── appends summary to .arckit/memory/sessions.md
+
+Session N+1 starts
+  └── arckit-session.mjs (SessionStart hook) reads sessions.md
+       └── surfaces last 3 sessions as context
+```
+
+The Stop hook fires automatically when a session ends. No configuration needed beyond installing the ArcKit plugin.
+
+## What Gets Captured
+
+Each session entry includes:
+
+- **Session classification** — compliance, governance, research, procurement, architecture, planning, discovery, operations, or general (auto-detected from artifact types)
+- **Commit count and files changed** — quantitative measure of session activity
+- **Artifact types** — which ArcKit document types (ADR, HLDR, WARD, etc.) were created or modified
+- **Commit summaries** — up to 8 commit messages for context
+
+## Session Classification
+
+Sessions are classified by the highest-priority category of artifacts touched:
+
+| Priority | Classification | Triggered by category |
+|---|---|---|
+| 1 | `compliance` | Compliance artifacts (TCOP, SECD, DPIA, JSP936, SVCASS, etc.) |
+| 2 | `governance` | Governance artifacts (RISK, TRAC, PRIN-COMP, CONF, etc.) |
+| 3 | `research` | Cloud research artifacts (AWRS, AZRS, GCRS) |
+| 4 | `procurement` | Procurement artifacts (SOW, EVAL, DOS, GCLD, VEND, etc.) |
+| 5 | `architecture` | Architecture artifacts (ADR, HLDR, DLDR, DIAG, WARD, etc.) |
+| 6 | `planning` | Planning artifacts (SOBC, PLAN, ROAD, STRAT, BKLG) |
+| 7 | `discovery` | Discovery artifacts (REQ, STKE, RSCH, DSCT) |
+| 8 | `operations` | Operations artifacts (SNOW, DEVOPS, MLOPS, FINOPS, OPS) |
+| 9 | `general` | No ARC artifacts or Other category only |
+
+## Timestamp Tracking
+
+The session-learner uses timestamp-based tracking to capture exactly the commits from each session:
+
+- Timestamp stored in `.arckit/memory/.last-session`
+- Each session captures commits since the previous session ended
+- First run uses `--since=4 hours ago` as a bootstrap
+- No overlap between sessions, no missed commits
+
+## Storage
+
+Session history is stored in `.arckit/memory/sessions.md` — a rolling log of the last 30 sessions. This file is committed to git by default for team visibility.
+
+### Example Entry
+
+```markdown
+### 2026-03-08 14:30 — governance
+
+- **Commits:** 4 | **Files changed:** 7
+- **Artifacts:**
+  - [001] Governance: Risk Register | Architecture: Architecture Decision Records
+  - [002] Compliance: Secure by Design
+- **Summary:**
+  - feat: add SECD assessment for cloud migration
+  - docs: update ADR-003 with security review outcome
+  - fix: correct risk rating in RISK register
+  - chore: update traceability matrix
+```
+
+Artifacts are grouped by project number (e.g., `[001]`) and organized by category, making it easy to see which projects were active and what type of work was done.
+
+## Relationship to Auto-Memory
+
+| Feature | Claude Auto-Memory | Session Learner |
+|---|---|---|
+| **What it captures** | What Claude decides is important | What actually happened (git commits) |
+| **Trigger** | Automatic (Claude's judgement) | Deterministic (Stop hook on every session) |
+| **Storage** | `~/.claude/projects/<project>/memory/` (machine-local) | `.arckit/memory/sessions.md` (in-repo) |
+| **Team sharing** | Not shareable | Committed to git |
+| **Content** | Freeform insights, preferences | Structured session summaries |
+
+The two systems are complementary, not competing. Auto-memory captures *insights*; session-learner captures *activity*.
+
+## Troubleshooting
+
+**No sessions.md created after ending a session:**
+
+- Check that `.arckit/` directory exists in your project root
+- Verify there were git commits since the last recorded session (or within 4 hours on first run)
+- Check hook registration: `hooks.json` should include a `Stop` event
+
+**Session classification seems wrong:**
+
+- Classification is based on artifact type codes in filenames (e.g., `ARC-001-SECD-v1.md`)
+- Non-ARC files don't contribute to classification
+- Sessions with no detected ARC artifacts default to `general`
+- When multiple categories are present, the highest-priority one wins (compliance > governance > research > ...)