plain-forge 1.0.1

package/forge/skills/plain-healthcheck/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: plain-healthcheck
+description: >-
+  Verification gate for a ***plain project. Verifies that every `config.yaml`
+  exists, points at scripts that actually live in `test_scripts/`, and that
+  `codeplain <top_module>.plain --dry-run` passes for every top module in
+  the project. Run this whenever anything in the project is finalized —
+  including (but not limited to) the end of `forge-plain`, the end of
+  `add-feature`, after `debug-specs`, after any single-skill edit that
+  finalizes a concept, functional spec, requirement, template, or config —
+  and any time the user asks "is the project ready to render?".
+---
+
+# Plain Healthcheck
+
+Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+
+## When to run
+
+Run this skill **whenever anything in the ***plain project is finalized** and the project is about to be left in a state the user (or another skill) might render from. That includes, but is not limited to:
+
+- **End of `forge-plain`** (Phase 4) — before presenting the render command.
+- **End of `add-feature`** (Phase 3 final review) — before declaring the feature done.
+- **End of `debug-specs`** — after applying a fix, before telling the user to re-render.
+- **After finalizing any single edit** that changes the renderable surface — e.g. after `add-concept`, `add-functional-spec`, `add-functional-specs`, `add-implementation-requirement`, `add-test-requirement`, `add-acceptance-test`, `add-template`, `add-resource`, `resolve-spec-conflict`, `break-down-func-spec`, `consolidate-concepts`, `refactor-module`, `create-import-module`, `create-requires-module`, or any of the `implement-*-testing-script` skills.
+- **After hand-editing** a `.plain` file, a `config.yaml`, or anything under `test_scripts/`.
+- **On demand** — whenever the user asks whether the project is in a renderable state.
+
+The healthcheck is **not** a forge-plain-only step. Treat it as the default closing move for any workflow that finalizes something in the project.
+
+Do **not** skip this skill because "the dry-run passed earlier" — `config.yaml`s, scripts, and specs can all drift between runs. The healthcheck is cheap; rendering against stale specs is expensive.
+
+## Workflow
+
+The skill is a **detect → fix → re-run** loop. It does not stop at the first failure; it surfaces everything wrong, fixes what it can, and only returns when either everything passes or a gap genuinely requires user input.
+
+### Step 1 — Inventory the project
+
+1. List every `.plain` file in the repo root (and any subdirectories that contain `.plain` files). Build the module graph from each file's YAML frontmatter (`requires`, `import`).
+2. Identify **top modules** — every module that is not `requires`-ed by any other module. A single-stack project has one top module; a multi-part project (e.g. backend + frontend) has one top module per part.
+3. List every `config.yaml` in the repo (root and per-part directories such as `backend/`, `frontend/`).
+4. List every script under `test_scripts/`.
+5. Pair each top module with the `config.yaml` that governs it. The pairing rule is: the config file in the same directory as the top module wins; failing that, the repo-root `config.yaml`. A multi-part project must have one config per part — record any top module that has no governing config as a failure.
+
+Print a one-line inventory summary so the rest of the run is easy to follow, e.g. `Top modules: backend/api.plain (config: backend/config.yaml), frontend/web.plain (config: frontend/config.yaml). Scripts in test_scripts/: 4.`
+
+### Step 2 — Validate every `config.yaml`
+
+For each `config.yaml` in the inventory, check **all** of the following. Collect every failure — do **not** stop at the first.
+
+1. **File parses.** It is valid YAML.
+2. **At minimum `unittests-script` is present.** Every project gets a unit-test runner.
+3. **For every script field that is present** (`unittests-script`, `conformance-tests-script`, `prepare-environment-script`):
+   - The path is a string ending in `.sh` (macOS/Linux) or `.ps1` (Windows). The extension must match the rest of the project — do not mix `.sh` and `.ps1` in a single config.
+   - The referenced file actually exists on disk under `test_scripts/`.
+   - On Unix, the script has the executable bit set (`-x`). If not, that is a fixable failure.
+4. **No mixed stacks per config.** Every script referenced from a single `config.yaml` must target the same language/stack. For example, `backend/config.yaml` should not reference `run_unittests_js.sh`. If a config crosses stacks, that is a failure — the project should have been split into multiple configs per the rule in `PLAIN_REFERENCE.md`.
+5. **No dangling fields.** Any `*-script` field whose target file does not exist is a failure.
+6. **`prepare-environment-script` implies `conformance-tests-script`.** A `prepare-environment-script` only makes sense in service of conformance tests — the environment is what those tests run against. If a `config.yaml` declares `prepare-environment-script` but does **not** declare `conformance-tests-script`, that is a failure. Surface it to the user and offer to either (a) invoke `implement-conformance-testing-script` to add the missing script, or (b) remove the `prepare-environment-script` field if it was added in error. Do not auto-pick.
+7. **No orphan scripts.** Every script under `test_scripts/` should be referenced by *some* `config.yaml`. If a script is never referenced, surface it as a **warning** (not a hard failure — the user may be in the middle of authoring).
+
+For each failure, record the offending config path, the offending field, and the concrete problem (`file missing`, `not executable`, `mixed stack`, etc.).
+
+#### Auto-fixes you may apply
+
+- **Missing executable bit** on a script that otherwise looks fine → `chmod +x <path>`.
+- **Stale path that points at a renamed script that clearly exists under a different name in `test_scripts/`** → only if there is exactly one obvious candidate (same language tag, same script kind). When in doubt, leave it for the user.
+
+Anything else (missing script, mixed stacks, missing `config.yaml`) must be surfaced to the user — do not silently regenerate scripts here. Re-invoking `implement-unit-testing-script`, `implement-conformance-testing-script`, or `implement-prepare-environment-script` from inside the healthcheck is allowed **only** if the user explicitly approves it after being shown the gap.
+
+### Step 3 — Dry-run every top module
+
+For each `(top_module, config.yaml)` pair from Step 1, run a dry-run from the project root via the `terminal` tool:
+
+```bash
+codeplain <top_module>.plain --dry-run
+```
+
+**Match the dry-run to how the user will actually render.** Pass the flags the user would pass for the real render so what you validate is what they will run:
+
+- **`--config-name <name>`** — required whenever the governing config file is not the default `config.yaml`, or when the project has multiple `config.yaml`s and the dry-run is being launched from somewhere that isn't the part's directory. `--config-name` takes a *file name*, not a path; if needed, `cd` into the part's directory before running so the right `config.yaml` is found.
+- **`--template-dir <path>`** — only when templates live outside `template/` **and** `template_dir` is not already set in the relevant config.
+- **`--full-plain`** — useful when an `import`/`requires` chain is suspect.
+- **`--verbose` / `-v`** — strongly recommended on a failed dry-run; the extra log output usually pinpoints the offending `.plain` file and spec.
+
+Treat the dry-run as a hard gate: the healthcheck **only passes** when every top module's dry-run exits successfully.
+
+#### When a dry-run fails
+
+Iterate until it passes:
+
+1. Read the error output. If the first run was not verbose, immediately re-run with `--verbose`. Identify the offending `.plain` file, the line (if reported), and the kind of issue: missing concept, syntax error, cyclic definition, complexity violation (`Functional spec too complex!`), conflicting reqs, missing template, broken `import`/`requires`, missing config field, etc.
+2. Fix only the `.plain` files (or the relevant `config.yaml` / template) using the appropriate edit skill — `add-concept`, `add-functional-spec`, `add-functional-specs`, `add-implementation-requirement`, `resolve-spec-conflict`, `break-down-func-spec`, `consolidate-concepts`, or an inline edit. **Never** modify generated code under `plain_modules/` or `conformance_tests/`.
+3. If you are uncertain about ***plain syntax for the failing construct, re-load `load-plain-reference` before fixing.
+4. Re-run the same `codeplain <top_module>.plain --dry-run …` command with the same flags. Repeat until it exits successfully.
+
+If the failure is something the healthcheck cannot reasonably fix on its own (e.g. the user has to choose between two contradictory specs and neither side was pre-approved, or a missing concept whose semantics aren't clear), **stop and surface it to the user** with the offending snippet and a concrete question. Do not invent behavior.
+
+#### Environment failures
+
+If `codeplain` is not on PATH, or `CODEPLAIN_API_KEY` is not set:
+
+- Do **not** pretend the dry-run passed.
+- Tell the user exactly what's missing and how to fix it (install the CLI, export the env var) and stop the healthcheck with a clearly-marked environment failure. This is the only kind of failure that may legitimately remain unresolved at the end of the skill.
+
+### Step 4 — Report
+
+Emit one of:
+
+- **`PASS`** — followed by a short summary of what was checked: `N config.yaml(s) validated`, `M top module(s) dry-run`, `K scripts referenced`. The caller (`forge-plain`, `add-feature`, `debug-specs`) can then continue to its hand-off step.
+- **`FAIL`** — followed by a numbered list of every unresolved problem. Each entry must include: the file (config / `.plain` / script) it applies to, the concrete issue, and what the user needs to decide if the healthcheck couldn't resolve it.
+
+The verdict goes on the first line so callers can pattern-match without parsing the whole report.
+
+## What this skill does NOT do
+
+- It does **not** author new specs from scratch — use `forge-plain` / `add-feature` for that.
+- It does **not** run the real render — only `--dry-run`.
+- It does **not** execute the testing scripts (`run_unittests`, `run_conformance_tests`, `prepare_environment`). It only verifies that the scripts are wired up correctly via `config.yaml`. The user runs the scripts themselves.
+- It does **not** silently regenerate config files or scripts. The most it does is `chmod +x` and (with user approval) re-invoke the relevant `implement-*-testing-script` skill.
+
+## Validation Checklist
+
+- [ ] Every `.plain` module was inventoried and every top module was identified
+- [ ] Every top module is governed by exactly one `config.yaml`
+- [ ] Every `config.yaml` parses as YAML and has at least `unittests-script`
+- [ ] Every `*-script` field points at a file that exists under `test_scripts/`
+- [ ] No `config.yaml` mixes stacks (e.g. Python + JS scripts in the same file)
+- [ ] No `config.yaml` declares `prepare-environment-script` without also declaring `conformance-tests-script`
+- [ ] Every `test_scripts/*` file is referenced by some `config.yaml` (or surfaced as a warning)
+- [ ] `codeplain <top>.plain --dry-run` exits successfully for **every** top module, with the right `--config-name` for multi-part projects
+- [ ] Verdict (`PASS` / `FAIL`) is on the first line, with a numbered list of remaining problems if it failed

package/forge/skills/refactor-module/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: refactor-module
+description: >-
+  Split a large ***plain module into smaller modules grouped by logical domain.
+  The resulting modules are connected via a requires chain so that functionality
+  is 100% preserved. Use when a module has grown too large and its functional
+  specs span multiple distinct concerns that would be clearer as separate modules.
+---
+
+# Refactor Module
+
+Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+
+## When to Use
+
+- A module has many functional specs spanning multiple distinct domains or feature areas.
+- The module is hard to reason about because unrelated concerns are interleaved.
+- New features are difficult to add because the module's scope is too broad.
+- The user explicitly asks to split or reorganize a module.
+
+## Guiding Principle
+
+The refactoring is purely structural. The **combined behavior** of the resulting modules must be **identical** to the original module. No functional spec is added, removed, or weakened. The split is semantic — grouping related specs together — not behavioral.
+
+## Input
+
+The `.plain` file to refactor, plus guidance from the user on the desired grouping (or ask the user to confirm your proposed grouping).
+
+## Phase 1 — Analyze the Current Module
+
+1. **Read the entire `.plain` file** — frontmatter, definitions, implementation reqs, test reqs, and all functional specs. Also read any `import` and `requires` chains to understand the full context.
+2. **Inventory the functional specs.** Number each spec and note which `:Concepts:` it references. Build a dependency map: which specs depend on earlier specs (by referencing behavior or state they introduced)?
+3. **Inventory the definitions.** For each concept, note which functional specs reference it. Identify concepts that are used across multiple logical groups vs. concepts used only within one group.
+4. **Identify logical groups.** Look for natural seams — clusters of functional specs that share concepts, represent a cohesive domain, or describe a single feature area. Common groupings:
+   - Data model setup and CRUD operations
+   - Business logic and processing rules
+   - UI screens and navigation
+   - Integrations and external interfaces
+   - Statistics, reporting, and analytics
+5. **Verify group independence.** Each group's specs should form a contiguous or near-contiguous block in chronological order. If a group's specs are scattered and interleaved with other groups, the split boundary may need adjustment.
+
+## Phase 2 — Plan the Split
+
+Present the proposed split to the user and get explicit confirmation before making any changes.
+
+### 2a. Define the module chain
+
+The modules form a `requires` chain that preserves the original chronological ordering of functional specs. The first module in the chain contains the earliest specs; each subsequent module `requires` the previous one and adds the next logical group.
+
+```
+original-module
+  ↓ splits into
+module-group-a  (no requires — this is the new base)
+module-group-b  (requires: module-group-a)
+module-group-c  (requires: module-group-b)
+```
+
+If the original module already had `requires` or `import` dependencies, the first new module inherits them.
+
+### 2b. Assign functional specs to modules
+
+Place each functional spec in exactly one module. The placement must respect chronological ordering:
+- Within each module, the specs appear in the same relative order as in the original.
+- Across the chain, the ordering is preserved: all specs in module A come before all specs in module B, which come before all specs in module C.
+- A spec **cannot** move to an earlier module than a spec it depends on.
+
+### 2c. Assign definitions to modules
+
+For each concept, determine where it belongs:
+
+| Concept usage | Placement |
+|---------------|-----------|
+| Used only within one module's specs | Define in that module |
+| Used across multiple modules in the chain | Define in the first module that uses it, and add to that module's `exported_concepts` |
+| Already defined in an import template | Leave in the import — no change needed |
+
+If many concepts are shared across all modules, consider creating a new import module (template) to hold them. This avoids long `exported_concepts` lists and keeps definitions centralized. Use the `create-import-module` skill for this.
+
+### 2d. Assign implementation reqs and test reqs
+
+- Reqs that apply to all modules should live in a shared import template. If one already exists, keep them there.
+- Reqs specific to a single module's domain move to that module.
+- When in doubt, keep reqs in the shared template — duplication across modules is worse than a slightly broad template.
+
+### 2e. Present the plan
+
+Summarize for the user:
+- Number of resulting modules and their names
+- Which functional specs go in each module (listed by number or short description)
+- The `requires` chain order
+- Any new import module being created
+- Which concepts are exported from each module
+- Confirmation that all original specs are accounted for (none lost)
+
+Get explicit user confirmation before proceeding.
+
+## Phase 3 — Execute the Split
+
+Create the new modules in order, from the base of the chain upward.
+
+### 3a. Create or update the import template (if needed)
+
+If shared definitions or reqs are being moved to a new import template, create it first using the `create-import-module` skill.
+
+### 3b. Create the base module
+
+Create the first module in the chain:
+1. Set the YAML frontmatter — inherit the original module's `import` references. Add `exported_concepts` for any concepts that downstream modules need.
+2. Add the `***definitions***` section with concepts used by this module's specs and concepts that need to be exported.
+3. Add `***implementation reqs***` and `***test reqs***` specific to this module (if not fully covered by the import template).
+4. Add the `***functional specs***` assigned to this module, preserving their original order and exact wording.
+5. Carry over any `***acceptance tests***` nested under the moved functional specs.
+
+### 3c. Create subsequent modules
+
+For each subsequent module in the chain:
+1. Set `requires` to point to the previous module in the chain. Set `import` if it uses shared templates.
+2. Add `exported_concepts` for any concepts that later modules in the chain need.
+3. Add `***definitions***` for concepts local to this module. Do **not** redefine concepts already available via `requires` (exported) or `import`.
+4. Add `***implementation reqs***` and `***test reqs***` specific to this module.
+5. Add the `***functional specs***` assigned to this module, preserving their original order and exact wording.
+6. Carry over any `***acceptance tests***`.
+
+### 3d. Handle the original module file
+
+After all new modules are created:
+- If the original module is being fully replaced (all specs moved out), delete it or rename it to avoid confusion.
+- If the original module was required by other modules, update those modules to `require` the last module in the new chain instead (since it transitively includes all prior modules' specs and generated code).
+
+## Phase 4 — Verify
+
+### 4a. Completeness check
+
+This is the most critical verification. Walk through every functional spec from the original module and confirm it appears in exactly one of the new modules. Nothing may be lost, weakened, modified, or left implicit.
+
+Checklist:
+- [ ] Total spec count across all new modules equals the original spec count
+- [ ] Each spec's text is identical to the original (no rewording)
+- [ ] Each spec's acceptance tests (if any) are carried over intact
+
+### 4b. Chronological ordering check
+
+Verify that the chronological order of all functional specs — when read across the requires chain from base to leaf — matches the original ordering exactly. A spec must not appear before a spec it depends on.
+
+### 4c. Concept availability check
+
+For each module, verify:
+- [ ] Every `:Concept:` referenced in its specs is either defined locally, available via `import`, or available via `exported_concepts` from the `requires` chain
+- [ ] `exported_concepts` includes every concept that downstream modules need
+- [ ] No concept name collisions between modules
+
+### 4d. Structural validation per module
+
+For each new module:
+- [ ] Has at least one functional spec and one implementation req
+- [ ] YAML frontmatter is correctly formatted
+- [ ] `requires` and `import` paths are correct
+- [ ] Module file is at the repository root (not in `template/`)
+- [ ] Specs are language-agnostic
+- [ ] All external interfaces remain explicit
+
+### 4e. Read all new modules
+
+Read each new `.plain` file in full and present the final structure to the user for approval. If the user requests changes, apply them and re-verify.
+
+## Common Pitfalls
+
+### Splitting too aggressively
+Creating many tiny modules with 1–2 specs each adds overhead without clarity. Aim for modules with 3–10 functional specs each, grouped around a cohesive theme.
+
+### Breaking chronological order
+Specs that set up foundational behavior (entry point, database init, core CRUD) must stay in the base module even if they touch concepts from multiple domains. Only split when specs are cleanly separable.
+
+### Forgetting exported_concepts
+If a concept defined in module A is referenced by a spec in module B (which requires A), the concept must be in A's `exported_concepts`. Missing exports cause rendering failures.
+
+### Modifying spec text during the split
+This is a refactoring, not a rewrite. Spec text must be copied verbatim. If a spec needs rewording to work in its new module context, that is a sign the split boundary is wrong — adjust the grouping instead.
+
+### Losing acceptance tests
+Acceptance tests are nested under their parent functional spec. When moving a spec to a new module, its acceptance tests must move with it.
+
+## Validation Checklist
+
+- [ ] User confirmed the split plan before execution
+- [ ] All original functional specs are present in exactly one new module — none lost
+- [ ] Spec text is identical to the original — no rewording
+- [ ] Acceptance tests moved with their parent specs
+- [ ] Chronological order preserved across the requires chain
+- [ ] Every referenced `:Concept:` is available in each module (local, import, or exported)
+- [ ] `exported_concepts` are correctly set on each module
+- [ ] No concept name collisions
+- [ ] Each module has at least one functional spec and one implementation req
+- [ ] `requires` chain is correctly ordered (base → leaf)
+- [ ] Original module removed or updated
+- [ ] Downstream modules (if any) updated to require the correct module
+- [ ] User approved the final result

package/forge/skills/resolve-spec-conflict/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: resolve-spec-conflict
+description: >-
+  Resolve a conflict between two functional specs in a ***plain spec file. Use
+  when conformance tests for a previously passing spec start failing after a new
+  spec is rendered, or when a potential conflict is detected while adding a new
+  functional spec (via `add-functional-spec` or `add-functional-specs`).
+---
+
+# Resolve Spec Conflict
+
+Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+
+## When This Applies
+
+A conflict exists (or is suspected) when:
+- Conformance tests for a **previously passing** functional spec begin to fail after a new spec is rendered.
+- A new spec being added (via the `add-functional-spec` or `add-functional-specs` skill) appears to contradict an existing spec.
+- Two specs make incompatible assertions about the same behavior, data, or state.
+
+## Workflow
+
+### Step 1: Identify the Conflicting Pair
+
+Read the `.plain` file and pinpoint the two specs in tension. If the conflict was detected via a conformance test failure, also read the failing test and the generated implementation in `plain_modules/` to understand what behavior changed.
+
+### Step 2: Diagnose the Root Cause
+
+There are three possible outcomes — determine which one applies **before** making changes:
+
+| Outcome | Symptom | Fix |
+|---------|---------|-----|
+| **Implementation is incorrect** | Generated code doesn't match the spec's intent. The specs themselves are fine. | Clarify the ambiguous spec so the renderer interprets it correctly. Re-render. |
+| **Conformance tests are incorrect** | The tests don't accurately verify the spec. The implementation is actually correct. | Adjust `***test reqs***` or `***acceptance tests***` to guide better test generation. Re-render. |
+| **Requirements truly conflict** | The two specs are inherently contradictory — no implementation can satisfy both. | One or both specs must be revised. See Step 3. |
+
+**How to diagnose:**
+1. Read both functional specs carefully. Can a single implementation satisfy both simultaneously?
+2. If yes → the specs are compatible; the issue is ambiguity (outcome 1) or bad tests (outcome 2).
+3. If no → the requirements truly conflict (outcome 3).
+
+### Step 3: Resolve the Conflict
+
+When the requirements truly conflict, choose a resolution strategy:
+
+**Strategy A: Add detail to disambiguate.** Often the specs aren't contradictory — they're just ambiguous enough that the renderer picks a conflicting interpretation. Adding explicit context to one or both specs eliminates the ambiguity.
+
+```
+Before (ambiguous):
+- The system should return all :Resource: items.
+- The system should return only active :Resource: items.
+
+After (disambiguated):
+- The system should return all :Resource: items when no filter is specified.
+- When the "active" filter is specified, the system should return only active :Resource: items.
+```
+
+**Strategy B: Revise the newer spec.** If the new spec introduced the conflict, rewrite it to be compatible with the established behavior from earlier specs.
+
+**Strategy C: Revise the older spec.** If the older spec was under-specified and the new requirement reveals a better design, update the older spec. This is more disruptive — all conformance tests for that spec and everything after it may need re-rendering.
+
+**Strategy D: Merge into one spec.** If the two specs describe overlapping behavior, combine them into a single, clear spec. Remove the redundant one. Be mindful of the 200 LOC limit.
+
+### Step 4: Validate the Resolution
+
+After editing:
+1. Re-read the full `***functional specs***` section to confirm no new conflicts were introduced.
+2. Check that any revised spec still respects the 200 LOC limit.
+3. Check that chronological ordering still makes sense (earlier specs should not depend on later ones).
+4. If resolving via test adjustments, verify the `***test reqs***` or `***acceptance tests***` changes are appropriate.
+
+## Prevention (for use during add-functional-spec / add-functional-specs)
+
+Before adding a new spec, run through this quick conflict check:
+
+1. List every existing functional spec that touches the same `:Concepts:` as the new spec.
+2. For each, ask: "Can a single implementation satisfy both this existing spec and the new one?"
+3. If any answer is "not obviously yes" — add explicit detail to the new spec to eliminate the ambiguity **before** inserting it.
+
+## Validation Checklist
+
+- [ ] Root cause diagnosed (implementation / tests / true conflict)
+- [ ] Resolution strategy chosen and applied
+- [ ] Revised specs are language-agnostic
+- [ ] Revised specs each imply ≤ 200 LOC
+- [ ] No new conflicts introduced by the fix
+- [ ] Chronological ordering preserved
+- [ ] All referenced `:Concepts:` are still defined