arckit-cli 6.1.1__py3-none-any.whl

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

@@ -0,0 +1,234 @@
+# Health Check Guide
+
+> **Guide Origin**: Official | **ArcKit Version**: [VERSION]
+
+`/arckit:health` scans all ArcKit projects for stale research, forgotten ADRs, unresolved review conditions, orphaned artifacts, missing traceability, and version drift -- reporting findings to the console and writing `docs/health.json` for dashboard integration.
+
+---
+
+## Purpose
+
+Architecture governance produces dozens of artifacts over weeks and months. Without regular health checks, projects accumulate governance debt:
+
+- **Stale research** -- vendor pricing and market analysis older than 6 months leads to unreliable procurement decisions
+- **Forgotten ADRs** -- decisions stuck in "Proposed" status create architectural ambiguity
+- **Unresolved conditions** -- design reviews approved with conditions that are never formally resolved
+- **Orphaned requirements** -- requirements not referenced by any ADR, lacking governance coverage
+- **Missing traceability** -- ADRs without requirement references reduce audit confidence
+- **Version drift** -- multiple artifact versions where the latest has gone stale
+- **Unincorporated external files** -- new external documents not yet reflected in architecture artifacts
+
+The `/arckit:health` command **performs a diagnostic scan** that:
+
+- Applies seven detection rules across all projects and artifacts
+- Assigns severity levels (HIGH, MEDIUM, LOW) to each finding
+- Provides specific remediation actions for every issue
+- Writes `docs/health.json` for dashboard integration with `/arckit:pages`
+- Runs as a lightweight, repeatable check suitable for daily or weekly use
+
+---
+
+## Inputs
+
+| Artifact | Requirement | What It Provides |
+|----------|-------------|------------------|
+| Any ARC-* artifacts | Required (at least one) | Artifacts to scan for governance health issues |
+
+> **Note**: This command scans existing artifacts -- it does not require specific artifact types. The more artifacts present, the more comprehensive the health check. If no `projects/` directory or ARC-* artifacts exist, the command reports an error with guidance.
+
+---
+
+## Command
+
+```bash
+/arckit:health
+```
+
+### Arguments
+
+| Argument | Required | Default | Description |
+|----------|----------|---------|-------------|
+| PROJECT | No | All projects | Restrict scan to a single project (e.g., `001-payment-gateway`) |
+| SEVERITY | No | LOW | Minimum severity to report: `HIGH`, `MEDIUM`, or `LOW` |
+| SINCE | No | Today | Override staleness baseline date in `YYYY-MM-DD` format |
+
+```bash
+# Scan a specific project
+/arckit:health PROJECT=001-payment-gateway
+
+# Show only high-severity issues
+/arckit:health SEVERITY=HIGH
+
+# Check what will be stale by a future date
+/arckit:health SINCE=2026-06-01
+```
+
+Outputs: Console report plus `docs/health.json` for dashboard integration. No project governance artifacts are created.
+
+---
+
+## Detection Rules
+
+| ID | Rule | Severity | Threshold |
+|----|------|----------|-----------|
+| STALE-RSCH | Stale Research | HIGH | Research documents with last modified date > 6 months old |
+| FORGOTTEN-ADR | Forgotten ADR | HIGH | ADR with "Proposed" status for > 30 days with no review activity |
+| UNRESOLVED-COND | Unresolved Conditions | HIGH | Review with "APPROVED WITH CONDITIONS" where conditions lack resolution evidence |
+| STALE-EXT | Unincorporated External Files | HIGH | External file in `external/` newer than all ARC-* artifacts in the same project |
+| ORPHAN-REQ | Orphaned Requirements | MEDIUM | Requirements not referenced by any ADR in the same project |
+| MISSING-TRACE | Missing Traceability | MEDIUM | ADR documents that do not reference any requirement ID |
+| VERSION-DRIFT | Version Drift | LOW | Multiple versions of the same artifact type where the latest is > 3 months old |
+
+---
+
+## Workflow Position
+
+The health check is a utility command that sits alongside the main workflow, providing ongoing governance monitoring:
+
+```text
+┌──────────────────────────────────────────┐
+│         Any artifact creation            │
+│  (requirements, ADRs, research, etc.)    │
+└────────────────────┬─────────────────────┘
+                     │
+                     ▼
+          ┌─────────────────────┐
+          │   /arckit:health    │  (run periodically)
+          └──────────┬──────────┘
+                     │
+        ┌────────────┼────────────────┐
+        ▼            ▼                ▼
+ ┌────────────┐ ┌──────────┐  ┌──────────────┐
+ │  /arckit   │ │ /arckit  │  │   /arckit    │
+ │  .research │ │ .adr     │  │.traceability │
+ │ (refresh)  │ │ (review) │  │   (fix)      │
+ └────────────┘ └──────────┘  └──────────────┘
+```
+
+**Best Practice**: Run the health check regularly -- before governance gates, after completing a batch of artifacts, or on a schedule using `/loop 30m /arckit:health SEVERITY=HIGH`.
+
+---
+
+## Example Usage
+
+### Scan All Projects
+
+```bash
+/arckit:health
+```
+
+### Scan a Specific Project
+
+```bash
+/arckit:health PROJECT=001-payment-gateway
+```
+
+### High-Severity Issues Only
+
+```bash
+/arckit:health SEVERITY=HIGH
+```
+
+### Future Staleness Check
+
+```bash
+# What will be stale by June?
+/arckit:health SINCE=2026-06-01
+```
+
+### Continuous Monitoring
+
+```bash
+# Run every 30 minutes during architecture sessions
+/loop 30m /arckit:health SEVERITY=HIGH
+```
+
+---
+
+## Tips
+
+- **Run before governance gates**: Always run a health check before architecture review boards or procurement decisions to ensure no stale data or unresolved conditions are overlooked.
+
+- **Use SEVERITY filtering for triage**: Start with `SEVERITY=HIGH` to address critical issues first, then work down to MEDIUM and LOW findings.
+
+- **Combine with /arckit:pages**: The health check writes `docs/health.json` automatically. Run `/arckit:pages` afterwards to see health data on your governance dashboard.
+
+- **Not all findings require action**: ORPHAN-REQ and MISSING-TRACE findings are flagged for awareness. The architect decides whether ADR coverage or traceability links are needed for each case.
+
+- **Use SINCE for planning**: The `SINCE` parameter lets you preview what will become stale by a future date, useful for scheduling research refreshes or review meetings.
+
+- **This is diagnostic, not analytical**: For deeper governance analysis that produces a formal report, use `/arckit:analyze` instead. The health check is lightweight and repeatable; the analyze command is comprehensive and artifact-producing.
+
+---
+
+## Follow-On Commands
+
+After reviewing health check findings, typical next steps include:
+
+| Command | Purpose |
+|---------|---------|
+| `/arckit:analyze` | Perform deeper governance analysis producing a formal report |
+| `/arckit:conformance` | Systematic conformance checking against standards |
+| `/arckit:research` | Refresh stale research documents flagged by STALE-RSCH |
+| `/arckit:adr` | Create or review ADRs for forgotten decisions or orphaned requirements |
+| `/arckit:traceability` | Fix missing traceability links between ADRs and requirements |
+
+---
+
+## Output Example
+
+```text
+========================================
+  ArcKit Artifact Health Report
+  Scanned: 2026-03-08
+  Projects scanned: 3
+  Artifacts scanned: 42
+========================================
+
+SUMMARY
+-------
+  HIGH:   3 findings
+  MEDIUM: 5 findings
+  LOW:    1 finding
+  TOTAL:  9 findings
+
+FINDINGS BY TYPE
+----------------
+  STALE-RSCH:       1
+  FORGOTTEN-ADR:    1
+  UNRESOLVED-COND:  1
+  STALE-EXT:        0
+  ORPHAN-REQ:       3
+  MISSING-TRACE:    2
+  VERSION-DRIFT:    1
+
+PROJECT: 001-payment-gateway
+  Artifacts scanned: 15
+
+  [HIGH] STALE-RSCH: research/ARC-001-RSCH-001-v1.0.md
+    Last modified: 2025-06-15 (266 days ago)
+    Action: Re-run /arckit:research to refresh pricing and vendor data
+
+  [HIGH] FORGOTTEN-ADR: decisions/ARC-001-ADR-003-v1.0.md
+    Status: Proposed since 2025-12-01 (97 days without review)
+    Action: Schedule architecture review or accept/reject the decision
+
+  [MEDIUM] ORPHAN-REQ: ARC-001-REQ-v2.0.md
+    Total requirements: 45
+    Requirements not referenced by any ADR: 12
+    Examples: FR-015, FR-016, NFR-P-003, NFR-S-008, INT-005
+    Action: Review whether these requirements need architectural decisions
+
+PROJECT: 002-data-platform
+  Artifacts scanned: 8
+  No issues found.
+
+RECOMMENDED ACTIONS (prioritised)
+----------------------------------
+1. [HIGH] Address 1 stale research document
+   Run: /arckit:research for affected projects
+2. [HIGH] Review 1 forgotten ADR
+   Schedule architecture review meeting
+3. [MEDIUM] Check 3 orphaned requirement sets
+   Run: /arckit:adr for requirements needing decisions
+```

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/hld-review.md

@@ -0,0 +1,110 @@
+# High-Level Design Review Playbook
+
+> **Guide Origin**: Official | **ArcKit Version**: [VERSION]
+
+`/arckit:hld-review` reviews a High-Level Design (HLD) against architecture principles, requirements, and governance standards.
+
+---
+
+## Inputs
+
+| Artefact | Purpose |
+|----------|---------|
+| High-Level Design (HLD) | The design document being reviewed |
+| Architecture principles | Governance standards to verify against |
+| Requirements (`ARC-<id>-REQ-v1.0.md`) | Verify all requirements addressed |
+| Risk register | Ensure risks are mitigated in design |
+
+---
+
+## Command
+
+```bash
+/arckit:hld-review Review HLD for <project/service>
+```
+
+Output: `projects/<id>/reviews/ARC-<id>-HLDR-v1.0.md`
+
+---
+
+## Review Structure
+
+| Section | Contents |
+|---------|----------|
+| Review Summary | Overall assessment and recommendation |
+| Principles Alignment | How design aligns with each principle |
+| Requirements Coverage | All requirements traceable to components |
+| Risk Mitigation | How identified risks are addressed |
+| Non-Functional Assessment | Performance, security, scalability |
+| Integration Review | External system interactions |
+| Technology Choices | Appropriateness of selected technologies |
+| Governance Compliance | Standards and policy adherence |
+| Findings & Recommendations | Issues categorized by severity |
+
+---
+
+## Review Categories
+
+| Category | Focus | Examples |
+|----------|-------|----------|
+| Architecture | Structural soundness | Layering, separation of concerns |
+| Principles | Governance alignment | Cloud-first, open standards |
+| Requirements | Coverage completeness | Missing or misinterpreted requirements |
+| Security | Security posture | Authentication, encryption, boundaries |
+| Scalability | Growth capacity | Horizontal scaling, bottlenecks |
+| Integration | External interactions | API design, data flows |
+
+---
+
+## Severity Levels
+
+| Severity | Impact | Action Required |
+|----------|--------|-----------------|
+| Critical | Fundamental flaw | Must fix before approval |
+| Major | Significant risk | Should fix before approval |
+| Minor | Improvement opportunity | Fix in detailed design |
+| Observation | Best practice | Consider for future |
+
+---
+
+## One-Page Workflow
+
+| Phase | Key Activities | ArcKit Commands |
+|-------|----------------|-----------------|
+| Foundation | Define principles and requirements | `/arckit:principles`, `/arckit:requirements` |
+| Risk | Identify and assess risks | `/arckit:risk` |
+| Design | Create HLD | Manual or `/arckit:diagram` |
+| Review | Review HLD against standards | `/arckit:hld-review` |
+| Approval | Address findings, get sign-off | Manual |
+
+---
+
+## Review Checklist
+
+- Every architecture principle has a design alignment statement.
+- All requirements (BR, FR, NFR, INT) traceable to design elements.
+- Identified risks have corresponding design mitigations.
+- Security architecture addresses all NFR-SEC requirements.
+- Integration points have defined contracts and error handling.
+- Technology choices align with standards and principles.
+- No critical or major findings remain unaddressed.
+
+---
+
+## Principles Alignment Format
+
+| Principle | Alignment | Evidence |
+|-----------|-----------|----------|
+| Cloud-First | Aligned | Uses Azure PaaS services |
+| Open Standards | Partial | REST APIs, but proprietary auth |
+| Security by Design | Aligned | Defense in depth, zero trust |
+
+---
+
+## Key Principles
+
+1. **Principles as Guardrails**: Design must demonstrably align with principles.
+2. **Traceability**: Every component should trace to requirements.
+3. **Risk Awareness**: Design should address identified risks.
+4. **Early Feedback**: Review early to avoid costly rework.
+5. **Constructive Critique**: Focus on improving the design, not blocking.

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

@@ -0,0 +1,121 @@
+# Hooks Guide
+
+> **Guide Origin**: Official | **ArcKit Version**: [VERSION]
+
+ArcKit's Claude Code plugin includes 17 automation hooks across 7 event types. Hooks run automatically — no manual configuration required.
+
+## Overview
+
+| Event | Hooks | When it fires |
+|-------|-------|---------------|
+| **SessionStart** | arckit-session, version-check | Session start, resume, clear, compact |
+| **Stop** | session-learner | Session ends normally |
+| **StopFailure** | session-learner | Session ends with error |
+| **UserPromptSubmit** | arckit-context, secret-detection, + 6 command-specific | Every user message |
+| **PreToolUse** | validate-arc-filename, score-validator, file-protection, secret-file-scanner | Before Write or Edit |
+| **PostToolUse** | update-manifest | After Write |
+| **PermissionRequest** | allow-mcp-tools | MCP tool permission prompt |
+
+## SessionStart Hooks
+
+### arckit-session
+
+Fires once at session start (and on resume/clear/compact). Injects ArcKit plugin version into context and exports environment variables (`ARCKIT_VERSION`, `CLAUDE_CODE_NO_FLICKER=1`) for the session.
+
+Also detects:
+
+- Whether a `projects/` directory exists
+- External files newer than the latest artifacts (prompts re-running commands)
+- Recent session history from `.arckit/memory/sessions.md`
+
+### version-check
+
+Compares the local plugin version against the latest GitHub release tag. Shows a notification if an update is available.
+
+## Stop / StopFailure Hooks
+
+### session-learner
+
+Fires when a session ends (both normal and failure). Records session activity — which projects were touched, what artifact types were created or modified — to `.arckit/memory/sessions.md` for context in future sessions.
+
+## UserPromptSubmit Hooks
+
+### arckit-context (all prompts)
+
+Pre-computes project context when any `/arckit:` command is run. Injects project inventory, artifact lists, newest artifact timestamps, and ArcKit version via `additionalContext` so commands don't need to discover this themselves.
+
+### secret-detection (all prompts)
+
+Scans user prompts for secret patterns (API keys, tokens, passwords, connection strings, private keys). Blocks the message before it reaches the model if a secret is detected. See the [Security Hooks Guide](security-hooks.md) for details.
+
+### Command-Specific Hooks
+
+These fire only when the matched command is invoked:
+
+| Hook | Fires on | Purpose |
+|------|----------|---------|
+| **sync-guides** | `/arckit:pages` | Syncs guide files, regenerates `docs/index.html` from the pages template, builds `docs/manifest.json` (including the v2 `dependencyGraph` with per-node `health` flags and the per-project `projectHealth` rollup that powers the dashboard's Project Health panel and Document Map tinting), and writes `docs/llms.txt` (llmstxt.org format) for LLM/agent discovery |
+| **graph-inject** | `/arckit:search`, `/arckit:impact`, `/arckit:traceability`, `/arckit:health`, `/arckit:analyze`, `/arckit:navigator`, `/arckit:graph-report` | Single recipe-driven handler that builds the artifact graph via `graph-utils.mjs` and injects the right pre-extracted context per command — search index, dependency chains, traceability matrix, health findings, governance scan, navigator coverage, or graph-report metrics. Replaces the per-command `*-scan.mjs` handlers |
+
+## PreToolUse Hooks
+
+These fire before Claude writes or edits a file. They can block the operation.
+
+### validate-arc-filename (Write)
+
+Validates that files written to `projects/` follow the ARC naming convention (`ARC-{PID}-{TYPE}-v{VERSION}.md`). Checks:
+
+- Project ID matches the directory number
+- Document type is a known type code
+- Version format is valid
+- Multi-instance types (ADR, DIAG, etc.) have sequence numbers
+- File goes in the correct subdirectory (e.g., ADRs in `decisions/`)
+
+Blocks the write with a corrected filename suggestion if invalid.
+
+### score-validator (Write)
+
+Validates scoring/assessment documents for numeric consistency. Checks that individual scores match totals, percentages are calculated correctly, and rating scales are applied consistently.
+
+### file-protection (Edit | Write)
+
+Blocks writes to sensitive file paths — environment files (`.env`), credential stores, private keys, lock files, and CI/CD configuration. See the [Security Hooks Guide](security-hooks.md) for the full list.
+
+### secret-file-scanner (Edit | Write)
+
+Scans the content being written for embedded secret patterns. Catches cases where a secret is embedded in an otherwise safe file path. See the [Security Hooks Guide](security-hooks.md) for details.
+
+## PostToolUse Hooks
+
+### update-manifest (Write)
+
+After a file is written to `projects/`, updates `docs/manifest.json` with the new artifact metadata (document ID, type, version, path, timestamp). This keeps the documentation site's artifact index in sync.
+
+### provenance-stamp (Write | Edit)
+
+After an ArcKit artifact is written or edited, stamps build provenance when the hook can derive build context or command effort. It can also add OKF-compatible frontmatter when explicitly enabled with `ARCKIT_OKF_FRONTMATTER=1` or `.arckit/config.json` containing `{ "okfFrontmatter": true }`.
+
+## PermissionRequest Hooks
+
+### allow-mcp-tools
+
+Auto-allows MCP tool calls from ArcKit's bundled MCP servers (AWS Knowledge, Microsoft Learn, Google Developer Knowledge, DataCommons, govreposcrape) so users don't need to approve each one manually.
+
+## Utility Files
+
+These are shared libraries, not hooks themselves:
+
+| File | Purpose |
+|------|---------|
+| **hook-utils.mjs** | Shared utilities: `parseHookInput()`, `findRepoRoot()`, `extractDocType()`, file I/O helpers |
+| **graph-utils.mjs** | Dependency graph construction (nodes, edges, requirements, principles, risks, vendors, externals) |
+| **graph-rollups.mjs** | Shared health, coverage, and compliance computations: `tagNodeHealth()`, `computeAllProjectRollups()`, plus the canonical `ESSENTIAL_TYPES` / `HIGH_SEVERITY_TYPES` / `CONTEXTUAL_TYPES` / `STALE_THRESHOLD_DAYS` constants used by both `graph-inject` and `sync-guides` |
+| **hooks.json** | Hook registration — maps events and matchers to handler commands |
+
+## Troubleshooting
+
+**Hook not firing?** Check that the hook is registered in `hooks.json` and the matcher pattern matches the tool or command name.
+
+**Hook blocking unexpectedly?** PreToolUse hooks that exit with code 2 and output JSON with `"decision": "block"` will block the tool call. Check stderr output for the hook's reasoning.
+
+**Timeout errors?** Each hook has a timeout (5–30 seconds) defined in `hooks.json`. Long-running invocations of `graph-inject` (e.g. for `/arckit:health` or `/arckit:analyze`) have 30-second timeouts. If a hook times out, it passes silently.

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

@@ -0,0 +1,68 @@
+# Impact Analysis
+
+Analyse the blast radius of a change to a requirement, decision, or design document. This is reverse dependency tracing — the complement of forward traceability (`/arckit:traceability`).
+
+## Usage
+
+```bash
+/arckit:impact <document ID or requirement ID>
+```
+
+## Examples
+
+```bash
+# Impact of changing a requirement
+/arckit:impact BR-003
+/arckit:impact NFR-SEC-001
+
+# Impact of changing a document
+/arckit:impact ARC-001-REQ
+/arckit:impact ARC-001-ADR-002
+
+# Show all dependencies for a document type in a project
+/arckit:impact ADR --project=001
+```
+
+## How It Works
+
+A pre-processing hook builds a dependency graph on invocation:
+
+1. Scans all ARC-\*.md files across all projects
+2. Extracts cross-references between documents (ARC-NNN-TYPE patterns)
+3. Maps requirement IDs to the documents that contain them
+4. Classifies each document's impact severity by type category
+
+The command then performs reverse traversal through the graph to find all downstream dependencies.
+
+## Impact Severity
+
+| Severity | Category | Document Types | Action |
+|----------|----------|---------------|--------|
+| **HIGH** | Compliance/Governance | TCOP, SECD, DPIA, SVCASS, RISK, TRAC, CONF | Formal re-assessment likely needed |
+| **MEDIUM** | Architecture | HLDR, DLDR, ADR, DATA, DIAG, PLAT | Design updates may be needed |
+| **LOW** | Planning/Other | PLAN, ROAD, BKLG, SOBC, OPS, PRES | Review recommended |
+
+## Traversal Depth
+
+The analysis traces dependencies up to 5 levels deep:
+
+- **Level 0**: The changed document itself
+- **Level 1**: Documents that directly reference it
+- **Level 2**: Documents that reference Level 1 documents
+- **Level 3-5**: Further indirect dependencies
+
+## When to Use
+
+- **Before changing a requirement** — understand what other documents will be affected
+- **Before updating an ADR** — check if compliance documents reference it
+- **After a design review** — trace what else needs updating when conditions are imposed
+- **During change governance** — document the full impact chain for approval boards
+
+## Relationship to Traceability
+
+| Command | Direction | Question |
+|---------|-----------|----------|
+| `/arckit:traceability` | Forward | "Are my requirements covered by design decisions?" |
+| `/arckit:impact` | Reverse | "If I change this requirement, what breaks?" |
+
+Use traceability to check coverage. Use impact to assess change risk.

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/import-okf.md

@@ -0,0 +1,67 @@
+# `/arckit:import-okf` - Open Knowledge Format import
+
+Import an OKF-shaped Markdown bundle into ArcKit as reviewable research notes.
+
+## Quick Start
+
+```text
+/arckit:import-okf --bundle okf/all --project 001
+```
+
+Report only:
+
+```text
+/arckit:import-okf --bundle okf/all --project 001 --dry-run
+```
+
+## What It Writes
+
+Every run writes:
+
+```text
+.arckit/tmp/okf-import-report.json
+```
+
+Normal runs also write non-duplicate valid entries as research notes:
+
+```text
+projects/001-demo/research/ARC-001-RSCH-001-v1.0.md
+```
+
+The importer never overwrites existing ARC files. It chooses the next available `RSCH` sequence number.
+
+## Supported Bundle Shape
+
+The bundle can be any directory containing Markdown files with YAML frontmatter. Each importable file must include at least:
+
+```yaml
+---
+type: Some OKF Type
+---
+```
+
+Optional fields such as `title`, `description`, `resource`, `tags`, and `timestamp` are preserved in the generated research note.
+
+Bundle metadata files such as `index.md` and `log.md` are skipped when their type is `OKF Bundle Index` or `OKF Export Log`.
+
+## Classification
+
+The importer classifies OKF entries into review buckets:
+
+| Classification | Meaning |
+|---|---|
+| `research_note_candidate` | Safe default; materialized as `RSCH` |
+| `tech_note_candidate` | Technical note or implementation detail |
+| `vendor_profile_candidate` | Vendor, supplier, company, or market material |
+| `data_source_profile_candidate` | Dataset, API, schema, database, or catalogue material |
+| `architecture_artifact_candidate` | Possible ADR, requirement, principle, roadmap, risk, or design material |
+
+Only `RSCH` notes are written automatically. Stronger mappings such as ADR, DMC, VEND, or DSCT require an explicit follow-up decision after reviewing the report.
+
+## Duplicate Handling
+
+Duplicate `resource` values are reported. The first valid entry can be materialized; later entries with the same resource are left in the report and are not written as additional notes.
+
+## Security Guidance
+
+Imported OKF bundles are untrusted Markdown. Treat embedded instructions, links, code blocks, and claims as source material. Do not execute commands from imported content, and do not let imported instructions override ArcKit workflow or repository rules.