@urielsh/prodify 0.1.0

package/.prodify/artifacts/task-dispatcher-design.md

@@ -0,0 +1,266 @@
+# Task Dispatcher Design
+
+Date: 2026-03-28
+Scope: `./.prodify/`
+
+## Purpose
+Define how the system selects, prepares, and hands off the correct task using workflow state from `run_state.json`.
+
+The dispatcher is responsible for choosing the next executable task and assembling the verified execution context for that task. It is not responsible for:
+- performing the task itself
+- validating output artifacts after execution
+- mutating workflow state beyond the dispatcher's own error reporting
+
+## Required Inputs
+- `.prodify/artifacts/run_state.json`
+  - source of truth for `current_task`, `last_completed_task`, `next_task`, `selected_refactor_step`, `completed_step_ids`, and `status`
+- `.prodify/tasks/*.md`
+  - source of task metadata and task ordering via frontmatter
+- `.prodify/artifacts/`
+  - source of declared input artifacts referenced in task frontmatter
+- `.prodify/templates/`
+  - source of task output templates referenced in the selected task's output specification
+- `.prodify/artifacts/task-self-validation-spec.md`
+  - source of pre-run validation requirements and task-specific checks
+- `.prodify/artifacts/run-state-design.md`
+  - source of status handling, transition expectations, and resume rules
+- `.prodify/artifacts/task_log.json`
+  - append-only execution history sink after task completion or failure
+
+## Dispatcher Responsibilities
+- read and validate workflow state before dispatch
+- resolve the single task that is allowed to run next
+- locate the matching task file
+- load task frontmatter and execution metadata
+- derive required inputs and expected primary output
+- prepare the execution payload for the selected task
+- stop and surface deterministic failure reasons when dispatch cannot continue
+
+## Dispatch Algorithm
+
+### Step 1 - Load State
+1. Read `.prodify/artifacts/run_state.json`.
+2. Confirm the required state fields exist:
+   - `current_task`
+   - `last_completed_task`
+   - `next_task`
+   - `selected_refactor_step`
+   - `completed_step_ids`
+   - `status`
+3. If required fields are missing or malformed, stop with dispatcher failure.
+
+### Step 2 - Resolve Dispatch Mode From Status
+Dispatch behavior depends on `status`:
+- `ready`
+  - dispatch `next_task`
+- `running`
+  - resume `current_task`
+- `awaiting_validation`
+  - dispatch `06-validate`
+- `blocked`
+  - do not dispatch; surface the blocker from `notes`
+- `failed`
+  - do not auto-advance; dispatch only the retry task identified by `next_task` after operator or system recovery logic resets state to runnable
+- `complete`
+  - do not dispatch; workflow is terminal
+
+### Step 3 - Resolve Target Task ID
+Determine the single target task ID:
+- for `ready`, use `next_task`
+- for `running`, use `current_task`
+- for `awaiting_validation`, use `06-validate`
+
+If the resolved target task ID is `null`, missing, or not one of:
+- `01-understand`
+- `02-diagnose`
+- `03-architecture`
+- `04-plan`
+- `05-refactor`
+- `06-validate`
+
+stop with dispatcher failure.
+
+### Step 4 - Resolve Task File
+Map the task ID to its file in `.prodify/tasks/`:
+- `01-understand` -> `.prodify/tasks/01-understand.md`
+- `02-diagnose` -> `.prodify/tasks/02-diagnose.md`
+- `03-architecture` -> `.prodify/tasks/03-architecture.md`
+- `04-plan` -> `.prodify/tasks/04-plan.md`
+- `05-refactor` -> `.prodify/tasks/05-refactor.md`
+- `06-validate` -> `.prodify/tasks/06-validate.md`
+
+If the mapped file does not exist, stop with dispatcher failure.
+
+### Step 5 - Load Task Metadata
+Read the task file frontmatter and extract:
+- `task_id`
+- `reads`
+- `writes`
+- `next_task`
+- `mode`
+
+Reject dispatch if:
+- frontmatter is missing
+- the frontmatter `task_id` does not match the resolved target task ID
+- more than one primary output is declared in `writes`
+- the `next_task` value conflicts with the expected pipeline or loop behavior
+
+### Step 6 - Derive Required Inputs
+From task metadata and current state, compute the execution inputs:
+- `task_file`
+- `task_id`
+- `mode`
+- `declared_inputs` from `reads`
+- `expected_output` from the single `writes` entry
+- `declared_next_task` from task frontmatter
+- `selected_refactor_step` from `run_state.json` when dispatching Tasks `05` or `06`
+- `completed_step_ids` from `run_state.json` when dispatching Tasks `05` or `06`
+
+For Task `05-refactor`, require:
+- `selected_refactor_step` to be non-null
+- the step to exist in `refactor_plan.md`
+
+For Task `06-validate`, require:
+- `selected_refactor_step` to be non-null
+- `last_completed_task` to be `05-refactor` or `status` to be `awaiting_validation`
+
+### Step 7 - Run Pre-Run Validation Hook
+Call the self-validation layer using `task-self-validation-spec.md`:
+- verify task file and frontmatter shape
+- verify declared input artifacts exist
+- verify the task's exact template exists
+- verify expected output path consistency
+
+If pre-run validation fails:
+- do not dispatch execution
+- return a structured failure
+- leave branching to the run-state failure/update logic
+
+### Step 8 - Emit Execution Payload
+If all checks pass, emit a dispatcher result containing:
+- `task_id`
+- `task_file`
+- `mode`
+- `inputs`
+- `expected_output`
+- `selected_refactor_step`
+- `code_modified`
+  - expected `no` for Tasks `01` through `04` and `06`
+  - expected `yes` only for Task `05`
+- `candidate_next_task`
+  - derived from frontmatter for Tasks `01` through `04`
+  - forced to `06-validate` after Task `05`
+  - resolved by validation result after Task `06`
+
+## Success And Failure Branching
+
+### Success Branching Before Execution
+- If dispatch succeeds, control passes to task execution.
+- The dispatcher does not advance run state on its own; the execution layer and state-update layer do that after task success or failure.
+
+### Success Branching After Execution
+The dispatcher consumes updated state on the next cycle:
+- after Tasks `01` through `04`, the next dispatch should use the next linear task
+- after Task `05`, the next dispatch should use `06-validate`
+- after Task `06` PASS, the next dispatch should either:
+  - loop to `05-refactor` for another step
+  - stop if the workflow is complete
+- after Task `06` FAIL, the next dispatch should not occur until state is recovered to a runnable form
+
+## Failure Paths
+
+### State Failures
+- `run_state.json` missing
+- required state fields missing
+- unsupported `status`
+- contradictory `current_task` and `next_task`
+- `next_task` not allowed by the pipeline
+
+Dispatcher action:
+- stop
+- report the invalid state condition
+- recommend setting workflow state to `blocked` or `failed`
+
+### Task Resolution Failures
+- target task file missing
+- frontmatter missing or malformed
+- resolved `task_id` and frontmatter `task_id` do not match
+- task declares zero or multiple primary outputs
+
+Dispatcher action:
+- stop
+- report the exact task metadata problem
+
+### Input Resolution Failures
+- declared input artifact missing
+- required template missing
+- Task `05` or `06` missing `selected_refactor_step`
+- `selected_refactor_step` not found in `refactor_plan.md`
+
+Dispatcher action:
+- stop
+- report the exact missing path or invalid step reference
+
+### Loop Control Failures
+- Task `06` selected when Task `05` did not complete for the current step
+- Task `05` selected while `status` is `awaiting_validation`
+- Task ordering attempts to skip `06-validate` after Task `05`
+
+Dispatcher action:
+- stop
+- report the illegal branch condition
+
+## Integration Points
+
+### Integration With Run-State Logic
+- The dispatcher reads, but does not authoritatively define, status semantics from `run-state-design.md`.
+- It must obey:
+  - `ready`
+  - `running`
+  - `awaiting_validation`
+  - `blocked`
+  - `failed`
+  - `complete`
+- It must use `selected_refactor_step` and `completed_step_ids` only as inputs, not as inferred values.
+
+### Integration With Self-Validation
+- The dispatcher invokes the pre-run checks from `task-self-validation-spec.md` before handing a task off for execution.
+- It does not perform post-run artifact validation; that belongs to the validation layer after execution.
+
+### Integration With Task Execution
+- The dispatcher provides the execution layer with one fully resolved task payload.
+- The execution layer is responsible for:
+  - loading task instructions
+  - performing the task
+  - writing the primary artifact
+  - calling post-run validation
+
+### Integration With Task Logging
+- After execution concludes, append one record to `.prodify/artifacts/task_log.json` including:
+  - dispatched task ID
+  - selected refactor step if any
+  - execution outcome
+  - output artifact path
+  - next state summary
+
+## Minimal Execution Payload Shape
+```json
+{
+  "task_id": "02-diagnose",
+  "task_file": ".prodify/tasks/02-diagnose.md",
+  "mode": "analysis",
+  "inputs": [
+    ".prodify/artifacts/orientation_map.md"
+  ],
+  "expected_output": ".prodify/artifacts/diagnostic_report.md",
+  "selected_refactor_step": null,
+  "code_modified": "no",
+  "candidate_next_task": "03-architecture"
+}
+```
+
+## Implementation Notes
+- Keep task ID to file-path mapping explicit and deterministic.
+- Prefer failing fast over trying to repair state implicitly.
+- Use relative paths only.
+- Keep dispatcher logic separate from artifact validation and state mutation so each layer remains testable and predictable.

package/.prodify/artifacts/task-header-audit.md

@@ -0,0 +1,42 @@
+# Task Header Audit
+
+Date: 2026-03-28
+Scope: `./.prodify/tasks/*.md`
+
+## Files Checked
+- `./.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`
+
+## Required Header Fields
+Expected frontmatter keys, in order:
+1. `task_id`
+2. `reads`
+3. `writes`
+4. `next_task`
+5. `mode`
+
+## Findings
+- All 6 task files include the required header keys.
+- All 6 task files already use the expected key order.
+- 5 of 6 task files already used valid list formatting for `reads` and `writes`.
+- `./.prodify/tasks/01-understand.md` used `reads:` with no value, which parsed as `null` rather than an empty list.
+
+## Missing Fields
+- None.
+
+## Normalization Changes Needed
+- `./.prodify/tasks/01-understand.md`
+  Changed `reads:` to `reads: []` so the field is explicitly an empty list and matches the intended metadata contract.
+
+## Recommended Fixes
+- Keep `reads` and `writes` typed as lists in every task file, including explicit empty lists where applicable.
+- Preserve the existing key order: `task_id`, `reads`, `writes`, `next_task`, `mode`.
+- If future task files are added, validate frontmatter shape before committing them so `null` values do not slip in for list fields.
+
+## Result
+- Task headers are now standardized across the audited task set.
+- No additional header fixes are currently needed in `./.prodify/tasks/`.

package/.prodify/artifacts/task-log-enhancement-spec.md

@@ -0,0 +1,264 @@
+# Task Log Enhancement Spec
+
+Date: 2026-03-29
+Scope: `./.prodify/artifacts/task_log.json`
+
+## Purpose
+
+Define a richer append-only execution log format for Prodify.
+
+The enhanced log should:
+
+- remain easy to inspect manually
+- provide enough detail for status and summary features
+- preserve deterministic append-only behavior
+
+## Updated Log Shape
+
+Keep the top-level container as:
+
+```json
+{
+  "executions": []
+}
+```
+
+Each entry in `executions` should use this shape:
+
+```json
+{
+  "timestamp": "2026-03-29T10:15:00Z",
+  "task": "02-diagnose",
+  "result": "success",
+  "artifacts_touched": [
+    ".prodify/artifacts/diagnostic_report.md"
+  ],
+  "notes": [
+    "Validated declared inputs before execution.",
+    "Wrote the diagnostic report template output."
+  ]
+}
+```
+
+## Entry Fields
+
+### `timestamp`
+Type:
+- string
+
+Format:
+- ISO 8601 UTC timestamp
+
+Purpose:
+- records when the execution result was appended
+
+Example:
+- `2026-03-29T10:15:00Z`
+
+### `task`
+Type:
+- string
+
+Purpose:
+- records the runtime task ID that was executed or attempted
+
+Allowed examples:
+- `01-understand`
+- `02-diagnose`
+- `03-architecture`
+- `04-plan`
+- `05-refactor`
+- `06-validate`
+
+### `result`
+Type:
+- string
+
+Allowed values:
+- `success`
+- `blocked`
+- `failed`
+
+Purpose:
+- captures the final outcome of that execution attempt
+
+Rules:
+- use `success` only when the task completed and its primary artifact passed required validation
+- use `blocked` when execution could not continue because inputs, state, or templates were incomplete
+- use `failed` when the task ran or attempted to run but ended in a failure condition
+
+### `artifacts_touched`
+Type:
+- array of strings
+
+Purpose:
+- records the runtime artifact paths written or materially updated during the task attempt
+
+Rules:
+- use relative paths only
+- keep the list limited to artifacts materially touched by that execution result
+- for blocked outcomes with no writes, this may be `[]`
+
+Examples:
+- `.prodify/artifacts/orientation_map.md`
+- `.prodify/artifacts/validation_report.md`
+- `.prodify/artifacts/run_state.json`
+
+### `notes`
+Type:
+- array of strings
+
+Purpose:
+- captures short high-signal details about what happened
+
+Rules:
+- keep entries concise
+- prefer factual statements over narrative prose
+- include failure or blocker reason when relevant
+- avoid duplicating full artifact contents
+
+## Append Rules
+
+### Rule 1 - Append Only
+Never rewrite or delete earlier execution entries during normal operation.
+
+Allowed action:
+- append exactly one new entry for each completed execution attempt
+
+### Rule 2 - One Entry Per Attempt
+Each task attempt should produce at most one appended log entry.
+
+This includes:
+- successful task completion
+- blocked attempt
+- failed attempt
+
+### Rule 3 - Append After Outcome Is Known
+Append only after the task outcome is determined.
+
+That means:
+- after artifact validation for success
+- after blocker detection for blocked outcomes
+- after failure handling decides the attempt failed
+
+### Rule 4 - Keep Order Chronological
+New entries must be appended at the end of the `executions` array in actual execution order.
+
+### Rule 5 - Preserve Prior Entries
+State repair, retries, and later successful executions must not erase earlier blocked or failed entries.
+
+### Rule 6 - Relative Paths Only
+Artifact paths in `artifacts_touched` must remain relative to the runtime root.
+
+## Result-Specific Rules
+
+### Success Entry
+A success entry should:
+
+- include the executed task
+- include the primary artifact written
+- include relevant state or summary artifacts if they were updated as part of the same execution cycle
+- include a short note confirming successful completion
+
+### Blocked Entry
+A blocked entry should:
+
+- include the task that could not proceed
+- include `artifacts_touched: []` when nothing was written
+- include a note naming the blocker
+
+### Failed Entry
+A failed entry should:
+
+- include the task that failed
+- include any artifact written before failure if it materially exists
+- include a short failure reason in `notes`
+
+## Sample Entries
+
+### Sample 1 - Success
+
+```json
+{
+  "timestamp": "2026-03-29T10:15:00Z",
+  "task": "03-architecture",
+  "result": "success",
+  "artifacts_touched": [
+    ".prodify/artifacts/architecture_spec.md",
+    ".prodify/artifacts/run_state.json"
+  ],
+  "notes": [
+    "Architecture spec written and validated.",
+    "Run state advanced to 04-plan."
+  ]
+}
+```
+
+### Sample 2 - Blocked
+
+```json
+{
+  "timestamp": "2026-03-29T10:22:00Z",
+  "task": "05-refactor",
+  "result": "blocked",
+  "artifacts_touched": [],
+  "notes": [
+    "selected_refactor_step could not be resolved from refactor_plan.md."
+  ]
+}
+```
+
+### Sample 3 - Failed
+
+```json
+{
+  "timestamp": "2026-03-29T10:28:00Z",
+  "task": "06-validate",
+  "result": "failed",
+  "artifacts_touched": [
+    ".prodify/artifacts/validation_report.md",
+    ".prodify/artifacts/run_state.json"
+  ],
+  "notes": [
+    "Validation reported a regression for step-03-extract-service.",
+    "Retry of 05-refactor is required."
+  ]
+}
+```
+
+## Inspection Guidelines
+
+The log should stay easy to inspect by humans.
+
+Guidelines:
+
+- keep field names stable
+- keep entries shallow
+- avoid nested diagnostic blobs
+- store only short note strings
+- prefer explicit results over inferred meaning
+
+## Integration Notes
+
+### Integration With Run State
+- `task_log.json` is not the control plane.
+- `run_state.json` remains the canonical source of workflow state.
+- the log exists to record execution history, not to replace state
+
+### Integration With Status Output
+- status views may use the latest execution entry to enrich human summaries
+- status must still prefer current state over stale history
+
+### Integration With Run Summary
+- Task `62-add-summary-output` should be able to read the latest log entry directly
+- the fields in this spec are intentionally chosen to support:
+  - task executed
+  - result
+  - artifact written or touched
+  - notes
+
+## Implementation Notes
+
+- Keep the existing top-level `executions` array for compatibility.
+- Prefer a small stable schema over a verbose event stream.
+- If no artifact was touched, use an empty array rather than inventing a placeholder path.

package/.prodify/artifacts/task-protocol-hardening-plan.md

@@ -0,0 +1,68 @@
+# Task Protocol Hardening Plan
+
+Date: 2026-03-29
+Task: `82-tighten-task-protocols`
+
+## Plan
+
+| Task file | Missing protocol elements | Exact wording to add or tighten | Severity |
+| --- | --- | --- | --- |
+| `01-understand.md` | explicit required inputs section, explicit no-code-modification rule, explicit failure conditions | Add `## Inputs` for repository root; add `MUST NOT modify source code`; add stop conditions for missing repository access, missing output-template compliance, or unsupported scan evidence. | High |
+| `02-diagnose.md` | explicit failure conditions, explicit no-code-modification rule, explicit stop conditions | Add `MUST NOT modify source code`; add stop conditions for missing `orientation_map.md`, missing required context, or inability to produce the declared template output. | High |
+| `03-architecture.md` | explicit failure conditions, explicit no-code-modification rule, explicit stop conditions | Add `MUST NOT modify source code`; add stop conditions for missing `orientation_map.md` or `diagnostic_report.md`, or inability to ground recommendations in evidence. | High |
+| `04-plan.md` | explicit failure conditions, explicit no-code-modification rule, explicit stop conditions, stronger plan-step structure requirement | Add `MUST NOT modify source code`; add stop conditions for missing required artifacts, ambiguous step structure, or output not matching the template; require fixed step blocks with stable IDs. | High |
+| `05-refactor.md` | explicit forbidden behavior section, explicit stop conditions, explicit ambiguity handling | Add `MUST execute exactly one selected step`; add `MUST NOT modify unrelated files`; add `MUST STOP if selected step is ambiguous, missing, or not isolated enough to execute safely`. | Critical |
+| `06-validate.md` | explicit no-code-modification rule, explicit required ordering, explicit PASS/FAIL requirement, explicit failure conditions | Add `MUST NOT modify source code`; add `MUST run only after Task 05`; add `MUST explicitly report PASS or FAIL`; add stop conditions for missing context or inability to produce a verdict. | Critical |
+
+## Protocol Additions By Task
+
+### Tasks 01 Through 04
+Add these protocol rules explicitly:
+
+- `MUST NOT modify source code.`
+- `MUST STOP if any required input artifact is missing.`
+- `MUST STOP if the declared output cannot be produced in the required template structure.`
+
+### Task 05
+Add these protocol rules explicitly:
+
+- `MUST execute exactly one selected refactor step.`
+- `MUST NOT modify unrelated files.`
+- `MUST STOP if the selected step is ambiguous, missing, or combines unrelated concerns.`
+
+### Task 06
+Add these protocol rules explicitly:
+
+- `MUST run after Task 05 for the same selected step.`
+- `MUST NOT modify source code.`
+- `MUST STOP if required context is missing.`
+- `MUST explicitly report PASS or FAIL.`
+
+## File-Specific Hardening Notes
+
+### `01-understand.md`
+- Convert narrative framing into explicit scope and input language.
+- Make conservative evidence gathering a stop rule, not just a style preference.
+
+### `02-diagnose.md`
+- Tighten the task so it clearly fails when the orientation artifact is absent or insufficient.
+
+### `03-architecture.md`
+- Tighten the task so architectural recommendations cannot proceed without evidence from Tasks `01` and `02`.
+
+### `04-plan.md`
+- Require fixed refactor-step structure aligned with the hardened template.
+- Tighten step atomicity into a stop condition, not just guidance.
+
+### `05-refactor.md`
+- Make one-step discipline and unrelated-file prohibition unambiguous.
+- Add explicit stop behavior for ambiguous or unsafe steps.
+
+### `06-validate.md`
+- Make explicit verdict reporting mandatory.
+- Add stop behavior for missing implementation context or missing plan context.
+
+## Result
+- Every core task now has a concrete hardening recommendation.
+- Missing fail and stop conditions are documented.
+- A deterministic upgrade path exists for the full `01` through `06` suite.