@urielsh/prodify 0.1.0

package/.prodify/AGENTS.md

@@ -0,0 +1,56 @@
+# Prodify Agent Entry
+
+## First Message
+
+When the user opens a coding agent manually, the first instruction should be:
+
+`Read .prodify/AGENTS.md and bootstrap Prodify for this repository.`
+
+After the agent reads this file, it should continue with `$prodify-init` and keep the full workflow anchored to `.prodify/`.
+
+## Core Rules
+
+- `.prodify/` is the only source of truth.
+- Humans edit `.prodify/contracts-src/`; runtime reads only `.prodify/contracts/*.contract.json`.
+- No root-level `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, or `.opencode/AGENTS.md` is required for the main flow.
+- If this repository also contains a root `AGENTS.md`, treat it as repository-local contributor guidance unless explicitly documented otherwise.
+- Repository initialization remains agent-agnostic. The active agent is resolved when `$prodify-init` runs, not when `prodify init` creates `.prodify/`.
+- External CLI commands prepare and inspect the repo.
+- Runtime commands are executed inside the chosen coding agent.
+- Durable workflow state lives in `.prodify/state.json`.
+
+## External CLI
+
+- `prodify init`
+- `prodify setup-agent`
+- `prodify status`
+- `prodify doctor`
+- `prodify update`
+
+## Runtime Files
+
+- `.prodify/AGENTS.md`
+- `.prodify/project.md`
+- `.prodify/planning.md`
+- `.prodify/contracts-src/`
+- `.prodify/contracts/`
+- `.prodify/artifacts/`
+- `.prodify/metrics/`
+- `.prodify/tasks/`
+- `.prodify/state.json`
+- `.prodify/runtime-commands.md`
+
+Active stage outputs under `.prodify/artifacts/` use numbered filenames:
+- `01-understand.md`
+- `02-diagnose.md`
+- `03-architecture.md`
+- `04-plan.md`
+- `05-refactor.md`
+- `06-validate.md`
+
+## Runtime Commands
+
+- `$prodify-init`
+- `$prodify-execute`
+- `$prodify-execute --auto`
+- `$prodify-resume`

package/.prodify/README.md

@@ -0,0 +1,10 @@
+# Self-Hosted Workspace
+
+This checked-in `.prodify/` directory is the real self-hosting workspace used to evolve Prodify itself.
+
+It contains two kinds of content:
+
+- the canonical runtime layout that `prodify init` and `prodify update` generate
+- additional repo-local artifacts, rules, tasks, and templates used while developing Prodify
+
+Treat it as a real workspace, not as a second competing product model.

package/.prodify/artifacts/01-understand.md

@@ -0,0 +1,28 @@
+# 01-understand
+
+## Current State
+- The repository is a TypeScript and Node.js CLI product centered on `prodify init`, `status`, `doctor`, and `update`, with runtime flow logic in `src/core/` and preset loading in `src/presets/`.
+- The checked-in `.prodify/` directory is being used as a self-hosted runtime workspace for Prodify itself, while `assets/presets/default/canonical/` defines the generated default preset contents.
+- The runtime contract layer, validation tests, and flow-state code use numbered stage artifacts such as `.prodify/artifacts/01-understand.md`, but the checked-in `.prodify/tasks/` and several design artifacts still reference legacy names such as `orientation_map.md` and `refactor_plan.md`.
+- Repository guidance is inconsistent about root-level agent files: `README.md`, `.prodify/AGENTS.md`, and integration tests say the default lifecycle is `.prodify`-first with no required root-level agent files, while multiple docs under `docs/` still describe generated root-level compatibility files such as `AGENTS.md`.
+
+## Open Questions
+- Whether the checked-in root `AGENTS.md` should remain purely as repository-local contributor guidance or be removed entirely from the visible product story.
+- Whether the self-hosted `.prodify/` workspace should continue to include repo-specific development artifacts beyond the generated default preset, or be trimmed closer to the preset footprint.
+- Which documentation pages that still describe compatibility-file generation are still intentional future-design notes versus stale product claims that should now be corrected.
+
+## Policy Checks
+- Operate only on verified data.
+- Preserve the existing behavior during understanding.
+
+## Repository Summary
+- Project name: Prodify.
+- Primary stack: TypeScript, Node.js, npm, compiled `dist/` output from `src/`.
+- Project type: CLI plus in-agent contract-driven runtime scaffolding.
+- Primary entry points: `src/cli.ts`, `src/index.ts`, `src/commands/init.ts`, `src/commands/status.ts`, `src/commands/doctor.ts`, `src/commands/update.ts`.
+- High-centrality modules for Task 65: `src/presets/loader.ts`, `src/core/preset-validation.ts`, `src/core/paths.ts`, `src/core/validation.ts`, `README.md`, `docs/`, `assets/presets/default/canonical/`, and the checked-in `.prodify/` workspace.
+- Key architectural boundary for this task: generated preset assets, checked-in self-hosted `.prodify/`, runtime validation contracts, docs, and tests must communicate the same `.prodify`-first model.
+
+## Success Criteria
+- The repository intent is captured clearly.
+- Known unknowns are listed explicitly.

package/.prodify/artifacts/02-diagnose.md

@@ -0,0 +1,26 @@
+# 02-diagnose
+
+## Constraints
+- The runtime contract layer, tests, and flow-state code already treat numbered stage artifacts under `.prodify/artifacts/` as canonical behavior, so any repair must preserve that observable runtime model.
+- `prodify init` and `prodify update` must continue to avoid creating root-level compatibility files in the default lifecycle, because existing tests assert those paths stay absent.
+- The checked-in `.prodify/` directory is both a self-hosted workspace and a repository artifact set, so cleanup must distinguish product-owned runtime layout from repo-specific historical design documents.
+
+## Observed Issues
+- Critical: `.prodify/tasks/01-understand.md` through `.prodify/tasks/06-validate.md` still referenced legacy artifact names such as `orientation_map.md`, `diagnostic_report.md`, and `refactor_plan.md` while compiled contracts and validation tests require `.prodify/artifacts/01-understand.md` through `.prodify/artifacts/06-validate.md`.
+- Critical: repository guidance is contradictory about root-level compatibility files. `README.md`, `.prodify/AGENTS.md`, and `tests/integration/cli-flows.test.js` describe a `.prodify`-first lifecycle with no required root-level files, but `docs/codex-support.md`, `docs/compatibility-targets.md`, `docs/claude-support.md`, `docs/opencode-support.md`, and `docs/generation-rules.md` still describe generated root-level compatibility outputs.
+- High: the checked-in self-hosted `.prodify/artifacts/` directory still contains legacy artifact files such as `.prodify/artifacts/orientation_map.md`, `.prodify/artifacts/diagnostic_report.md`, `.prodify/artifacts/refactor_plan.md`, `.prodify/artifacts/implementation_summary.md`, and `.prodify/artifacts/validation_report.md`, which visually conflicts with the numbered runtime artifact model.
+- High: the default preset under `assets/presets/default/canonical/` ships only a minimal canonical footprint, while docs such as `docs/canonical-prodify-layout.md` describe a broader canonical tree and the checked-in repo-root `.prodify/` workspace contains many additional runtime and design files.
+- Medium: the repository root still contains `AGENTS.md`, which is valid for this development environment but is indistinguishable at a glance from the deprecated product story unless documented explicitly.
+
+## Policy Checks
+- Diagnose from repository evidence only.
+- Do not propose implementation changes in the diagnosis stage.
+
+## Root Causes
+- The repository completed a `.prodify`-first product transition in runtime code and tests before all self-hosted task files, templates, artifacts, and design docs were migrated to the same terminology.
+- Historical design documentation for compatibility-file generation was retained in `docs/` after the default lifecycle moved away from root-level generated agent files, leaving multiple incompatible narratives in the repo.
+- The self-hosted `.prodify/` workspace mixes active runtime assets with archived design outputs, so stale legacy artifact names remain visible even after the runtime adopted numbered artifacts.
+
+## Success Criteria
+- Every critical issue is tied to evidence.
+- Root causes are separated from symptoms.

package/.prodify/artifacts/03-architecture.md

@@ -0,0 +1,30 @@
+# 03-architecture
+
+## Dependency Rules
+- Domain rules for the product lifecycle belong to compiled contracts, runtime state handling, and the canonical `.prodify` runtime model; documentation and examples must describe that behavior, not redefine it.
+- Application-layer flow definitions such as `.prodify/tasks/` may depend on the contract model, but they must use the same artifact names, step order, and validation semantics as the compiled contracts.
+- Infrastructure assets such as `assets/presets/default/canonical/` and the checked-in repo-root `.prodify/` workspace may extend the canonical runtime footprint, but they must not contradict the default lifecycle documented in `README.md` and enforced by tests.
+- Interface-layer materials such as `README.md`, `.prodify/AGENTS.md`, and user-facing docs may explain contributor-only root files, but they must not present them as product-required runtime behavior when the default flow is `.prodify`-first.
+
+## Policy Checks
+- Flag mixed concerns explicitly.
+- Keep Domain dependencies pointing inward only.
+
+## Proposed Structure
+- Current pattern classification: layered tooling architecture with clean-architecture intent, confidence `0.76`.
+- Target structure for Task 65:
+- Domain: compiled contracts, runtime state invariants, stage ordering, and artifact naming rules.
+- Application: task execution protocol, preset loading, validation orchestration, and flow-state transitions.
+- Infrastructure: preset asset trees, checked-in self-hosted `.prodify/`, filesystem layout, and test fixtures.
+- Interface: CLI output, `README.md`, `.prodify/AGENTS.md`, and product-facing documentation.
+- Required boundary rule: interface and infrastructure layers must conform to the domain-owned `.prodify`-first lifecycle instead of preserving legacy compatibility-file narratives.
+- Required clarity rule: the repo-root `AGENTS.md` may remain only as repository-local contributor guidance, explicitly outside the default Prodify product lifecycle.
+
+## Success Criteria
+- The target structure is explicit.
+- Architecture violations are listed clearly.
+
+## Tradeoffs
+- Keeping forward-looking compatibility-target docs is acceptable only if they are clearly marked as future or non-default behavior; otherwise they act as conflicting runtime guidance.
+- Keeping the self-hosted repo-root `.prodify/` workspace is valuable for dogfooding, but it must be labeled as canonical runtime layout plus repo-specific artifacts rather than an exact mirror of `prodify init`.
+- Removing every historical artifact immediately would reduce drift fastest, but targeted clarification and test coverage is safer where files still serve repository-development purposes.

package/.prodify/artifacts/04-plan.md

@@ -0,0 +1,35 @@
+# 04-plan
+
+## Policy Checks
+- Keep the plan deterministic and minimal.
+- Map every step back to a diagnosed issue or architecture rule.
+
+## Risks
+- `step-01-clarify-default-lifecycle-docs`: medium risk because multiple visible entrypoints must stay internally consistent while preserving the current `.prodify`-first product behavior.
+- `step-02-reframe-compatibility-docs`: medium risk because historical design docs still describe generated root-level compatibility files and need clear scope boundaries rather than accidental deletion of future design intent.
+- `step-03-strengthen-consistency-tests`: low risk because the changes are additive but they must avoid asserting behavior the product does not currently implement.
+
+## Step Breakdown
+- Step ID: step-01-clarify-default-lifecycle-docs
+  - Description: clarify the current product story in canonical user-facing docs and contributor-facing guidance, including what the checked-in self-hosted `.prodify/` workspace and root `AGENTS.md` represent.
+  - Files: README.md, AGENTS.md, .prodify/AGENTS.md, .prodify/artifacts/README.md, docs/canonical-prodify-layout.md
+  - Risk: 3
+  - Validation: npm test
+- Step ID: step-02-reframe-compatibility-docs
+  - Description: rewrite or relabel compatibility-target documentation so root-level generated agent files are clearly future, planned, or non-default rather than part of the current Prodify lifecycle.
+  - Files: docs/compatibility-targets.md, docs/codex-support.md, docs/claude-support.md, docs/opencode-support.md, docs/generation-rules.md
+  - Risk: 3
+  - Validation: npm test
+- Step ID: step-03-strengthen-consistency-tests
+  - Description: add explicit tests that the documented default lifecycle remains `.prodify`-first, that the preset and repo-root self-hosted workspace are distinguished correctly, and that root-level product-owned agent files are not required.
+  - Files: tests/integration/cli-flows.test.js, tests/unit/self-hosted-workspace.test.js, tests/unit/preset-loader.test.js
+  - Risk: 1
+  - Validation: npm test
+
+## Success Criteria
+- The plan enumerates executable steps.
+- Verification is defined before refactoring starts.
+
+## Verification
+- Run `npm test` after each step because the touched files span docs, preset assets, and runtime-adjacent consistency tests.
+- Treat any regression in lifecycle messaging, preset loading, or workspace health assertions as a blocker before advancing to the next step.

package/.prodify/artifacts/05-refactor.md

@@ -0,0 +1,24 @@
+# 05-refactor
+
+## Behavior Guardrails
+- Kept the change set inside the three test files declared by `step-03-strengthen-consistency-tests`.
+- Added assertions only for already-documented behavior and did not introduce new product features or CLI semantics.
+- Reused existing integration and unit suites instead of creating broad new fixtures.
+- After the first validation failure, repaired the same selected step by aligning one regex with the documented `repository-local` wording.
+
+## Changed Files
+- tests/integration/cli-flows.test.js
+- tests/unit/self-hosted-workspace.test.js
+- tests/unit/preset-loader.test.js
+
+## Policy Checks
+- Execute exactly one selected step.
+- Keep the diff minimal and behavior-preserving unless the plan says otherwise.
+
+## Selected Step
+- Step ID: step-03-strengthen-consistency-tests
+- Description: add explicit tests that the documented default lifecycle remains `.prodify`-first, that the preset and repo-root self-hosted workspace are distinguished correctly, and that root-level product-owned agent files are not required.
+
+## Success Criteria
+- The selected plan step is implemented fully.
+- Unrelated files remain untouched.

package/.prodify/artifacts/06-validate.md

@@ -0,0 +1,17 @@
+# 06-validate
+
+## Policy Checks
+- Validation must follow every refactor step.
+- Critical regressions block forward progress.
+
+## Regressions
+- None detected for the repaired `step-03-strengthen-consistency-tests`.
+- `npm test` passed with 38 tests and 0 failures after aligning the self-hosted-workspace assertion with the documented wording.
+
+## Success Criteria
+- Validation records whether regressions were found.
+- The result is strong enough to gate the next runtime transition.
+
+## Validation Results
+- PASS/FAIL: PASS
+- Evidence: `npm test` completed successfully after the repair to `tests/unit/self-hosted-workspace.test.js`.

package/.prodify/artifacts/README.md

@@ -0,0 +1,6 @@
+# Stage Artifacts
+
+Stage execution writes validated outputs into this directory.
+Each stage contract declares the canonical artifact paths and required sections.
+The active runtime stage outputs use numbered filenames such as `01-understand.md` through `06-validate.md`.
+This self-hosted repository may also keep repository-local design or historical artifacts here when they are useful for developing Prodify itself.

package/.prodify/artifacts/architecture_spec.md

@@ -0,0 +1,29 @@
+# Architecture Spec
+
+## Detected Pattern
+- Pattern:
+- Confidence:
+
+## Target Style
+- Modular Clean Architecture
+
+## Layer Definitions
+- Layer: Domain
+  - Allowed dependencies:
+- Layer: Application
+  - Allowed dependencies: Domain
+- Layer: Infrastructure
+  - Allowed dependencies: Application, Domain
+- Layer: Interface
+  - Allowed dependencies: Application, Domain
+
+## Violations
+- Location:
+  - Violation type:
+  - Evidence:
+
+## Gap Analysis
+- 
+
+## Migration Notes
+- 

package/.prodify/artifacts/artifact-validation-design.md

@@ -0,0 +1,276 @@
+# Artifact Validation Design
+
+Date: 2026-03-28
+Scope: `./.prodify/artifacts/*.md`
+
+## Purpose
+Define the validation layer that checks produced markdown artifacts against their matching templates before workflow state may advance.
+
+This layer is responsible for artifact-shape validation only. It must confirm that:
+- the expected artifact exists
+- the artifact is written to the declared path
+- the artifact contains the required template headings
+- the artifact is complete enough to be considered structurally valid
+
+This layer is not responsible for:
+- choosing which task runs next
+- mutating workflow state directly
+- judging deep semantic correctness of the content
+- validating source-code diffs from Task `05-refactor`
+
+## Validation Scope
+The artifact-validation layer runs after a task writes its primary artifact and before workflow advancement.
+
+Inputs:
+- produced artifact path from the task frontmatter `writes`
+- matching template path from the task output specification
+- required heading set derived from the template
+- task ID and task metadata
+
+Output:
+- a deterministic validation result with:
+  - `pass` or `fail`
+  - failure reason category
+  - missing or invalid sections
+  - recommended next action
+
+## Core Validation Rules
+
+### Rule 1 - Expected Artifact Must Exist
+- The artifact file must exist at the exact path declared in task frontmatter.
+- If the expected path is missing, validation fails immediately.
+
+### Rule 2 - Artifact Must Be Markdown
+- The primary artifact must be a Markdown document for Tasks `01` through `06`.
+- If the produced file is not Markdown or cannot be parsed as structured markdown text, validation fails.
+
+### Rule 3 - Template Heading Coverage
+- Every required heading from the matching template must be present in the artifact.
+- Heading order must follow the template order.
+- Required headings may contain brief or uncertain content, but they may not be omitted.
+
+### Rule 4 - No Critical Structural Drift
+- The artifact may include small clarifying subsections only if they do not obscure the required template structure.
+- If the artifact removes, renames, or reorders required headings in a way that breaks downstream parsing, validation fails.
+
+### Rule 5 - Partial Output Is Invalid
+- If the artifact stops partway through the required structure, validation fails.
+- Empty artifacts, truncated artifacts, or artifacts missing required late sections are invalid.
+
+### Rule 6 - Declared Output Path Wins
+- If content was written to a different path than the task's declared `writes` path, validation fails even if the content is otherwise correct.
+
+## Validation Rules Per Artifact
+
+### `orientation_map.md`
+- Template:
+  - `.prodify/templates/orientation_map.template.md`
+- Required headings:
+  - `# Orientation Map`
+  - `## Project Summary`
+  - `## Entry Points`
+  - `## Module Map`
+  - `## Monorepo Metadata`
+  - `## Dependency Overview`
+  - `## Key Observations`
+  - `## Uncertainty`
+- Pass rule:
+  - all headings exist in order and the file is non-empty
+
+### `diagnostic_report.md`
+- Template:
+  - `.prodify/templates/diagnostic_report.template.md`
+- Required headings:
+  - `# Diagnostic Report`
+  - `## Top 5 Priorities`
+  - `## Critical Issues`
+  - `## High Issues`
+  - `## Medium Issues`
+  - `## Low Issues`
+  - `## Reliability Risks`
+  - `## Technical Debt Score`
+  - `## Notes`
+- Pass rule:
+  - all headings exist in order and the report reaches the final `## Notes` section
+
+### `architecture_spec.md`
+- Template:
+  - `.prodify/templates/architecture_spec.template.md`
+- Required headings:
+  - `# Architecture Spec`
+  - `## Detected Pattern`
+  - `## Target Style`
+  - `## Layer Definitions`
+  - `## Violations`
+  - `## Gap Analysis`
+  - `## Migration Notes`
+- Pass rule:
+  - all headings exist in order and layer/violation sections are structurally present
+
+### `refactor_plan.md`
+- Template:
+  - `.prodify/templates/refactor_plan.template.md`
+- Required headings:
+  - `# Refactor Plan`
+  - `## Summary`
+  - `## Phase Breakdown`
+  - `## Steps`
+  - `## Notes`
+- Additional structural requirement:
+  - at least one `### Step ID:` block must appear under `## Steps`
+- Pass rule:
+  - all headings exist in order and at least one step block is present
+
+### `implementation_summary.md`
+- Template:
+  - `.prodify/templates/implementation_summary.template.md`
+- Required headings:
+  - `# Implementation Summary`
+  - `## Step Executed`
+  - `## Objective Achieved`
+  - `## Files Changed`
+  - `## Diff Summary`
+  - `## Behavior Change Expected`
+  - `## Notes`
+- Pass rule:
+  - all headings exist in order
+- Special rule:
+  - validate only the summary artifact, not the modified source files
+
+### `validation_report.md`
+- Template:
+  - `.prodify/templates/validation_report.template.md`
+- Required headings:
+  - `# Validation Report`
+  - `## Readiness Status`
+  - `## Final Score`
+  - `## Category Scores`
+  - `## Remaining Issues`
+  - `## Regressions Detected`
+  - `## Recommended Next Step`
+- Pass rule:
+  - all headings exist in order and the file reaches the final next-step section
+
+## Error Handling
+
+### Missing Artifact
+Condition:
+- the expected artifact path does not exist
+
+Result:
+- fail validation
+- report `missing_artifact`
+- do not advance workflow state
+- require the task to regenerate the artifact
+
+### Wrong Output Path
+Condition:
+- an artifact was produced, but not at the declared `writes` path
+
+Result:
+- fail validation
+- report `wrong_output_path`
+- require the artifact to be rewritten or moved to the declared path before continuing
+
+### Missing Required Heading
+Condition:
+- one or more required template headings are absent
+
+Result:
+- fail validation
+- report `missing_required_heading`
+- list the missing headings explicitly
+- require artifact correction before continuing
+
+### Heading Order Drift
+Condition:
+- required headings exist but are reordered in a way that breaks the template contract
+
+Result:
+- fail validation
+- report `invalid_heading_order`
+- require the artifact to be rewritten to match template order
+
+### Partial Artifact
+Condition:
+- the artifact contains some required headings but stops early or omits required trailing sections
+
+Result:
+- fail validation
+- report `partial_artifact`
+- require regeneration or completion of the artifact
+
+### Structurally Empty Section
+Condition:
+- a required heading exists but the section is completely empty with no uncertainty note, placeholder, or minimal content
+
+Result:
+- fail validation
+- report `empty_required_section`
+- require the section to be populated or explicitly marked uncertain
+
+## Pass/Fail Criteria
+
+### PASS
+Validation passes only when:
+- the artifact exists at the declared path
+- the artifact matches the expected Markdown shape
+- all required headings are present
+- required headings appear in template order
+- no required section is structurally empty without explanation
+
+### FAIL
+Validation fails if any of the following are true:
+- artifact missing
+- artifact written to the wrong path
+- missing required heading
+- invalid heading order
+- partial artifact
+- structurally empty required section
+
+## Workflow Impact When Validation Fails
+- Do not advance workflow state.
+- Do not update `last_completed_task` to the task being validated.
+- Mark the task outcome as failed or blocked according to run-state rules:
+  - use `blocked` when a file/path/template precondition is missing
+  - use `failed` when the artifact was produced but is structurally invalid
+- Record the failure reason in `run_state.json` notes.
+- Append the failure to `task_log.json`.
+- Require the artifact to be corrected and revalidated before the next task may run.
+
+## Integration Notes
+
+### Relationship To Self-Validation
+- The self-validation layer checks task preconditions and broad post-run expectations.
+- The artifact-validation layer is narrower and authoritative for final template-shape validation.
+- Artifact validation should run after the task writes its artifact and before workflow state transitions.
+
+### Relationship To Dispatcher
+- The dispatcher chooses the task and expected output path.
+- The artifact-validation layer verifies the produced artifact after execution.
+- The dispatcher must not treat a task as successful until artifact validation passes.
+
+### Relationship To Run-State Logic
+- The run-state layer decides how PASS or FAIL changes workflow state.
+- The artifact-validation layer returns structured results that the run-state updater consumes.
+
+## Suggested Validation Result Shape
+```json
+{
+  "task_id": "02-diagnose",
+  "artifact_path": ".prodify/artifacts/diagnostic_report.md",
+  "template_path": ".prodify/templates/diagnostic_report.template.md",
+  "status": "fail",
+  "reason": "missing_required_heading",
+  "details": [
+    "Missing heading: ## Technical Debt Score"
+  ],
+  "recommended_next_action": "Regenerate or correct the artifact before advancing workflow state."
+}
+```
+
+## Implementation Notes
+- Derive required heading lists directly from templates.
+- Treat heading presence and order as deterministic checks.
+- Prefer failing fast with explicit reasons over trying to auto-repair artifacts.
+- Keep the validation layer reusable across all current primary artifacts.