@urielsh/prodify 0.1.0

package/.prodify/artifacts/task-self-validation-spec.md

@@ -0,0 +1,171 @@
+# Task Self-Validation Spec
+
+Date: 2026-03-28
+Scope: `./.prodify/tasks/*.md`
+
+## Purpose
+Define a lightweight, agent-executable validation contract that every Prodify task should run before execution and after producing its output artifact.
+
+## Validation Model
+
+### Pre-Run Checks
+Run these checks before starting task execution:
+
+1. Confirm the task file exists and contains the required frontmatter keys:
+   - `task_id`
+   - `reads`
+   - `writes`
+   - `next_task`
+   - `mode`
+2. Confirm every declared input artifact in `reads` exists, unless the task intentionally declares an empty `reads` list.
+3. Confirm every declared template file referenced in the task's output specification exists.
+4. Confirm the task's declared output artifact in `writes` matches the artifact described in the task body.
+5. Confirm the output specification names an exact template file rather than a generic or freeform instruction.
+
+### Post-Run Checks
+Run these checks after task execution completes:
+
+1. Confirm every declared output artifact in `writes` exists.
+2. Confirm the output artifact contains the section headings defined by the matching template.
+3. Confirm the artifact is Markdown when the task expects a Markdown artifact.
+4. Confirm the produced artifact path matches the task's declared `writes` path.
+5. Confirm the task did not omit required template sections, even if some sections are intentionally left brief.
+
+## Failure Handling Rules
+
+### Pre-Run Failure Rules
+- If a required input artifact is missing, stop execution and report the missing path.
+- If the required template file is missing, stop execution and report the missing template path.
+- If the task metadata and task body disagree about the output artifact, stop execution and resolve the mismatch before proceeding.
+- If the output specification allows a freeform artifact, stop execution and tighten the task instructions before proceeding.
+
+### Post-Run Failure Rules
+- If the declared output artifact was not created, mark the task as failed.
+- If required template headings are missing, mark the artifact as invalid and revise it before moving to the next task.
+- If the artifact was written to the wrong path, move or regenerate it at the declared path before continuing.
+- If a section is present but empty because the data is unknown, note uncertainty explicitly instead of deleting the section.
+
+## Execution Rules
+- Keep validation file-based and heading-based.
+- Prefer deterministic checks over subjective quality judgments.
+- Do not treat deep content correctness as part of this self-validation layer.
+- Allow conservative placeholders when the template expects a section but the data is not yet known.
+
+## Task Integration Notes
+
+### Task 01 - `01-understand.md`
+- Expected inputs:
+  - none
+- Required template:
+  - `.prodify/templates/orientation_map.template.md`
+- Expected output:
+  - `.prodify/artifacts/orientation_map.md`
+- Required post-run headings:
+  - `# Orientation Map`
+  - `## Project Summary`
+  - `## Entry Points`
+  - `## Module Map`
+  - `## Monorepo Metadata`
+  - `## Dependency Overview`
+  - `## Key Observations`
+  - `## Uncertainty`
+
+### Task 02 - `02-diagnose.md`
+- Expected inputs:
+  - `.prodify/artifacts/orientation_map.md`
+- Required template:
+  - `.prodify/templates/diagnostic_report.template.md`
+- Expected output:
+  - `.prodify/artifacts/diagnostic_report.md`
+- Required post-run headings:
+  - `# Diagnostic Report`
+  - `## Top 5 Priorities`
+  - `## Critical Issues`
+  - `## High Issues`
+  - `## Medium Issues`
+  - `## Low Issues`
+  - `## Reliability Risks`
+  - `## Technical Debt Score`
+  - `## Notes`
+
+### Task 03 - `03-architecture.md`
+- Expected inputs:
+  - `.prodify/artifacts/orientation_map.md`
+  - `.prodify/artifacts/diagnostic_report.md`
+- Required template:
+  - `.prodify/templates/architecture_spec.template.md`
+- Expected output:
+  - `.prodify/artifacts/architecture_spec.md`
+- Required post-run headings:
+  - `# Architecture Spec`
+  - `## Detected Pattern`
+  - `## Target Style`
+  - `## Layer Definitions`
+  - `## Violations`
+  - `## Gap Analysis`
+  - `## Migration Notes`
+
+### Task 04 - `04-plan.md`
+- Expected inputs:
+  - `.prodify/artifacts/diagnostic_report.md`
+  - `.prodify/artifacts/architecture_spec.md`
+- Required template:
+  - `.prodify/templates/refactor_plan.template.md`
+- Expected output:
+  - `.prodify/artifacts/refactor_plan.md`
+- Required post-run headings:
+  - `# Refactor Plan`
+  - `## Summary`
+  - `## Phase Breakdown`
+  - `## Steps`
+  - `## Notes`
+
+### Task 05 - `05-refactor.md`
+- Expected inputs:
+  - `.prodify/artifacts/refactor_plan.md`
+- Required template:
+  - `.prodify/templates/implementation_summary.template.md`
+- Expected output:
+  - `.prodify/artifacts/implementation_summary.md`
+- Required post-run headings:
+  - `# Implementation Summary`
+  - `## Step Executed`
+  - `## Objective Achieved`
+  - `## Files Changed`
+  - `## Diff Summary`
+  - `## Behavior Change Expected`
+  - `## Notes`
+- Special rule:
+  - Validate only the summary artifact against the template. Source-file diffs are validated separately by task-specific review and verification.
+
+### Task 06 - `06-validate.md`
+- Expected inputs:
+  - `.prodify/artifacts/architecture_spec.md`
+  - `.prodify/artifacts/refactor_plan.md`
+  - `.prodify/artifacts/implementation_summary.md`
+- Required template:
+  - `.prodify/templates/validation_report.template.md`
+- Expected output:
+  - `.prodify/artifacts/validation_report.md`
+- Required post-run headings:
+  - `# Validation Report`
+  - `## Readiness Status`
+  - `## Final Score`
+  - `## Category Scores`
+  - `## Remaining Issues`
+  - `## Regressions Detected`
+  - `## Recommended Next Step`
+
+## Suggested Minimal Check Sequence
+1. Read the task frontmatter.
+2. Verify all input paths in `reads`.
+3. Verify the named template path.
+4. Execute the task.
+5. Verify the output path in `writes`.
+6. Verify required template headings in the output artifact.
+7. Fail fast if any required file or heading is missing.
+
+## Out Of Scope
+- Semantic correctness of the artifact contents.
+- Code quality or architecture judgment beyond file existence and template-shape compliance.
+- Deep validation of modified source files produced during Task 05.

package/.prodify/artifacts/task_log.json

@@ -0,0 +1,160 @@
+{
+  "executions": [
+    {
+      "timestamp": "2026-04-02T18:45:05Z",
+      "task": "01-understand",
+      "result": "success",
+      "artifacts_touched": [
+        ".prodify/artifacts/01-understand.md",
+        ".prodify/artifacts/run_state.json"
+      ],
+      "notes": [
+        "Verified repository structure, preset assets, docs, and tests relevant to Task 65.",
+        "Wrote the understand-stage artifact and advanced run state to 02-diagnose."
+      ]
+    },
+    {
+      "timestamp": "2026-04-02T18:45:51Z",
+      "task": "02-diagnose",
+      "result": "success",
+      "artifacts_touched": [
+        ".prodify/artifacts/02-diagnose.md",
+        ".prodify/artifacts/run_state.json"
+      ],
+      "notes": [
+        "Recorded evidence-backed consistency drift across tasks, docs, preset assets, and checked-in artifacts.",
+        "Advanced run state to 03-architecture."
+      ]
+    },
+    {
+      "timestamp": "2026-04-02T18:46:35Z",
+      "task": "03-architecture",
+      "result": "success",
+      "artifacts_touched": [
+        ".prodify/artifacts/03-architecture.md",
+        ".prodify/artifacts/run_state.json"
+      ],
+      "notes": [
+        "Defined the target truth boundaries for contracts, tasks, preset assets, docs, and contributor-only root files.",
+        "Advanced run state to 04-plan."
+      ]
+    },
+    {
+      "timestamp": "2026-04-02T18:47:33Z",
+      "task": "04-plan",
+      "result": "success",
+      "artifacts_touched": [
+        ".prodify/artifacts/04-plan.md",
+        ".prodify/artifacts/run_state.json"
+      ],
+      "notes": [
+        "Planned three atomic consistency steps for Task 65.",
+        "Selected step-01-clarify-default-lifecycle-docs as the first refactor step."
+      ]
+    },
+    {
+      "timestamp": "2026-04-02T18:50:35Z",
+      "task": "05-refactor",
+      "result": "success",
+      "artifacts_touched": [
+        ".prodify/artifacts/05-refactor.md",
+        ".prodify/artifacts/run_state.json"
+      ],
+      "notes": [
+        "Clarified the default `.prodify`-first lifecycle across root and canonical guidance files.",
+        "Validation is now required for step-01-clarify-default-lifecycle-docs."
+      ]
+    },
+    {
+      "timestamp": "2026-04-02T18:51:31Z",
+      "task": "06-validate",
+      "result": "success",
+      "artifacts_touched": [
+        ".prodify/artifacts/06-validate.md",
+        ".prodify/artifacts/run_state.json"
+      ],
+      "notes": [
+        "Validation passed for step-01-clarify-default-lifecycle-docs with npm test.",
+        "Advanced to step-02-reframe-compatibility-docs."
+      ]
+    },
+    {
+      "timestamp": "2026-04-02T18:54:14Z",
+      "task": "05-refactor",
+      "result": "success",
+      "artifacts_touched": [
+        ".prodify/artifacts/05-refactor.md",
+        ".prodify/artifacts/run_state.json"
+      ],
+      "notes": [
+        "Reframed compatibility-target documentation as future or non-default behavior.",
+        "Validation is now required for step-02-reframe-compatibility-docs."
+      ]
+    },
+    {
+      "timestamp": "2026-04-02T18:55:06Z",
+      "task": "06-validate",
+      "result": "success",
+      "artifacts_touched": [
+        ".prodify/artifacts/06-validate.md",
+        ".prodify/artifacts/run_state.json"
+      ],
+      "notes": [
+        "Validation passed for step-02-reframe-compatibility-docs with npm test.",
+        "Advanced to step-03-strengthen-consistency-tests."
+      ]
+    },
+    {
+      "timestamp": "2026-04-02T18:57:22Z",
+      "task": "05-refactor",
+      "result": "success",
+      "artifacts_touched": [
+        ".prodify/artifacts/05-refactor.md",
+        ".prodify/artifacts/run_state.json"
+      ],
+      "notes": [
+        "Added explicit consistency assertions for the `.prodify`-first lifecycle and self-hosted workspace boundaries.",
+        "Validation is now required for step-03-strengthen-consistency-tests."
+      ]
+    },
+    {
+      "timestamp": "2026-04-02T18:58:17Z",
+      "task": "06-validate",
+      "result": "failed",
+      "artifacts_touched": [
+        ".prodify/artifacts/06-validate.md",
+        ".prodify/artifacts/run_state.json"
+      ],
+      "notes": [
+        "Validation failed for step-03-strengthen-consistency-tests during npm test.",
+        "Repair the same selected step before continuing."
+      ]
+    },
+    {
+      "timestamp": "2026-04-02T18:59:29Z",
+      "task": "05-refactor",
+      "result": "success",
+      "artifacts_touched": [
+        ".prodify/artifacts/05-refactor.md",
+        ".prodify/artifacts/run_state.json"
+      ],
+      "notes": [
+        "Repaired step-03-strengthen-consistency-tests by aligning the regex with the documented repository-local wording.",
+        "Validation was retried for the same selected step."
+      ]
+    },
+    {
+      "timestamp": "2026-04-02T18:59:29Z",
+      "task": "06-validate",
+      "result": "success",
+      "artifacts_touched": [
+        ".prodify/artifacts/06-validate.md",
+        ".prodify/artifacts/run_state.json"
+      ],
+      "notes": [
+        "Validation passed for step-03-strengthen-consistency-tests with npm test after the repair.",
+        "All planned Task 65 steps are now complete."
+      ]
+    }
+  ]
+}

package/.prodify/artifacts/template-usage-audit.md

@@ -0,0 +1,20 @@
+# Template Usage Audit
+
+Date: 2026-03-28
+Scope: `./.prodify/tasks/*.md`
+
+## Audit Results
+
+| Task file | Expected artifact | Matching template | Gaps found | Exact fix recommendation |
+| --- | --- | --- | --- | --- |
+| `./.prodify/tasks/01-understand.md` | `.prodify/artifacts/orientation_map.md` | `.prodify/templates/orientation_map.template.md` | Output specification said "matching markdown template" without naming the file. | Replace the generic sentence with: `Use .prodify/templates/orientation_map.template.md and fill every section explicitly. Do not substitute a freeform structure.` |
+| `./.prodify/tasks/02-diagnose.md` | `.prodify/artifacts/diagnostic_report.md` | `.prodify/templates/diagnostic_report.template.md` | Output specification said "matching markdown template" without naming the file. | Replace the generic sentence with: `Use .prodify/templates/diagnostic_report.template.md and fill every section explicitly. Do not substitute a freeform structure.` |
+| `./.prodify/tasks/03-architecture.md` | `.prodify/artifacts/architecture_spec.md` | `.prodify/templates/architecture_spec.template.md` | Output specification said "matching markdown template" without naming the file. | Replace the generic sentence with: `Use .prodify/templates/architecture_spec.template.md and fill every section explicitly. Do not substitute a freeform structure.` |
+| `./.prodify/tasks/04-plan.md` | `.prodify/artifacts/refactor_plan.md` | `.prodify/templates/refactor_plan.template.md` | Output specification said "matching markdown template" without naming the file. | Replace the generic sentence with: `Use .prodify/templates/refactor_plan.template.md and fill every section explicitly. Do not substitute a freeform structure.` |
+| `./.prodify/tasks/05-refactor.md` | `.prodify/artifacts/implementation_summary.md` | `.prodify/templates/implementation_summary.template.md` | Output specification said "matching markdown template" without naming the file, even though the task also allows updated source files. | Replace the generic sentence with: `Use .prodify/templates/implementation_summary.template.md and fill every section explicitly for implementation_summary.md. Do not substitute a freeform structure for the summary artifact.` |
+| `./.prodify/tasks/06-validate.md` | `.prodify/artifacts/validation_report.md` | `.prodify/templates/validation_report.template.md` | Output specification said "matching markdown template" without naming the file. | Replace the generic sentence with: `Use .prodify/templates/validation_report.template.md and fill every section explicitly. Do not substitute a freeform structure.` |
+
+## Summary
+- Every task now has a clear one-to-one mapping from output artifact to template file.
+- The ambiguity was consistent across all six task files and has been corrected.
+- No additional template-usage gaps were found in the current task set.

package/.prodify/artifacts/validation_report.md

@@ -0,0 +1,22 @@
+# Validation Report
+
+## Readiness Status
+- PASS/FAIL:
+
+## Final Score
+- Score:
+
+## Category Scores
+- Architecture:
+- Maintainability:
+- Reliability:
+- Testability:
+
+## Remaining Issues
+- 
+
+## Regressions Detected
+- 
+
+## Recommended Next Step
+- 

package/.prodify/contracts/README.md

@@ -0,0 +1,3 @@
+# Compiled Contracts
+
+This directory contains deterministic runtime-only JSON contracts generated from `.prodify/contracts-src/`.

package/.prodify/contracts/architecture.contract.json

@@ -0,0 +1,42 @@
+{
+  "schema_version": "1",
+  "contract_version": "1.0.0",
+  "stage": "architecture",
+  "task_id": "03-architecture",
+  "source_path": ".prodify/contracts-src/architecture.contract.md",
+  "source_hash": "4069286860c23df3a2cb441a115ffa001544e318e7410f645a8cfebb5b5b30a4",
+  "required_artifacts": [
+    {
+      "path": ".prodify/artifacts/03-architecture.md",
+      "format": "markdown",
+      "required_sections": [
+        "Dependency Rules",
+        "Policy Checks",
+        "Proposed Structure",
+        "Success Criteria",
+        "Tradeoffs"
+      ],
+      "required_json_keys": []
+    }
+  ],
+  "allowed_write_roots": [
+    ".prodify/artifacts/"
+  ],
+  "forbidden_writes": [
+    "src/",
+    "tests/"
+  ],
+  "policy_rules": [
+    "Flag mixed concerns explicitly.",
+    "Keep Domain dependencies pointing inward only."
+  ],
+  "success_criteria": [
+    "Architecture violations are listed clearly.",
+    "The target structure is explicit."
+  ],
+  "skill_routing": {
+    "default_skills": [],
+    "allowed_skills": [],
+    "conditional_skills": []
+  }
+}

package/.prodify/contracts/diagnose.contract.json

@@ -0,0 +1,42 @@
+{
+  "schema_version": "1",
+  "contract_version": "1.0.0",
+  "stage": "diagnose",
+  "task_id": "02-diagnose",
+  "source_path": ".prodify/contracts-src/diagnose.contract.md",
+  "source_hash": "73a614c393ff1fa7829128f7b05881121efd1a18ec3ad697cfcc73039664a19c",
+  "required_artifacts": [
+    {
+      "path": ".prodify/artifacts/02-diagnose.md",
+      "format": "markdown",
+      "required_sections": [
+        "Constraints",
+        "Observed Issues",
+        "Policy Checks",
+        "Root Causes",
+        "Success Criteria"
+      ],
+      "required_json_keys": []
+    }
+  ],
+  "allowed_write_roots": [
+    ".prodify/artifacts/"
+  ],
+  "forbidden_writes": [
+    "src/",
+    "tests/"
+  ],
+  "policy_rules": [
+    "Diagnose from repository evidence only.",
+    "Do not propose implementation changes in the diagnosis stage."
+  ],
+  "success_criteria": [
+    "Every critical issue is tied to evidence.",
+    "Root causes are separated from symptoms."
+  ],
+  "skill_routing": {
+    "default_skills": [],
+    "allowed_skills": [],
+    "conditional_skills": []
+  }
+}

package/.prodify/contracts/plan.contract.json

@@ -0,0 +1,42 @@
+{
+  "schema_version": "1",
+  "contract_version": "1.0.0",
+  "stage": "plan",
+  "task_id": "04-plan",
+  "source_path": ".prodify/contracts-src/plan.contract.md",
+  "source_hash": "69d7175649ed28daef3cd83059944c26e99821802016124b451f3dc0ead2bfca",
+  "required_artifacts": [
+    {
+      "path": ".prodify/artifacts/04-plan.md",
+      "format": "markdown",
+      "required_sections": [
+        "Policy Checks",
+        "Risks",
+        "Step Breakdown",
+        "Success Criteria",
+        "Verification"
+      ],
+      "required_json_keys": []
+    }
+  ],
+  "allowed_write_roots": [
+    ".prodify/artifacts/"
+  ],
+  "forbidden_writes": [
+    "src/",
+    "tests/"
+  ],
+  "policy_rules": [
+    "Keep the plan deterministic and minimal.",
+    "Map every step back to a diagnosed issue or architecture rule."
+  ],
+  "success_criteria": [
+    "The plan enumerates executable steps.",
+    "Verification is defined before refactoring starts."
+  ],
+  "skill_routing": {
+    "default_skills": [],
+    "allowed_skills": [],
+    "conditional_skills": []
+  }
+}

package/.prodify/contracts/refactor.contract.json

@@ -0,0 +1,45 @@
+{
+  "schema_version": "1",
+  "contract_version": "1.0.0",
+  "stage": "refactor",
+  "task_id": "05-refactor",
+  "source_path": ".prodify/contracts-src/refactor.contract.md",
+  "source_hash": "0445b0239d888c292430f8fe5ddba557813f0e19a6bafdb9c7a7ad7d10c627b1",
+  "required_artifacts": [
+    {
+      "path": ".prodify/artifacts/05-refactor.md",
+      "format": "markdown",
+      "required_sections": [
+        "Behavior Guardrails",
+        "Changed Files",
+        "Policy Checks",
+        "Selected Step",
+        "Success Criteria"
+      ],
+      "required_json_keys": []
+    }
+  ],
+  "allowed_write_roots": [
+    ".prodify/artifacts/",
+    "assets/",
+    "README.md",
+    "src/",
+    "tests/"
+  ],
+  "forbidden_writes": [
+    ".prodify/contracts/"
+  ],
+  "policy_rules": [
+    "Execute exactly one selected step.",
+    "Keep the diff minimal and behavior-preserving unless the plan says otherwise."
+  ],
+  "success_criteria": [
+    "The selected plan step is implemented fully.",
+    "Unrelated files remain untouched."
+  ],
+  "skill_routing": {
+    "default_skills": [],
+    "allowed_skills": [],
+    "conditional_skills": []
+  }
+}

package/.prodify/contracts/understand.contract.json

@@ -0,0 +1,42 @@
+{
+  "schema_version": "1",
+  "contract_version": "1.0.0",
+  "stage": "understand",
+  "task_id": "01-understand",
+  "source_path": ".prodify/contracts-src/understand.contract.md",
+  "source_hash": "850c024b5d54208e101c16797c84ab43a35bfa8ba46c0fcd8f37ab6783f024cb",
+  "required_artifacts": [
+    {
+      "path": ".prodify/artifacts/01-understand.md",
+      "format": "markdown",
+      "required_sections": [
+        "Current State",
+        "Open Questions",
+        "Policy Checks",
+        "Repository Summary",
+        "Success Criteria"
+      ],
+      "required_json_keys": []
+    }
+  ],
+  "allowed_write_roots": [
+    ".prodify/artifacts/"
+  ],
+  "forbidden_writes": [
+    "src/",
+    "tests/"
+  ],
+  "policy_rules": [
+    "Operate only on verified data.",
+    "Preserve the existing behavior during understanding."
+  ],
+  "success_criteria": [
+    "Known unknowns are listed explicitly.",
+    "The repository intent is captured clearly."
+  ],
+  "skill_routing": {
+    "default_skills": [],
+    "allowed_skills": [],
+    "conditional_skills": []
+  }
+}

package/.prodify/contracts/validate.contract.json

@@ -0,0 +1,52 @@
+{
+  "schema_version": "1",
+  "contract_version": "1.0.0",
+  "stage": "validate",
+  "task_id": "06-validate",
+  "source_path": ".prodify/contracts-src/validate.contract.md",
+  "source_hash": "10c9f32b2bbed054884a3c9c5ad5f195954ca0c702f14a783835d79a07aca2ed",
+  "required_artifacts": [
+    {
+      "path": ".prodify/artifacts/06-validate.md",
+      "format": "markdown",
+      "required_sections": [
+        "Policy Checks",
+        "Regressions",
+        "Success Criteria",
+        "Validation Results"
+      ],
+      "required_json_keys": []
+    },
+    {
+      "path": ".prodify/state.json",
+      "format": "json",
+      "required_sections": [],
+      "required_json_keys": [
+        "preset_name",
+        "preset_version",
+        "runtime",
+        "schema_version"
+      ]
+    }
+  ],
+  "allowed_write_roots": [
+    ".prodify/artifacts/",
+    ".prodify/metrics/"
+  ],
+  "forbidden_writes": [
+    "src/"
+  ],
+  "policy_rules": [
+    "Critical regressions block forward progress.",
+    "Validation must follow every refactor step."
+  ],
+  "success_criteria": [
+    "The result is strong enough to gate the next runtime transition.",
+    "Validation records whether regressions were found."
+  ],
+  "skill_routing": {
+    "default_skills": [],
+    "allowed_skills": [],
+    "conditional_skills": []
+  }
+}

package/.prodify/contracts-src/README.md

@@ -0,0 +1,4 @@
+# Contract Sources
+
+Edit the human-readable Markdown contracts in this directory.
+Run `prodify update` to regenerate the compiled runtime JSON under `.prodify/contracts/`.