@mriekki/project-forge 2.0.0 → 2.2.0

package/assets/generated/core/core/process/PROJECT_REQUIREMENTS_EXPORT.md

@@ -0,0 +1,165 @@
+# Project Requirements Export
+
+`PROJECT_REQUIREMENTS.json` is the canonical portable Project Forge interchange artifact for durable product, domain, experience, roadmap, and approved cross-cutting intent.
+
+It exists to support workflows such as replatforming the same product onto a different implementation stack without treating the source repository's framework/tool choices as product requirements.
+
+## Authority
+
+The JSON file is a **derived export**, not a competing source of truth.
+
+Repository authorities continue to own their facts. In a normal generated workspace that commonly means:
+
+```text
+docs/product/PRODUCT_BRIEF.md
+→ docs/work-items/<FB-...>/brief.md
+→ approved requirements.md when present
+```
+
+Additional product/domain authorities may include roadmap, system-design/domain invariants, product-level design/accessibility guidance, accepted ADR consequences, and project-owned decisions.
+
+The export must retain source paths/authority/provenance so a consumer can trace normalized facts back to their repository authorities.
+
+## Canonical filename and state
+
+Only this filename is canonical:
+
+```text
+PROJECT_REQUIREMENTS.json
+```
+
+The contract has no compatibility alias or alternate export filename.
+
+State is explicit:
+
+```text
+draft
+review
+approved
+```
+
+Only `approved` may be consumed as replatform input.
+
+## Portable content model
+
+The export should represent, when present:
+
+- project/product identity;
+- problem, users/stakeholders, desired outcomes, scope/non-scope;
+- product workflows/capabilities and success measures;
+- Feature Briefs with source ID, title, target milestone, target disposition, authority/status/maturity, outcomes, scope/non-scope, workflows, business/domain rules, dependencies, acceptance criteria, learning objectives, and open questions;
+- domain concepts and relationships;
+- domain invariants, lifecycle/state semantics, and business rules;
+- cross-cutting security/privacy, accessibility, reliability, performance, and data requirements;
+- portable product/UX principles, responsive constraints, and interaction intent;
+- roadmap milestones/sequencing facts that express product intent;
+- accepted decisions whose consequences are portable;
+- explicit learning intent/future ideas while preserving their non-authorizing maturity;
+- exact source repository/commit and contributing artifact paths.
+
+## Product Brief model
+
+Project Forge generated workspaces currently use one canonical product authority:
+
+```text
+docs/product/PRODUCT_BRIEF.md
+```
+
+The export therefore uses one normalized `product` object rather than inventing a multi-Product-Brief hierarchy.
+
+If a non-generated/adopted workspace declares a different authority model, export only what that model actually establishes. Do not manufacture a second Product Brief merely to fit Project Forge defaults.
+
+## Work-item maturity
+
+Preserve maturity exactly.
+
+Typical generated-project semantics include:
+
+```text
+V1 + committed
+V2 + planned
+V3 + directional
+```
+
+Presence in `PROJECT_REQUIREMENTS.json` is never implementation authorization. A roadmap Feature remains roadmap/directional until separately promoted through the normal requirements/work-item process.
+
+## Engineering Enablers
+
+Engineering Enablers are usually implementation-specific and are not portable product requirements.
+
+The export may retain an enabler in source traceability when it establishes a durable cross-cutting requirement, but replatforming normally re-derives stack-specific enablers rather than copying their IDs/scope.
+
+Examples:
+
+```text
+PRESERVE: secure individual authentication is required for remote internet use
+RE-DERIVE: configure ASP.NET authentication middleware
+
+PRESERVE: database schema changes must be reproducible and controlled
+RE-DERIVE: use EF Core migrations
+```
+
+## Mixed authorities
+
+Some documents mix durable intent with implementation choices. Treat these as classification inputs rather than all-or-nothing copies.
+
+Examples:
+
+- a Project Blueprint may contain product/domain facts plus current technology baseline;
+- a System Design may contain portable domain invariants plus React/.NET/SQLite topology;
+- a UX pattern may contain portable interaction behavior plus component-library details;
+- an ADR may establish both a product/security consequence and a stack-specific mechanism.
+
+Extract the portable fact, retain source traceability, and exclude/reconcile the mechanism.
+
+## Exclusions
+
+Do not export as portable requirements unless the repository explicitly makes them true product constraints:
+
+- programming languages/frameworks/component libraries;
+- ORMs, package managers, build tools, test runners;
+- repository/project directory layouts;
+- generated client/tooling mechanisms;
+- CI implementation commands;
+- current deployment host/provider bindings;
+- secrets/credentials/private runtime values;
+- application source code;
+- work-item plans/review/delivery history;
+- Git/PR/CI evidence;
+- Project Forge/Core/Bootstrap baseline state.
+
+## Replatform relationship
+
+The canonical flow is:
+
+```text
+project authorities
+→ /export-requirements
+→ PROJECT_REQUIREMENTS.json state=review
+→ human approval
+→ PROJECT_REQUIREMENTS.json state=approved
+→ /replatform <target-stack>
+→ current Bootstrap catalog reconciliation
+→ PROJECT_BOOTSTRAP.json state=review
+→ human Bootstrap approval
+→ deterministic generation into a new repository
+```
+
+`PROJECT_BOOTSTRAP.json` remains the generation/provenance contract for one implementation. `PROJECT_REQUIREMENTS.json` remains the portable product/domain interchange contract.
+
+## No in-place replatforming
+
+Replatforming creates a sibling/new implementation repository. It never rewrites the source application in place.
+
+This preserves historical truth and allows multiple implementations of the same product intent to coexist, such as:
+
+```text
+Family Meal Planner requirements
+├── React + ASP.NET Core implementation
+├── Angular + Spring Boot implementation
+└── Blazor + ASP.NET Core implementation
+```
+
+## Security
+
+The export must not contain secrets, credentials, private keys, access tokens, production data, machine-local bindings, or arbitrary runtime/log transcripts.

package/assets/generated/core/core/skills/build/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: build
+description: "Build the current project through its repository-owned build command without turning local compilation into setup, testing, delivery, or deployment."
+argument-hint: "[target|all]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Build
+
+`/build` is a thin local helper. It hides framework-specific command details while preserving the repository as the authority for how the project builds.
+
+## Contract
+
+Invoking `/build` authorizes one bounded local build attempt for the requested target. It does not authorize setup, dependency upgrades, source edits, delivery, release publication, deployment, or Production access.
+
+Resolve the build command from current repository evidence in this order:
+
+1. an explicit repository-owned build wrapper or documented build command;
+2. an explicit package/task script whose purpose is build;
+3. an unambiguous ecosystem-native build entry point already present in the repository.
+
+Do not invent a command because a framework is recognizable. If multiple materially different build targets exist and no default is documented, require a target such as `/build web`, `/build api`, or `/build all`.
+
+## Preconditions
+
+Before execution:
+
+- identify the repository root and current Git state;
+- inspect `PROJECT_BOOTSTRAP.json` and scaffold/readiness evidence when present;
+- verify that the selected build entry point exists;
+- do not create an intentionally deferred scaffold merely to make `/build` succeed.
+
+If the approved scaffold is deferred or required build markers do not exist, return `BUILD NOT AVAILABLE` with the smallest relevant reason. Do not run installation/scaffolding commands as an implicit repair.
+
+If dependencies or workstation tools are missing, recommend `/setup` rather than broadening `/build`.
+
+## Execution
+
+Run the selected build visibly and report:
+
+- target;
+- resolved repository-owned command identity;
+- success/failure and exit code when available;
+- produced artifact/output locations when the build contract makes them explicit;
+- effective application release/build identity when the build exposes it;
+- a concise actionable failure summary.
+
+Do not add linting, tests, formatting, packaging, container publishing, or code generation unless the repository's selected build command already defines them as part of that build.
+
+When the project implements `docs/process/APPLICATION_VERSIONING.md`, report observed version evidence from the build output/artifact metadata. Do not synthesize a build number, commit, or display version when the repository did not produce it.
+
+## Operation journal
+
+A consequential build may write a concise sanitized journal under `.project-forge/logs/build/` following `docs/process/OPERATION_JOURNAL.md`.
+
+Record the command identity, target, timestamps, exit status, explicit artifact paths, and observed application version/build identity when available. Do not blindly capture unlimited compiler/application output or secrets.
+
+## Git and lifecycle boundary
+
+`/build` must not:
+
+- edit source or configuration to fix a build;
+- stage, commit, push, open/update PRs, merge, or clean branches;
+- mark a work item accepted or delivered;
+- bump the application's release version merely to create a unique build;
+- publish a package/image/release;
+- deploy locally or remotely.
+
+A successful build is local machine evidence only.

package/assets/generated/core/core/skills/cleanup-branches/SKILL.md

@@ -114,18 +114,14 @@ If no branch is safely deletable, stop after the preview.
 
 ## 5. Cleanup gate
 
-For a non-empty verified-safe set, present one bounded destructive gate:
+For a non-empty verified-safe set, present one bounded destructive gate using the host-native **single-select structured choice UI** when available; in VS Code use the native question surface such as `vscode_askQuestions`. Offer:
 
-```text
-BRANCH CLEANUP READY
-
-1. Delete verified-safe local + remote branches [GIT + GITHUB WRITE] — recommended
-2. Delete verified-safe remote branches only [GITHUB WRITE]
-3. Delete verified-safe local branches only [GIT WRITE]
-4. Stop [NO ACTION]
-```
+- `Delete verified-safe local + remote branches` `[GIT + GITHUB WRITE]` — `RECOMMENDED`
+- `Delete verified-safe remote branches only` `[GITHUB WRITE]`
+- `Delete verified-safe local branches only` `[GIT WRITE]`
+- `Stop` `[NO ACTION]`
 
-Only the selected option authorizes the corresponding deletions. Do not include REVIEW REQUIRED branches in the bounded action.
+Use a numbered text menu only when structured choice UI is unavailable. Only the selected choice authorizes the corresponding deletions. Do not include REVIEW REQUIRED branches in the bounded action.
 
 ## 6. Revalidate before deletion
 

package/assets/generated/core/core/skills/code-walkthrough/SKILL.md

@@ -58,6 +58,8 @@ Deep    — important methods/blocks, state/data flow, dependencies, edge cases,
 
 Depth may vary by file. Treat trivial configuration lightly unless it materially affects behavior; spend more depth on implementation anchors.
 
+If the human needs to choose a depth, use host-native **single-select structured choice UI** when available. Do not recommend a depth unless the requested learning goal or change complexity clearly supports one; `Focused` is a descriptive default, not permission to manufacture a recommendation.
+
 ## 4. Build the walkthrough plan
 
 Before explaining the first file:
@@ -125,13 +127,15 @@ Group trivial generated/configuration changes when that improves learning, but d
 
 Default to one file or one tightly related file group at a time. Do not dump the whole implementation at once.
 
-At a natural file boundary, show a compact navigation cue such as:
+At a natural file boundary, a compact navigation cue may be shown:
 
 ```text
 NEXT: <suggested file>
 Use: next | deeper | explain this | trace | why this design | diagram | quiz | debug | interview | skip | stop
 ```
 
+When the host exposes structured choice UI and the human is being asked to choose among these navigation actions, prefer a relevant **single-select** subset rather than forcing the human to type a token. Keep free-text commands valid. Do not turn the full command vocabulary into a large mandatory selector when the next action is already obvious.
+
 Interpret these naturally:
 - `next` — continue to the suggested next file;
 - `deeper` — increase depth for the current file/topic;
@@ -185,13 +189,13 @@ When the planned change set is covered or the human stops, summarize:
 - learning gaps or topics worth revisiting,
 - optional next learning actions.
 
-Offer only relevant next choices, such as:
+When offering bounded next actions, use host-native **single-select structured choice UI** when available. Relevant choices may include:
 
-```text
-1. /learning-review <same scope> [READ ONLY]
-2. /coach <specific concept> [READ ONLY]
-3. Return to engineering workflow [NO ACTION]
-4. Stop [NO ACTION]
-```
+- `/learning-review <same scope>` `[READ ONLY]`
+- `/coach <specific concept>` `[READ ONLY]`
+- `Return to engineering workflow` `[NO ACTION]`
+- `Stop` `[NO ACTION]`
+
+Recommend at most one only when the walkthrough evidence shows a clear learning gap or the engineering workflow is clearly the better next step; otherwise present the choices without a recommendation. Use a numbered text menu only when structured choice UI is unavailable.
 
 Do not create a new engineering state such as `CODE_WALKTHROUGH_PENDING`. Walkthrough completion is learning evidence, not a delivery gate.

package/assets/generated/core/core/skills/core-sync/SKILL.md

@@ -94,7 +94,9 @@ If the checkout is dirty, ahead, diverged, intentionally pinned, or ambiguous, p
 
 ## 5. Present one bounded component-sync choice
 
-For a safe local source:
+Use the host-native **single-select structured choice UI** when available because exactly one next action is authorized. In VS Code use the native question surface such as `vscode_askQuestions`. Preserve the consequence labels and show the recommended choice. Use a numbered text list only when structured choice UI is unavailable.
+
+For a safe local source, show the evidence:
 
 ```text
 CORE SYNC READY
@@ -102,13 +104,15 @@ CORE SYNC READY
 Consumer baseline: <commit/version>
 Source: LOCAL <core-path>
 Distribution: <distribution>
-
-1. Sync the component-only Core baseline [GIT + FILE WRITE] — recommended
-2. Keep inspecting only [READ ONLY]
-3. Stop [NO ACTION]
 ```
 
-For a configured remote source:
+Then offer:
+
+- `Sync the component-only Core baseline` `[GIT + FILE WRITE]` — `RECOMMENDED`
+- `Keep inspecting only` `[READ ONLY]`
+- `Stop` `[NO ACTION]`
+
+For a configured remote source, show:
 
 ```text
 CORE SYNC READY
@@ -116,17 +120,19 @@ CORE SYNC READY
 Consumer baseline: <commit/version>
 Source: REMOTE PROVIDER
 Provider: <provider repository>
-
-1. Request remote Core sync [REMOTE WRITE] — recommended
-2. Keep inspecting only [READ ONLY]
-3. Stop [NO ACTION]
 ```
 
+Then offer:
+
+- `Request remote Core sync` `[REMOTE WRITE]` — `RECOMMENDED`
+- `Keep inspecting only` `[READ ONLY]`
+- `Stop` `[NO ACTION]`
+
 The selected choice does not authorize merge, release publication, or deployment.
 
 ## 6. Local component path
 
-After local option 1 is selected:
+After `Sync the component-only Core baseline` is selected:
 
 1. Refresh Core remote state.
 2. Reclassify the accepted/default Core branch.

package/assets/generated/core/core/skills/define-feature/SKILL.md

@@ -63,7 +63,7 @@ Do not create a competing source of truth.
 
 Ask one material question at a time when a real decision is unresolved.
 
-For bounded decisions with a small credible answer space, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md`. Keep initial product/problem framing, desired outcomes, workflows, and other answers that need the human's own wording open-ended rather than constraining them to invented options.
+For bounded decisions with a small credible answer space, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md`. When the host exposes structured choice controls, render mutually exclusive alternatives through single-select UI rather than a plain numbered menu; use multi-select only when several simultaneous selections are actually valid. Keep `Other / specify` or free-text available when choices may be incomplete. Keep initial product/problem framing, desired outcomes, workflows, and other answers that need the human's own wording open-ended rather than constraining them to invented options.
 
 Clarify only what matters, such as:
 - user/engineering outcome,
@@ -123,22 +123,13 @@ If systematic lower-level coverage is valuable, recommend:
 
 ## 7. Guided ending
 
-Use a small evidence-backed menu, for example:
+Use a small evidence-backed set of relevant actions. In VS Code, render them through the host-native **single-select structured choice UI** such as `vscode_askQuestions` when available. Conceptual choices may include:
 
-```text
-CURRENT STATE
-<what is defined and what remains open>
-
-RECOMMENDED NEXT STEP
-<one action and why>
-
-OPTIONS
-1. Review definition [READ ONLY]
-2. Grill unresolved behavior [READ ONLY]
-3. Refine detailed requirements [READ ONLY initially]
-4. Approve requirements/scope when applicable [REQUIREMENTS GATE]
-5. Start work if already ready [READ ONLY]
-6. Stop [NO ACTION]
-```
+- `Review definition` `[READ ONLY]`
+- `Grill unresolved behavior` `[READ ONLY]`
+- `Refine detailed requirements` `[READ ONLY initially]`
+- `Approve requirements/scope` `[REQUIREMENTS GATE]` when applicable
+- `Start work` `[READ ONLY]` when already ready
+- `Stop` `[NO ACTION]`
 
-Only show relevant options. A file-changing choice authorizes only that bounded action/session.
+Make the recommended next action visible when evidence supports one. Use a numbered text menu only when structured choice UI is unavailable. A file-changing choice authorizes only that bounded action/session.

package/assets/generated/core/core/skills/deliver/SKILL.md

@@ -197,7 +197,7 @@ If a Draft PR was required earlier and all readiness conditions are now satisfie
 
 ## 8. Single merge + finalize gate
 
-When PR evidence still matches the accepted implementation and CI/policy are satisfactory, combine final PR acceptance and merge authorization into one meaningful gate:
+When PR evidence still matches the accepted implementation and CI/policy are satisfactory, combine final PR acceptance and merge authorization into one meaningful gate. First show:
 
 ```text
 MERGE READY
@@ -206,13 +206,17 @@ PR CI: GREEN
 Reviewer: READY
 PR diff: matches accepted delivery scope
 Mergeable/policy: <observed state>
-
-1. Merge and finalize delivery [HUMAN ACCEPTANCE + GITHUB/GIT WRITE] — recommended
-2. Review final PR diff first [READ ONLY]
-3. Leave PR open [NO ACTION]
 ```
 
-Selecting option 1 means:
+Then render the mutually exclusive gate through the host-native **single-select structured choice UI** when available. In VS Code use the native question surface such as `vscode_askQuestions`. Offer:
+
+- `Merge and finalize delivery` `[HUMAN ACCEPTANCE + GITHUB/GIT WRITE]` — `RECOMMENDED`
+- `Review final PR diff first` `[READ ONLY]`
+- `Leave PR open` `[NO ACTION]`
+
+Use a numbered text list only when structured choice UI is unavailable.
+
+Selecting `Merge and finalize delivery` means:
 - the human accepts the final PR as observed,
 - merge is authorized using the repository-approved strategy,
 - applicable post-merge default-branch CI/policy may be observed/rechecked automatically,
@@ -247,7 +251,7 @@ Only after configured post-merge default-branch CI and any additional observable
 
 ## 10. Delivered-branch finalization
 
-For a normal short-lived delivered branch, option 1 at the merge gate already authorizes finalization. Do not ask a separate `Delete branch?` question.
+For a normal short-lived delivered branch, the `Merge and finalize delivery` gate choice already authorizes finalization. Do not ask a separate `Delete branch?` question.
 
 Preserve by default:
 - the configured default branch,
@@ -394,4 +398,4 @@ The optional learning handoff does not block or replace deployment readiness whe
 
 `/deliver` takes reviewed/accepted work through routine branch/commit/push/PR/CI mechanics automatically, then stops once for the merge-and-finalize decision. After successful engineering completion it may prepare disposable learning workbenches and shows an optional learning handoff without creating another gate.
 
-`/cleanup-branches` is the standalone preview-first path for accumulated, previously retained, unrelated, or otherwise out-of-band branch housekeeping.
+`/cleanup-branches` is the standalone preview-first path for accumulated, previously retained, unrelated, or otherwise out-of-band branch housekeeping.

package/assets/generated/core/core/skills/deploy/SKILL.md

@@ -33,7 +33,7 @@ Resolve exact configured name, purpose/Production classification, placement, iso
 
 If `demo` exists, `/deploy demo` targets exactly `demo`. If `prod-east` has purpose `production`, `/deploy prod-east` remains a Production deployment even though the literal name differs.
 
-If no environment is named, enumerate configured environments and ask the human to choose; never silently default to Production. The deployment workflow must never fall back to another environment/placement/host/provider because deployment fails.
+If no environment is named, enumerate configured environments and ask the human to choose through host-native **single-select structured choice UI** when available; in VS Code use the native question surface such as `vscode_askQuestions`; never silently default to Production. Do not recommend an environment unless current project evidence or the user's stated deployment goal clearly supports one. The deployment workflow must never fall back to another environment/placement/host/provider because deployment fails.
 
 If the requested environment is missing or ambiguous, route to `/setup` rather than guessing.
 
@@ -73,7 +73,7 @@ immutable application image/release policy
 smoke validation
 ```
 
-When a bounded choice is useful, provide a small recommended menu plus `Other / specify` and `Not sure — recommend one`.
+When a bounded choice is useful, follow `INTERACTIVE_SESSION_GUIDE.md`: use host-native structured choice UI when available, single-select for mutually exclusive values and multi-select only when several simultaneous selections are valid. Keep `Other / specify` or free-text available when the choices may be incomplete. Recommend at most one option, only when evidence or a clear engineering tradeoff supports it, and explain why briefly; otherwise show the choices without a recommendation. Record only the human's selected/confirmed answer.
 
 Once these facts are durably established, later deployments should be routine rather than repeating onboarding.
 

package/assets/generated/core/core/skills/export-requirements/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: export-requirements
+description: "Export the workspace's durable product, domain, UX, roadmap, and approved feature intent into canonical PROJECT_REQUIREMENTS.json without copying stack-specific implementation choices."
+argument-hint: "[review|approve]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Export Project Requirements
+
+`/export-requirements` creates the portable Project Forge requirements interchange artifact:
+
+```text
+PROJECT_REQUIREMENTS.json
+```
+
+It is a derived export of the workspace's existing authorities. It is not a competing requirements database and it never outranks the source Product Brief, Feature Briefs, approved detailed requirements, accepted product/domain decisions, or other repository authorities.
+
+## Purpose
+
+Use this export when the same product/system intent should be carried into a new implementation, especially `/replatform`.
+
+The export answers:
+
+> What must remain true about the product, domain, user experience, roadmap, and accepted cross-cutting behavior independent of this implementation stack?
+
+It must not answer:
+
+> Which framework, language, ORM, build tool, folder layout, or CI implementation should the next repository use?
+
+## Source model
+
+Start from the workspace's declared authority model. In a normal generated Project Forge workspace, inspect as applicable:
+
+1. `docs/product/PRODUCT_BRIEF.md` as product authority;
+2. `docs/product/IMPLEMENTATION_ROADMAP.md` for milestone/feature maturity and product sequencing facts;
+3. Product Feature folders under `docs/work-items/`, including `brief.md` and approved `requirements.md`;
+4. product/domain portions of architecture or system-design documents;
+5. durable domain concepts, relationships, invariants, and business rules;
+6. product-level design principles, accessibility/responsive requirements, and relevant interaction patterns;
+7. accepted ADRs/decisions that constrain product/domain behavior;
+8. approved cross-cutting security/privacy, reliability, performance, and data requirements;
+9. learning goals/future ideas when they are explicitly part of project intent, preserving their non-authorizing status.
+
+Treat summaries such as AI context briefs as reference/navigation unless the repository declares them authoritative.
+
+## Preserve authority and maturity
+
+Do not flatten roadmap maturity.
+
+Preserve distinctions such as:
+
+```text
+V1 / committed / approved
+V2 / planned / roadmap
+V3 / directional / roadmap
+```
+
+A directional Feature remains directional in the export. Exporting it must not promote it into implementation scope.
+
+## Classification
+
+Classify source material before export.
+
+### Preserve
+
+Normally portable:
+
+- product problem, goals, users, outcomes, scope/non-scope;
+- Feature Brief intent and product dependencies;
+- approved functional/domain requirements and acceptance criteria;
+- domain concepts, relationships, invariants, lifecycle/state semantics, business rules;
+- security/privacy outcomes and constraints;
+- accessibility/responsive/product-experience requirements;
+- product-level design principles and interaction intent;
+- milestone/roadmap target and maturity;
+- learning intent when explicitly part of the project.
+
+### Reconcile
+
+Require human review when a durable requirement is mixed with implementation detail, for example:
+
+- API/persistence semantics expressed using a current framework;
+- architecture documents containing both domain invariants and technology topology;
+- ADRs that combine product consequences with stack choices;
+- UX patterns containing both user behavior and component-library detail.
+
+Preserve the durable intent and exclude/rephrase the implementation-specific mechanism.
+
+### Exclude / re-derive
+
+Do not export as portable requirements:
+
+- React, Angular, Blazor, Java, C#, Spring Boot, ASP.NET Core, ORM, package-manager, or build-tool choices unless they are explicitly approved product constraints;
+- source directory/project layout;
+- framework/component-library implementation details;
+- stack-specific Engineering Enablers;
+- CI implementation commands;
+- deployment scripts/bindings/credentials;
+- implementation plans, code, review history, branch/PR/CI evidence;
+- generated Project Forge/Core provenance.
+
+## Artifact state and human gate
+
+Default `/export-requirements` writes or refreshes `PROJECT_REQUIREMENTS.json` with `state: "review"` and exact source repository/commit provenance.
+
+Before calling it approved, present a compact reconciliation summary:
+
+```text
+PROJECT REQUIREMENTS EXPORT
+
+Preserved product/features: ...
+Preserved domain rules: ...
+Preserved UX/cross-cutting constraints: ...
+Roadmap maturity retained: ...
+Implementation-specific material excluded: ...
+Items requiring reconciliation: ...
+
+Approve PROJECT_REQUIREMENTS.json as the portable requirements baseline?
+```
+
+Only explicit human approval may set `state: "approved"`.
+
+`/export-requirements approve` may perform only that bounded finalization after confirming the reviewed content/evidence has not materially changed.
+
+## Safety and scope
+
+The skill may create/update only `PROJECT_REQUIREMENTS.json` unless the human separately authorizes source-document edits.
+
+It must not silently rewrite source Product/Feature Briefs, requirements, architecture, ADRs, roadmap, or design documents to make export easier.
+
+Do not export secrets, credentials, production values, personal runtime data, or machine-local bindings.

package/assets/generated/core/core/skills/grill-with-docs/SKILL.md

@@ -34,7 +34,7 @@ Ask one material question at a time and challenge:
 - architecture/operational tradeoffs,
 - testability.
 
-When the challenge is a bounded decision with a small credible option set, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md` and explain important tradeoffs. When the purpose is to expose or strengthen the human's reasoning, ask open-ended first; introduce options or hints later only when useful as scaffolding.
+When the challenge is a bounded decision with a small credible option set, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md` and explain important tradeoffs. Use host-native single-select UI for mutually exclusive alternatives when available, and multi-select only when several choices may be valid together. When the purpose is to expose or strengthen the human's reasoning, ask open-ended first; introduce options or hints later only when useful as scaffolding.
 
 Cadence:
 
@@ -66,15 +66,13 @@ For local-document models, common homes are:
 
 Invocation alone does not imply broad document-write permission.
 
-When document changes are needed, present a bounded choice such as:
+When document changes are needed, present a bounded **single-select structured choice** through the host UI when available. In VS Code use the native question surface such as `vscode_askQuestions`. Relevant choices are:
 
-```text
-1. Continue grilling only [READ ONLY]
-2. Reconcile resolved decisions during this session [MODIFIES DOCS]
-3. Stop [NO ACTION]
-```
+- `Continue grilling only` `[READ ONLY]`
+- `Reconcile resolved decisions during this session` `[MODIFIES DOCS]`
+- `Stop` `[NO ACTION]`
 
-After option 2 is selected, focused updates to the permitted current work-item documents are authorized for the active session. Do not ask again after each answer.
+Use a numbered text list only when structured choice UI is unavailable. After `Reconcile resolved decisions during this session` is selected, focused updates to the permitted current work-item documents are authorized for the active session. Do not ask again after each answer.
 
 Pause only when a new answer would change higher-level approved scope, contradict another authority/ADR, or require a new cross-cutting decision.