@windyroad/itil 0.19.3-preview.198 → 0.19.4-preview.200
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -162,6 +162,23 @@ What "work" means depends on the problem's status:
|
|
|
162
162
|
|
|
163
163
|
## Steps
|
|
164
164
|
|
|
165
|
+
### 0. README reconciliation preflight (P118)
|
|
166
|
+
|
|
167
|
+
Before parsing the request, run the diagnose-only reconciliation check. The contract here catches **cross-session drift** that per-operation refresh paths (P094 refresh-on-create + P062 refresh-on-transition) cannot retroactively see — if any past session committed a ticket change without staging the README refresh, the next manage-problem invocation reads a stale README that lies about what is open / verifying / closed.
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
bash packages/itil/scripts/reconcile-readme.sh docs/problems
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Exit-code routing:
|
|
174
|
+
- **Exit 0 (clean)**: continue to Step 1.
|
|
175
|
+
- **Exit 1 (drift detected)**: structured diff lines printed to stdout, one per drift entry (≤150 bytes per ADR-038 progressive-disclosure budget). **Halt this invocation** with a directive to invoke `/wr-itil:reconcile-readme` (interactive mode) or auto-route through the same skill in non-interactive mode (per ADR-013 Rule 6, AFK orchestrator). The reconciliation must complete and commit before this manage-problem invocation proceeds — proceeding into ticket creation / update / transition with a stale README would re-encode the drift into the post-operation refresh and propagate the lie.
|
|
176
|
+
- **Exit 2 (parse error)**: README missing or malformed. Halt with the parse-error message; this needs investigation, not mechanical reconciliation. AFK orchestrators halt-with-report per ADR-013 Rule 6.
|
|
177
|
+
|
|
178
|
+
This is a **preflight CHECK only** — manage-problem does NOT itself apply edits. The edit application lives in `/wr-itil:reconcile-readme`'s Step 4 with narrative preservation. Per architect verdict on P118 (Q3): manage-problem and work-problems Step 0 invoke the script (cheap mechanical check); transition-problem does NOT (P062 already covers transition-time refresh inside the same commit, redundant preflight there would pay the cost on every transition).
|
|
179
|
+
|
|
180
|
+
This step is a robustness layer ON TOP of P094 + P062, not a supersession of either — both per-operation contracts remain in force at Step 5 (creation refresh) and Step 7 (transition refresh).
|
|
181
|
+
|
|
165
182
|
### 1. Parse the request
|
|
166
183
|
|
|
167
184
|
Determine the operation from `$ARGUMENTS`:
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: wr-itil:reconcile-readme
|
|
3
|
+
description: Detect and correct drift between docs/problems/README.md and the on-disk ticket inventory. Wraps the diagnose-only `packages/itil/scripts/reconcile-readme.sh` script with an agent-applied-edits pattern that preserves narrative content (the "Last reviewed" prose paragraph and Closed-section closure-via free text). Use when README WSJF Rankings, Verification Queue, or Closed sections drift from filesystem state — typically detected by manage-problem Step 0 preflight or work-problems Step 0 preflight.
|
|
4
|
+
allowed-tools: Read, Edit, Write, Bash, Grep, Glob
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Reconcile Problem Backlog README
|
|
8
|
+
|
|
9
|
+
Reconcile `docs/problems/README.md` against on-disk ticket state when drift is detected. This is the cross-session robustness layer ON TOP of P094 (refresh-on-create) and P062 (refresh-on-transition). Both per-operation contracts hold their per-session evidence — but if any past session committed a ticket change without staging the README refresh, the next session inherits a stale README that no per-operation contract retroactively fixes.
|
|
10
|
+
|
|
11
|
+
This skill closes that gap. It runs the diagnose-only mechanical drift detector, then applies the corrections to the README in a way that preserves human-curated narrative content.
|
|
12
|
+
|
|
13
|
+
## Scope
|
|
14
|
+
|
|
15
|
+
Reconcile drift between `docs/problems/README.md` and these on-disk ticket states:
|
|
16
|
+
|
|
17
|
+
| File suffix | Belongs in README section | Drift class |
|
|
18
|
+
|------------|---------------------------|-------------|
|
|
19
|
+
| `*.open.md` / `*.known-error.md` | WSJF Rankings | MISSING (file exists, row absent) or DRIFT (row claims wrong status) |
|
|
20
|
+
| `*.verifying.md` | Verification Queue | MISSING (file exists, row absent) or DRIFT (WSJF Rankings row stale) |
|
|
21
|
+
| `*.closed.md` | Closed (curated, not exhaustive) | MISMATCH (Closed row points to wrong-status file) or STALE (still in WSJF / VQ) |
|
|
22
|
+
| `*.parked.md` | Parked (own section) | not enforced — Parked is its own narrative table |
|
|
23
|
+
|
|
24
|
+
Out of scope:
|
|
25
|
+
- Re-rating WSJF or Effort. The script trusts each ticket file's stored values; re-ranking happens in `/wr-itil:review-problems`.
|
|
26
|
+
- Editing ticket file bodies. Reconciliation is README-only.
|
|
27
|
+
- Migrating between status suffixes. That belongs in `/wr-itil:transition-problem`.
|
|
28
|
+
|
|
29
|
+
## When invoked
|
|
30
|
+
|
|
31
|
+
Three invocation surfaces, all routed through this skill so the agent-applied-edits logic stays single-sourced:
|
|
32
|
+
|
|
33
|
+
1. **Direct user invocation**: `claude /wr-itil:reconcile-readme` — interactive when the user spots drift in the README.
|
|
34
|
+
2. **Manage-problem Step 0 preflight halt**: when `/wr-itil:manage-problem` Step 0 detects drift via the script, it halts with a directive to invoke this skill (interactive) or auto-applies via this skill in non-interactive mode (AFK orchestrator per ADR-013 Rule 6).
|
|
35
|
+
3. **Work-problems Step 0 preflight halt**: when `/wr-itil:work-problems` Step 0 detects drift via the script, the same halt-with-directive / auto-apply behaviour applies.
|
|
36
|
+
|
|
37
|
+
## Steps
|
|
38
|
+
|
|
39
|
+
### Step 1. Run the diagnose-only script
|
|
40
|
+
|
|
41
|
+
Invoke the mechanical drift detector:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
bash packages/itil/scripts/reconcile-readme.sh docs/problems
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Exit codes:
|
|
48
|
+
- `0` — clean. No drift; nothing to do. Report "Reconciliation: clean (0 drift entries)" and exit.
|
|
49
|
+
- `1` — drift detected. The script prints one structured row per drift entry to stdout (each ≤ 150 bytes per ADR-038 progressive-disclosure budget). Continue to Step 2.
|
|
50
|
+
- `2` — parse error. README is missing, malformed, or section headers are absent. Halt with the parse-error message; this is a deeper repair that needs investigation, not mechanical reconciliation. In AFK mode (ADR-013 Rule 6), halt-with-report; do not attempt edits.
|
|
51
|
+
|
|
52
|
+
### Step 2. Bucket the drift entries by section
|
|
53
|
+
|
|
54
|
+
Each drift line is one of four shapes:
|
|
55
|
+
|
|
56
|
+
| Marker | Meaning | Required edit |
|
|
57
|
+
|--------|---------|---------------|
|
|
58
|
+
| `DRIFT P<NNN> wsjf-rankings: claims=open actual=<X>` | README WSJF Rankings row claims Open but file is `<X>` | REMOVE the row from WSJF Rankings; if `<X>=verifying`, ADD to Verification Queue; if `<X>=closed`, optionally ADD to Closed |
|
|
59
|
+
| `MISSING P<NNN> wsjf-rankings: actual=<X>` | File exists as `.open.md` / `.known-error.md`; row absent from WSJF Rankings | ADD a row to WSJF Rankings, sourced from the ticket file's `**WSJF**`, `**Priority**`, `**Effort**`, `**Status**`, and `# Problem <NNN>: <title>` line |
|
|
60
|
+
| `MISSING P<NNN> verification-queue: actual=verifying` | File exists as `.verifying.md`; row absent from Verification Queue | ADD a row to Verification Queue, sourced from the ticket file's `## Fix Released` marker (release marker + date) and title |
|
|
61
|
+
| `STALE P<NNN> verification-queue: actual=<X>` | Row in Verification Queue but file is `<X>` (typically `closed`) | REMOVE the row from Verification Queue |
|
|
62
|
+
| `MISMATCH P<NNN> closed: actual=<X>` | Row in Closed section names a non-`.closed.md` file | REMOVE the row from Closed (or fix the ID — investigate) |
|
|
63
|
+
|
|
64
|
+
### Step 3. Read the affected ticket files for ADD edits
|
|
65
|
+
|
|
66
|
+
For each `MISSING` entry, read the ticket file to extract the row data:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
# For WSJF Rankings ADD:
|
|
70
|
+
grep -E '^\*\*(Status|Priority|Effort|WSJF)\*\*:' docs/problems/<NNN>-*.open.md
|
|
71
|
+
grep -E '^# Problem <NNN>:' docs/problems/<NNN>-*.open.md
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Render the WSJF Rankings row in the existing format:
|
|
75
|
+
|
|
76
|
+
```
|
|
77
|
+
| <WSJF> | P<NNN> | <title> | <severity> | <status> | <effort> |
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
For each `MISSING` Verification Queue entry, read the `## Fix Released` block:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
sed -n '/^## Fix Released/,/^## /p' docs/problems/<NNN>-*.verifying.md
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Render the Verification Queue row in the existing format:
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
| P<NNN> | <title> | <release marker> | <Likely verified? per P048 Candidate 4: yes if ≥14 days, else no (<N> days)> |
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Step 4. Apply edits via Edit tool — preserve narrative
|
|
93
|
+
|
|
94
|
+
This is the load-bearing step. Use the `Edit` tool to apply each row-level change. DO NOT regenerate the entire README from scratch — the long "Last reviewed: ..." prose paragraph at the top, and the per-Closed-row free-text closure-via column, are human-curated narrative that a full regeneration would destroy.
|
|
95
|
+
|
|
96
|
+
For each REMOVE: `Edit` with the existing row as `old_string`, and remove it (replace with empty string) or replace with a re-positioned row in another section (REMOVE-from-WSJF-Rankings + ADD-to-Verification-Queue is two Edit operations: one to delete the WSJF row, one to insert the VQ row).
|
|
97
|
+
|
|
98
|
+
For each ADD to WSJF Rankings: locate the correct WSJF position by descending order. Use `Edit` to insert the new row immediately above the next-lower-WSJF row (or append at the bottom of the table if the new row's WSJF is the lowest). The Edit's `old_string` is the line that the new row inserts above; the `new_string` is the new row + the same line below.
|
|
99
|
+
|
|
100
|
+
For each ADD to Verification Queue: append at the bottom of the VQ table (the table is loosely sorted by release age, oldest first; recent releases land at the bottom).
|
|
101
|
+
|
|
102
|
+
After all edits, re-run `packages/itil/scripts/reconcile-readme.sh docs/problems` to confirm exit 0. If the second run still reports drift, investigate the residual edits — do NOT re-run reconciliation in a loop, as that hides systematic edit failures.
|
|
103
|
+
|
|
104
|
+
### Step 5. Update the "Last reviewed" annotation
|
|
105
|
+
|
|
106
|
+
Prepend (or append, per existing convention — the README uses a single ever-growing prose paragraph) a short note to the "Last reviewed:" paragraph of the form:
|
|
107
|
+
|
|
108
|
+
> 2026-MM-DD **README reconciled** — (N) drift entries corrected: <comma-separated ID list>. Reconciliation contract per P118 + ADR-014 amended ("Reconciliation as preflight robustness layer").
|
|
109
|
+
|
|
110
|
+
Keep the note ≤ 200 bytes; the long narrative form belongs in retros and ADR amendments, not in this annotation. Do not re-write the existing prose.
|
|
111
|
+
|
|
112
|
+
### Step 6. Commit (when invoked from an AFK orchestrator subprocess)
|
|
113
|
+
|
|
114
|
+
In AFK mode (per ADR-013 Rule 6), commit the reconciled README in a dedicated single-purpose commit:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
git add docs/problems/README.md
|
|
118
|
+
git commit -m "chore(problems): reconcile README against filesystem (P118)"
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
When invoked interactively, do NOT auto-commit — present a diff summary to the user and let them stage + commit. The reconciled state should always be staged together (no partial reconciliation) — when the agent has applied N edits in Step 4, all N belong in the same commit.
|
|
122
|
+
|
|
123
|
+
## ADR alignment
|
|
124
|
+
|
|
125
|
+
- **ADR-014** (governance skills commit their own work) — amended to add "Reconciliation as preflight robustness layer" sub-rule. P094 and P062 cover per-operation refresh; this skill covers cross-session drift detection + correction.
|
|
126
|
+
- **ADR-022** (Verification Pending lifecycle status conventions) — Confirmation criterion 3 extended to "and matches the Verification Queue table in `README.md` modulo narrative content".
|
|
127
|
+
- **ADR-038** (Progressive disclosure for governance tooling context) — script output is per-row terse (≤150 bytes per drift entry); the agent expands narrative-aware edits on demand.
|
|
128
|
+
- **ADR-005** (Plugin testing strategy) — script-level bats lives at `packages/itil/scripts/test/reconcile-readme.bats`; ADR-037 (skill testing) governs this skill's own contract bats.
|
|
129
|
+
- **ADR-013** (Structured interaction) — Rule 6 (non-interactive fail-safe) governs the AFK auto-apply branch.
|
|
130
|
+
|
|
131
|
+
## Confirmation
|
|
132
|
+
|
|
133
|
+
This skill's contract holds when:
|
|
134
|
+
1. The script `packages/itil/scripts/reconcile-readme.sh` is read-only — no live README mutation in the script layer (mutation only in this skill's Step 4, via the Edit tool).
|
|
135
|
+
2. Each agent-applied edit preserves the README's narrative content (prose paragraph at top, Closed section free text).
|
|
136
|
+
3. After Step 4 + Step 5, a re-run of the script reports exit 0 (clean).
|
|
137
|
+
4. In AFK mode, the reconciled README rides a single commit (Step 6 single-purpose commit).
|
|
138
|
+
5. The skill is invoked from `/wr-itil:manage-problem` Step 0, `/wr-itil:work-problems` Step 0, AND direct user invocation — no other invocation surface (e.g., `/wr-itil:transition-problem` does NOT call this skill; per architect verdict P062 already covers transition-time refresh inside the same commit, redundant preflight here would pay the cost on every transition).
|
|
139
|
+
|
|
140
|
+
## Related
|
|
141
|
+
|
|
142
|
+
- `packages/itil/scripts/reconcile-readme.sh` — the diagnose-only mechanical drift detector.
|
|
143
|
+
- `packages/itil/scripts/test/reconcile-readme.bats` — script-level bats per ADR-005.
|
|
144
|
+
- `packages/itil/skills/manage-problem/SKILL.md` — invokes this skill from Step 0 preflight.
|
|
145
|
+
- `packages/itil/skills/work-problems/SKILL.md` — invokes the script (not the skill) from Step 0 preflight; halts with directive on drift.
|
|
146
|
+
- `docs/problems/118-readme-drifts-from-filesystem-truth-despite-refresh-contracts-closed.open.md` — the originating problem ticket.
|
|
147
|
+
- `docs/decisions/014-governance-skills-commit-their-own-work.proposed.md` — amended Reconciliation sub-rule.
|
|
148
|
+
- `docs/decisions/022-problem-lifecycle-verification-pending-status.proposed.md` — Confirmation criterion 3 extension.
|
|
149
|
+
- **P094** (`docs/problems/094-...closed.md`) — refresh-on-create. Composes; this skill is robustness on top, not supersession.
|
|
150
|
+
- **P062** (`docs/problems/062-...closed.md`) — refresh-on-transition. Composes; same.
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
#!/usr/bin/env bats
|
|
2
|
+
# Contract assertions for /wr-itil:reconcile-readme (P118).
|
|
3
|
+
#
|
|
4
|
+
# This skill wraps the diagnose-only `packages/itil/scripts/reconcile-readme.sh`
|
|
5
|
+
# script with an agent-applied-edits pattern. The contract here asserts the
|
|
6
|
+
# skill's structure (frontmatter, ADR pointers, invocation-surface
|
|
7
|
+
# enumeration) — the script's behaviour is asserted in
|
|
8
|
+
# packages/itil/scripts/test/reconcile-readme.bats per ADR-005.
|
|
9
|
+
#
|
|
10
|
+
# Structural assertion — Permitted Exception to the source-grep ban
|
|
11
|
+
# (ADR-005 / P011 / ADR-037 contract-assertion pattern).
|
|
12
|
+
#
|
|
13
|
+
# @problem P118
|
|
14
|
+
# @jtbd JTBD-006 (Progress the Backlog While I'm Away — orchestrators
|
|
15
|
+
# read README to pick highest-WSJF actionable ticket; drift burns iters)
|
|
16
|
+
# @jtbd JTBD-001 (Enforce Governance Without Slowing Down — read-only
|
|
17
|
+
# diagnostic, no interactive friction on the happy path)
|
|
18
|
+
|
|
19
|
+
setup() {
|
|
20
|
+
SKILL_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
|
|
21
|
+
SKILL_FILE="${SKILL_DIR}/SKILL.md"
|
|
22
|
+
REPO_ROOT="$(cd "${SKILL_DIR}/../../../.." && pwd)"
|
|
23
|
+
SCRIPT="${REPO_ROOT}/packages/itil/scripts/reconcile-readme.sh"
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
# ── Frontmatter contract ────────────────────────────────────────────────────
|
|
27
|
+
|
|
28
|
+
@test "reconcile-readme: SKILL.md exists and has frontmatter" {
|
|
29
|
+
[ -f "$SKILL_FILE" ]
|
|
30
|
+
run head -1 "$SKILL_FILE"
|
|
31
|
+
[ "$status" -eq 0 ]
|
|
32
|
+
[ "$output" = "---" ]
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
@test "reconcile-readme: frontmatter name is wr-itil:reconcile-readme" {
|
|
36
|
+
run grep -n "^name: wr-itil:reconcile-readme$" "$SKILL_FILE"
|
|
37
|
+
[ "$status" -eq 0 ]
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
@test "reconcile-readme: frontmatter description names the drift-correction intent (P118)" {
|
|
41
|
+
run grep -E "^description: .*[Dd]rift" "$SKILL_FILE"
|
|
42
|
+
[ "$status" -eq 0 ]
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
@test "reconcile-readme: allowed-tools includes Read, Edit, Bash" {
|
|
46
|
+
# Read for the ticket files. Edit for narrative-preserving row edits.
|
|
47
|
+
# Bash for the script invocation. (Write is also present for the
|
|
48
|
+
# rare case of an empty README rebuild.)
|
|
49
|
+
run grep -E "^allowed-tools:.*Read.*Edit.*Bash" "$SKILL_FILE"
|
|
50
|
+
[ "$status" -eq 0 ]
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
# ── Script wrapping contract ────────────────────────────────────────────────
|
|
54
|
+
|
|
55
|
+
@test "reconcile-readme: SKILL.md references the script path" {
|
|
56
|
+
run grep -F "packages/itil/scripts/reconcile-readme.sh" "$SKILL_FILE"
|
|
57
|
+
[ "$status" -eq 0 ]
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
@test "reconcile-readme: the underlying script exists" {
|
|
61
|
+
[ -f "$SCRIPT" ]
|
|
62
|
+
[ -x "$SCRIPT" ]
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
@test "reconcile-readme: SKILL.md documents the three exit codes (0/1/2)" {
|
|
66
|
+
# Exit-code semantics must be explicit so adopters know what to do
|
|
67
|
+
# on parse error vs drift vs clean.
|
|
68
|
+
run grep -E "exit.*\b0\b|^- \`0\`" "$SKILL_FILE"
|
|
69
|
+
[ "$status" -eq 0 ]
|
|
70
|
+
run grep -E "exit.*\b1\b|^- \`1\`" "$SKILL_FILE"
|
|
71
|
+
[ "$status" -eq 0 ]
|
|
72
|
+
run grep -E "exit.*\b2\b|^- \`2\`" "$SKILL_FILE"
|
|
73
|
+
[ "$status" -eq 0 ]
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
# ── Narrative-preservation contract (architect Q2 verdict) ──────────────────
|
|
77
|
+
|
|
78
|
+
@test "reconcile-readme: SKILL.md asserts narrative preservation (no full regen)" {
|
|
79
|
+
# Architect verdict (Q2): the skill+script split exists specifically
|
|
80
|
+
# to preserve the README's "Last reviewed" prose paragraph and
|
|
81
|
+
# Closed-section closure-via free text. A regression that introduces
|
|
82
|
+
# full README regeneration would void the architect's choice.
|
|
83
|
+
run grep -iE "preserve.*narrative|narrative.*preserve|do not regenerate|DO NOT regenerate" "$SKILL_FILE"
|
|
84
|
+
[ "$status" -eq 0 ]
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
# ── Invocation-surface enumeration (architect Q3 verdict) ───────────────────
|
|
88
|
+
|
|
89
|
+
@test "reconcile-readme: SKILL.md names manage-problem Step 0 as one invocation surface" {
|
|
90
|
+
run grep -E "manage-problem.*Step 0|Step 0.*manage-problem" "$SKILL_FILE"
|
|
91
|
+
[ "$status" -eq 0 ]
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
@test "reconcile-readme: SKILL.md names work-problems Step 0 as one invocation surface" {
|
|
95
|
+
run grep -E "work-problems.*Step 0|Step 0.*work-problems" "$SKILL_FILE"
|
|
96
|
+
[ "$status" -eq 0 ]
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
@test "reconcile-readme: SKILL.md explicitly excludes transition-problem (P062 already covers transition refresh)" {
|
|
100
|
+
# Architect Q3 verdict: transition-problem does NOT call this skill.
|
|
101
|
+
# This is load-bearing — adding it would pay reconciliation cost on
|
|
102
|
+
# every transition, redundant with P062.
|
|
103
|
+
run grep -E "transition-problem.*does NOT|NOT call.*transition-problem|NO.*transition-problem" "$SKILL_FILE"
|
|
104
|
+
[ "$status" -eq 0 ]
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
# ── ADR alignment ───────────────────────────────────────────────────────────
|
|
108
|
+
|
|
109
|
+
@test "reconcile-readme: SKILL.md cites ADR-014 (Reconciliation as preflight robustness layer)" {
|
|
110
|
+
run grep -F "ADR-014" "$SKILL_FILE"
|
|
111
|
+
[ "$status" -eq 0 ]
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
@test "reconcile-readme: SKILL.md cites ADR-022 (Verification Pending lifecycle)" {
|
|
115
|
+
run grep -F "ADR-022" "$SKILL_FILE"
|
|
116
|
+
[ "$status" -eq 0 ]
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
@test "reconcile-readme: SKILL.md cites ADR-038 (progressive disclosure / per-row byte budget)" {
|
|
120
|
+
run grep -F "ADR-038" "$SKILL_FILE"
|
|
121
|
+
[ "$status" -eq 0 ]
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
@test "reconcile-readme: SKILL.md cites ADR-013 Rule 6 for AFK non-interactive auto-apply" {
|
|
125
|
+
# The auto-apply branch in AFK mode must cite ADR-013 Rule 6
|
|
126
|
+
# explicitly so the non-interactive fail-safe inheritance is
|
|
127
|
+
# discoverable.
|
|
128
|
+
run grep -E "ADR-013.*Rule 6|Rule 6.*ADR-013|Rule 6" "$SKILL_FILE"
|
|
129
|
+
[ "$status" -eq 0 ]
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
# ── Composition with closed contracts (P094 + P062) ─────────────────────────
|
|
133
|
+
|
|
134
|
+
@test "reconcile-readme: SKILL.md asserts composition with P094 (robustness on top, not supersession)" {
|
|
135
|
+
run grep -E "P094.*compose|compose.*P094|robustness.*on top|on top of P094" "$SKILL_FILE"
|
|
136
|
+
[ "$status" -eq 0 ]
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
@test "reconcile-readme: SKILL.md asserts composition with P062 (robustness on top, not supersession)" {
|
|
140
|
+
run grep -E "P062.*compose|compose.*P062|on top of.*P062|P094.*P062" "$SKILL_FILE"
|
|
141
|
+
[ "$status" -eq 0 ]
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
# ── Self-healing re-check after edits ───────────────────────────────────────
|
|
145
|
+
|
|
146
|
+
@test "reconcile-readme: SKILL.md mandates a re-run of the script after Step 4 edits land" {
|
|
147
|
+
# The contract is self-healing only if the post-edit re-check fires.
|
|
148
|
+
# Without it, a partial edit set ships silently.
|
|
149
|
+
run grep -iE "re-run.*script|re.run.*reconcile-readme|re-run.*reconcile" "$SKILL_FILE"
|
|
150
|
+
[ "$status" -eq 0 ]
|
|
151
|
+
}
|
|
@@ -59,6 +59,21 @@ After the fetch/divergence check, Step 0 MUST run a session-continuity detection
|
|
|
59
59
|
|
|
60
60
|
Step 6.75 treats a Step-0-resolved-with-user-confirmation state as `dirty-for-known-reason`: if the interactive branch's Resume option landed the drafted ADR as iter 1, the iter's commit clears the dirty state and the rest of the loop proceeds normally.
|
|
61
61
|
|
|
62
|
+
#### README reconciliation preflight (per P118)
|
|
63
|
+
|
|
64
|
+
After the session-continuity detection pass, Step 0 MUST run the diagnose-only README reconciliation check. The orchestrator reads `docs/problems/README.md`'s WSJF Rankings table to pick the highest-WSJF actionable ticket (Step 3); if that table lies about which tickets are open vs verifying vs closed, the orchestrator burns iterations on no-op tickets — exactly the failure class P118 captures (a prior session committed a ticket transition without staging the README refresh, and no subsequent session systematically reconciled).
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
bash packages/itil/scripts/reconcile-readme.sh docs/problems
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Exit-code routing:
|
|
71
|
+
- **Exit 0 (clean)**: continue to Step 1.
|
|
72
|
+
- **Exit 1 (drift detected)**: structured diff lines printed to stdout, one per drift entry (≤150 bytes per ADR-038 progressive-disclosure budget). Per ADR-013 Rule 6 (non-interactive AFK fail-safe), invoke `/wr-itil:reconcile-readme` to apply the corrections + commit a `chore(problems): reconcile README ...` commit, then proceed to Step 1. The reconciled README is the orchestrator's source of truth for Step 3 ranking — a stale read at Step 1 would propagate the lie into the iteration's selection.
|
|
73
|
+
- **Exit 2 (parse error)**: README missing or malformed. Halt the loop with the parse-error message and the structured Prior-Session State report — this is a deeper repair that needs investigation, not mechanical reconciliation.
|
|
74
|
+
|
|
75
|
+
This is a robustness layer ON TOP of P094 + P062, not a supersession — both per-operation contracts remain in force inside each iteration's manage-problem / transition-problem invocation.
|
|
76
|
+
|
|
62
77
|
### Step 1: Scan the backlog
|
|
63
78
|
|
|
64
79
|
Read `docs/problems/README.md` if it exists and is fresh (check via git history — see manage-problem step 9 for the cache freshness check). If stale or missing, scan all `.open.md` and `.known-error.md` files in `docs/problems/`, extract their WSJF scores, and rank them.
|