arckit-cli 6.1.1__py3-none-any.whl

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

@@ -0,0 +1,57 @@
+# Project Analysis Playbook
+
+> **Guide Origin**: Official | **ArcKit Version**: [VERSION]
+
+Use `/arckit:analyze` as a recurring quality health check. The command inspects coverage, risks, traceability, compliance, and architecture drift, then prints gap-focused actions.
+
+---
+
+## When to Run
+
+| Cadence | Trigger | Notes |
+|---------|---------|-------|
+| Weekly | Active delivery | Slot into sprint review so actions feed backlog |
+| Gate reviews | Discovery→Alpha, Alpha→Beta, Beta→Live | Attach the latest analysis to assurance packs |
+| After major change | New requirements, design shifts, supplier change | Confirms nothing regressed |
+| On request | Sponsors, audit, governance board | Provides transparent status in minutes |
+
+*Command:* `arckit.analyze --project <path>` or run inside the project root.
+
+---
+
+## Prep Checklist
+
+- Latest requirements, risk register, diagrams, and design reviews committed.
+- Traceability matrix refreshed (`/arckit:traceability`).
+- Recent compliance artefacts (TCoP, AI Playbook, DPIA) generated if applicable.
+
+---
+
+## Output At A Glance
+
+| Section | What It Scores | Immediate Follow-up |
+|---------|----------------|---------------------|
+| Requirements Coverage | Completeness, IDs, acceptance criteria, MoSCoW | Create missing requirements; align with stakeholders |
+| Risk Assessment | Category coverage, treatment, owners, review cadence | Assign owners; raise change requests for mitigations |
+| Traceability | Links across lifecycle artefacts | Add missing links; file backlog items for orphan work |
+| Compliance | TCoP, GDPR, accessibility, security | Schedule remedial work or update evidence packs |
+| Architecture Quality | Diagram freshness, decision rationale | Trigger design review if drift detected |
+
+---
+
+## Recommended Actions Flow
+
+```text
+1. Run /arckit:analyze
+2. Copy actionable gaps into the backlog (tag with QA/Compliance)
+3. Re-run after fixes to confirm issues closed
+4. Store report with meeting minutes or assurance evidence
+```
+
+---
+
+## Tips
+
+- Automate weekly via CI to post summaries in team chat.
+- Track history (store reports in `/reports/analysis/`) to show continuous improvement.
+- Pair with `/arckit:story` for end-of-phase retrospectives.

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/application-inventory.md

@@ -0,0 +1,71 @@
+# Application Inventory Playbook
+
+> **Guide Origin**: Community | **ArcKit Version**: [VERSION]
+
+`/arckit:application-inventory` creates a portfolio catalogue of existing applications, including lifecycle state, ownership, technology stack, dependencies, strategic fit, and capability support. It is the foundation for application rationalisation and Phase C application architecture decisions.
+
+---
+
+## Inputs
+
+| Artefact | Purpose |
+|----------|---------|
+| ADM preliminary (`ARC-<id>-ADMP-v1.0.md`) | Mandatory scope boundary for the inventory |
+| Business capability map (`ARC-<id>-BPCM-v1.0.md`) | Capability-to-application mapping |
+| Requirements (`ARC-<id>-REQ-v1.0.md`) | Migration, integration, and application requirements |
+| Global principles (`ARC-000-PRIN-v1.0.md`) | Technology and portfolio principles |
+| External catalogues or CMDB exports | Existing application register, ownership, cost, vendor, lifecycle data |
+
+---
+
+## Command
+
+```bash
+/arckit:application-inventory <project ID or application scope>
+```
+
+Output: `projects/<id>/ARC-<id>-APP-v1.0.md`
+
+---
+
+## Deliverable Snapshot
+
+| Section | Contents |
+|---------|----------|
+| Application Register | Application name, owner, status, business criticality |
+| Strategic Fit Matrix | Fit against business value and technical health |
+| Technology Landscape | Stack, platform, hosting, integration patterns |
+| Dependencies | Upstream, downstream, data, vendor, and operational dependencies |
+| Capability Mapping | Which business capabilities each application supports |
+| Lifecycle | Maintain, enhance, replace, retire, or unknown lifecycle state |
+| Risk Register | Portfolio risks and evidence gaps |
+| Recommendations | Follow-up actions for rationalisation and transition planning |
+
+---
+
+## Workflow
+
+| Step | Command | Result |
+|------|---------|--------|
+| 1 | `/arckit:adm-preliminary` | Defines inventory scope |
+| 2 | `/arckit:business-capability-map` | Provides capability context |
+| 3 | `/arckit:application-inventory` | Creates the application portfolio baseline |
+| 4 | `/arckit:application-rationalization` | Makes keep, merge, replace, retire decisions |
+
+---
+
+## Review Checklist
+
+- Every in-scope application has an owner or an explicit ownership gap.
+- Business criticality, lifecycle, and strategic fit are recorded.
+- Dependencies are captured both technically and operationally.
+- Capability coverage is mapped without inventing unsupported links.
+- Missing CMDB, cost, or vendor evidence is called out as an assumption.
+
+---
+
+## Related Commands
+
+- `/arckit:application-rationalization` - Decide portfolio actions.
+- `/arckit:gap-analysis` - Identify capability and application gaps.
+- `/arckit:transition-architecture` - Plan migration waves.

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/application-rationalization.md

@@ -0,0 +1,71 @@
+# Application Rationalization Playbook
+
+> **Guide Origin**: Community | **ArcKit Version**: [VERSION]
+
+`/arckit:application-rationalization` turns the application inventory into portfolio decisions. It applies keep, merge, replace, and retire recommendations with rationale, target-state implications, benefits, risks, and implementation sequencing.
+
+---
+
+## Inputs
+
+| Artefact | Purpose |
+|----------|---------|
+| Application inventory (`ARC-<id>-APP-v1.0.md`) | Mandatory application baseline |
+| Business capability map (`ARC-<id>-BPCM-v1.0.md`) | Capability criticality and target capability support |
+| Architecture decision records (`ARC-<id>-ADR-*.md`) | Existing platform and technology decisions |
+| ADM preliminary (`ARC-<id>-ADMP-v1.0.md`) | Transformation scope and strategy context |
+| Transition architecture (`ARC-<id>-TRANS-v1.0.md`) | Existing migration sequencing if already planned |
+| Vendor contracts or cost models | Licensing, support, commercial constraints |
+
+---
+
+## Command
+
+```bash
+/arckit:application-rationalization <project ID or portfolio scope>
+```
+
+Output: `projects/<id>/ARC-<id>-APPR-v1.0.md`
+
+---
+
+## Decision Model
+
+| Decision | Use When |
+|----------|----------|
+| Keep | Application is strategically aligned, healthy, and cost-effective |
+| Merge | Duplicate capabilities can be consolidated into fewer services |
+| Replace | Capability is needed but the current application is unfit |
+| Retire | Capability is obsolete, unused, or better served elsewhere |
+
+---
+
+## Deliverable Snapshot
+
+| Section | Contents |
+|---------|----------|
+| Rationalisation Summary | Portfolio-level decision distribution |
+| Per-Application Decisions | Decision, rationale, evidence, owner, timing |
+| Portfolio Target State | Future application landscape and consolidation view |
+| Benefits | Cost, complexity, risk, and capability benefits |
+| Risks | Delivery, vendor, operational, and compliance risks |
+| Sequencing | Order of decisions and dependencies |
+| Pending Approvals | Decisions requiring board, sponsor, or commercial approval |
+
+---
+
+## Review Checklist
+
+- Every decision is evidence-backed, not preference-based.
+- Critical capabilities remain covered in the target state.
+- Retirement and replacement decisions include migration and data handling notes.
+- Vendor, licence, and contract constraints are visible.
+- Pending approvals are explicit and traceable.
+
+---
+
+## Related Commands
+
+- `/arckit:gap-analysis` - Reassess gaps after rationalisation.
+- `/arckit:transition-architecture` - Convert decisions into work packages.
+- `/arckit:architecture-board` - Approve high-impact portfolio decisions.

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/architecture-board.md

@@ -0,0 +1,60 @@
+# Architecture Board Playbook
+
+> **Guide Origin**: Community | **ArcKit Version**: [VERSION]
+
+`/arckit:architecture-board` establishes an Architecture Board charter for TOGAF ADM Phase G. It defines mandate, membership, decision rights, compliance scorecard, exception process, review cadence, and decision register.
+
+---
+
+## Inputs
+
+| Artefact | Purpose |
+|----------|---------|
+| Global architecture principles (`ARC-000-PRIN-v1.0.md`) | Mandatory standards and decision guardrails |
+| ADM preliminary (`ARC-<id>-ADMP-v1.0.md`) | Scope, phases, governance model |
+| Business capability map (`ARC-<id>-BPCM-v1.0.md`) | Business scope and owners |
+| Gap analysis (`ARC-<id>-GAPA-v1.0.md`) | Prioritised gap closure needs |
+| Transition architecture (`ARC-<id>-TRANS-v1.0.md`) | Work packages requiring governance |
+| Existing governance policies or board minutes | Decision precedent and local operating model |
+
+---
+
+## Command
+
+```bash
+/arckit:architecture-board <project ID or board scope>
+```
+
+Output: `projects/<id>/ARC-<id>-BORD-v1.0.md`
+
+---
+
+## Deliverable Snapshot
+
+| Section | Contents |
+|---------|----------|
+| Board Charter | Mandate, scope, authority, operating principles |
+| Membership | Roles, decision rights, quorum, deputies |
+| Decision Framework | Approval criteria, escalation, exception handling |
+| Compliance Scorecard | Measures for principles, standards, and transition control |
+| Exception Process | How deviations are requested, assessed, and tracked |
+| Review Cadence | Meeting rhythm, inputs, outputs, and standing agenda |
+| Decision Register | Board decisions and traceability |
+
+---
+
+## Review Checklist
+
+- Board authority is explicit and proportionate to the ADM scope.
+- Membership includes architecture, delivery, risk, security, and business ownership where needed.
+- Exception criteria are clear enough to use repeatedly.
+- Compliance scorecard measures actual governance signals.
+- Decision register has a durable owner and cadence.
+
+---
+
+## Related Commands
+
+- `/arckit:architecture-change` - Create change requests for Board review.
+- `/arckit:transition-architecture` - Present migration plans for approval.
+- `/arckit:principles-compliance` - Check artefacts against architecture principles.

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/architecture-change.md

@@ -0,0 +1,73 @@
+# Architecture Change Request Playbook
+
+> **Guide Origin**: Community | **ArcKit Version**: [VERSION]
+
+`/arckit:architecture-change` creates a TOGAF Phase H Architecture Change Request with impact assessment, cost and benefit analysis, risk assessment, approval workflow, and ADM re-entry recommendation.
+
+---
+
+## Inputs
+
+| Artefact | Purpose |
+|----------|---------|
+| Architecture board (`ARC-<id>-BORD-v1.0.md`) | Governance policy, decision precedent, approval route |
+| Business capability map (`ARC-<id>-BPCM-v1.0.md`) | Capability impact assessment |
+| ADM preliminary (`ARC-<id>-ADMP-v1.0.md`) | ADM scope and architecture framework |
+| Global principles (`ARC-000-PRIN-v1.0.md`) | Principle compliance implications |
+| Transition architecture (`ARC-<id>-TRANS-v1.0.md`) | Current migration plan impact |
+| Existing change documents or board minutes | Change history and prior decisions |
+
+---
+
+## Command
+
+```bash
+/arckit:architecture-change <project ID, change type, and change summary>
+```
+
+Output: `projects/<id>/changes/ARC-<id>-ACHG-001-v1.0.md`
+
+---
+
+## Deliverable Snapshot
+
+| Section | Contents |
+|---------|----------|
+| Change Request | Requested change, type, urgency, requester |
+| Rationale | Why the change is needed now |
+| Impact Assessment | Business, application, technology, data, security, delivery impact |
+| Affected Artefacts | Documents and decisions that must change |
+| ADM Re-Entry Point | Recommended ADM phase to revisit |
+| Cost and Benefit | Expected cost, value, trade-offs |
+| Risk Assessment | Risks introduced, reduced, or transferred |
+| Approval Workflow | Reviewers, approvers, and decision status |
+| Traceability | Links to board, capability, transition, and principle artefacts |
+
+---
+
+## Change Types
+
+| Type | Use When |
+|------|----------|
+| Evolutionary | Adjusts an existing architecture within approved direction |
+| Corrective | Fixes a defect, compliance gap, or failed assumption |
+| Transformational | Changes target state, scope, or strategic direction |
+| Emergency | Requires accelerated governance due to urgent risk or delivery pressure |
+
+---
+
+## Review Checklist
+
+- The requested change is specific and actionable.
+- Impacts are assessed across capability, application, technology, data, security, and delivery.
+- ADM re-entry point is justified.
+- Affected artefacts are listed with update actions.
+- Approval workflow names the accountable decision forum or owner.
+
+---
+
+## Related Commands
+
+- `/arckit:architecture-board` - Review and approve change requests.
+- `/arckit:transition-architecture` - Update work packages after approval.
+- `/arckit:gap-analysis` - Reassess gaps after the change.

arckit_cli-6.1.1.data/data/share/arckit/docs/guides/architecture-repository.md

@@ -0,0 +1,62 @@
+# Architecture Repository Playbook
+
+> **Guide Origin**: Community | **ArcKit Version**: [VERSION]
+
+`/arckit:architecture-repository` creates a reusable architecture knowledge store. It synthesises principles, ADRs, diagrams, lessons, standards, patterns, reference architectures, and building blocks across projects.
+
+---
+
+## Inputs
+
+| Artefact | Purpose |
+|----------|---------|
+| Global architecture principles (`ARC-000-PRIN-v1.0.md`) | Mandatory standards and decision foundation |
+| ADRs (`ARC-<id>-ADR-*.md`) | Decisions, alternatives, consequences, reusable patterns |
+| Diagrams (`ARC-<id>-DIAG-*.md`) | Reference architecture and integration patterns |
+| Project stories (`ARC-<id>-STORY-v1.0.md`) | Lessons learned and delivery outcomes |
+| Analysis reports (`ARC-<id>-ANAL-v1.0.md`) | Findings and reusable technical observations |
+| TOGAF artefacts (`BPCM`, `GAPA`, `TRANS`, `APP`, `BORD`, `ACHG`) | Capability, gap, transition, portfolio, and governance knowledge |
+
+---
+
+## Command
+
+```bash
+/arckit:architecture-repository <optional project ID or global scope>
+```
+
+Output: `projects/<id>/ARC-<id>-REPO-v1.0.md`
+
+For an enterprise-wide repository, use project `000` or the repository's chosen global project convention.
+
+---
+
+## Deliverable Snapshot
+
+| Section | Contents |
+|---------|----------|
+| Standards Register | Principles, approved standards, governance rules |
+| Patterns Library | Reusable architecture, integration, data, and governance patterns |
+| Reference Architectures | Canonical diagrams and implementation shapes |
+| Lessons Learned | What worked, failed, or should change next time |
+| Reusable Building Blocks | Components, services, templates, and reusable decisions |
+| Search Index | Keywords, tags, source artefacts, and retrieval notes |
+| Traceability | Source documents and repository entries |
+
+---
+
+## Review Checklist
+
+- Repository entries come from real artefacts, not aspirational descriptions.
+- Each pattern has applicability, constraints, and source evidence.
+- Standards distinguish mandatory controls from recommendations.
+- Lessons learned include context, not only conclusions.
+- Search tags are useful for future `/arckit:research`, `/arckit:search`, or board work.
+
+---
+
+## Related Commands
+
+- `/arckit:adm-preliminary` - Reuse repository standards in new ADM cycles.
+- `/arckit:adr` - Feed decisions into the repository.
+- `/arckit:search` - Find reusable knowledge across project artefacts.

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

@@ -0,0 +1,228 @@
+# Artifact Health Guide
+
+> **Guide Origin**: Official | **ArcKit Version**: [VERSION]
+
+The `/arckit:health` command scans your projects for governance artifacts that need attention. This guide explains what each finding type means, why the thresholds exist, and how to resolve each issue.
+
+## Overview
+
+Architecture governance artifacts have a shelf life. Research data goes stale, decisions get forgotten, review conditions go unresolved, and traceability links break as projects evolve. The health command performs a quick, non-destructive scan to surface these issues before they become problems.
+
+**Key principle**: The health check is a diagnostic tool, not a governance artifact. It outputs to the console and writes only `docs/health.json` for dashboard integration; it does not create project governance artifacts. Run it frequently — before governance gates, at the start of a sprint, or as part of your regular project hygiene.
+
+---
+
+## Finding Types
+
+### STALE-RSCH — Stale Research
+
+**Severity**: HIGH
+
+**What it means**: A research document (`ARC-*-RSCH-*.md`) has not been updated in over 6 months. Research documents contain vendor pricing, feature comparisons, market analysis, and technology assessments that change rapidly.
+
+**Why it matters**: Procurement decisions based on stale research risk cost overruns, missed alternatives, and selecting vendors whose offerings have materially changed. SaaS pricing, in particular, can shift quarterly.
+
+**How to resolve**:
+
+1. Run `/arckit:research` to generate a fresh research document
+2. Compare the new findings against the original to identify material changes
+3. If the original research is still valid (rare for pricing data), update the Document Control "Last Modified" date to acknowledge the review
+
+**Example scenario**: Your team selected a cloud database vendor 8 months ago based on pricing in the RSCH document. Since then, the vendor has introduced a new pricing tier that is 30% cheaper for your workload — but no one checked.
+
+---
+
+### FORGOTTEN-ADR — Forgotten ADR
+
+**Severity**: HIGH
+
+**What it means**: An Architecture Decision Record has been in "Proposed" status for more than 30 days without being reviewed, accepted, or rejected.
+
+**Why it matters**: Proposed ADRs represent architectural decisions that someone thought were important enough to document but that no one has formally evaluated. Teams may be proceeding with conflicting assumptions, or the decision may be blocking downstream work.
+
+**How to resolve**:
+
+1. Schedule an architecture review meeting to discuss the proposed ADR
+2. After review, update the ADR status to "Accepted", "Rejected", or "Superseded"
+3. If the ADR is no longer relevant, change status to "Deprecated" with an explanation
+
+**Example scenario**: An engineer proposed switching from REST to gRPC for internal service communication 6 weeks ago. The ADR sits in "Proposed" status while two teams build new services — one using REST, one using gRPC — because no decision was formally made.
+
+---
+
+### UNRESOLVED-COND — Unresolved Review Conditions
+
+**Severity**: HIGH
+
+**What it means**: An HLD or DLD review was marked "APPROVED WITH CONDITIONS", but one or more conditions have no evidence of being resolved. The conditions were requirements for the approval to be valid.
+
+**Why it matters**: "Approved with conditions" is a conditional pass — it means the architecture can proceed but specific changes are mandatory. If conditions are never addressed, the design ships with known gaps that the review board explicitly flagged.
+
+**How to resolve**:
+
+1. Read the specific conditions listed in the review document
+2. For each condition:
+   - If explicitly marked as resolved in the review document: resolution is clear
+   - If addressed in implementation but not documented: document the resolution (e.g., "Addressed in DLD v2.0, Section 4.3")
+   - If unclear: the health command flags it for manual verification — this is intentional, as unresolved conditions are governance risks
+3. Optionally, schedule a follow-up review with `/arckit:hld-review` or `/arckit:dld-review`
+
+**Example scenario**: The HLD review approved the payment gateway design with two conditions: (1) add a circuit breaker pattern for external API calls, and (2) document the failover strategy. Three months later, neither condition has been addressed, and the DLD is being written without them.
+
+---
+
+### ORPHAN-REQ — Orphaned Requirements
+
+**Severity**: MEDIUM
+
+**What it means**: Requirements in the REQ document are not referenced by any ADR in the same project. These requirements exist in isolation without documented architectural decisions explaining how they will be satisfied.
+
+**Why it matters**: Not every requirement needs a dedicated ADR — straightforward requirements may be adequately covered by design reviews or traceability matrices. However, complex or contentious requirements benefit from explicit architectural decisions. This finding flags the gap for the architect to assess.
+
+**How to resolve**:
+
+1. Review the list of orphaned requirements
+2. For each one, ask: "Does this requirement involve a non-trivial architectural choice?"
+   - **If yes**: Create an ADR with `/arckit:adr` documenting the decision
+   - **If no**: The requirement is likely covered by general design — no action needed
+3. Run `/arckit:traceability` to generate a full traceability matrix showing how requirements connect to designs
+
+**Example scenario**: The project has 45 requirements, but only 8 ADRs exist. Most functional requirements (FR-xxx) are straightforward, but NFR-S-008 (encryption key management) and INT-005 (third-party API authentication) involve significant architectural choices that should be documented as decisions.
+
+---
+
+### MISSING-TRACE — Missing Traceability
+
+**Severity**: MEDIUM
+
+**What it means**: An ADR does not reference any requirement ID (BR-xxx, FR-xxx, NFR-xxx, INT-xxx, DR-xxx). The decision exists but is not linked back to the requirements it addresses.
+
+**Why it matters**: Traceability is a governance best practice. ADRs without requirement references are harder to audit, harder to assess for impact when requirements change, and may indicate decisions made without clear justification.
+
+**How to resolve**:
+
+1. Open the flagged ADR
+2. Identify which requirements motivated the decision
+3. Add references in the ADR body (e.g., "This decision addresses FR-015 and NFR-P-003")
+4. Run `/arckit:traceability` to validate the full traceability chain
+
+**Example scenario**: ADR-005 documents the decision to use PostgreSQL as the primary database. The ADR explains the reasoning well, but does not reference DR-001 (relational data storage) or NFR-P-002 (query performance <100ms). Adding these references makes the decision auditable.
+
+---
+
+### STALE-EXT — Unincorporated External Files
+
+**Severity**: HIGH
+
+**What it means**: One or more files in a project's `external/` directory have a modification time newer than the most recent `ARC-*` artifact in the same project. These external files — API specifications, compliance reports, PoC results, vendor documents — contain information that has not yet been reflected in the project's architecture artifacts.
+
+**Why it matters**: External files are placed in `external/` specifically to inform architecture decisions. When a new API spec arrives or a compliance report is updated, the existing requirements, diagrams, risk registers, and other artifacts may no longer accurately represent the current state. Governance decisions made on outdated artifacts create risk — particularly for procurement, security, and compliance.
+
+**How to resolve**:
+
+1. Review each flagged external file to understand what changed
+2. The health report includes recommended commands per file based on filename patterns (e.g., `*api*` files suggest `/arckit:requirements`, `/arckit:data-model`, `/arckit:diagram`)
+3. Re-run the recommended commands, pointing them to the new external content
+4. After updating artifacts, the external files will no longer be flagged (their mtime will be older than the newly generated artifacts)
+
+**Example scenario**: A penetration test report (`pentest-report-q1.pdf`) is added to `external/` after the security assessment was written. The existing `ARC-001-SECD-v1.0.md` does not account for the findings in the new report. The STALE-EXT finding flags this gap and recommends re-running `/arckit:secure` and `/arckit:dpia` to incorporate the pentest results.
+
+---
+
+### VERSION-DRIFT — Version Drift
+
+**Severity**: LOW
+
+**What it means**: Multiple versions of the same artifact type exist for a project, and the latest version has not been updated in over 3 months. This suggests the artifact was being actively iterated but the iteration has stalled.
+
+**Why it matters**: Version drift can indicate abandoned revisions, teams working from outdated versions, or simply a completed artifact that has accumulated old versions. The risk is low but worth periodic review.
+
+**How to resolve**:
+
+1. Check whether the latest version is still the authoritative document
+2. If the latest version is current and complete: no action needed (the age is acceptable)
+3. If older versions are superseded: consider archiving or deleting them to reduce confusion
+4. If the latest version is incomplete: either complete it or revert to the last stable version
+
+**Example scenario**: The requirements document exists in v1.0, v1.1, and v2.0. Version 2.0 was created 4 months ago during a major scope change but was never completed. The team is still referencing v1.1 without realising v2.0 exists.
+
+---
+
+## Staleness Thresholds
+
+| Finding Type | Threshold | Rationale |
+|-------------|-----------|-----------|
+| Stale Research | 6 months | Vendor pricing, SaaS features, and market conditions change materially within 6 months. Procurement decisions require current data. |
+| Forgotten ADR | 30 days | Architecture decisions should be reviewed within one or two sprint cycles. 30 days provides a generous buffer. |
+| Unresolved Conditions | Any age | Conditions are requirements for the approval to be valid. There is no safe period to defer them. |
+| Orphaned Requirements | Any age | Flagged for awareness. The architect decides whether ADR coverage is needed based on requirement complexity. |
+| Missing Traceability | Any age | Traceability is a best practice for auditability. Missing references should be added as part of regular governance hygiene. |
+| Unincorporated External Files | Any age | External files newer than all artifacts indicate content not yet reflected in governance artifacts. No safe deferral window. |
+| Version Drift | 3 months | Multiple versions indicate active iteration. Three months of inactivity suggests the iteration has stalled or been abandoned. |
+
+---
+
+## Usage Examples
+
+### Daily Hygiene Check
+
+```bash
+/arckit:health
+```
+
+Quick scan across all projects. Run this at the start of a session to see what needs attention.
+
+### Pre-Gate Check
+
+```bash
+/arckit:health PROJECT=001-payment-gateway SEVERITY=HIGH
+```
+
+Before a governance gate, check a specific project for high-severity issues only. Any HIGH findings should be resolved before proceeding.
+
+### Planning Ahead
+
+```bash
+/arckit:health SINCE=2026-06-01
+```
+
+Project forward — "what will be stale by June?" Useful for planning refresh cycles and scheduling reviews.
+
+---
+
+## Relationship to /arckit:analyze
+
+The health check and the analyse command serve different purposes:
+
+| Aspect | `/arckit:health` | `/arckit:analyze` |
+|--------|------------------|-------------------|
+| **Scope** | Cross-project staleness and hygiene | Single-project deep governance analysis |
+| **Output** | Console only (diagnostic) | Saved to `ARC-*-ANAL-*.md` (governance artifact) |
+| **Depth** | Metadata scan (dates, statuses, references) | Content analysis (quality, compliance, traceability) |
+| **Speed** | Quick (seconds) | Thorough (minutes) |
+| **Use case** | Regular hygiene, pre-gate checks | Formal governance reviews, audit preparation |
+
+**Recommended workflow**: Run `/arckit:health` frequently for quick checks. Run `/arckit:analyze` before formal gates or when the health check reveals issues that need deeper investigation.
+
+---
+
+## Customising Thresholds (Future Enhancement)
+
+A future release will support a `.arckit/health-config.yaml` file to override default thresholds:
+
+```yaml
+# .arckit/health-config.yaml (planned — not yet implemented)
+thresholds:
+  stale-research-days: 90      # Default: 180
+  forgotten-adr-days: 14       # Default: 30
+  version-drift-days: 60       # Default: 90
+
+exclude:
+  projects:
+    - 000-global               # Always excluded
+    - 999-archive              # Skip archived projects
+  types:
+    - PRES                     # Presentation decks don't need freshness checks
+```
+
+Until this is implemented, the built-in thresholds apply. If you need different thresholds, specify the `SINCE` argument to shift the baseline date.