You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .archcore/plugin/actualize-implementation.plan.md
+40-58Lines changed: 40 additions & 58 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,9 +8,11 @@ tags:
8
8
- "skills"
9
9
---
10
10
11
+
> **Outcome (2026-05-15):** Plan executed. Layer 1 (`bin/check-staleness`) and Layer 2 (`bin/check-cascade`) shipped as designed. Layer 3 (deep analysis) shipped as the `--drift` mode of `/archcore:audit` rather than as a standalone `/archcore:actualize` intent skill, per `skill-surface-collapse.adr.md`. The drift-mode protocol lives at `skills/audit/lib/drift-detection.md`. All acceptance criteria below are met under the new naming.
12
+
11
13
## Goal
12
14
13
-
Implement the 3-layer Actualize system for documentation freshness detection as specified in the Actualize System ADR and Specification. Deliver all components: two new bin scripts (check-staleness, check-cascade), updated session-start script, updated hooks.json, new `/archcore:actualize` intent skill, and updated `/archcore:help` skill.
15
+
Implement the 3-layer Actualize system for documentation freshness detection as specified in the Actualize System ADR and Specification. Deliver all components: two new bin scripts (check-staleness, check-cascade), updated session-start script, updated hook configs, deep-analysis mode in the appropriate audit/inspection skill, and updated `/archcore:help` skill.
14
16
15
17
## Tasks
16
18
@@ -29,22 +31,13 @@ Logic:
29
31
5. If no changes → exit 0
30
32
6. Count changed files
31
33
7. For each `.archcore/*.md` document: grep for directory references from changed files
32
-
8. Output formatted warning (max 2KB)
34
+
8. Output formatted warning (max 2KB), rate-limited to once per 24 hours
33
35
34
36
Files: `bin/check-staleness` (new, ~50 lines)
35
37
36
38
**1.2 Extend `bin/session-start`**
37
39
38
-
Add call to `bin/check-staleness` after the successful `archcore hooks claude-code session-start` line. The staleness output is appended to the session context.
Add call to `bin/check-staleness` after the successful `archcore hooks <host> session-start` line. The staleness output is appended to the session context.
48
41
49
42
Files: `bin/session-start` (edit, ~5 lines added)
50
43
@@ -64,67 +57,55 @@ Logic:
64
57
6. Extract document title from tool result or path
65
58
7. Output JSON with `hookSpecificOutput.additionalContext` listing affected documents
66
59
67
-
Note: Reads `.sync-state.json` directly (faster than CLI call, within 3s budget). This file is always present and updated by MCP tools.
68
-
69
60
Files: `bin/check-cascade` (new, ~60 lines)
70
61
71
-
**2.2 Update `hooks/hooks.json`**
62
+
**2.2 Update hook configs**
72
63
73
-
Add new PostToolUse entry for cascade detection:
64
+
Add new PostToolUse entry for cascade detection across all hosts:
### Phase 3: Layer 3 — Deep Analysis (drift mode of audit)
95
76
96
-
New Layer 1 intent skill for comprehensive staleness analysis.
77
+
**3.1 Move drift protocol into the audit skill**
97
78
98
-
Frontmatter:
79
+
Per `skill-surface-collapse.adr.md`, Layer 3 ships as the `--drift` mode of `/archcore:audit`. Originally this phase was scoped to a new `skills/actualize/SKILL.md`; the same content (routing table, 3-dimension analysis, assisted-fix flow) now lives at `skills/audit/lib/drift-detection.md` and is loaded by `skills/audit/SKILL.md` on `--drift`.
99
80
100
-
-`name: actualize`
101
-
-`argument-hint: "[scope: tag, category, or 'all']"`
102
-
-`description: Detect stale documentation and suggest updates based on code changes and relation graph.`
81
+
Frontmatter for `audit`:
103
82
104
-
Note: under the Inverted Invocation Policy (adopted after this plan was drafted), intent skills are auto-invocable and do NOT carry `disable-model-invocation`. The actualize skill follows that policy as shipped.
83
+
-`name: audit`
84
+
-`argument-hint: "[--deep] [--drift] [category, tag, or scope]"`
85
+
-`description: "Audit Archcore docs: dashboard (counts, status, relations, orphans), deep coverage audit, or drift detection (code/cascade/temporal staleness)."`
Copy file name to clipboardExpand all lines: .archcore/plugin/actualize-system.adr.md
+23-11Lines changed: 23 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,17 +8,19 @@ tags:
8
8
- "skills"
9
9
---
10
10
11
+
> **Outcome (2026-05-15):** Decision accepted as-is, but Layer 3 shipped as the `--drift` mode of `/archcore:audit` rather than as a standalone `/archcore:actualize` intent skill (see `skill-surface-collapse.adr.md`). The 3-layer architecture, detection dimensions, and naming rationale below remain authoritative; substitute `/archcore:audit --drift` for `/archcore:actualize` throughout.
12
+
11
13
## Context
12
14
13
-
The Archcore Claude Plugin has a comprehensive validation system (PreToolUse blocking, PostToolUse validation via `archcore doctor`) that ensures **structural integrity** of `.archcore/` documents. The `/archcore:review` skill provides on-demand health checks for coverage gaps, relation health, and status issues.
15
+
The Archcore Plugin has a comprehensive validation system (PreToolUse blocking, PostToolUse validation via `archcore doctor`) that ensures **structural integrity** of `.archcore/` documents. The `/archcore:audit` skill (formerly `/archcore:review`) provides on-demand health checks for coverage gaps, relation health, and status issues.
14
16
15
-
However, no mechanism detects when documentation **content becomes stale**. Three types of staleness go undetected:
17
+
However, no mechanism detected when documentation **content becomes stale**. Three types of staleness went undetected:
16
18
17
19
1.**Document cascade**: Updating document A while documents that `implements`, `depends_on`, or `extends` A remain unchanged. Example: PRD is rewritten but the plan that `implements` it still describes the old scope.
18
20
2.**Code-document drift**: Source code changes that invalidate assumptions, APIs, or patterns described in archcore documents. Example: auth module is refactored but the ADR still describes the old JWT strategy.
19
21
3.**Temporal staleness**: Documents stuck in inappropriate statuses — long-lived drafts, plans with passed deadlines, rejected documents still referenced in active chains.
20
22
21
-
Currently, staleness is only discovered during manual `/archcore:review` invocations or when someone happens to read an outdated document. There is no proactive or reactive detection.
23
+
At the time this ADR was drafted, staleness was only discovered during manual audit invocations or when someone happened to read an outdated document. There was no proactive or reactive detection.
22
24
23
25
## Decision
24
26
@@ -36,23 +38,25 @@ Extend `bin/session-start` to run a lightweight git-based staleness check at eve
36
38
37
39
Add cascade detection logic to the PostToolUse hook pipeline. After `mcp__archcore__update_document`, query the relation graph for documents connected to the updated document via `implements`, `depends_on`, or `extends` relations (where the updated document is the target). Inject a cascade warning naming potentially affected documents.
38
40
39
-
**Mechanism**: Parse updated document path from tool input, query `archcore` CLI for relations, filter by directional relation types.
41
+
**Mechanism**: Parse updated document path from tool input, query the `.sync-state.json` relation graph, filter by directional relation types.
40
42
41
43
**Character**: Informational only. Injected as `additionalContext` after the update succeeds. Never blocks operations.
42
44
43
-
### Layer 3 — Deep Analysis (/archcore:actualize intent skill)
45
+
### Layer 3 — Deep Analysis (drift mode of /archcore:audit)
44
46
45
-
Add an 8th Layer 1 intent skill that performs comprehensive staleness analysis on demand. Three detection dimensions:
47
+
Add comprehensive staleness analysis on demand. Three detection dimensions:
46
48
47
49
-**Code→Doc drift**: For each document, find referenced code paths in content, check `git log` for changes since document was last modified.
48
50
-**Doc→Doc cascade**: For recently updated documents, traverse the relation graph to find stale dependents.
49
51
-**Temporal**: Draft documents older than 30 days, accepted plans with past deadlines, rejected documents still in active relation chains.
50
52
51
53
Offers interactive assisted fixes via MCP `update_document`.
52
54
55
+
> When this ADR was originally drafted, Layer 3 was to ship as a standalone `/archcore:actualize` intent skill (8th primary command). It later shipped as the `--drift` mode of the unified `/archcore:audit` skill per `skill-surface-collapse.adr.md`.
56
+
53
57
### Naming
54
58
55
-
The skill is named `actualize` because:
59
+
The system is called Actualize because:
56
60
-`refresh` implies reloading data, not content analysis
-`update` conflicts with `update_document` MCP tool name
@@ -78,17 +82,17 @@ When document A is updated, which documents may be stale?
78
82
79
83
## Alternatives Considered
80
84
81
-
### Only enhance /archcore:review
85
+
### Only enhance /archcore:audit (dashboard/deep modes)
82
86
83
-
Add staleness checks to the existing review skill. **Rejected**: review is on-demand only — no passive or reactive detection. Users must remember to run it. The actualize system catches staleness automatically.
87
+
Add staleness checks to the existing audit skill's dashboard or `--deep` mode. **Initially rejected** because review/audit was on-demand only — no passive or reactive detection. The actualize system catches staleness automatically via hooks. **Later partially reconsidered**: Layer 3 of this decision was folded into `/archcore:audit --drift` per `skill-surface-collapse.adr.md`, but Layer 1 and Layer 2 (the hook-driven detection) remained separate as designed.
84
88
85
89
### Background polling via /loop
86
90
87
91
Use Claude Code's `/loop` command to periodically check for staleness. **Rejected**: requires a persistent session open in terminal, wasteful of resources, and stops when the user closes the terminal.
88
92
89
93
### MCP-side staleness check
90
94
91
-
Add `check_staleness` command to the archcore CLI itself. **Deferred, not rejected**: good for cross-tool portability (works in any IDE plugin, not just Claude Code). The plugin-side implementation delivers value now without CLI changes. If the CLI adds this later, the hook can delegate to it.
95
+
Add `check_staleness` command to the archcore CLI itself. **Deferred, not rejected**: good for cross-tool portability. The plugin-side implementation delivers value now without CLI changes. If the CLI adds this later, the hook can delegate to it.
92
96
93
97
### Git pre-commit hook (outside Claude Code)
94
98
@@ -110,4 +114,12 @@ Check staleness before git commits. **Rejected**: wrong timing — by the time t
110
114
-**Heuristic false positives**: File-path matching in Layer 1 may flag documents that reference a directory where unrelated files changed. Acceptable tradeoff — false positives are informational nudges, not errors.
111
115
-**SessionStart latency**: Layer 1 adds ~1-2 seconds to session startup for git operations. Acceptable — already within the 3-second budget and user expects startup to load context.
112
116
-**PostToolUse overhead**: Layer 2 adds relation graph query after every `update_document`. Must complete within existing 3-second timeout.
113
-
-**Skill count increase**: Layer 1 intent skills go from 7 to 8. Requires updating plugin-architecture.spec, skills-system.spec, and commands-system.spec constraints.
117
+
-**Skill surface**: When this ADR was drafted, the cost was "Layer 1 intent skills go from 7 to 8." That cost was later eliminated by folding Layer 3 into the existing `audit` skill as `--drift`.
118
+
119
+
### Supersedes
120
+
121
+
- (none — this is a net addition to the plugin)
122
+
123
+
### Superseded by (partially)
124
+
125
+
- The standalone `/archcore:actualize` skill described in this ADR was superseded by `skill-surface-collapse.adr.md`. Layer 3 ships as `/archcore:audit --drift`; Layers 1 and 2 remain as designed.
0 commit comments