@jskit-ai/jskit-cli 0.2.81 → 0.2.82

package/src/server/sessionRuntime/prompts/issue_details.md

@@ -0,0 +1,52 @@
+Gather exact issue details for JSKIT session {{session_id}}.
+
+GitHub issue: {{issue_url}}
+Issue number: {{issue_number}}
+Issue title: {{issue_title}}
+Issue body file: {{issue_file}}
+Issue details file JSKIT will write after user approval (`issue_details.md`): {{issue_details_file}}
+Worktree: {{worktree}}
+
+This step exists before planning. Do not edit files, create session receipts, create or overwrite the issue details file, create commits, create branches, create issues, create pull requests, merge, or clean worktrees. JSKIT will save the approved details to the issue details file after the user reviews them.
+
+No stones unturned:
+
+- Read the issue and inspect the app enough to understand the implementation surface.
+- Read `.jskit/APP_BLUEPRINT.md` and `.jskit/helper-map.md` when present.
+- Read package.json, `.jskit/lock.json`, `config/public.js`, relevant `src/`, relevant `packages/`, and relevant package docs or `npx --no-install jskit show ... --details`.
+- Ask follow-up questions until all important issue details are known.
+- Ask for final confirmation before emitting final details.
+
+When you are ready to discuss details with the user, output this marker exactly once:
+
+[issue_details_conversation_ready]
+ready
+[/issue_details_conversation_ready]
+
+Then ask the user for whatever is still needed. Do not output the final markers below until the user has confirmed the details.
+
+For CRUD or persisted data, confirm entity/table name, fields, field types, nullability, defaults, uniqueness, indexes, relationships, ownership, allowed operations, list/view/form shape, validation, permissions, migration/generator lane, and exact CRUD generator command or exact reason no CRUD generator applies.
+
+For UI, confirm route path, surface/placement target, navigation expectations, responsive layout, loading/empty/error/disabled/success states, Material/Vuetify expectations, Playwright verification path, and auth/bootstrap strategy if needed.
+
+For server-only work, confirm endpoint/command/job shape, request/response shape, validation, auth/permission behavior, persistence ownership, error behavior, and verification path.
+
+For package/generator work, confirm exact `npx --no-install jskit add` or `npx --no-install jskit generate` command, why it applies, expected generated files, and follow-up custom code areas.
+
+When the details are confirmed, output only the final classification, details, and decision notes surrounded by these exact markers:
+
+[issue_category]
+<client | server | client_server | tooling | unknown>
+[/issue_category]
+
+[ui_impact]
+<none | possible | definite | unknown>
+[/ui_impact]
+
+[issue_details]
+<confirmed issue details in Markdown>
+[/issue_details]
+
+[agent_decisions]
+<concise decision entries with reasons>
+[/agent_decisions]

package/src/server/sessionRuntime/prompts/new_issue.md

@@ -2,13 +2,26 @@ Create a GitHub issue from this user request:
 
 {{user_input}}
 
-First inspect the local app enough to understand the request in context. Use package.json, config, .jskit metadata, routes, packages, and any saved app blueprint when available. Classify the current app state as empty, non_jskit_repo, partial_jskit_app, or jskit_app before assuming ordinary feature work is possible.
+First inspect the local app enough to understand the request in context. App setup has already passed before this prompt is rendered; treat this as a ready JSKIT app. This issue-drafting step is read-only.
+
+Allowed inspection:
+
+- Read files with commands such as `pwd`, `ls`, `find`, `rg`, `cat`, `sed`, and `git status`.
+- Read package.json, `.jskit/lock.json`, config, routes, packages, source files, `.jskit/APP_BLUEPRINT.md`, and `.jskit/helper-map.md` when available.
+- Use non-mutating JSKIT inspection commands when available and relevant: `npx --no-install jskit list`, `npx --no-install jskit show <package> --details`, and `npx --no-install jskit list-placements`.
+- If the filesystem contradicts a ready JSKIT app, stop and report that app setup must be rerun. Do not draft a recovery issue inside this session.
+
+Do not run workflow, repair, or mutation commands during issue drafting:
+
+- Do not run `npx --no-install jskit session`, `npx --no-install jskit session step`, or any command that advances a JSKIT session.
+- Do not run `gh`, `git add`, `git commit`, `git push`, `npm install`, generators, tests, verification, devlinks, or doctor commands.
+- Do not try to fix missing PATH entries or missing command shims. If a tool is unavailable, continue with read-only file inspection.
+- Do not edit files.
 
 Draft an implementation-ready issue, not a broad product essay.
 
 Preserve these JSKIT boundaries:
 
-- If the app is empty or a partial JSKIT app, the issue should be about bootstrap or recovery before feature implementation.
 - If platform choices are still provisional, make the issue resolve those choices before installing tenancy-sensitive packages.
 - Do not ask the developer to redesign standard JSKIT package-owned workflows from scratch. Treat selected package workflows as defaults unless the request asks for overrides, restrictions, or custom additions.
 - For persisted app-owned data, prefer generated/package ownership over direct hand-built persistence. A new ordinary table should usually become a server CRUD-owned entity before CRUD UI or route work.

package/src/server/sessionRuntime/prompts/plan_issue.md

@@ -1,18 +1,43 @@
 Create an implementation plan for JSKIT session {{session_id}}.
 
+Active cycle: {{active_cycle}}
+Plan source: {{plan_source}}
+
 GitHub issue: {{issue_url}}
 Issue number: {{issue_number}}
 Issue title: {{issue_title}}
 Issue body file: {{issue_file}}
 Issue title file: {{issue_title_file}}
-Plan file to create: {{plan_file}}
+Issue details file (`issue_details.md`): {{issue_details_file}}
+Agent decisions file (`agent_decisions.md`): {{agent_decisions_file}}
+App blueprint file (`.jskit/APP_BLUEPRINT.md`): {{app_blueprint_file}}
+Plan file JSKIT will write after user approval: {{plan_file}}
 Worktree: {{worktree}}
 
-Read the issue and inspect the local app before planning. Use the issue files, package.json, .jskit metadata, config, packages, routes, generated references, package docs, and any saved app blueprint when available.
+This planning step is read-only. Do not edit files, create session receipts, create or overwrite the plan file, create commits, create branches, create issues, create pull requests, merge, or clean worktrees. JSKIT will save the approved plan to the plan file after the user reviews it.
+
+If Plan source is `issue`, create the plan from the issue and confirmed issue details.
+
+If Plan source is `rework`, create a revised plan from the user's rework request for this cycle. Preserve the original issue constraints, but focus the plan on fixing the reported problem.
+
+Rework request file: {{rework_request_file}}
+
+Rework request:
+
+{{rework_request}}
 
-Start by identifying the app state and the implementation lane:
+Read the issue, confirmed issue details, rework request when present, agent decisions, and local app before planning. Use the issue files, issue details file, package.json, .jskit metadata, config, packages, routes, generated references, package docs, any saved app blueprint, and `.jskit/helper-map.md` when available.
+
+Confirmed issue details:
+
+{{issue_details_text}}
+
+Known decisions:
+
+{{agent_decisions_text}}
+
+Start by identifying the implementation lane:
 
-- empty, non_jskit_repo, partial_jskit_app, or jskit_app
 - package install
 - generator scaffolding
 - custom local code
@@ -21,16 +46,18 @@ Start by identifying the app state and the implementation lane:
 Planning rules:
 
 - Keep the plan scoped to the issue. Avoid "while I am here" work.
+- Follow the confirmed issue details and preserve the issue category and UI impact in the plan. If details are insufficient, say exactly what is missing instead of inventing foundational details.
 - Prefer vertical slices that produce visible or end-to-end progress.
 - If the work is too broad to review confidently, split it into clear chunks.
-- Make generator decisions concrete. Name the exact `jskit` commands to run when a generator or package install applies.
-- For non-CRUD route page work, plan to check `jskit show ui-generator --details` and `jskit list-placements` before hand-writing pages or placement entries.
-- For CRUD work, plan server ownership first. Name the `jskit generate crud-server-generator scaffold ...` command before any CRUD UI plan.
+- Make generator decisions concrete. Name the exact `npx --no-install jskit` commands to run when a generator or package install applies.
+- For non-CRUD route page work, plan to check `npx --no-install jskit show ui-generator --details` and `npx --no-install jskit list-placements` before hand-writing pages or placement entries.
+- For CRUD work, plan server ownership first. Name the `npx --no-install jskit generate crud-server-generator scaffold ...` command before any CRUD UI plan.
 - For CRUD-owned tables, plan around the real database table shape. Do not plan a separate hand-written migration for a table that `crud-server-generator` will own.
 - Every persisted app-owned table should have generated/package CRUD ownership unless there is a narrow explicit exception.
 - Do not hand-build CRUD routes, CRUD endpoints, or CRUD page trees before the server CRUD package and shared resource file exist.
 - `feature-server-generator` is for non-CRUD workflows and orchestration, not ordinary persisted entity tables.
 - Keep runtime, UI, and data concerns separated.
+- Before planning new helpers, composables, service functions, maps, or package glue, check `.jskit/helper-map.md` when it exists and prefer existing entries.
 - Keep direct knex exceptional and minimal. Prefer internal json-rest-api seams outside generated CRUD packages and explicit weird-custom feature lanes.
 - For package-owned baseline workflows, plan to install and verify the baseline before inventing custom code around it.
 - For user-facing UI, include Material/Vuetify quality expectations and a Playwright verification path.
@@ -41,10 +68,14 @@ If setup values are needed, ask plainly using exact env var or option names. For
 
 If the issue is not clear enough to plan safely, ask the user concise follow-up questions first.
 
-When the plan is ready, output only the final plan surrounded by these exact markers:
+When the plan is ready, output only the final plan for this cycle and any new decisions surrounded by these exact markers:
 
 [plan]
 <implementation plan in Markdown>
 [/plan]
 
-Keep the plan concrete and implementation-oriented. Include the likely files or areas to touch, ordered steps, generator commands to consider, review expectations, and checks that should be run.
+[agent_decisions]
+<new planning decisions with reasons, or "No new decisions.">
+[/agent_decisions]
+
+Keep the plan concrete and implementation-oriented. Include the issue category, UI impact, likely files or areas to touch, ordered steps, generator commands to consider, review expectations, and checks that should be run.

package/src/server/sessionRuntime/prompts/review_changes.md

@@ -1,16 +1,31 @@
 Review changes for session {{session_id}}.
 
-Changed files from the latest commit:
+Review pass: {{review_pass_number}}.
+
+Changed files in the current session worktree:
 
 {{changed_files}}
 
-Review the committed changes and fix important issues in this worktree when the fix is clear and scoped.
+Review the current worktree changes, but do not silently fix everything you find unless Studio explicitly asks you to resolve selected findings.
+
+First, inspect the worktree and produce a short, prioritized list of important findings. The answer should be conversational and useful for the user to read. End every review answer with one small machine-readable `[deslop_result]` block so Studio can decide whether to automate another pass.
+
+Use priorities this way:
+
+- `high`: correctness, broken flow, data loss, security, route/runtime breakage, or serious JSKIT ownership/generator mistake.
+- `medium`: maintainability, meaningful duplication, missing required state, weak JSKIT reuse, important verification gap, or visible UI quality issue inside the requested scope.
+- `low`: polish, optional cleanup, copy tuning, minor test expansion, or judgment-call improvements the user should decide on.
+
+If Studio later sends a `[resolve_deslop_findings]` block, fix only the listed findings in the current worktree. After fixing them, summarize what changed and wait for the next review prompt.
+
+If there are no important findings, say so explicitly and do not make cosmetic churn.
 
 Use four passes:
 
 1. Deslop review
    - repeated functions or duplicated local helpers
    - helpers reimplemented locally when a kernel/runtime seam already exists
+   - helpers reimplemented locally when `.jskit/helper-map.md` already lists a usable app-local helper or JSKIT export
    - placeholder, fake-complete, or vague UI/copy/code structure
    - dead code, unused props/imports, TODO-shaped gaps, or accidental abstractions
    - missing loading, empty, error, permission, or ownership states
@@ -18,8 +33,9 @@ Use four passes:
    - surface or entity ownership mistakes: public, user, workspace, workspace_user
 2. JSKIT review
    - existing helper/runtime seam available?
+   - was `.jskit/helper-map.md` checked before introducing helper-like code?
    - should this have been a package install, generator step, or scaffold extension instead of hand code?
-   - if a generator existed, was the exact `jskit` command used or was the gap documented?
+   - if a generator existed, was the exact `npx --no-install jskit` command used or was the gap documented?
    - for CRUD work, was `crud-server-generator scaffold` used before CRUD UI or CRUD route hand-coding?
    - for CRUD-owned tables, did the change avoid a separate hand-written CRUD migration?
    - does every live app-owned table have generated/package CRUD ownership or a narrow explicit exception?
@@ -34,10 +50,35 @@ Use four passes:
 4. Verification review
    - run the smallest relevant verification commands for the changed scope
    - any changed user-facing UI should be exercised with Playwright when possible
-   - UI verification should normally be recorded through `jskit app verify-ui`
+   - UI verification should normally be recorded through `npx --no-install jskit app verify-ui`
    - if login is required, use the chosen local test-auth path instead of live external auth
    - if there is no usable local auth bootstrap path, record it as a blocking testability gap
 
 Do not create commits, branches, pull requests, merges, or worktree cleanup yourself. JSKIT session owns those steps.
 
-When finished, report findings ordered by severity, fixes made, changed files, checks run, and anything still unverified. If there are no important findings, say so explicitly and list residual risk.
+When finished, report the findings considered, fixes made during this pass if any, changed files, checks run, and anything still unverified. If there are no important findings, say so explicitly and list residual risk.
+
+At the very end of each review answer, include this block. Keep it plain text, not JSON:
+
+[deslop_result]
+priority: high | medium | low
+category: bug | maintainability | jskit | ui | verification | content | other
+title: Short finding title
+files:
+- path/to/file
+reason: Why this matters
+recommended_action: What should be done
+
+priority: low
+category: other
+title: Another optional finding
+files:
+- path/to/file
+reason: Why this is optional
+recommended_action: What the user may choose to do
+[/deslop_result]
+
+If there are no findings, return an empty result block:
+
+[deslop_result]
+[/deslop_result]

package/src/server/sessionRuntime/prompts/update_blueprint.md

@@ -0,0 +1,36 @@
+Update the durable JSKIT app blueprint for session {{session_id}}.
+
+GitHub issue: {{issue_url}}
+Issue number: {{issue_number}}
+Issue title: {{issue_title}}
+Issue body file: {{issue_file}}
+Issue details file (`issue_details.md`): {{issue_details_file}}
+Plan file: {{plan_file}}
+Agent decisions file (`agent_decisions.md`): {{agent_decisions_file}}
+Current blueprint file (`.jskit/APP_BLUEPRINT.md`): {{app_blueprint_file}}
+Worktree: {{worktree}}
+
+Use the accepted issue work to update only durable app/product/architecture memory. Read the current blueprint when present, issue title/body, issue details, approved plan, agent decisions, helper map, package/app metadata, and changed files.
+
+Changed files since the session base:
+
+{{changed_files}}
+
+Rules:
+
+- Do not use this as task tracking.
+- Do not recreate `.jskit/WORKBOARD.md`.
+- Do not over-expand tiny issues into broad product rewrites.
+- Preserve useful existing blueprint content.
+- If `.jskit/APP_BLUEPRINT.md` does not exist, create it.
+- Edit `.jskit/APP_BLUEPRINT.md` directly in the worktree.
+- Add durable facts, architecture decisions, surfaces, routes, data ownership, package choices, and verification-relevant app behavior that future sessions should know.
+- Keep the result concise enough to remain useful over many issues.
+- Do not edit files other than `.jskit/APP_BLUEPRINT.md`.
+- Do not commit, branch, push, create PRs, merge, or clean up worktrees.
+
+When finished, summarize the blueprint result normally, then end with this exact marker:
+
+[jskit_step_result]
+Blueprint updated.
+[/jskit_step_result]

package/src/server/sessionRuntime/prompts/user_check.md

@@ -1,13 +1,27 @@
 User check for session {{session_id}}.
 
+Issue: {{issue_url}}
+Issue title: {{issue_title}}
+Issue body file: {{issue_file}}
+Issue details file (`issue_details.md`): {{issue_details_file}}
+Plan file: {{plan_file}}
+
 The code should already be built or runnable according to the implementation instructions.
 
+Confirmed issue details:
+
+{{issue_details_text}}
+
+Approved plan:
+
+{{plan_text}}
+
 Ask the user to test the changed behavior in the app and report whether it works as intended. Be specific about the user-visible behavior, route, command, or workflow to inspect.
 
 If the user finds a problem, diagnose the root cause and fix it in this worktree. Keep the fix scoped. Reuse JSKIT helpers, generated seams, and package workflows where they apply.
 
 If the behavior works, tell the user to run:
 
-jskit session {{session_id}} step --user-check passed
+npx --no-install jskit session {{session_id}} step --user-check passed
 
 Do not commit, push, create a PR, merge, or clean up the worktree yourself. JSKIT session owns those steps.