feat: /aidlc --doctor --bundle - generate a redacted diagnostic report

[leandrodamascena]

Problem

When a workflow misbehaves, such as a gate that will not open, a stage that will not advance, or an approved report that is repeatedly refused, debugging often requires requesting the user's project directory.

That approach is:

• Huge: it includes source code, dependencies, build output, and unrelated files.
• Leaky: workflow records contain requirements, designs, decisions, questions, and other business data.
• Manual: maintainers must reconstruct the execution from state, audit events, runtime markers, and generated graphs.

Recent PR reviews demonstrate the need:

• feat: three-role ensemble - mode as communication topology (2.5.0) #568: a Kiro collaborator cannot write its required contribution, causing the ensemble evidence gate to remain blocked.
• feat: opencode harness support (2.3.5) #571: runtime compilation can fail to run, leaving runtime-graph.json stale without an obvious user-facing explanation.

A diagnostic bundle should identify these conditions without exposing the project's work product.

Proposal

Add --bundle to /aidlc --doctor.

The command runs a fresh doctor analysis and produces:

• A human-readable report.md.
• A machine-readable report.json.
• A redacted, normalized evidence set.
• A manifest.json describing versions, checksums, redactions, and included files.

The canonical output is a bundle directory. When a supported archive mechanism is available, the directory is packaged as a .tar.gz. If archiving fails or is unavailable, the directory remains usable and the command clearly reports its location.

The value is the diagnosis, not raw file collection.

Shared Diagnostic Model

Refactor doctor findings into a shared structured model:

interface DoctorFinding {
  id: string;
  severity: "info" | "warning" | "error";
  summary: string;
  evidence: Record<string, unknown>;
  remedy: string;
  safeToAutomate: boolean;
}

The live doctor output and exported bundle must use the same findings. This prevents the command and bundle from developing separate diagnostic rules or remediation text.

Every bundle runs a fresh doctor analysis. Cached results are not used because stale diagnostics may hide the problem being investigated.

Bundle Contents

Reconstructed Timeline

Build a timeline from available audit events:

• Stage entry and completion.
• Observed duration when both timestamps exist.
• Gate opened, approved, rejected, or currently unresolved.
• Revision count.
• Reviewer READY or NOT-READY outcomes and iteration count.
• Time between stages.
• Abnormally long or incomplete stages.

Missing evidence must be represented as unknown. The report must not infer events that were not recorded.

Deterministic Diagnosis

Use fixed, versioned condition-to-remedy rules with no LLM involvement.

Initial conditions:

• Open or unresolved gates.
• Ensemble evidence missing or malformed.
• State and audit disagreement.
• Runtime graph older than its authored inputs.
• Frozen or missing hook heartbeats.
• Missing or malformed runtime markers.
• Reviewer loop exhausted or incomplete.

For ensemble evidence, report only structural results:

• Expected collaborator identifier.
• Contribution exists: yes or no.
• Identity marker matches: yes or no.
• File size and modification time.

Do not include contribution content or its first line.

Recovery-only remedies such as AIDLC_DISABLE_ENSEMBLE_EVIDENCE=1 must carry a prominent warning that they bypass validation and are appropriate only when legitimate evidence was lost. They must never be marked safe to automate.

Normalized Evidence

Export allowlisted fields rather than copying source files verbatim:

• Selected workflow state fields needed for routing and gate diagnosis.
• Selected audit event types and fields.
• Structural runtime graph data.
• Hook-health timestamps and statuses.
• Plan and recovery status.
• Turn counter and latch states.
• Sensor names and outcomes.
• Artifact, contribution, and question-file metadata.

Do not export raw aidlc-state.md, audit files, runtime graphs, artifact bodies, contribution bodies, question bodies, memory, environment variables, or command output.

Redaction and Safety

Apply redaction before writing any bundle file:

• Home directories become ~.
• Project root becomes <project>.
• Intent identifiers in filenames become stable short hashes.
• Unit and custom artifact identifiers are hashed when not required for diagnosis.
• Core stage and agent slugs may remain because they identify framework behavior.
• Error messages and audit fields are scanned for absolute paths and secret-like values.
• Symlinks are never followed.
• Individual files and total bundle size are capped.
• Bundle files are created with owner-only permissions where supported.

Add manifest.json containing:

• Bundle schema version.
• AI-DLC version.
• Harness name and version.
• Creation timestamp.
• Hashed intent identifier.
• Included files.
• Applied redaction rules.
• Per-file checksums.
• Truncation notices.

Tests must use secret canaries and verify that none appear anywhere in the generated directory or archive.

Packaging

Do not implement a bespoke tar format in the first iteration.

Packaging order:

1. Generate and validate the canonical bundle directory.
2. Use a runtime-supported archive API when available.
3. Otherwise use an available system tar implementation.
4. If archiving is unavailable or fails, retain the directory and print clear manual-sharing instructions.

This keeps the diagnostic feature portable without introducing an archive parser or new package dependency.

Output

Example:

Diagnostic bundle created:
  aidlc-doctor-bundle-20260714T144321Z-a81f09.tar.gz

Findings:
  ERROR ensemble-evidence-missing
  WARNING runtime-graph-stale

No source files or artifact bodies were included.

Explicitly Excluded

• Workspace source code.
• node_modules and build output.
• Artifact and contribution bodies.
• Question and answer bodies.
• Memory files.
• Raw environment variables.
• Raw command output.
• Unredacted state, audit, or runtime graph files.
• LLM-generated diagnosis.
• Automatic execution of recovery commands.

Harness Support

The first implementation must support currently shipped harnesses:

• Claude Code.
• Kiro CLI.
• Kiro IDE.
• Codex CLI.

OpenCode support should be added when that harness is integrated into the target branch. The bundle model must remain harness-neutral so projection requires only a utility-handler wiring change.

Acceptance Criteria

• /aidlc --doctor --bundle always performs a fresh doctor run.
• Produces report.md, report.json, manifest.json, and normalized evidence.
• Produces a timestamped .tar.gz when archive support is available.
• Falls back to the canonical bundle directory when archiving fails.
• Reconstructs stages, durations, gates, revisions, and reviewer iterations without inventing missing events.
• Diagnoses unresolved gates, ensemble evidence failures, state-audit drift, stale runtime graphs, and cold hooks.
• Uses one shared structured finding model for live doctor and bundle output.
• Every finding has a fixed remedy and safeToAutomate classification.
• Recovery bypasses are visibly marked unsafe.
• Exports normalized allowlisted fields instead of raw workflow files.
• Never includes artifact, contribution, question, or memory bodies.
• Redacts project paths, home paths, intent identifiers, and secret-like values.
• Does not follow symlinks.
• Enforces per-file and total-size limits.
• Creates owner-only files where supported.
• Includes schema/version metadata, checksums, and redaction details.
• Secret-canary tests verify that sensitive values do not appear in either directory or archive output.
• Works across all currently shipped harnesses.
• Adds OpenCode support when that harness is integrated.
• Introduces no package dependency.
• Updates the utility-command reference and troubleshooting guide.
• Updates the Utility Handler Checklist.
• Includes the required version bump and CHANGELOG entry.