cuioss/manage-assessments

Manage Assessments

Component evaluation storage providing structured JSONL persistence for certainty/confidence assessments from analysis agents.

Enforcement

Execution mode: Run scripts exactly as documented; parse TOON output for status and route accordingly.

Prohibited actions:

• Do not modify assessments.jsonl directly; all mutations go through the script API
• Do not invent script arguments not listed in the CLI Commands section
• Do not use invalid certainty values (only CERTAIN_INCLUDE, CERTAIN_EXCLUDE, UNCERTAIN)

Constraints:

• All commands use python3 .plan/execute-script.py plan-marshall:manage-assessments:manage-assessments {command} {args}
• Assessments are plan-scoped; always provide --plan-id
• Confidence values must be numeric (0-100)

Scope Distinction

| Scope | Storage | Lifecycle | |-------|---------|-----------| | Project-level | .plan/lessons-learned/ | Persists across plans | | Plan-level | .plan/plans/{plan_id}/artifacts/ | Temporary, read-only after creation |

Assessments are working data during plan execution, consumed by Q-Gate validation and analysis agents.

Storage

.plan/plans/{plan_id}/
└── artifacts/
    └── assessments.jsonl  # Component assessments (certainty, confidence)

Schema

{
  "hash_id": "a3f2c1",
  "timestamp": "...",
  "file_path": "src/File.java",
  "certainty": "CERTAIN_INCLUDE|CERTAIN_EXCLUDE|UNCERTAIN",
  "confidence": 95,
  "agent": "optional",
  "detail": "optional",
  "evidence": "optional"
}

Certainty values: CERTAIN_INCLUDE, CERTAIN_EXCLUDE, UNCERTAIN

CLI Commands

# Add assessment
python3 .plan/execute-script.py plan-marshall:manage-assessments:manage-assessments \
  add --plan-id {plan_id} --file-path {file_path} --certainty {certainty} --confidence {confidence} \
  [--agent AGENT] [--detail DETAIL] [--evidence EVIDENCE]

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

# Get single assessment
python3 .plan/execute-script.py plan-marshall:manage-assessments:manage-assessments \
  get --plan-id {plan_id} --hash-id {hash_id}

# Clear assessments (all or by agent)
python3 .plan/execute-script.py plan-marshall:manage-assessments:manage-assessments \
  clear --plan-id {plan_id} [--agent AGENT]

Output Format

All commands return TOON format.

Add response:

status: success
hash_id: a3f2c1
file_path: src/File.java

Query response:

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

assessments[15]{hash_id,file_path,certainty,confidence}:
a3f2c1,src/File.java,CERTAIN_INCLUDE,95
b4e3d2,src/Other.java,CERTAIN_EXCLUDE,80

Integration

Producers

| Client | Operation | |--------|-----------| | Analysis agents | add | | Outline agents | add, clear |

Consumers

| Client | Operation | |--------|-----------| | Q-Gate agent | query | | Workflow orchestration | query |