promote to stable

.github/copilot-instructions.md

@@ -0,0 +1,163 @@
+# Copilot Instructions for `form8ion/project` (Strict)
+
+## Primary Rule
+
+Follow existing repository patterns exactly.
+Do not introduce new architecture, naming conventions, or directory structure.
+Only do that when explicitly requested.
+
+## Scope and Safety
+
+* Make the smallest possible change to satisfy the request.
+* Do not perform unrelated cleanup, refactors, or file moves.
+* Preserve existing public exports and contracts unless a break is required.
+* If required behavior is ambiguous, ask for clarification.
+
+## Repository Conventions (Mandatory)
+
+* Use ESM syntax only (`import` / `export`) in `src/**/*.js`.
+* Feature implementation files usually default-export their primary function.
+* Re-export plugin convention (protocol contract) names from each directory
+  `index.js`.
+* Valid plugin convention names include `scaffold`, `lift`, `test`,
+  `remove`, and `qualify`.
+* Keep feature logic in existing role files.
+  * `prompt.js`
+  * `schema.js`
+  * `scaffolder.js`
+  * `lifter.js`
+  * `tester.js`
+  * `index.js`
+* Keep tests colocated with implementation as `*.test.js`.
+
+## Naming Rules (Mandatory)
+
+* File names use `kebab-case` and are noun-based.
+* Function names are verb-based.
+* Default export functions must be named, not anonymous.
+* Prompt ID constants must use `*_PROMPT_ID`.
+* Shared question maps must use `questionNames`.
+* Prompt ID aggregators must use `ids`.
+* Aggregator keys stay `CONSTANT_CASE`.
+* Reuse existing identifiers where possible.
+
+## Prompt Wiring Rules (Mandatory)
+
+When adding or modifying prompt flow:
+
+1. Define and export the prompt ID constant in the feature module.
+1. Wire the prompt ID into `src/prompts/index.js` if it is in core flow.
+1. Add or update keys in `src/prompts/question-names.js` when needed.
+1. Merge through existing `questionNames` composition patterns.
+1. Do not remove or rename existing IDs or keys unless requested.
+
+### Prompt Consumer Pattern (Mandatory)
+
+Consumers of the prompt handler must dispatch by `id` and resolve question key
+names through `promptConstants`:
+
+* Accept the prompt payload and destructure only the properties the handler
+  uses, including `id`.
+* Destructure `{questionNames, ids}` from `promptConstants`.
+* Alias each prompt ID from `ids` into a local `*PromptId` variable.
+* Use a `switch (id)` with one `case` per prompt ID.
+* Within each `case`, destructure question key names from
+  `questionNames[promptId]`.
+* Throw an error with the unknown prompt ID in the `default` case.
+* Reference `example.js` and `form8ion/github` `example.js` for the canonical
+  shape.
+
+## Testing Rules (Mandatory)
+
+* Any behavior change requires test updates.
+* Follow TDD and the three laws with Red-Green-Refactor iteration.
+* Unit test rules live in
+  `.github/instructions/unit-testing.instructions.md`.
+* Integration rules live in
+  `.github/instructions/integration-testing.instructions.md`.
+* Do not leave new logic untested.
+
+## Workflow: Outside-First, Inside-Out Delivery Required
+
+Use integration and unit tests together to drive new functionality.
+Define behavior from the outside first.
+Then build implementation layers from the inside out.
+
+Follow this sequence for new behavior:
+
+1. Define or update the integration scenario first in
+   `test/integration/features/**`.
+1. Commit that scenario before implementation as its own commit when it is the
+   first statement of the new behavior.
+1. Tag incomplete new integration scenarios with `@wip` so they can be pushed
+   to remote before the implementation is complete.
+1. Use `@focus` locally while iterating on a specific `@wip` scenario.
+1. Do not commit `@focus`.
+1. Add or update unit tests in `src/**/*.test.js` to drive the next internal
+   implementation layer.
+1. Implement the minimum code needed to satisfy the unit test.
+1. Commit partial production-quality implementation progress as `wip` while the
+   full integration scenario is still incomplete.
+1. Repeat unit-test-driven layer delivery until all required layers are
+   implemented.
+1. Complete the integration scenario from the outside perspective and remove
+   `@wip` when it passes in the normal integration flow.
+1. Commit the consumer-visible completion as `feat` or `fix`.
+
+Treat the scenario-definition commit, intermediate `wip` implementation
+commits, and final `feat`/`fix` completion commit as separate steps.
+
+## Code Style Rules
+
+* Match import ordering and formatting in the edited file.
+* Prefix Node built-in imports with `node:`.
+* Use two separated import groups in most files.
+* Put package imports first and relative imports second.
+* Keep exactly one blank line between package and relative groups.
+* Within package imports, order by distance as built-ins, third-party,
+  `@travi`, then `@form8ion`.
+* In relative imports, more parent traversals come first and same-folder
+  imports come last.
+* For test files, use three groups: other packages,
+  testing dependencies, then relative imports.
+* Prefer simple, explicit logic over abstractions.
+* Prefer existing popular packages over complex local logic.
+* Do not add dependencies for things easily done inline.
+* Avoid comments; write code that reads clearly without them.
+* In markdown documentation, use at most one sentence per line.
+* In markdown tables, use spaces around cells for readability.
+
+## README and Documentation
+
+* Do not hand-edit the `## Example` section of `README.md`.
+* Run `npm run generate:md` to regenerate it from `example.js` via remark.
+* The script runs `remark . --output` after a build, so a build must be current.
+
+## Commit Message Conventions
+
+When making commits, follow the guidelines in
+`.github/instructions/commit-conventions.md`.
+
+For commit approval, history shaping, fixup commits, and rebase preferences,
+follow `.github/instructions/commit-workflow.md`.
+
+Key principle: use the commit type that accurately describes what changed.
+
+semantic-release determines release impact from the commit type and any
+`BREAKING CHANGE:` footer.
+
+## Prohibited Without Explicit Request
+
+* Cross-feature refactors.
+* Renaming files or symbols for style only.
+* Reorganizing folder structure.
+* Changing module boundaries.
+* Altering behavior outside task scope.
+
+## Completion Checklist
+
+* Change is minimal and task-focused.
+* Naming follows repository conventions.
+* Prompt and question wiring is consistent with `src/prompts/index.js`.
+* Tests are added or updated for behavior changes.
+* No unrelated modifications were introduced.

.github/instructions/commit-conventions.md

@@ -0,0 +1,158 @@
+---
+---
+
+# Commit Message Conventions
+
+This project uses [semantic-release](https://github.com/semantic-release/semantic-release)
+with the default Angular commit convention to automate versioning and releases.
+
+## Rule Sources
+
+Effective commit rules come from the repo config chain.
+
+* `.commitlintrc.json` extends `@form8ion`
+* `@form8ion/commitlint-config` extends
+  `@commitlint/config-conventional`
+
+Use these rules as the source of truth when writing commits.
+
+## Core Principle
+
+Write commit messages from the **consumer perspective**, not from an
+implementation perspective.
+
+This means:
+
+* Use the commit type that accurately describes what the commit does
+* The commit type makes clear whether the change affects consumers:
+  * `feat`, `fix`, `perf`, and `BREAKING CHANGE:` affect consumers
+  * `test`, `docs`, `chore`, `refactor` do not affect consumers
+* semantic-release uses this to determine whether to create a release
+* Always include clear motivation for why the change was made
+
+## Format
+
+Follow Angular convention:
+
+```
+<type>(<scope>): <summary>
+
+<body>
+
+<footer>
+```
+
+## Type
+
+Allowed commit types include conventional types plus `wip`.
+
+* Release-triggering types: `feat`, `fix`, `perf`
+* Non-release types: `build`, `chore`, `ci`, `docs`, `refactor`,
+  `revert`, `style`, `test`, `wip`
+
+Type should describe the primary intent of the commit:
+
+* `feat`: new user-facing capability
+* `fix`: user-facing bug fix
+* `perf`: user-facing performance improvement
+* `refactor`: structural/internal change with no user-facing behavior or API
+  impact
+* `test`: tests only
+* `docs`: documentation only
+* `chore`/`build`/`ci`/`style`: maintenance and tooling
+
+`refactor` is valid only when there is no user-facing behavior or API change.
+If the public interface changes, use `feat` or `fix` and add
+`BREAKING CHANGE:` when required.
+
+### `wip` Type
+
+`wip` is for incremental work toward another type, usually a future `feat` or
+`fix`, when there is no user-facing behavior change yet.
+
+A `wip` commit should still be production-quality and releasable.
+It is distinct from other non-release types because it communicates
+in-progress product work, not just maintenance or documentation updates.
+
+When any `@word` token appears in a commit message summary or body, wrap it in
+backticks to prevent GitHub from interpreting it as a user mention.
+Cucumber tags (such as `@wip` or `@skip`) are a common source of this.
+
+## Scope
+
+`scope` should be kebab-case.
+Choose a scope that reflects the package area, for example `prompts`,
+`scaffolder`, `api`, `vcs`, or `language`.
+
+## Line Length and Lint Constraints
+
+commitlint enforces these limits:
+
+* Header max length: `100`
+* Body line max length: `100`
+* Footer line max length: `100`
+
+It also enforces lowercase `type` and kebab-case `scope`.
+
+## Summary
+
+The summary line should:
+
+* State the purpose of the change
+* Be imperative
+* Match the selected type and scope
+
+Good examples:
+
+* `feat(prompts): define prompt constants for prompt-specific expectations`
+* `test(language): cover scaffolder fallback behavior`
+* `wip(prompts): split prompt-id mapping before feat completion`
+
+Poor examples:
+
+* `refactor(api): remove questionNames from public exports`
+* `update copilot instructions`
+
+## Breaking Changes
+
+A breaking change is **only** when the public API or consumer-facing contract
+changes.
+
+Examples of breaking changes:
+
+* Removing a public export
+* Changing required function signatures
+* Modifying the structure of returned values
+* Changing behavior consumers depend on
+
+Examples of changes that are usually not breaking by themselves:
+
+* Moving internal code between files
+* Updating internal documentation or instructions
+* Changing test structure or test files
+* Updating how internal constants are wired
+
+## BREAKING CHANGE Footer
+
+When introducing a breaking change:
+
+* Include a `BREAKING CHANGE:` footer
+* State what changed for consumers
+* Include migration instructions
+
+Example:
+
+```
+BREAKING CHANGE: `questionNames` is no longer exported from @form8ion/project
+
+Use `promptConstants.questionNames` instead of importing `questionNames`
+directly from `@form8ion/project`.
+```
+
+## Body
+
+In the body, explain:
+
+* Why the change was made
+* What changes for users when consumer-facing
+* Technical context needed for reviewers

.github/instructions/commit-workflow.md

@@ -0,0 +1,65 @@
+---
+---
+
+# Commit Workflow
+
+## Core Principle
+
+Treat commit history as part of the product story for a branch.
+Each commit should be production-quality, releasable, and contribute to a clean,
+intentional history.
+
+## Current Approval Rules
+
+* Do not create commits automatically.
+* Always show the full proposed commit message before creating a commit.
+* Show the subject, body, and any footers in the proposal.
+* Wait for explicit user approval before running `git commit`.
+* For breaking changes, include the proposed `BREAKING CHANGE:` footer and
+  migration instructions before asking for approval.
+
+## Commit Story Rules
+
+* Prefer a commit history that tells a coherent story of the feature or fix.
+* Do not rely on squash merging to clean up history.
+* Assume branch commits should be meaningful on their own.
+* Keep commits focused and avoid mixing unrelated concerns.
+
+## Fixup and Rebase Preferences
+
+* When revising earlier work on a feature branch, prefer fixup commits over
+  noisy follow-up commits that clutter the story.
+* Prefer interactive rebase to fold fixup commits into the appropriate earlier
+  commits before merge.
+* Use fixup commits to improve an existing commit without changing the intended
+  story of the branch.
+* Preserve a clean progression of intent across the branch history.
+
+## `wip` Commits
+
+* `wip` commits are allowed for incremental work toward a later `feat` or
+  `fix`.
+* A `wip` commit must still be production-quality and releasable.
+* Use `wip` only when the work is intentionally incomplete from a product
+  perspective and there is no user-facing behavior change yet.
+* Preserve `wip` commits in history to keep the progress story intact.
+
+## Future Automation Guidance
+
+If commit automation is enabled later:
+
+* Continue to show the proposed commit message before creating commits unless
+  explicitly instructed otherwise.
+* Prefer creating fixup commits when adjusting previous commits on a branch.
+* Prefer interactive rebase to clean up history before merge.
+* Do not assume squash merge is the preferred cleanup strategy.
+* Optimize for a branch history that communicates the right story to reviewers
+  and future readers.
+
+## Relationship to Commit Conventions
+
+Use `.github/instructions/commit-conventions.md` for commit message format,
+commit type selection, commitlint rules, and semantic-release behavior.
+Use this file for approval, history, and workflow expectations.
+
+