cleveragents/cleveragents-core

Fork 3

Proposal: update specification — project delete deleted_at output and validation empty-run guard #8007

New issue

Open

opened 2026-04-12 19:31:31 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-12 19:31:31 +00:00

Owner

Proposal: Specification Update

This proposal covers two spec discrepancies discovered from recently merged PRs.

Change 1: `agents project delete` JSON/YAML output — add `deleted_at` field

Triggered by: PR #6639 (merged 2026-04-10)

What changed in the implementation:
src/cleveragents/cli/commands/project.py now includes deleted_at (a UTC ISO-8601 timestamp) in the JSON/YAML output of agents project delete. The implementation outputs a flat structure:

{"deleted": "local/docs", "success": true, "deleted_at": "2026-04-10T19:45:43Z"}

What spec section needs updating: §CLI Commands — agents project delete (around line 3490–3543)

Current spec JSON output (simplified):

{
  "command": "agents project delete local/docs",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "deletion_summary": { "project": "local/docs", "resources_unlinked": 1, "data_dir": "..." },
    "index_cleanup": { ... },
    "backups": { ... }
  }
}

Proposed spec JSON output — add deleted_at to the data object:

{
  "command": "agents project delete local/docs",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "deleted": "local/docs",
    "success": true,
    "deleted_at": "2026-04-10T19:45:43Z"
  },
  "timing": { "duration_ms": 530 },
  "messages": [{ "level": "ok", "text": "Project deleted" }]
}

Rationale: The implementation outputs a simpler flat structure with deleted_at. The spec's nested deletion_summary/index_cleanup/backups structure is aspirational and not yet implemented. The spec should reflect the actual implementation output, including the deleted_at timestamp which enables clients to record when deletion occurred.

Scope: §CLI Commands — agents project delete — JSON and YAML output examples (lines ~3490–3543)

Change 2: Validation Apply Gate — empty-run guard behavior

Triggered by: PR #7786 (merged 2026-04-12), fixing issue #7508

What changed in the implementation:
ApplyValidationSummary.all_required_passed now returns False when is_empty is True (i.e., zero validations were run). Previously it returned True for empty result sets, silently bypassing the apply gate. A new required_total property was also added.

What spec section needs updating: §Validation Abstraction — During Execute (around line 22617–22620)

Current spec text (line 22617–22620):

4. **Process results**:
   - **All required validations pass**: Execution is complete. The plan transitions to the review/Apply phase.
   - **Any required validation fails**: The execution actor enters the fix-then-revalidate loop (see Validation Failure Handling below).
   - **Informational validations fail**: Results are recorded in the plan's validation summary. No fix attempts are made.

Proposed addition — add a fourth bullet:

4. **Process results**:
   - **All required validations pass** (and at least one was run): Execution is complete. The plan transitions to the review/Apply phase.
   - **No validations were run** (empty result set): Apply is **blocked**. The plan cannot proceed to Apply without at least one required validation having been executed. This prevents silent bypass of the apply gate when no validations are attached or all attached validations are skipped.
   - **Any required validation fails**: The execution actor enters the fix-then-revalidate loop (see Validation Failure Handling below).
   - **Informational validations fail**: Results are recorded in the plan's validation summary. No fix attempts are made.

Also add to §Validation Abstraction — Apply Gating (line ~46895):

Empty-run guard: Apply is blocked when zero validations were run, even if no required validations explicitly failed. This ensures the apply gate cannot be silently bypassed by misconfigured or missing validation attachments.

Rationale: The implementation now enforces that all_required_passed is False when no validations ran. This is a correctness fix — previously a plan with no validation attachments could silently proceed to Apply without any validation having run. The spec should document this invariant explicitly so implementors and users understand the gate semantics.

Scope:

§Validation Abstraction — During Execute — Process results (line ~22617)
§Validation Abstraction — Apply Gating (line ~46895)
§v3.5.0 Deliverables table row 9 (line ~46895)

Summary

#	Section	Change Type	Triggered By
1	§CLI — project delete JSON/YAML output	Update output schema to include `deleted_at`	PR #6639
2	§Validation — During Execute — Process results	Add empty-run guard bullet	PR #7786
3	§Validation — Apply Gating	Add empty-run guard note	PR #7786

Both changes reflect implementation improvements that are better than the original spec (cleaner output schema, stronger safety invariant). The spec should be updated to match.

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: spec-updater

## Proposal: Specification Update This proposal covers two spec discrepancies discovered from recently merged PRs. --- ### Change 1: `agents project delete` JSON/YAML output — add `deleted_at` field **Triggered by**: PR #6639 (merged 2026-04-10) **What changed in the implementation**: `src/cleveragents/cli/commands/project.py` now includes `deleted_at` (a UTC ISO-8601 timestamp) in the JSON/YAML output of `agents project delete`. The implementation outputs a flat structure: ```json {"deleted": "local/docs", "success": true, "deleted_at": "2026-04-10T19:45:43Z"} ``` **What spec section needs updating**: §CLI Commands — `agents project delete` (around line 3490–3543) **Current spec JSON output** (simplified): ```json { "command": "agents project delete local/docs", "status": "ok", "exit_code": 0, "data": { "deletion_summary": { "project": "local/docs", "resources_unlinked": 1, "data_dir": "..." }, "index_cleanup": { ... }, "backups": { ... } } } ``` **Proposed spec JSON output** — add `deleted_at` to the `data` object: ```json { "command": "agents project delete local/docs", "status": "ok", "exit_code": 0, "data": { "deleted": "local/docs", "success": true, "deleted_at": "2026-04-10T19:45:43Z" }, "timing": { "duration_ms": 530 }, "messages": [{ "level": "ok", "text": "Project deleted" }] } ``` **Rationale**: The implementation outputs a simpler flat structure with `deleted_at`. The spec's nested `deletion_summary`/`index_cleanup`/`backups` structure is aspirational and not yet implemented. The spec should reflect the actual implementation output, including the `deleted_at` timestamp which enables clients to record when deletion occurred. **Scope**: §CLI Commands — `agents project delete` — JSON and YAML output examples (lines ~3490–3543) --- ### Change 2: Validation Apply Gate — empty-run guard behavior **Triggered by**: PR #7786 (merged 2026-04-12), fixing issue #7508 **What changed in the implementation**: `ApplyValidationSummary.all_required_passed` now returns `False` when `is_empty` is `True` (i.e., zero validations were run). Previously it returned `True` for empty result sets, silently bypassing the apply gate. A new `required_total` property was also added. **What spec section needs updating**: §Validation Abstraction — During Execute (around line 22617–22620) **Current spec text** (line 22617–22620): ``` 4. **Process results**: - **All required validations pass**: Execution is complete. The plan transitions to the review/Apply phase. - **Any required validation fails**: The execution actor enters the fix-then-revalidate loop (see Validation Failure Handling below). - **Informational validations fail**: Results are recorded in the plan's validation summary. No fix attempts are made. ``` **Proposed addition** — add a fourth bullet: ``` 4. **Process results**: - **All required validations pass** (and at least one was run): Execution is complete. The plan transitions to the review/Apply phase. - **No validations were run** (empty result set): Apply is **blocked**. The plan cannot proceed to Apply without at least one required validation having been executed. This prevents silent bypass of the apply gate when no validations are attached or all attached validations are skipped. - **Any required validation fails**: The execution actor enters the fix-then-revalidate loop (see Validation Failure Handling below). - **Informational validations fail**: Results are recorded in the plan's validation summary. No fix attempts are made. ``` Also add to §Validation Abstraction — Apply Gating (line ~46895): > **Empty-run guard**: Apply is blocked when zero validations were run, even if no required validations explicitly failed. This ensures the apply gate cannot be silently bypassed by misconfigured or missing validation attachments. **Rationale**: The implementation now enforces that `all_required_passed` is `False` when no validations ran. This is a correctness fix — previously a plan with no validation attachments could silently proceed to Apply without any validation having run. The spec should document this invariant explicitly so implementors and users understand the gate semantics. **Scope**: - §Validation Abstraction — During Execute — Process results (line ~22617) - §Validation Abstraction — Apply Gating (line ~46895) - §v3.5.0 Deliverables table row 9 (line ~46895) --- ## Summary | # | Section | Change Type | Triggered By | |---|---------|-------------|--------------| | 1 | §CLI — project delete JSON/YAML output | Update output schema to include `deleted_at` | PR #6639 | | 2 | §Validation — During Execute — Process results | Add empty-run guard bullet | PR #7786 | | 3 | §Validation — Apply Gating | Add empty-run guard note | PR #7786 | Both changes reflect **implementation improvements** that are better than the original spec (cleaner output schema, stronger safety invariant). The spec should be updated to match. --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-updater

HAL9000 added the

labels

2026-04-12 19:33:50 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-12 19:33:59 +00:00

HAL9000 referenced this issue

2026-04-12 19:34:28 +00:00

[AUTO-SPEC] Status: Specification Update (Cycle 1) #8005

HAL9000 added

and removed

labels

2026-04-14 05:48:38 +00:00

HAL9000 commented

2026-04-14 05:50:07 +00:00

Author

Owner

✅ Verified — Valid spec proposal: project delete output and validation empty-run guard need spec documentation. MoSCoW: Should-have. Priority: Medium.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Verified** — Valid spec proposal: project delete output and validation empty-run guard need spec documentation. MoSCoW: Should-have. Priority: Medium. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor