Manage Plan Artifacts

Plan-level artifact storage providing structured JSONL persistence for assessments and findings.

Scope Distinction

| Scope | Storage | Lifecycle | |-------|---------|-----------| | Project-level | .plan/lessons-learned/ | Persists across plans | | Plan-level | .plan/plans/{plan_id}/artifacts/ | Temporary, promoted or discarded |

Plan artifacts are working data during plan execution. Notable findings are promoted to project-level at 7-finalize.

Storage Structure

.plan/plans/{plan_id}/artifacts/
├── assessments.jsonl  # Component assessments (certainty, confidence)
└── findings.jsonl     # Unified: lessons + bugs (optionally promotable)

Artifact Types

Assessments

Component evaluations from analysis agents with certainty gates and confidence scores.

Certainty values: CERTAIN_INCLUDE, CERTAIN_EXCLUDE, UNCERTAIN

Findings

Unified storage for lessons and bugs. All types optionally promotable.

Finding types:

| Type | Origin | Default Promotion Target | |------|--------|--------------------------| | bug | Implementation errors | manage-lessons | | improvement | Discovered patterns | manage-lessons | | anti-pattern | Bad practices found | manage-lessons | | triage | Triage decisions | manage-lessons | | tip | Helpful hints | architecture (tips) | | insight | Deeper understanding | architecture (insights) | | best-practice | Recommended patterns | architecture (best_practices) | | build-error | Compilation failures | (any, if pattern emerges) | | test-failure | Test failures | (any, if pattern emerges) | | lint-issue | Linter warnings | (any, if pattern emerges) | | sonar-issue | Sonar findings | (any, if pattern emerges) | | pr-comment | PR review comments | (any, if pattern emerges) |

Resolution values: pending, fixed, suppressed, accepted

CLI Commands

Assessment Commands

# Add assessment
python3 .plan/execute-script.py pm-workflow:manage-plan-artifacts:manage-artifacts \
  assessment add {plan_id} {file_path} {certainty} {confidence} \
  [--agent AGENT] [--detail DETAIL] [--evidence EVIDENCE]

# Query assessments
python3 .plan/execute-script.py pm-workflow:manage-plan-artifacts:manage-artifacts \
  assessment query {plan_id} [--certainty C] [--min-confidence N] \
  [--max-confidence N] [--file-pattern PATTERN]

# Get single assessment
python3 .plan/execute-script.py pm-workflow:manage-plan-artifacts:manage-artifacts \
  assessment get {plan_id} {hash_id}

Finding Commands

# Add finding
python3 .plan/execute-script.py pm-workflow:manage-plan-artifacts:manage-artifacts \
  finding add {plan_id} {type} {title} --detail DETAIL \
  [--file-path PATH] [--line N] [--component C] \
  [--module M] [--rule R] [--severity S]

# Query findings
python3 .plan/execute-script.py pm-workflow:manage-plan-artifacts:manage-artifacts \
  finding query {plan_id} [--type T] [--resolution R] \
  [--promoted BOOL] [--file-pattern PATTERN]

# Get single finding
python3 .plan/execute-script.py pm-workflow:manage-plan-artifacts:manage-artifacts \
  finding get {plan_id} {hash_id}

# Resolve finding
python3 .plan/execute-script.py pm-workflow:manage-plan-artifacts:manage-artifacts \
  finding resolve {plan_id} {hash_id} {resolution} [--detail DETAIL]

# Promote finding
python3 .plan/execute-script.py pm-workflow:manage-plan-artifacts:manage-artifacts \
  finding promote {plan_id} {hash_id} {promoted_to}

Output Format

All commands return TOON format.

Add response:

status: success
hash_id: a3f2c1
type: bug

Query response:

status: success
plan_id: my-plan
total_count: 30
filtered_count: 15

findings[15]{hash_id,type,title,resolution}:
a3f2c1,bug,Null check missing,pending
b4e3d2,sonar-issue,TODO comment,fixed

Integration

Producers

| Client | Artifact | Operation | |--------|----------|-----------| | Analysis agents | assessment | add | | Sonar integration | finding (sonar-issue) | add, resolve | | CI integration | finding (pr-comment) | add, resolve | | phase-7-finalize | finding | add, promote |

Consumers

| Client | Artifact | Operation | |--------|----------|-----------| | Q-Gate agent | assessment | query | | phase-7-finalize | finding | query, resolve, promote | | Workflow orchestration | assessment | query |

Promotion Workflow

At 7-finalize:

Query unpromoted findings: finding query {plan_id} --promoted false

For each finding to promote:

To manage-lessons (bug, improvement, anti-pattern, triage):

manage-lessons add --component {component} --category {type} ...
finding promote {plan_id} {hash_id} {promoted_id}

To architecture (tip, insight, best-practice):

architecture enrich {type} --module {module} --{type} "{content}" --reasoning "From plan {plan_id}"
finding promote {plan_id} {hash_id} architecture