tractorjuice/arckit-health

Artifact Health Check

You are performing a diagnostic health check across all ArcKit projects, identifying governance artifacts that need attention — stale data, forgotten decisions, unresolved conditions, broken traceability, and version drift.

This is a diagnostic command. Output goes to the console only — do NOT create a file. The health report is a point-in-time scan, not a governance artifact.

User Input

$ARGUMENTS

Arguments

PROJECT (optional): Restrict scan to a single project directory

• Example: PROJECT=001-payment-gateway
• Default: scan all projects under projects/

SEVERITY (optional): Minimum severity to report (default: LOW)

• Valid: HIGH, MEDIUM, LOW
• Example: SEVERITY=HIGH shows only high-severity findings

SINCE (optional): Override staleness baseline date (default: today)

• Valid: ISO date YYYY-MM-DD
• Useful for "what would be stale as of date X" scenarios

STALE_DRAFT_DAYS (optional): Threshold (in days) for STALE-DRAFT findings (default: 30)

• Valid: positive integer
• Example: STALE_DRAFT_DAYS=14 matches the session-start monitor's legacy threshold

---

What This Command Does

Scans the projects/ directory for all ARC-* artifacts and applies nine detection rules to identify governance health issues. Each finding is assigned a severity (HIGH, MEDIUM, or LOW) with a suggested remediation action. The hook also writes docs/health.json on every run for dashboard integration (consumed by $arckit-pages).

The STALE-DRAFT and REVIEW-OVERDUE rules are intentionally a superset of what the session-start stale-artifact-scan monitor surfaces, so the on-demand command and the background notification agree on the same set of artifacts.

This command does NOT modify any project files. It is a diagnostic tool. The only file written is docs/health.json.

Detection Rules

| ID | Rule | Severity | Threshold | |----|------|----------|-----------| | STALE-RSCH | Stale Research | HIGH | RSCH documents with created/modified date >6 months old | | FORGOTTEN-ADR | Forgotten ADR | HIGH | ADR with status "Proposed" for >30 days with no review activity | | UNRESOLVED-COND | Unresolved Conditions | HIGH | HLD/DLD review with "APPROVED WITH CONDITIONS" where conditions lack resolution evidence | | ORPHAN-REQ | Orphaned Requirements | MEDIUM | REQ documents not referenced by any ADR in the same project | | MISSING-TRACE | Missing Traceability | MEDIUM | ADR documents that do not reference any requirement (REQ, FR-xxx, NFR-xxx, BR-xxx) | | VERSION-DRIFT | Version Drift | LOW | Multiple versions of the same artifact type where the latest version is >3 months old | | STALE-EXT | Unincorporated External Files | HIGH | External file in external/ newer than all ARC-* artifacts in the same project | | REVIEW-OVERDUE | Overdue Review | HIGH | Document Control Next Review Date is in the past, on a non-DRAFT/SUPERSEDED/ARCHIVED artifact | | STALE-DRAFT | Long-running Draft | MEDIUM | Artifact with Status: DRAFT whose Last Modified (or Created Date) is >30 days old (override via STALE_DRAFT_DAYS=N) |

---

Process

Steps 1-3: Pre-processed by Hook

Note: The Health Pre-processor Hook (graph-inject.mjs, health recipe) has already completed Steps 1-3 automatically:

1. Scan Scope — identified all projects and ARC-* artifacts
2. Metadata Extraction — read every artifact and extracted dates, statuses, requirement IDs, review verdicts, and conditions
3. Rule Application — applied all 7 detection rules and generated findings with severities

The hook's hook context above contains all findings — use them directly. Do NOT re-read any artifact files. Proceed to Step 4 to format the console output.

If the hook data is not present (hook context missing), fall back to manual scanning: read each ARC-* artifact, extract Document Control fields, and apply the detection rules described below.

Rule 1: STALE-RSCH — Stale Research

Scan: All ARC-*-RSCH-*.md files

Logic:

1. Extract the created date and last modified date from the Document Control section
2. Calculate age = baseline date - last modified date (or created date if no modified date)
3. If age > 180 days (6 months): flag as HIGH severity

Rationale: Research documents contain pricing data, vendor comparisons, and market analysis that becomes unreliable after 6 months. Procurement decisions based on stale research risk cost overruns and missed alternatives.

Output per finding:

[HIGH] STALE-RSCH: {filepath}
  Last modified: {date} ({N} days ago)
  Action: Re-run $arckit-research to refresh pricing and vendor data

Rule 2: FORGOTTEN-ADR — Forgotten ADR

Scan: All ARC-*-ADR-*-*.md files

Logic:

1. Extract the status field from the ADR content
2. If status is "Proposed": a. Extract the proposed/created date b. Calculate age = baseline date - proposed date c. If age > 30 days: flag as HIGH severity

Rationale: An ADR stuck in "Proposed" status for over 30 days indicates a decision that has been raised but never reviewed. This creates architectural ambiguity — teams may proceed without a formal decision or make conflicting assumptions.

Output per finding:

[HIGH] FORGOTTEN-ADR: {filepath}
  Status: Proposed since {date} ({N} days without review)
  Action: Schedule architecture review or accept/reject the decision

Rule 3: UNRESOLVED-COND — Unresolved Review Conditions

Scan: All ARC-*-HLDR-*.md and ARC-*-DLDR-*.md files, plus review files in reviews/ subdirectories

Logic:

1. Check the overall verdict/status in the review document
2. If verdict is "APPROVED WITH CONDITIONS": a. Extract the list of conditions (typically in a "Conditions" or "Required Changes" section) b. For each condition, search for resolution evidence:
   • Keywords indicating closure: "Resolved", "Addressed", "Completed", "Condition met", "Fixed in v", "Implemented", "Mitigated", "Satisfied"
   • Follow-up documentation: A later review document, ADR, or design document that references and resolves the condition
   • Implementation evidence: If unclear whether resolution exists, flag it as unresolved AND note in output that manual architect verification is needed c. If ANY condition lacks resolution evidence: flag as HIGH severity

Rationale: "Approved with conditions" means the design can proceed but specific changes are required. If conditions are never formally resolved, the design may ship with known gaps — creating technical debt or compliance risk.

Output per finding:

[HIGH] UNRESOLVED-COND: {filepath}
  Verdict: APPROVED WITH CONDITIONS
  Unresolved conditions: {count}
  Conditions:
    - {condition 1 text}
    - {condition 2 text}
  Action: Address conditions and update review document, or schedule follow-up review

Rule 4: ORPHAN-REQ — Orphaned Requirements

Scan: All ARC-*-REQ-*.md files, cross-referenced with ARC-*-ADR-*-*.md files in the same project

Logic:

1. For each project that has a REQ document: a. Extract the list of requirement IDs from the REQ document (BR-xxx, FR-xxx, NFR-xxx, INT-xxx, DR-xxx) b. Read all ADR documents in the same project c. Search each ADR for references to any requirement ID d. Identify requirement IDs that are NOT referenced by any ADR e. If orphaned requirements exist: flag as MEDIUM severity

Note: Not all requirements need a dedicated ADR. This rule flags the gap for awareness — the architect decides whether an ADR is needed. Requirements covered by traceability matrices (TRAC) or design reviews (HLDR/DLDR) may be adequately governed without a specific ADR.

Output per finding:

[MEDIUM] ORPHAN-REQ: {project-dir}
  Requirements document: {filepath}
  Total requirements: {count}
  Requirements not referenced by any ADR: {count}
  Examples: {first 5 orphaned requirement IDs}
  Action: Review whether these requirements need architectural decisions documented as ADRs

Rule 5: MISSING-TRACE — Missing Traceability

Scan: All ARC-*-ADR-*-*.md files

Logic:

1. For each ADR document: a. Search the content for references to requirement IDs (patterns: BR-\d{3}, FR-\d{3}, NFR-\w+-\d{3}, INT-\d{3}, DR-\d{3}) b. Also check for references to REQ documents (ARC-*-REQ-*) c. If the ADR does not reference ANY requirement: flag as MEDIUM severity

Rationale: ADRs should be traceable to the requirements they address. An ADR with no requirement references may indicate a decision made without clear justification, or simply missing cross-references that should be added.

Output per finding:

[MEDIUM] MISSING-TRACE: {filepath}
  ADR title: {title from document}
  Status: {status}
  Action: Add requirement references to link this decision to specific requirements

Rule 6: VERSION-DRIFT — Version Drift

Scan: All ARC-* files, grouped by project and document type

Logic:

1. Group all artifacts by project and document type code (e.g., all REQ files for project 001)
2. For each group with multiple versions: a. Identify the latest version by version number b. Extract the last modified date of the latest version c. Calculate age = baseline date - last modified date d. If age > 90 days (3 months): flag as LOW severity

Rationale: Multiple versions of an artifact suggest active iteration. If the latest version has not been updated in over 3 months, the artifact may have been abandoned mid-revision or the team may be working from an outdated version.

Output per finding:

[LOW] VERSION-DRIFT: {project-dir}/{type}
  Versions found: {list of version numbers}
  Latest version: {filepath} (last modified: {date}, {N} days ago)
  Action: Confirm the latest version is current, or archive superseded versions

Rule 7: STALE-EXT — Unincorporated External Files

Scan: All files in projects/*/external/ directories (including 000-global/external/)

Logic:

1. For each project that has an external/ directory: a. Find the newest ARC-* artifact modification time across the project directory and its subdirectories (decisions/, diagrams/, wardley-maps/, data-contracts/, reviews/) b. For each file in external/ (excluding README.md):
   • Compare the file's modification time against the newest artifact modification time
   • If the external file is newer than the newest artifact (or no artifacts exist): flag as HIGH severity
2. For each flagged file, match the filename against known patterns to recommend specific commands:

| Pattern | Recommended Commands | |---------|---------------------| | *api*, *swagger*, *openapi* | $arckit-requirements, $arckit-data-model, $arckit-diagram | | *schema*, *erd*, *.sql | $arckit-data-model, $arckit-data-mesh-contract | | *security*, *pentest*, *vuln* | $arckit-secure, $arckit-dpia | | *compliance*, *audit* | $arckit-tcop, $arckit-conformance | | *cost*, *pricing*, *budget* | $arckit-sobc, $arckit-finops | | *pipeline*, *ci*, *deploy* | $arckit-devops | | *rfp*, *itt*, *tender* | $arckit-sow, $arckit-evaluate | | *risk*, *threat* | $arckit-risk, $arckit-secure | | *policy*, *standard* | $arckit-principles, $arckit-tcop | | (default) | $arckit-requirements, $arckit-analyze |

Rationale: External files (PoC results, API specs, compliance reports, vendor documents) are placed in external/ to inform architecture decisions. If these files are newer than all existing artifacts, the architecture may not yet reflect their content — creating a governance gap.

Output per finding:

[HIGH] STALE-EXT: {project-dir}
  Unincorporated external files: {count}
  Files:
    - {filename} → Recommended: {matched commands}
    - {filename} → Recommended: {matched commands}
  Action: Re-run recommended commands to incorporate external file content into architecture artifacts

Rule 8: REVIEW-OVERDUE — Overdue Review

Scan: All ARC-* artifacts in scanned projects

Logic:

1. Read the Document Control Next Review Date field
2. If the date parses as YYYY-MM-DD and is before the baseline date: flag as HIGH severity
3. Skip artifacts whose Status is DRAFT, SUPERSEDED, or ARCHIVED — a review schedule is not meaningful for not-yet-approved or retired artifacts

Rationale: The review cycle is a governance commitment captured in Document Control. An overdue review on an approved or published artifact means the team has missed a planned reassurance gate — the artifact may now be out of date with reality but is still being treated as authoritative.

Output per finding:

[HIGH] REVIEW-OVERDUE: {filepath}
  Next Review Date: {date} ({N} days overdue, status: {status})
  Action: Run the review, bump the version with refreshed Document Control dates, or archive the artifact

Rule 9: STALE-DRAFT — Long-running Draft

Scan: All ARC-* artifacts with Status: DRAFT

Logic:

1. Extract the Document Control Status field
2. If status is DRAFT: a. Extract Last Modified (or Created Date if missing) b. Calculate age = baseline date − that date c. If age > STALE_DRAFT_DAYS (default 30): flag as MEDIUM severity

Rationale: A DRAFT artifact that hasn't been touched for over a month is usually one of three things — stalled work, abandoned scaffolding, or a decision that has been silently overtaken by events. Either way, it's a governance signal worth surfacing.

Output per finding:

[MEDIUM] STALE-DRAFT: {filepath}
  Status: DRAFT, unchanged since {date} ({N} days ago, threshold {threshold})
  Action: Promote to IN_REVIEW/APPROVED, bump the version, or archive the draft

Step 4: Compile Health Report

Produce the health report as console output only (do NOT write a file). Structure the report as follows:

4.1: Summary Table

========================================
  ArcKit Artifact Health Report
  Scanned: {date}
  Projects scanned: {count}
  Artifacts scanned: {count}
========================================

SUMMARY
-------
  HIGH:   {count} findings
  MEDIUM: {count} findings
  LOW:    {count} findings
  TOTAL:  {count} findings

FINDINGS BY TYPE
----------------
  STALE-RSCH:       {count}
  FORGOTTEN-ADR:    {count}
  UNRESOLVED-COND:  {count}
  STALE-EXT:        {count}
  REVIEW-OVERDUE:   {count}
  ORPHAN-REQ:       {count}
  MISSING-TRACE:    {count}
  STALE-DRAFT:      {count}
  VERSION-DRIFT:    {count}

4.2: Findings by Project

Group findings by project directory, then by finding type within each project.

For each project:

PROJECT: {project-dir}
  Artifacts scanned: {count}

  [HIGH] STALE-RSCH: research/ARC-001-RSCH-001-v1.0.md
    Last modified: 2025-06-15 (250 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 (81 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

  ... (continue for all findings in this project)

If a project has no findings:

PROJECT: {project-dir}
  Artifacts scanned: {count}
  No issues found.

4.3: Recommended Actions

At the end of the report, provide a prioritised action list:

RECOMMENDED ACTIONS (prioritised)
----------------------------------

1. [HIGH] Address {count} stale research documents
   Run: $arckit-research for affected projects
   Why: Pricing data older than 6 months is unreliable for procurement decisions

2. [HIGH] Review {count} forgotten ADRs
   Schedule architecture review meetings for proposed decisions >30 days old
   Why: Unresolved decisions create architectural ambiguity

3. [HIGH] Resolve {count} review conditions
   Update review documents with resolution evidence
   Why: Unresolved conditions may indicate unaddressed design gaps

4. [HIGH] Incorporate {count} new external files
   Run the recommended commands listed per file to update architecture artifacts
   Why: External files (API specs, compliance reports, PoC results) contain information not yet reflected in governance artifacts

5. [HIGH] Run {count} overdue reviews
   For each flagged artifact, run the appropriate review command and bump the version
   Why: A missed review on an approved artifact means the assurance gate has lapsed — the artifact is being trusted without current evidence

6. [MEDIUM] Check {count} orphaned requirements
   Run: $arckit-adr for requirements needing architectural decisions
   Why: Requirements without ADR coverage may lack governance

7. [MEDIUM] Add traceability to {count} ADRs
   Update ADRs with requirement references
   Run: $arckit-traceability to generate full traceability matrix
   Why: Untraceable decisions reduce audit confidence

8. [MEDIUM] Resolve {count} long-running drafts
   Promote DRAFT artifacts to IN_REVIEW/APPROVED, bump the version, or archive them
   Why: Drafts unchanged for over a month usually indicate stalled or abandoned work

9. [LOW] Review {count} artifacts with version drift
   Confirm latest versions are current or archive old versions
   Why: Stale multi-version artifacts may indicate abandoned work

4.4: Clean Report

If no findings are detected across all projects:

========================================
  ArcKit Artifact Health Report
  Scanned: {date}
  Projects scanned: {count}
  Artifacts scanned: {count}
========================================

All clear. No stale artifacts, forgotten decisions, or traceability gaps detected.

Step 5: JSON Output (automatic)

The hook automatically writes docs/health.json on every run. No action is needed from the command for JSON output.

Dashboard integration: Run $arckit-pages after the health check to see health data on the governance dashboard.

JSON schema (written by hook to docs/health.json):

{
  "generated": "2026-02-20T14:30:00Z",
  "scanned": {
    "projects": 3,
    "artifacts": 42
  },
  "summary": {
    "HIGH": 2,
    "MEDIUM": 5,
    "LOW": 1,
    "total": 8
  },
  "byType": {
    "STALE-RSCH": 1,
    "FORGOTTEN-ADR": 1,
    "UNRESOLVED-COND": 0,
    "STALE-EXT": 0,
    "ORPHAN-REQ": 3,
    "MISSING-TRACE": 2,
    "VERSION-DRIFT": 1,
    "REVIEW-OVERDUE": 0,
    "STALE-DRAFT": 0
  },
  "projects": [
    {
      "id": "001-project-name",
      "artifacts": 15,
      "findings": [
        {
          "severity": "HIGH",
          "rule": "STALE-RSCH",
          "file": "research/ARC-001-RSCH-001-v1.0.md",
          "message": "Last modified: 2025-06-15 (250 days ago)",
          "action": "Re-run $arckit-research to refresh pricing and vendor data"
        }
      ]
    }
  ]
}

Field definitions:

• generated — ISO 8601 timestamp of when the scan was run
• scanned.projects — number of projects scanned
• scanned.artifacts — total number of artifacts scanned across all projects
• summary — finding counts by severity level (HIGH, MEDIUM, LOW) plus total
• byType — finding counts per detection rule (always include all 9 rule IDs, using 0 for rules with no findings)
• projects[] — per-project breakdown; each entry includes the project directory ID, artifact count, and an array of findings
• Each finding includes: severity, rule (detection rule ID), file (artifact filename), message (human-readable detail), and action (suggested remediation)

---

Error Handling

No projects directory:

No projects/ directory found. Run $arckit-init to create your first project.

No artifacts found:

No ARC-* artifacts found in projects/. Generate artifacts using /arckit commands first.

Single project specified but not found:

Project directory not found: projects/{PROJECT}
Available projects:
  - 001-payment-gateway
  - 002-data-platform

---

Examples

Example 1: Scan All Projects

$arckit-health

Scans every project under projects/ and reports all findings.

Example 2: Scan a Specific Project

$arckit-health PROJECT=001-payment-gateway

Scans only the specified project.

Example 3: Show Only High-Severity Issues

$arckit-health SEVERITY=HIGH

Filters output to show only HIGH severity findings.

Example 4: Check Staleness as of a Future Date

$arckit-health SINCE=2026-06-01

Useful for planning — "what will be stale by June?"

Example 5: Repeat Monitoring

$arckit-health SEVERITY=HIGH

Re-run this health check periodically during long architecture sessions to surface HIGH severity findings as artifacts change. Codex does not provide a built-in loop command; use a scheduler if you need automation.

---

Integration with Other Commands

Run After

• $arckit-analyze — health check complements the deeper governance analysis
• Any artifact creation — verify new artifacts don't introduce drift

Triggers For

• $arckit-research — refresh stale RSCH documents
• $arckit-adr — create ADRs for orphaned requirements
• $arckit-traceability — fix missing traceability links
• $arckit-hld-review or $arckit-dld-review — follow up on unresolved conditions
• Various commands per STALE-EXT findings — incorporate new external files (see filename-to-command mapping)

---

Design Notes

Why Console Output as Primary?

The health check is a diagnostic tool, not a governance artifact. Unlike $arckit-analyze which produces a formal analysis report (saved as ARC-*-ANAL-*.md), the health check is:

• Ephemeral: Results change every time you run it
• Actionable: Designed to trigger other commands, not to be filed
• Lightweight: Quick scan, not a deep analysis
• Repeatable: Run it daily, weekly, or before any governance gate

Console output is the primary user-facing output. docs/health.json is always written as a side effect for dashboard integration ($arckit-pages).

Threshold Rationale

| Threshold | Value | Rationale | |-----------|-------|-----------| | Research staleness | 6 months | Vendor pricing and SaaS feature sets change significantly within 6 months; procurement decisions require current data | | ADR forgotten | 30 days | Architecture decisions should be reviewed within a sprint cycle; 30 days is generous | | Review conditions | Any age | Unresolved conditions are a blocker regardless of age; there is no safe window to ignore them | | Requirements orphaned | Any age | Flagged for awareness, not urgency; architect decides if ADR coverage is needed | | ADR traceability | Any age | Traceability is a governance best practice; missing references should be added when convenient | | Version drift | 3 months | Multiple versions indicate active iteration; 3 months of inactivity suggests the iteration has stalled | | External file staleness | Any age | External files newer than all artifacts indicate unincorporated content; no safe window to ignore since governance may be based on outdated information | | Review overdue | Any past date | The review cycle is a governance commitment captured at creation; once the date passes, the assurance gate has lapsed regardless of how recently | | Draft staleness | 30 days | Long enough that "actively iterating" is no longer plausible; matches the session-start monitor so both surfaces agree (override via STALE_DRAFT_DAYS) |

Future Enhancements

• Custom thresholds: Allow .arckit/health-config.yaml to override default thresholds
• Trend tracking: Compare current scan against previous scan to show improvement/regression
• CI integration: Exit code 1 if HIGH findings exist (for pipeline gates)

Important Notes

• Markdown escaping: When writing less-than or greater-than comparisons, always include a space after < or > (e.g., < 3 seconds, > 99.9% uptime) to prevent markdown renderers from interpreting them as HTML tags or emoji