@urielsh/prodify 0.1.0

package/.prodify/artifacts/status-output-spec.md

@@ -0,0 +1,349 @@
+# Status Output Spec
+
+Date: 2026-03-29
+Scope: `./.prodify/`
+
+## Purpose
+
+Define a concise human-readable status view for Prodify.
+
+The status view is intended for:
+
+- CLI output from `prodify status`
+- quick operator inspection
+- agent-readable summaries that do not require opening raw JSON artifacts
+
+The status view must summarize the current run without executing work or mutating state.
+
+## Fields Shown
+
+The status view should show these fields in this order:
+
+1. `Status`
+2. `Current task`
+3. `Next task`
+4. `Current phase`
+5. `Last completed task`
+6. `Completed tasks`
+7. `Pending tasks`
+8. `Selected refactor step`
+9. `Latest validation`
+10. `Note`
+
+## Field Definitions
+
+### Status
+Source:
+- `run_state.json.status`
+
+Meaning:
+- the top-level runtime condition
+
+Examples:
+- `ready`
+- `running`
+- `awaiting_validation`
+- `blocked`
+- `failed`
+- `complete`
+
+### Current Task
+Source:
+- `run_state.json.current_task`
+
+Display rule:
+- show the active task if non-null
+- otherwise show `none`
+
+### Next Task
+Source:
+- `run_state.json.next_task`
+- optionally confirmed by the resolver when status output is enriched by resolver logic
+
+Display rule:
+- show the next deterministic task when available
+- show `none` for terminal completion
+- show `blocked` or `unavailable` when state is incomplete and no trustworthy next task can be shown
+
+### Current Phase
+Derived from runtime status and task position.
+
+Display rule:
+- `ready` -> `ready to run`
+- `running` -> `executing`
+- `awaiting_validation` -> `validation pending`
+- `blocked` -> `blocked`
+- `failed` -> `retry or repair required`
+- `complete` -> `complete`
+
+This is a human-friendly phase label, not a separate stored runtime field.
+
+### Last Completed Task
+Source:
+- `run_state.json.last_completed_task`
+
+Display rule:
+- show the last completed runtime task
+- show `none` when no task has completed yet
+
+### Completed Tasks
+Derived from:
+- `run_state.json.last_completed_task`
+- `task_log.json.executions`
+
+Display rule:
+- summarize completed runtime tasks from the fixed pipeline:
+  - `01-understand`
+  - `02-diagnose`
+  - `03-architecture`
+  - `04-plan`
+  - repeated `05-refactor` and `06-validate` cycles should be summarized compactly
+
+Recommended display:
+- show a short list for linear tasks already completed
+- for refactor-loop work, show either:
+  - completed step count, or
+  - completed step IDs if the list is short
+
+### Pending Tasks
+Derived from:
+- fixed runtime pipeline
+- current `next_task`
+- loop state
+- completed-step state when available
+
+Display rule:
+- for the linear pipeline, show remaining named tasks after `last_completed_task`
+- when in the refactor loop:
+  - show `05-refactor -> 06-validate` as the remaining loop path
+  - optionally include remaining step count if available
+
+### Selected Refactor Step
+Source:
+- `run_state.json.selected_refactor_step`
+
+Display rule:
+- show the step ID when relevant
+- show `none` when not in refactor-loop work
+
+### Latest Validation
+Derived from:
+- `validation_report.md`
+- current runtime state when validation report is incomplete
+
+Display rule:
+- show one of:
+  - `PASS`
+  - `FAIL`
+  - `inconclusive`
+  - `unknown`
+
+Rules:
+- if `validation_report.md` explicitly contains a resolved result, show it
+- if the report is template-only or missing a trustworthy result, show `unknown` or `inconclusive`
+- do not display `PASS` unless it is actually supported by the validation source
+
+### Note
+Source:
+- first high-signal entry in `run_state.json.notes`
+
+Display rule:
+- show the most useful short note if one exists
+- omit the field entirely if there is no note
+
+## Formatting Guidelines
+
+### General Style
+- keep the output concise
+- prefer one line per field
+- use stable labels
+- avoid prose paragraphs
+- avoid dumping raw JSON
+
+### Recommended Format
+
+Use this compact line-oriented format:
+
+```text
+Status: <status>
+Current task: <task-or-none>
+Next task: <task-or-none>
+Current phase: <human-phase>
+Last completed task: <task-or-none>
+Completed tasks: <summary>
+Pending tasks: <summary>
+Selected refactor step: <step-or-none>
+Latest validation: <result>
+Note: <short-note>
+```
+
+### Omission Rules
+- omit `Selected refactor step` when no step is active and the run has not entered refactor work yet
+- omit `Note` when no note exists
+- keep `Completed tasks` and `Pending tasks` summarized rather than exhaustive when the output would become noisy
+
+### Readability Rules
+- prefer task IDs over verbose restatements
+- keep lists comma-separated on a single line when short
+- if a list grows long, compress to counts plus the most relevant item
+- never print placeholder values from templates literally, such as `PASS/FAIL:`
+
+## State-Specific Output Rules
+
+### Ready
+Show:
+- current status
+- next runnable task
+- pending pipeline tasks
+
+Tone:
+- runnable and calm
+
+### Running
+Show:
+- active current task
+- next task if known
+- current phase as `executing`
+
+Tone:
+- resume-oriented
+
+### Awaiting Validation
+Show:
+- `Current phase: validation pending`
+- `Next task: 06-validate`
+- active selected refactor step
+
+Tone:
+- immediate and specific
+
+### Blocked
+Show:
+- `Status: blocked`
+- blocker note if present
+- latest validation as `unknown` or `inconclusive` when appropriate
+
+Tone:
+- clear, not noisy
+
+### Failed
+Show:
+- failed state
+- retry target if one exists
+- selected failed step when relevant
+- failure note
+
+Tone:
+- actionable
+
+### Complete
+Show:
+- terminal completion
+- no next task
+- completed tasks summary
+- latest validation result if known
+
+Tone:
+- succinct and final
+
+## Example Output
+
+### Example 1 - Fresh Start
+
+```text
+Status: ready
+Current task: none
+Next task: 01-understand
+Current phase: ready to run
+Last completed task: none
+Completed tasks: none
+Pending tasks: 01-understand, 02-diagnose, 03-architecture, 04-plan, 05-refactor -> 06-validate
+Latest validation: unknown
+```
+
+### Example 2 - Awaiting Validation
+
+```text
+Status: awaiting_validation
+Current task: none
+Next task: 06-validate
+Current phase: validation pending
+Last completed task: 05-refactor
+Completed tasks: 01-understand, 02-diagnose, 03-architecture, 04-plan, 1 validated refactor step
+Pending tasks: 06-validate, remaining refactor loop
+Selected refactor step: step-03-extract-service
+Latest validation: unknown
+```
+
+### Example 3 - Blocked State
+
+```text
+Status: blocked
+Current task: none
+Next task: unavailable
+Current phase: blocked
+Last completed task: 04-plan
+Completed tasks: 01-understand, 02-diagnose, 03-architecture, 04-plan
+Pending tasks: 05-refactor -> 06-validate
+Latest validation: inconclusive
+Note: run_state.json is missing completed_step_ids
+```
+
+### Example 4 - Failed Validation
+
+```text
+Status: failed
+Current task: none
+Next task: 05-refactor
+Current phase: retry or repair required
+Last completed task: 05-refactor
+Completed tasks: 01-understand, 02-diagnose, 03-architecture, 04-plan, 2 validated refactor steps
+Pending tasks: retry selected refactor step, then continue validation loop
+Selected refactor step: step-03-extract-service
+Latest validation: FAIL
+Note: retry the selected step after correcting the regression
+```
+
+### Example 5 - Complete
+
+```text
+Status: complete
+Current task: none
+Next task: none
+Current phase: complete
+Last completed task: 06-validate
+Completed tasks: 01-understand, 02-diagnose, 03-architecture, 04-plan, all planned refactor steps validated
+Pending tasks: none
+Latest validation: PASS
+```
+
+## Current-State Compatibility Rules
+
+The current runtime artifacts are still partial, so status output must handle incompleteness gracefully.
+
+### Missing `completed_step_ids`
+If `run_state.json` lacks `completed_step_ids`:
+
+- do not assume an empty list
+- show status as currently recorded
+- set `Next task` to `blocked` or `unavailable` if resolver logic cannot trust the state
+- use `Note` to explain the schema gap
+
+### Template-Only `validation_report.md`
+If the validation report still contains placeholder template fields:
+
+- show `Latest validation: unknown` or `Latest validation: inconclusive`
+- do not claim `PASS`
+- do not echo placeholder template text directly
+
+### Empty `task_log.json`
+If task history is empty:
+
+- allow `Completed tasks: none`
+- do not infer hidden task progress
+
+## Implementation Notes
+
+- `prodify status` should remain a summary view, not a full diagnostic dump.
+- If resolver enrichment is used, it should only clarify the displayed next task; it should not expand into a full `prodify next` response.
+- Prefer showing trustworthy unknowns over presenting guessed progress.

package/.prodify/artifacts/step-selection-design.md

@@ -0,0 +1,251 @@
+# Step Selection Design
+
+Date: 2026-03-28
+Scope: `./.prodify/artifacts/refactor_plan.md`
+
+## Purpose
+Define how the system selects the next refactor step automatically for Task `05-refactor`.
+
+The step selector is responsible for:
+- parsing candidate step IDs from `refactor_plan.md`
+- comparing those step IDs against workflow state
+- selecting the next safe executable step
+- deciding when the loop should stop because no valid remaining steps exist
+
+The step selector is not responsible for:
+- executing Task `05-refactor`
+- validating the resulting artifact after Task `05-refactor`
+- mutating workflow state directly
+
+## Selection Logic
+
+### Inputs
+- `.prodify/artifacts/refactor_plan.md`
+- `.prodify/artifacts/run_state.json`
+
+Required state fields:
+- `selected_refactor_step`
+- `completed_step_ids`
+- `status`
+- `next_task`
+- `last_completed_task`
+
+### Selection Priority
+Select the next step using this priority order:
+
+1. **Existing runnable selected step**
+   - If `selected_refactor_step` is non-null
+   - and that step exists in `refactor_plan.md`
+   - and that step is not already in `completed_step_ids`
+   - then keep it as the selected step
+
+2. **Retry after failed validation**
+   - If `status` is `failed`
+   - and `next_task` is `05-refactor`
+   - and `selected_refactor_step` still exists in the plan
+   - retry the same selected step unless operator logic explicitly replaces it
+
+3. **First remaining step in plan order**
+   - Parse steps from `refactor_plan.md` in document order
+   - remove all step IDs already present in `completed_step_ids`
+   - choose the first remaining valid step
+
+4. **No selectable step**
+   - If no valid uncompleted step remains, return stop/no-step-selected
+
+### Safe-Step Rule
+The next safe step is the first valid, uncompleted step in the declared order of `refactor_plan.md`.
+
+The selector does not reorder steps by risk, file count, or complexity unless `refactor_plan.md` itself changes the order. Safety comes from honoring the planned order rather than inventing a new one.
+
+## Parsing Assumptions
+
+### Primary Format Assumption
+The selector parses step blocks from the `## Steps` section of `refactor_plan.md`.
+
+Each step block must begin with:
+```md
+### Step ID:
+```
+
+And should be followed by the standard fields:
+- `Description:`
+- `Files:`
+- `Risk:`
+- `Expected outcome:`
+- `Validation command:`
+
+### Step ID Extraction Rule
+Treat the first non-empty value associated with `### Step ID:` as the canonical step ID.
+
+Acceptable parsed examples:
+- `### Step ID: step-01-rename-module`
+- `### Step ID:` followed by `- step-01-rename-module`
+
+### Plan Completeness Assumption
+A plan is considered populated only if at least one step block yields a non-placeholder step ID.
+
+Placeholder values that must not count as real step IDs:
+- `Step ID`
+- `step-id`
+- `TBD`
+- empty value
+
+### Ordering Rule
+Step order is the document order of parsed step blocks under `## Steps`.
+
+## Parsing Outcomes
+
+### Valid Parsed Plan
+A parsed plan is valid when:
+- `## Steps` exists
+- at least one step block is present
+- every parsed step block has a non-placeholder step ID
+- step IDs are unique
+
+### Unpopulated Template Plan
+A plan is considered unpopulated when:
+- `## Steps` exists but only template placeholder content is present
+- or no real step IDs can be extracted
+
+This is not the same as "no steps remain." It means planning is incomplete and step selection must stop in a blocked state.
+
+### Malformed Plan
+A plan is malformed when:
+- `## Steps` is missing
+- a step block exists without a parseable ID
+- duplicate step IDs are present
+- step structure is broken enough that deterministic selection is impossible
+
+Malformed plans must fail selection rather than silently guessing.
+
+## Comparison With Run State
+
+### Completed Vs Remaining Steps
+- `completed_step_ids` are authoritative for steps that already passed validation.
+- Parsed plan step IDs minus `completed_step_ids` yields the remaining candidate steps.
+
+### Selected Step Consistency
+- If `selected_refactor_step` exists and is already in `completed_step_ids`, it is stale and must be cleared or ignored by the selector.
+- If `selected_refactor_step` is missing from the current plan, selection must stop with an invalid-state result.
+
+### Loop-State Expectations
+- During `awaiting_validation`, no new step should be selected; the existing `selected_refactor_step` remains active for Task `06-validate`.
+- During `ready` with `next_task: "05-refactor"`, the selector may choose the next step.
+- During `failed` with `next_task: "05-refactor"`, the selector should preserve the failed step if it is still valid.
+
+## Edge Cases
+
+### Edge Case 1 - Template-Only Refactor Plan
+Condition:
+- `refactor_plan.md` still contains placeholder template content and no real step IDs
+
+Behavior:
+- do not select a step
+- return `plan_unpopulated`
+- recommend blocking Task `05-refactor` until Task `04-plan` produces a real step list
+
+This is the canonical `template-only refactor plan` case.
+
+### Edge Case 2 - Duplicate Step IDs
+Condition:
+- two or more step blocks share the same parsed step ID
+
+Behavior:
+- fail selection
+- return `duplicate_step_id`
+- require plan correction before continuing
+
+### Edge Case 3 - Missing Selected Step
+Condition:
+- `selected_refactor_step` is set in `run_state.json` but no matching step exists in `refactor_plan.md`
+
+Behavior:
+- fail selection
+- return `selected_step_missing`
+- require state repair or plan repair before continuing
+
+### Edge Case 4 - All Steps Completed
+Condition:
+- every parsed step ID appears in `completed_step_ids`
+
+Behavior:
+- do not select a new step
+- return `no_steps_remaining`
+- signal that the refactor loop may stop after validation logic confirms completion
+
+### Edge Case 5 - Completed Step IDs Not In Plan
+Condition:
+- `completed_step_ids` contains one or more IDs absent from the current plan
+
+Behavior:
+- fail selection
+- return `completed_step_not_in_plan`
+- require state repair before continuing
+
+### Edge Case 6 - Failed Step Retry
+Condition:
+- `status` is `failed`
+- `next_task` is `05-refactor`
+- `selected_refactor_step` still exists in the plan and is not completed
+
+Behavior:
+- keep the same selected step
+- do not advance to a later step automatically
+
+## Stop Conditions
+
+### Stop Condition 1 - Plan Unpopulated
+- no real steps can be parsed from `refactor_plan.md`
+- result: stop selection and block execution
+
+### Stop Condition 2 - Plan Malformed
+- parsing cannot produce a deterministic ordered step list
+- result: stop selection and fail/ block execution
+
+### Stop Condition 3 - No Steps Remaining
+- every valid parsed step has already been completed
+- result: stop selection and signal loop completion
+
+### Stop Condition 4 - Invalid State
+- `selected_refactor_step` or `completed_step_ids` contradict the current plan
+- result: stop selection and require state correction
+
+## Suggested Selection Result Shape
+```json
+{
+  "status": "selected",
+  "selected_step_id": "step-01-rename-module",
+  "remaining_step_ids": [
+    "step-01-rename-module",
+    "step-02-add-guard-clause"
+  ],
+  "reason": "first_remaining_step"
+}
+```
+
+Possible `status` values:
+- `selected`
+- `no_steps_remaining`
+- `plan_unpopulated`
+- `malformed_plan`
+- `invalid_state`
+
+## Integration Notes
+
+### Integration With Run-State Logic
+- The selector reads `selected_refactor_step`, `completed_step_ids`, `status`, and `next_task`.
+- The run-state updater decides how the selection result changes `run_state.json`.
+
+### Integration With Dispatcher
+- The dispatcher should invoke step selection before dispatching Task `05-refactor` when `selected_refactor_step` is null or needs validation.
+- The dispatcher should not choose a step by itself if the step selector returns a stop condition.
+
+### Integration With Task 06 Loop
+- Step selection runs only when the workflow is returning to `05-refactor`.
+- It must not choose a new step while `06-validate` is still pending for the current one.
+
+## Implementation Notes
+- Parse only the `## Steps` section to avoid accidentally treating summary text as steps.
+- Prefer explicit failure over heuristics when step structure is ambiguous.
+- Preserve document order; do not sort step IDs independently of the plan.