aidd-lint rule: workflow-war-story

jared commented

2026-07-23 11:30:54 +00:00

Owner

Problem

Workflow steps carrying incident history instead of instruction. Verbatim, from plugins/os-sdlc/skills/mine-lints/SKILL.md:32-34 as of commit 5ea6bbf (fixed in c6a4177):

   - Once more from the repo root, as a sanity check -- a missing/changed root
     `.rubocop.yml` regresses into a several-hundred-line pending-cops advisory wall (fixed
     in commit 632f1ea). Flag this proactively if it reappears.

"fixed in commit 632f1ea" is provenance, not instruction: it justifies the step but costs hot-path tokens on every execution and dates the file. Same file, lines 54-57, cited "tickets #87 and #89" the same way.

Detection

Inputs: a markdown file; its heading tree.
Algorithm:
1. Select sections whose heading matches /workflow|process|steps/i.
2. Scan prose lines (skip code fences) for any of: commit SHA /\b[0-9a-f]{7,40}\b/, issue ref /#\d+/, ISO date /\b\d{4}-\d{2}-\d{2}\b/, or incident phrases: "last time", "last batch", "fixed in", "shipped", "regressed", "went wrong".
3. One offense per matching line.
Failure message (verbatim contract): "<file>:<line>: Workflow step cites incident history ('<match>'). Provenance belongs in a reference file or the artifact the rule justifies -- keep only the instruction in the step."

Correction

-   - Once more from the repo root, as a sanity check -- a missing/changed root
-     `.rubocop.yml` regresses into a several-hundred-line pending-cops advisory wall (fixed
-     in commit 632f1ea). Flag this proactively if it reappears.
+   - Once more from the repo root (a several-hundred-line pending-cops wall means the root
+     `.rubocop.yml` regressed -- flag it).

Full rationale relocated to skills/mine-lints/references/reconcile-gate.md (the fix pattern: relocate, don't delete).

Pass/fail examples

Must fail: a ## Workflow numbered step containing "fixed in commit 632f1ea"; a step containing "tickets #87 and #89 shipped self-contradictions".
Must pass: the identical sentences inside references/reconcile-gate.md or under a ## Provenance heading; a SHA inside a fenced code block in a Workflow section.

Provenance

mine-lints simplification session 2026-07-23; simplifier + implementer perspective critique; commit c6a4177 is the exemplar fix. Part of the aidd-lint system (see mapping ticket).

Implementation plan

Ruby markdown-lint infra (home decided by the mapping ticket's ADR); TDD with fixture .md files; same validation discipline as the Sdlc/* cops.

## Problem Workflow steps carrying incident history instead of instruction. Verbatim, from `plugins/os-sdlc/skills/mine-lints/SKILL.md:32-34` as of commit 5ea6bbf (fixed in c6a4177): ``` - Once more from the repo root, as a sanity check -- a missing/changed root `.rubocop.yml` regresses into a several-hundred-line pending-cops advisory wall (fixed in commit 632f1ea). Flag this proactively if it reappears. ``` "fixed in commit 632f1ea" is provenance, not instruction: it justifies the step but costs hot-path tokens on every execution and dates the file. Same file, lines 54-57, cited "tickets #87 and #89" the same way. ## Detection - **Inputs:** a markdown file; its heading tree. - **Algorithm:** 1. Select sections whose heading matches `/workflow|process|steps/i`. 2. Scan prose lines (skip code fences) for any of: commit SHA `/\b[0-9a-f]{7,40}\b/`, issue ref `/#\d+/`, ISO date `/\b\d{4}-\d{2}-\d{2}\b/`, or incident phrases: "last time", "last batch", "fixed in", "shipped", "regressed", "went wrong". 3. One offense per matching line. - **Failure message (verbatim contract):** `"<file>:<line>: Workflow step cites incident history ('<match>'). Provenance belongs in a reference file or the artifact the rule justifies -- keep only the instruction in the step."` ## Correction ```diff - - Once more from the repo root, as a sanity check -- a missing/changed root - `.rubocop.yml` regresses into a several-hundred-line pending-cops advisory wall (fixed - in commit 632f1ea). Flag this proactively if it reappears. + - Once more from the repo root (a several-hundred-line pending-cops wall means the root + `.rubocop.yml` regressed -- flag it). ``` Full rationale relocated to `skills/mine-lints/references/reconcile-gate.md` (the fix pattern: relocate, don't delete). ## Pass/fail examples - **Must fail:** a `## Workflow` numbered step containing "fixed in commit 632f1ea"; a step containing "tickets #87 and #89 shipped self-contradictions". - **Must pass:** the identical sentences inside `references/reconcile-gate.md` or under a `## Provenance` heading; a SHA inside a fenced code block in a Workflow section. ## Provenance mine-lints simplification session 2026-07-23; simplifier + implementer perspective critique; commit c6a4177 is the exemplar fix. Part of the aidd-lint system (see mapping ticket). ## Implementation plan Ruby markdown-lint infra (home decided by the mapping ticket's ADR); TDD with fixture .md files; same validation discipline as the `Sdlc/*` cops.

jared referenced this issue

2026-07-23 11:31:45 +00:00

aidd-lint: system map (umbrella) #109

jared referenced this issue

2026-07-23 12:09:09 +00:00

aidd-lint: system map (umbrella) #109

jared added the

review

label

2026-07-23 12:44:02 +00:00

jared commented

2026-07-23 12:44:02 +00:00

Author

Owner

Implemented on branch aidd-lint/tier-1 (plugins/os-aidd-lint, cop: workflow_war_story.rb). 55-test suite green; report-only corpus scan run. Awaiting human review — open items noted on #109.

jared commented

2026-07-23 12:44:14 +00:00

Author

Owner

Implemented on branch aidd-lint/tier-1 (plugins/os-aidd-lint, cop: workflow_war_story.rb). 55-test suite green; report-only corpus scan run. Awaiting human review — open items noted on #109.

jared added the

labels

2026-08-01 16:39:41 +00:00

jared commented

2026-08-01 16:44:51 +00:00

Author

Owner

This was generated by AI during triage.

Implemented: plugins/os-aidd-lint/lib/aidd_lint/cops/workflow_war_story.rb (WorkflowWarStory cop, TDD'd, tests in tests/cops/workflow_war_story_test.rb), matching this ticket's detection spec and message contract. Corpus scan ran and surfaced a follow-up defect in the #\d+ pattern, tracked separately as #168. Closing #100 as implemented; #168 is the live successor.

> *This was generated by AI during triage.* Implemented: `plugins/os-aidd-lint/lib/aidd_lint/cops/workflow_war_story.rb` (WorkflowWarStory cop, TDD'd, tests in `tests/cops/workflow_war_story_test.rb`), matching this ticket's detection spec and message contract. Corpus scan ran and surfaced a follow-up defect in the `#\d+` pattern, tracked separately as #168. Closing #100 as implemented; #168 is the live successor.

jared closed this issue

2026-08-01 16:44:52 +00:00

Rows
Columns

aidd-lint rule: workflow-war-story #100

Problem

Detection

Correction

Pass/fail examples

Provenance

Implementation plan