@urielsh/prodify 0.1.0

package/.prodify/artifacts/cli-command-design.md

@@ -0,0 +1,299 @@
+# CLI Command Design
+
+Date: 2026-03-29
+Scope: `./.prodify/`
+
+## Purpose
+
+Define the operator-facing CLI surface for running, advancing, and inspecting Prodify.
+
+This command set must:
+
+- use the runtime state and resolver design as the control source
+- expose a minimal, understandable interface
+- separate state-changing commands from read-only commands
+
+## Command List
+
+The initial CLI surface contains exactly three commands:
+
+- `prodify run`
+- `prodify next`
+- `prodify status`
+
+## Shared Inputs
+
+All three commands may read:
+
+- `.prodify/artifacts/run_state.json`
+- `.prodify/artifacts/task_log.json`
+- `.prodify/artifacts/validation_report.md`
+
+Supporting design references:
+
+- `.prodify/artifacts/run-state-design.md`
+- `.prodify/artifacts/next-step-resolver-design.md`
+
+## Command Boundaries
+
+### `prodify run`
+- mutates workflow state by executing work
+- may write runtime artifacts and update task history
+- uses the resolver to decide what to execute now
+
+### `prodify next`
+- does not execute work
+- does not mutate workflow state
+- shows the resolver's current next-step decision
+
+### `prodify status`
+- does not execute work
+- does not mutate workflow state
+- shows a concise human-readable snapshot of progress
+
+## Command Behavior
+
+### `prodify run`
+
+#### Goal
+Execute the next allowed unit of work from the current runtime state.
+
+#### Inputs
+- required:
+  - `.prodify/artifacts/run_state.json`
+- optional but normally present:
+  - `.prodify/artifacts/task_log.json`
+  - `.prodify/artifacts/validation_report.md`
+  - runtime task files under `.prodify/tasks/`
+  - runtime templates under `.prodify/templates/`
+
+#### Behavior
+1. Load and validate `run_state.json`.
+2. Invoke the next-step resolver.
+3. If the resolver returns:
+   - `dispatch`:
+     - dispatch the resolved task
+   - `resume`:
+     - resume the interrupted task
+   - `retry`:
+     - rerun the required retry task only
+   - `stop_blocked`:
+     - stop without mutation and print the blocker
+   - `stop_failed`:
+     - stop without mutation and print the failure
+   - `stop_complete`:
+     - stop without mutation and print completion
+4. If a task runs:
+   - perform pre-run validation
+   - execute the task
+   - validate the output artifact
+   - update `run_state.json`
+   - append to `task_log.json`
+5. Exit after one deterministic run cycle.
+
+#### Output
+Machine-oriented summary plus concise human feedback:
+
+- resolved decision
+- task executed or resumed, if any
+- artifact written, if any
+- state result
+- next recommended action
+
+#### Mutation Rule
+`prodify run` is the only command in this initial CLI surface that may advance workflow state.
+
+### `prodify next`
+
+#### Goal
+Show what Prodify would do next if asked to run now.
+
+#### Inputs
+- `.prodify/artifacts/run_state.json`
+- `.prodify/artifacts/task_log.json`
+- `.prodify/artifacts/validation_report.md`
+
+#### Behavior
+1. Load runtime state.
+2. Invoke the next-step resolver in read-only mode.
+3. Return the resolver decision without executing any task.
+
+#### Output
+Return:
+
+- decision
+- resolved task or stop outcome
+- reason
+- resume condition
+- required repair items if blocked or failed
+
+#### Mutation Rule
+`prodify next` must not change:
+
+- `run_state.json`
+- `task_log.json`
+- any artifact
+
+### `prodify status`
+
+#### Goal
+Show a concise operator summary of current workflow progress.
+
+#### Inputs
+- `.prodify/artifacts/run_state.json`
+- `.prodify/artifacts/task_log.json`
+- `.prodify/artifacts/validation_report.md`
+
+#### Behavior
+1. Read current runtime state.
+2. Summarize current progress and latest known validation posture.
+3. Optionally call the resolver to enrich status with the current next-step decision.
+4. Print a concise human-readable view.
+
+#### Output
+Must include at minimum:
+
+- current status
+- current task or next task
+- last completed task
+- selected refactor step, if any
+- completed step count or IDs when relevant
+- latest validation posture
+
+Detailed formatting is deferred to Task `52-add-status-output`.
+
+#### Mutation Rule
+`prodify status` is strictly read-only.
+
+## Mapping To Workflow State
+
+| State condition | `prodify run` | `prodify next` | `prodify status` |
+| --- | --- | --- | --- |
+| `ready` with valid `next_task` | execute the resolved task | show the task to be run | show runnable state and upcoming task |
+| `running` with valid `current_task` | resume current task | show resume target | show interrupted task and resumable state |
+| `awaiting_validation` | execute `06-validate` | show validation-required next step | show validation pending |
+| `blocked` | stop and print blocker | show blocked decision | show blocker notes |
+| `failed` with retryable target | retry only the required task | show retry target | show failed state and retry context |
+| `complete` | stop and print completion | show complete stop | show completed run |
+
+## State-Specific Command Notes
+
+### Ready
+- `run` should advance one step.
+- `next` should expose the exact resolver choice.
+- `status` should communicate that the system is runnable.
+
+### Running
+- `run` should resume, not skip ahead.
+- `next` should report `resume`.
+- `status` should show the interrupted task clearly.
+
+### Awaiting Validation
+- `run` must execute `06-validate` immediately.
+- `next` must not suggest `05-refactor`.
+- `status` should make validation urgency visible.
+
+### Blocked
+- `run` must not guess or auto-repair.
+- `next` should report the blocker and repair condition.
+- `status` should surface the blocker note plainly.
+
+### Failed
+- `run` should only retry the deterministic retry target after failure conditions are corrected.
+- `next` should expose whether retry is possible or state reconciliation is needed.
+- `status` should show the failed step or task and the failure note.
+
+### Complete
+- `run` should exit cleanly without further work.
+- `next` should return a stop-complete decision.
+- `status` should show terminal completion.
+
+## Current-State Compatibility Rules
+
+The current repo still contains partial runtime artifacts. The CLI design must account for that.
+
+### Missing `completed_step_ids`
+If `run_state.json` is missing required resolver fields:
+
+- `run` must stop blocked
+- `next` must report schema incompleteness
+- `status` must show that state is incomplete rather than pretending the run is healthy
+
+### Template-Only `validation_report.md`
+If the validation report is still placeholder-shaped:
+
+- `run` must treat validation-dependent decisions as blocked or inconclusive when resolver rules require it
+- `next` must report `validation_inconclusive`
+- `status` should show latest validation as unknown or inconclusive, not PASS
+
+## Example Command Outputs
+
+### Example 1 - `prodify next`
+Input condition:
+- `status: ready`
+- `next_task: "04-plan"`
+
+Example output:
+
+```text
+decision: dispatch
+resolved_task: 04-plan
+reason: linear_pipeline_ready
+resume_condition: state already runnable
+```
+
+### Example 2 - `prodify run`
+Input condition:
+- `status: awaiting_validation`
+- `next_task: "06-validate"`
+
+Example output:
+
+```text
+decision: dispatch
+executed_task: 06-validate
+artifact_written: .prodify/artifacts/validation_report.md
+state_result: ready
+next_action: evaluate remaining refactor steps
+```
+
+### Example 3 - `prodify status`
+Input condition:
+- `status: failed`
+- `next_task: "05-refactor"`
+- `selected_refactor_step: "step-03-extract-service"`
+
+Example output:
+
+```text
+Status: failed
+Current task: none
+Next task: 05-refactor
+Last completed task: 05-refactor
+Selected refactor step: step-03-extract-service
+Latest validation: FAIL
+Note: retry the selected step after correcting the regression
+```
+
+## Minimal Interface Contract
+
+### `prodify run`
+- input: current runtime artifacts
+- output: one execution-cycle result
+- side effects: yes
+
+### `prodify next`
+- input: current runtime artifacts
+- output: one resolver decision
+- side effects: no
+
+### `prodify status`
+- input: current runtime artifacts
+- output: one concise status summary
+- side effects: no
+
+## Implementation Notes
+
+- Keep the first CLI version narrow and deterministic.
+- Route all execution intent through the resolver instead of duplicating branching logic inside commands.
+- Let Task `52-add-status-output` refine formatting, while this task defines command semantics and command/state boundaries.

package/.prodify/artifacts/completed-steps-tracking.md

@@ -0,0 +1,201 @@
+# Completed Steps Tracking
+
+Date: 2026-03-28
+Scope: `./.prodify/artifacts/run_state.json`
+
+## Purpose
+Define how completed refactor steps are recorded, reused, protected from duplicate execution, and safely overridden when recovery is necessary.
+
+## Storage Model
+
+### Canonical Store
+Use `completed_step_ids` in `.prodify/artifacts/run_state.json` as the canonical source of truth for completed refactor steps.
+
+Field shape:
+```json
+{
+  "completed_step_ids": [
+    "step-01-rename-module",
+    "step-02-add-guard-clause"
+  ]
+}
+```
+
+### Meaning
+- Each entry represents one refactor-plan step that:
+  - was executed by Task `05-refactor`
+  - was validated successfully by Task `06-validate`
+- A step is not complete merely because Task `05-refactor` ran.
+- A step becomes complete only after validation PASS.
+
+### Scope Constraint
+- `completed_step_ids` applies only to steps parsed from `refactor_plan.md`.
+- IDs not present in the current parsed plan are invalid and must trigger state repair.
+
+## Update Rules
+
+### Add Rule
+Append a step ID to `completed_step_ids` only when all of the following are true:
+- `selected_refactor_step` is non-null
+- Task `06-validate` completed with PASS for that step
+- the step exists in the current parsed `refactor_plan.md`
+- the step ID is not already present in `completed_step_ids`
+
+### Do Not Add Rule
+Do not append the step ID when:
+- Task `05-refactor` finished but Task `06-validate` has not run yet
+- Task `06-validate` failed
+- Task `06-validate` was inconclusive
+- the selected step is missing from the plan
+- the plan is malformed or unpopulated
+
+### Remove Rule
+Remove a step ID only through an explicit manual override or state-repair action.
+
+Automatic execution must not silently remove completed steps.
+
+### Reconciliation Rule
+On every step-selection or resume pass:
+- compare `completed_step_ids` against the current parsed plan
+- if any completed ID is absent from the plan:
+  - stop execution
+  - mark the state invalid or failed
+  - require reconciliation before continuing
+
+## Duplicate Prevention
+
+### Storage-Level Prevention
+- `completed_step_ids` must behave as a set, even though it is stored as an ordered array.
+- The same step ID must not appear more than once.
+
+### Execution-Level Prevention
+Before selecting or dispatching a step:
+- exclude every ID already present in `completed_step_ids`
+- do not re-run a step that is already marked complete unless a manual override explicitly removed it from the completed list
+
+### Append Guard
+Before appending a step on validation PASS:
+- check whether the step ID already exists in `completed_step_ids`
+- if it already exists:
+  - do not append it again
+  - treat the situation as a stale-state warning rather than creating a duplicate
+
+### Order Rule
+- Preserve completion order in the array for traceability.
+- Duplicate prevention takes priority over preserving attempted append order.
+
+## Override Behavior
+
+### Override Types
+Supported manual overrides:
+1. **Remove one completed step**
+   - used when a previously completed step must be rerun
+2. **Reset all completed steps**
+   - used when the loop must restart from the beginning
+3. **Add a completed step manually**
+   - allowed only for explicit recovery/migration scenarios, never as the normal execution path
+
+### Override Requirements
+Every override must:
+- be explicit and operator-driven
+- name the exact step IDs affected
+- leave a high-signal note in `run_state.json`
+- trigger a consistency check against the current parsed plan
+
+### Safe Remove Override
+When removing a completed step:
+- remove the step ID from `completed_step_ids`
+- clear or reset `selected_refactor_step` if it points to an inconsistent step
+- set `next_task` to `05-refactor`
+- set `status` to `ready` or `blocked` depending on whether more repair is needed
+
+### Safe Reset Override
+When resetting all completed steps:
+- set `completed_step_ids` to `[]`
+- set `selected_refactor_step` to `null`
+- set `next_task` to `05-refactor` only if a valid step can be reselected
+- otherwise block until planning/state repair is complete
+
+### Manual Add Override
+Manual addition is the riskiest override and should be rare.
+
+Allowed only when:
+- the operator is reconciling known-good historical state
+- the step exists in the current parsed plan
+- a note explains why the system is trusting this completion without the current loop replay
+
+After a manual add:
+- re-run consistency checks
+- ensure the step selector excludes the step
+
+## Override Safety Rules
+- Overrides must never create duplicates.
+- Overrides must never reference step IDs absent from the current plan.
+- Overrides must never silently skip required validation for new work.
+- After any override, the system must re-evaluate:
+  - `selected_refactor_step`
+  - `completed_step_ids`
+  - `next_task`
+  - `status`
+
+## Reuse Rules
+
+### Normal Reuse
+Completed steps are reused by exclusion:
+- the step-selection layer subtracts `completed_step_ids` from the parsed plan steps
+- only remaining steps are considered selectable
+
+### Loop Reuse
+After Task `06-validate` PASS:
+- append the just-validated step
+- select the next remaining step if any exist
+- stop complete if none remain
+
+### Resume Reuse
+On resume:
+- trust `completed_step_ids` only after verifying all IDs still exist in the current plan
+- if verification fails, block execution until repaired
+
+## Invalid States
+
+### Invalid Completed-Step States
+The following states are invalid:
+- duplicate step IDs in `completed_step_ids`
+- a completed step ID not present in `refactor_plan.md`
+- a completed step ID that is also the active `selected_refactor_step` for retry
+- marking a step complete before validation PASS
+
+### Invalid-State Behavior
+If any invalid state is detected:
+- stop execution
+- set the workflow to `failed` or `blocked`
+- record a precise repair note
+- require reconciliation before the next step may be selected
+
+## Integration Notes
+
+### Integration With Run-State Logic
+- `completed_step_ids` lives in `run_state.json`.
+- The run-state layer owns the actual write/update mechanics.
+- This document defines when updates are valid.
+
+### Integration With Step Selection
+- Step selection must exclude completed IDs from candidate selection.
+- If completed IDs contradict the parsed plan, step selection must stop.
+
+### Integration With Refactor/Validate Loop
+- The refactor/validate loop may add a step only after validation PASS.
+- FAIL or inconclusive validation must leave `completed_step_ids` unchanged.
+
+## Suggested Consistency Check
+Before dispatching or resuming Task `05-refactor`:
+1. Parse valid step IDs from `refactor_plan.md`.
+2. Confirm `completed_step_ids` contains unique values only.
+3. Confirm every completed ID exists in the parsed plan.
+4. Confirm `selected_refactor_step` is not simultaneously treated as completed unless state repair explicitly requires it.
+5. Stop on any inconsistency.
+
+## Implementation Notes
+- Treat `completed_step_ids` as append-only during normal successful execution.
+- Reserve deletions for explicit override or reconciliation flows.
+- Prefer blocking on ambiguous state over guessing which steps are complete.

package/.prodify/artifacts/diagnostic_report.md

@@ -0,0 +1,45 @@
+# Diagnostic Report
+
+## Top 5 Priorities
+1. 
+2. 
+3. 
+4. 
+5. 
+
+## Critical Issues
+- Issue:
+  - File:
+  - Category:
+  - Impact:
+  - Evidence:
+
+## High Issues
+- Issue:
+  - File:
+  - Category:
+  - Impact:
+  - Evidence:
+
+## Medium Issues
+- Issue:
+  - File:
+  - Category:
+  - Impact:
+  - Evidence:
+
+## Low Issues
+- Issue:
+  - File:
+  - Category:
+  - Impact:
+  - Evidence:
+
+## Reliability Risks
+- 
+
+## Technical Debt Score
+- Score:
+
+## Notes
+- 

package/.prodify/artifacts/hardening-patch-summary.md

@@ -0,0 +1,57 @@
+# Hardening Patch Summary
+
+## Scope
+This patch applied the hardening changes defined by Tasks 81 through 84 to the canonical runtime at `.prodify/` and the root `AGENTS.md`.
+
+## Files Changed
+- `AGENTS.md`
+- `.prodify/tasks/01-understand.md`
+- `.prodify/tasks/02-diagnose.md`
+- `.prodify/tasks/03-architecture.md`
+- `.prodify/tasks/04-plan.md`
+- `.prodify/tasks/05-refactor.md`
+- `.prodify/tasks/06-validate.md`
+- `.prodify/templates/refactor_plan.template.md`
+
+## Changes Applied
+### Persona and role language removal
+- Removed persona-style sections such as `## Identity & Mandate`.
+- Removed role labels and identity framing from the core task suite.
+- Replaced persona framing with operational sections:
+  - `## Goal`
+  - `## Scope`
+  - `## Inputs`
+  - `## Execution Instructions`
+  - `## Output Specification`
+  - `## Failure Conditions`
+  - `## Definition of Done`
+
+### Task protocol hardening
+- Added explicit failure conditions to every core task.
+- Added explicit template conformance requirements for every task output.
+- Added explicit non-modification constraints to Tasks `01` through `04` and `06`.
+- Tightened Task `05` so it must execute exactly one selected refactor step and stop on ambiguous or widened scope.
+- Tightened Task `06` so it must run after Task `05` for the same step and must emit an explicit `PASS` or `FAIL` verdict.
+
+### Refactor plan template hardening
+- Replaced the loose plan structure with a fixed repeated step block.
+- Added `Total steps` to the summary section.
+- Standardized each step block to:
+  - `### Step: <ID>`
+  - `- Status: pending`
+  - `- Description:`
+  - `- Files:`
+  - `- Risk:`
+  - `- Expected outcome:`
+  - `- Validation command:`
+
+### Runtime rule alignment
+- Updated `AGENTS.md` to use `completed_step_ids` as the canonical completed-step field.
+- Updated the refactor/validate loop wording so a failed validation retries or repairs the same selected step before continuing.
+- Updated the stop condition so a passed validation continues only when more steps remain.
+
+## Deviations From Plan
+- `AGENTS.md` required a targeted update in addition to the task docs and template so the runtime contract would match the hardened task suite. This was necessary to avoid leaving conflicting loop and state semantics in the root protocol.
+
+## Unresolved Items
+- None identified in the hardening patch itself.

package/.prodify/artifacts/hardening-verification-report.md

@@ -0,0 +1,48 @@
+# Hardening Verification Report
+
+## Verification Scope
+Verify that the runtime hardening changes from Tasks 81 through 85 were applied consistently across the canonical runtime under `.prodify/` and the root `AGENTS.md`.
+
+## Results
+### Check 1: Persona language removed from core tasks
+- Result: PASS
+- Evidence: No remaining matches for persona or role markers in `.prodify/tasks/01-understand.md` through `.prodify/tasks/06-validate.md`.
+
+### Check 2: Explicit failure conditions present in all core tasks
+- Result: PASS
+- Evidence: Every core task now includes a `## Failure Conditions` section with explicit stop criteria.
+
+### Check 3: Source-modification constraints preserved
+- Result: PASS
+- Evidence:
+  - Tasks `01` through `04` explicitly state `MUST NOT modify source code`.
+  - Task `06` explicitly states `MUST NOT modify source code`.
+  - Task `05` explicitly restricts scope to one selected step and forbids unrelated file edits.
+
+### Check 4: Refactor execution discipline enforced
+- Result: PASS
+- Evidence: Task `05` explicitly requires execution of exactly one selected refactor step and requires stopping when the selected step is ambiguous, missing, malformed, or overly broad.
+
+### Check 5: Validation verdict discipline enforced
+- Result: PASS
+- Evidence: Task `06` explicitly requires a `PASS` or `FAIL` verdict and treats unsupported verdicts as a stop condition.
+
+### Check 6: Refactor plan template hardened
+- Result: PASS
+- Evidence: `.prodify/templates/refactor_plan.template.md` now uses a fixed repeated step block with `### Step: <ID>` and `- Status: pending`.
+
+### Check 7: Runtime contract aligned
+- Result: PASS
+- Evidence:
+  - `AGENTS.md` now refers to `completed_step_ids`.
+  - `AGENTS.md` loop behavior now matches the hardened refactor/validate semantics.
+
+## Commands Used
+- `rg -n "Identity & Mandate|Role:|@Repository-Explorer|@Security-Auditor|@Principal-Architect|@DevOps-Planner|@Implementation-Specialist|@Quality-Gatekeeper|## Data Contract" .prodify/tasks`
+- `rg -n "MUST NOT modify source code|MUST STOP|MUST execute exactly one selected refactor step|MUST explicitly report PASS or FAIL|### Step: <ID>|- Status: pending|completed_step_ids|retry or repair the same selected step" .prodify/tasks .prodify/templates/refactor_plan.template.md AGENTS.md`
+
+## Verdict
+- PASS
+
+## Notes
+- The verification covered the canonical runtime locations only: `.prodify/...` and root `AGENTS.md`.

package/.prodify/artifacts/implementation_summary.md

@@ -0,0 +1,19 @@
+# Implementation Summary
+
+## Step Executed
+- Step ID:
+
+## Objective Achieved
+- Yes/No:
+
+## Files Changed
+- 
+
+## Diff Summary
+- 
+
+## Behavior Change Expected
+- Yes/No:
+
+## Notes
+-