# AI Folder Structure DRY Refactor Audit

Date: 2026-05-11
Related Chunk: `ai/chunks/active/chunk-000057-ai-folder-structure-dry-refactor-audit.md`
Scope: audit-only; no behavior refactor.

## Summary

The `ai/` workflow system has become capable, but many rules now appear in
three or four layers at once: standards define the rule, roles summarize the
rule, templates restate the required sections, and shell helpers encode a
partial executable interpretation. This is expected after rapid hardening, but
it creates drift risk.

The safest next direction is not a broad rewrite. The high-value path is to
centralize definitions in standards, keep roles focused on responsibilities,
keep templates as thin fill-in forms, and extract shared shell parsing only
after scenario coverage protects current behavior.

## Current Structure Map

| Area | Current Role | Observed Ownership |
| --- | --- | --- |
| `ai/roles` | Role-specific operating instructions. | Should describe responsibilities, boundaries, and when to use central standards. |
| `ai/standards` | Source of truth for workflow rules. | Should own naming, lifecycle states, QA gates, handoff fields, retry rules, Test Impact, and human-verifiable delivery. |
| `ai/commands` | Executable workflow helpers and scenario harnesses. | Should encode central standards, not redefine policy prose. |
| `ai/tasks` | Templates for repeatable outputs. | Should provide shapes and field placeholders, with references to standards for rules. |
| `ai/chunks` | Chunk lifecycle files and documentation. | Should document chunk usage and point to central naming/state standards. |
| `ai/requirements` | Requirements lifecycle files and documentation. | Should point to requirements and artifact naming standards. |
| `ai/work-packages` | Work package lifecycle files and documentation. | Should point to work package orchestration and artifact naming standards. |
| `ai/reports` | Audit, simulation, baseline, and final reports. | Should own report index only; naming is now central in `artifact-naming.md`. |
| `ai/fixtures` | Deterministic simulation inputs. | Should remain fixture data, not policy. |
| `ai/tools/telegram` | Telegram transport and command UI. | Should wrap shared helpers and avoid duplicating workflow interpretation. |

## Duplicated Definitions Inventory

### Artifact Naming

Central source now exists: `ai/standards/artifact-naming.md`.

Remaining duplication is mostly acceptable examples, but these files still
carry convention details:

- `ai/chunks/README.md`
- `ai/requirements/README.md`
- `ai/work-packages/README.md`
- `ai/reports/README.md`
- `ai/tasks/chunk-plan-template.md`
- `ai/tasks/work-package-template.md`
- `ai/tasks/requirements-template.md`

Recommended treatment: keep examples in templates, but move explanatory rules
to the central standard. Do not duplicate ID-width rationale elsewhere.

### Lifecycle State And Completion Rules

Primary sources:

- `ai/standards/workflow-state.md`
- `ai/standards/orchestration-workflow.md`
- `ai/standards/chunk-autopilot.md`
- `ai/standards/work-package-orchestration.md`

Duplicated consumers:

- `ai/roles/orchestrator.md`
- `ai/roles/developer.md`
- `ai/roles/qa.md`
- `ai/commands/workflow-state.sh`
- `ai/commands/orchestrator-next.sh`
- `ai/commands/prompt-synthesize.sh`
- `ai/commands/workflow-summary.sh`

Risk: state names and next commands can drift between standards and helpers.
This already happened previously with readiness gate commands being confused
with next-action commands.

Recommended treatment: keep `workflow-state.md` as the canonical state model.
Move command-selection policy into `workflow-handoff.md`, then have
`orchestrator-next.sh`, `workflow-summary.sh`, and prompt synthesis consume the
same small helper or shared table.

### Handoff Fields

Primary source:

- `ai/standards/workflow-handoff.md`

Repeated in:

- `ai/tasks/chunk-plan-template.md`
- `ai/tasks/qa-review-template.md`
- `ai/tasks/requirements-intake-template.md`
- `ai/tasks/requirements-review-template.md`
- `ai/tasks/work-package-template.md`
- `ai/commands/orchestrator-next.sh`
- `ai/commands/workflow-summary.sh`
- `ai/commands/prompt-synthesize.sh`

Risk: templates and helpers can preserve outdated fields or command semantics.

Recommended treatment: templates should include only a short block and link to
`workflow-handoff.md`. Helper output should be covered by scenario assertions
for each canonical state.

### QA Gates, DoD, And Adversarial Review

Primary sources:

- `ai/standards/done.md`
- `ai/standards/qa-gates.md`
- `ai/standards/workflow-output-quality.md`
- `ai/standards/human-verifiable-delivery.md`
- `ai/standards/test-strategy.md`

Repeated in:

- `ai/roles/qa.md`
- `ai/tasks/qa-review-template.md`
- `ai/roles/developer.md`

Risk: QA role and template are now long and contain gate descriptions that can
drift from standards. The template is useful, but it should not become another
policy source.

Recommended treatment: `qa-gates.md` should be the gate index, with detailed
gate standards linked. `qa.md` should say QA must apply those gates, while the
template records results.

### Test Impact

Primary source:

- `ai/standards/test-strategy.md`

Repeated in:

- `ai/roles/developer.md`
- `ai/roles/qa.md`
- `ai/tasks/qa-review-template.md`
- active/completed chunk files

Risk: if required fields change, `workflow-state.sh` and templates must be
updated in lockstep.

Recommended treatment: extract a single documented Test Impact field list and
make `workflow-state.sh` check that list. Keep chunk examples descriptive, not
normative.

### Human-Verifiable Delivery And Environment Configuration

Primary source:

- `ai/standards/human-verifiable-delivery.md`

Repeated in:

- `ai/standards/qa-gates.md`
- `ai/roles/developer.md`
- `ai/roles/qa.md`
- `ai/tasks/qa-review-template.md`

Risk: gate applicability could become inconsistent between Developer handoff
and QA review.

Recommended treatment: keep examples in the detailed standard, keep
`qa-gates.md` as a short index, and reduce role docs to responsibility
statements plus links.

### Retry, Escalation, And Autopilot

Primary sources:

- `ai/standards/orchestrator-retry-policy.md`
- `ai/standards/chunk-autopilot.md`
- `ai/standards/work-package-orchestration.md`
- `ai/standards/orchestration-workflow.md`

Overlap:

- Retry limits and stop conditions appear in `iteration-policy.md`,
  `orchestration-workflow.md`, `orchestrator-retry-policy.md`,
  `chunk-autopilot.md`, and `work-package-orchestration.md`.

Risk: stop conditions are easy to miss or interpret differently during
autopilot.

Recommended treatment: make `orchestrator-retry-policy.md` own retry behavior,
make `chunk-autopilot.md` own queue automation, and make
`work-package-orchestration.md` own milestones. Other documents should link to
those owners.

### Acceptance Criteria Verification

Primary executable source:

- `ai/commands/workflow-state.sh`

Primary prose sources:

- `ai/standards/workflow-state.md`
- `ai/standards/workflow-handoff.md`
- `ai/roles/developer.md`
- `ai/roles/qa.md`

Risk: the checker is executable but embedded in a large workflow-state helper.
Future criteria syntax changes could silently break readiness.

Recommended treatment: extract acceptance verification into a dedicated helper
or sourced shell function only after adding focused scenario coverage for
missing, blocked, unmarked, duplicate, and paraphrased criteria.

### Report Naming And Indexing

Primary source:

- `ai/standards/artifact-naming.md`

Index owner:

- `ai/reports/README.md`

Risk: manual report numbering can collide or skip if several agents create
reports concurrently.

Recommended treatment: add a small read-only report helper later that prints
the next report ID and validates index consistency.

## Shell Helper Duplication

The command helpers repeatedly implement similar functions:

- `repo_root`: nearly every helper.
- `section`: `workflow-state.sh`, `workflow-summary.sh`,
  `prompt-synthesize.sh`, `requirements-state.sh`,
  `approve-requirements.sh`, and Telegram section readers.
- `metadata_value`: `workflow-state.sh`, `workflow-summary.sh`,
  `prompt-synthesize.sh`, `requirements-state.sh`, and Telegram.
- active artifact discovery: chunk globs appear in workflow, orchestrator, and
  Telegram helpers.
- pass history parsing: `workflow-state.sh`, `prompt-synthesize.sh`, and
  Telegram all parse latest pass entries.
- git status/diff summary: workflow state, summary, prompt synthesis,
  orchestrator status, Telegram, and chunk docs repeat command expectations.
- blocked output and handoff command selection: split across
  `orchestrator-next.sh`, `workflow-summary.sh`, and `prompt-synthesize.sh`.

Risk rating: medium to high. Duplication itself is not dangerous, but shell
parsing changes are easy to regress because small formatting differences affect
state, prompts, Telegram, and summaries.

Recommended treatment: do not extract everything at once. First add more
fixture coverage, then extract one shared `ai/commands/lib/workflow-md.sh` or
similar for section/metadata parsing and one shared command-selection table.

## Ownership Matrix

| Concept | Should Own | Should Reference |
| --- | --- | --- |
| Artifact names and lifecycle folders | `ai/standards/artifact-naming.md` | READMEs, templates, helpers |
| Canonical chunk states | `ai/standards/workflow-state.md` | roles, prompt synthesis, summaries |
| Handoff fields and next-command semantics | `ai/standards/workflow-handoff.md` | templates, orchestrator, summary, Telegram |
| Definition of Done | `ai/standards/done.md` | Developer, QA, Orchestrator |
| QA gate index | `ai/standards/qa-gates.md` | QA role/template |
| Detailed gate behavior | focused standards such as `test-strategy.md` and `human-verifiable-delivery.md` | QA gates, roles, templates |
| Retry classification | `ai/standards/orchestrator-retry-policy.md` | workflow state, prompt synthesis, Orchestrator |
| Work package milestones | `ai/standards/work-package-orchestration.md` | work package template, Orchestrator |
| Chunk Autopilot | `ai/standards/chunk-autopilot.md` | Orchestrator, QA, work packages |
| Requirements lifecycle | `ai/standards/requirements.md` and `requirements-gates.md` | requirements roles/templates/helpers |
| Markdown section parsing | future shared shell helper | workflow, requirements, prompt, Telegram helpers |
| Report index | `ai/reports/README.md` | reports and summaries |

## Recommended Central Sources Of Truth

1. `ai/standards/artifact-naming.md`: all artifact naming and lifecycle folder
   rules.
2. `ai/standards/workflow-state.md`: state names, readiness semantics, and
   state transitions.
3. `ai/standards/workflow-handoff.md`: field names and safe next-command
   selection.
4. `ai/standards/qa-gates.md`: gate index only.
5. `ai/standards/test-strategy.md`: Test Impact format and blocking rules.
6. `ai/standards/human-verifiable-delivery.md`: human/operator and environment
   verification rules.
7. `ai/standards/orchestrator-retry-policy.md`: retry classification and stop
   behavior after QA BLOCKED.
8. `ai/standards/chunk-autopilot.md`: approved queue automation.
9. `ai/standards/work-package-orchestration.md`: work package and milestone
   ownership.
10. A future shell helper library for section/metadata/path parsing.

## Proposed Refactor Batches

### Batch 1: Documentation Reference Cleanup

Risk: low.

Scope:

- Replace duplicated naming, handoff, Test Impact, and gate prose in roles and
  templates with short references to central standards.
- Keep examples where they help operators fill a file.
- Do not change helper behavior.

Validation:

- `bash -n ai/commands/*.sh ai/tools/telegram/*.sh ai/tools/telegram/test/*.sh`
- `ai/commands/workflow-state.sh`
- `ai/commands/workflow-summary.sh`
- `ai/commands/workflow-scenarios-test.sh`
- manual review that templates still contain required headings.

### Batch 2: QA Template And Gate DRY Pass

Risk: low to medium.

Scope:

- Keep `ai/tasks/qa-review-template.md` as an output form.
- Move detailed gate explanations back to standards.
- Ensure QA role references, rather than restates, gate requirements.

Validation:

- Prompt synthesis QA output still includes required fields.
- Workflow scenario coverage still recognizes QA Review and QA Pass fields.
- A fixture QA review with missing adversarial fields still fails when expected.

### Batch 3: Shared Markdown Parsing Library

Risk: medium.

Scope:

- Add a sourced helper such as `ai/commands/lib/workflow-md.sh`.
- Move `section`, `metadata_value`, first-heading, and field extraction helpers.
- Convert one command at a time, starting with non-mutating helpers.

Validation:

- Existing workflow and requirements scenario harnesses.
- New focused parser fixtures for repeated headings, empty sections, metadata
  values with colons, missing headings, and pass history entries.
- Telegram tests after Telegram adopts the shared parser.

### Batch 4: Shared Artifact Discovery Library

Risk: medium.

Scope:

- Centralize active/backlog/completed chunk discovery.
- Centralize requirements/work-package path validation.
- Preserve support for six-digit generated files and numeric-width migration
  tolerance.

Validation:

- Scenarios for zero, one, and multiple active chunks.
- Six-digit backlog/completed chunk scenarios.
- Requirements active/approved path scenarios.
- Telegram `/completechunk` ambiguity scenarios.

### Batch 5: Handoff Command Selection Table

Risk: high.

Scope:

- Centralize canonical-state to next-command mapping.
- Have `orchestrator-next.sh`, `workflow-summary.sh`, and
  `prompt-synthesize.sh` share it.

Why high-risk: command wording is operator-facing and previous regressions
confused gates with next actions.

Validation:

- Scenario assertions for every canonical state.
- Operator sanity checks for `ready_for_qa`, `qa_blocked_fixable`,
  decision-required blocked states, `ready_to_complete`, and `commit_ready`.
- Telegram wrapper consistency tests.

### Batch 6: Acceptance Verification Helper Extraction

Risk: high.

Scope:

- Extract acceptance criteria matching from `workflow-state.sh`.
- Keep readiness behavior identical.

Validation:

- Missing verification.
- Blocked verification.
- Unmarked verification.
- Extra unmatched verification.
- Paraphrased-but-equivalent criteria if supported.
- Multi-line criteria behavior.

### Batch 7: Report Index Helper

Risk: low.

Scope:

- Add a read-only helper that prints the next report ID and validates report
  filenames/index rows.

Validation:

- Fixture reports with missing index rows.
- Duplicate report IDs.
- Incorrect date/slug shape.

## Recommended Execution Order

1. Batch 1: documentation reference cleanup.
2. Batch 2: QA template and gate DRY pass.
3. Batch 7: report index helper.
4. Batch 3: shared markdown parsing library.
5. Batch 4: shared artifact discovery library.
6. Batch 5: handoff command selection table.
7. Batch 6: acceptance verification helper extraction.

This order removes low-risk prose drift first, then adds guardrails before
touching high-risk helper behavior.

## Do Not Touch Yet

- Do not merge `workflow-state.sh`, `orchestrator-next.sh`,
  `workflow-summary.sh`, and `prompt-synthesize.sh` into one large script.
  Their separate command surfaces are useful.
- Do not rewrite Telegram command handling until shared helper behavior is
  protected by parser and handoff scenarios.
- Do not change canonical state names until all prompt, summary, Telegram, and
  scenario consumers are migrated together.
- Do not simplify QA gates by removing adversarial, operator sanity, or
  human-verifiable delivery sections. They catch different failure modes.
- Do not replace executable scenario harnesses with prose standards.
- Do not refactor acceptance matching without dedicated fixtures for tricky
  acceptance criteria formats.
- Do not rename artifacts again unless the central naming standard changes
  through a dedicated migration chunk.

## Likely False Simplification Risks

- Collapsing standards into role docs would make prompts easier to read but
  would weaken source-of-truth boundaries.
- Collapsing all helpers into one script would reduce duplication but increase
  blast radius.
- Removing template fields because they duplicate standards would make output
  less complete unless prompt synthesis and readiness checks enforce those
  fields.
- Treating Telegram as only a wrapper is correct directionally, but Telegram
  still owns transport-specific confirmation and formatting behavior.

## Recommended Next Chunk

Create a low-risk documentation cleanup chunk:

`chunk-000058-ai-workflow-docs-central-reference-cleanup.md`

Goal: replace duplicated policy prose in roles/templates/READMEs with concise
references to central standards, preserving examples and headings required by
helpers. Do not change helper behavior.

## Validation Strategy For This Audit

This audit should be validated with:

- shell syntax validation for existing helpers.
- current workflow state, next action, and summary helpers.
- workflow and requirements scenario harnesses.
- file structure listing.
- git status and diff stat.

No runtime smoke is required because this report changes no app runtime or
workflow helper behavior.