@jskit-ai/jskit-cli 0.2.80 → 0.2.82

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

@@ -12,4 +12,24 @@ Failure output:
 
 {{doctor_output}}
 
-Fix the root cause in this worktree. Do not push, open a PR, merge, or remove the worktree. When the fix is ready, report changed files and verification, then the user will rerun the JSKIT session step.
+Fix the root cause in this worktree. Do not silence the failure or remove checks to make the step pass.
+
+Diagnosis rules:
+
+- Re-read the issue, `issue_details.md`, the active cycle plan file, `agent_decisions.md`, `.jskit/APP_BLUEPRINT.md`, `.jskit/helper-map.md`, check receipts, and UI check receipts before repairing.
+- Identify whether the failure is dependency/setup, JSKIT metadata, generated contract drift, routing/surface wiring, CRUD ownership, UI verification receipt, test-auth, or ordinary application code.
+- Prefer repairing the JSKIT-owned contract or generated metadata over adding local-path hacks.
+- Do not run `npm install` only because optional agent docs are missing. Run installs only when the failure or a JSKIT setup/session step requires dependency repair.
+- If a generator/package command is the correct repair, use the `npx --no-install jskit` command rather than hand-recreating generated structure.
+- For UI receipt failures, run the relevant Playwright check and record it with `npx --no-install jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>` when possible.
+- If login is required, use the app's development auth bootstrap path rather than a live external auth flow.
+
+Do not push, open a PR, merge, or remove the worktree. When the fix is ready, report the root cause, files changed, verification, and anything still unverified. The user or Studio will rerun the JSKIT session step.
+
+If the repair records a meaningful verification decision, tradeoff, missing coverage, or root-cause explanation future steps should know, include concise entries with reasons in this exact marker block:
+
+```text
+[agent_decisions]
+<verification or repair decisions, or "No new decisions.">
+[/agent_decisions]
+```

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

@@ -0,0 +1,61 @@
+Execute the approved implementation plan 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 (`issue_details.md`): {{issue_details_file}}
+Plan file: {{plan_file}}
+Worktree: {{worktree}}
+
+Confirmed issue details:
+
+{{issue_details_text}}
+
+Approved plan:
+
+{{plan_text}}
+
+Implement the plan in the session worktree. Keep the change scoped to the issue, confirmed issue details, and approved plan.
+
+Implementation rules:
+
+- Inspect the current app before editing. App setup has already passed; if required JSKIT app files are missing, report setup failure rather than inventing recovery work.
+- Follow both `{{issue_details_file}}` and `{{plan_file}}`. If they disagree, ask for clarification before changing files.
+- Read `.jskit/helper-map.md` when it exists before creating helpers, composables, service functions, maps, or package glue.
+- Prefer existing JSKIT helpers, app-local helpers, package runtime seams, generated scaffolds, and documented generators over new local helpers.
+- If the plan calls for a generator or package install, use the planned `npx --no-install jskit` command unless inspection proves it does not apply. If you skip a generator, explain the exact gap.
+- For non-CRUD route pages, use `npx --no-install jskit generate ui-generator page ...` when it fits instead of hand-writing both route files and placement entries.
+- For CRUD work, scaffold the server side first with `crud-server-generator` before CRUD UI or CRUD route work.
+- Do not hand-write a separate CRUD migration for a table owned by `crud-server-generator`.
+- Do not hand-build CRUD endpoints or page trees before the server CRUD package and shared resource file exist.
+- Keep direct knex exceptional and minimal. Prefer internal json-rest-api seams outside generated CRUD packages and explicit weird-custom feature lanes.
+- Keep runtime, UI, and data concerns separated.
+- Avoid accidental scope expansion.
+- Do not create old workflow files such as `.jskit/WORKBOARD.md`; the session files and receipts are the workflow record.
+- If user-facing UI changes, bring the screen to Material Design and Vuetify quality before calling it done. Include coherent responsive layout, loading, empty, error, disabled, and success states where relevant.
+- If verification needs login, use the app's local development auth bootstrap path rather than a live external auth login.
+
+After making changes:
+
+- Review for repeated code, unnecessary helpers, fragmented functions, placeholder work, missing states, broken route wiring, ownership mistakes, and weak JSKIT reuse.
+- Run the smallest relevant checks you can run safely in the worktree.
+- For changed user-facing UI, run or clearly identify the Playwright verification path. When possible, record UI verification with `npx --no-install jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>`.
+- Summarize changed files and checks run.
+- If implementation deviated from the approved plan, generator choices, package ownership, helper reuse, UI verification path, or data ownership, include concise decision entries with reasons in this exact marker block:
+
+```text
+[agent_decisions]
+<implementation decisions or "No new decisions.">
+[/agent_decisions]
+```
+
+Do not create commits, branches, issues, pull requests, merges, or worktree cleanup yourself. JSKIT session will handle those steps.
+
+At the very end, include this completion block so Studio knows the step is complete:
+
+[jskit_step_result]
+status: complete
+step: plan_executed
+summary: Short summary of what changed and what was checked.
+[/jskit_step_result]

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

@@ -1,8 +1,10 @@
 Codex thread id: {{codex_thread_id}}
 Issue session status: finished
 PR: {{pr_url}}
+PR outcome: {{pr_outcome}}
+Outcome reason: {{pr_outcome_reason}}
 Local transcript: {{transcript_log}}
 
 Summary:
 
-Session {{session_id}} finished and merged.
+Session {{session_id}} finished with PR outcome `{{pr_outcome}}`.

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,12 +2,43 @@ Create a GitHub issue from this user request:
 
 {{user_input}}
 
-Ask clarifying questions if the request is not specific enough to produce a useful implementation issue.
+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.
 
-When the issue text is ready, output only the final issue body surrounded by these exact markers:
+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 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.
+- For non-CRUD app pages, prefer the JSKIT UI generator when it fits.
+- Keep direct knex or low-level runtime work exceptional and explicitly justified.
+- Do not include workflow bookkeeping such as old workboards in the issue body. JSKIT session state and receipts are the workflow tracker.
+
+Ask concise clarifying questions if the request is not specific enough to produce a useful implementation issue. Ask only for details that materially change the ticket.
+
+When the issue is ready, output only the final issue title and body surrounded by these exact markers:
+
+[issue_title]
+<short issue title>
+[/issue_title]
 
 [issue_text]
-<issue title and body>
+<issue body in Markdown, without repeating the title as a heading>
 [/issue_text]
 
 The issue should be concrete, scoped, and implementation-ready. Include acceptance criteria when they are useful.

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

@@ -0,0 +1,81 @@
+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}}
+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}}
+
+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}}
+
+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:
+
+- package install
+- generator scaffolding
+- custom local code
+- a combination of those
+
+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 `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.
+- If login is required for UI verification, plan for a development-only auth bootstrap path instead of live external auth.
+- Do not create or update the old `.jskit/WORKBOARD.md` workflow. JSKIT session state, receipts, issue text, plan file, transcript, and commits are the tracker.
+
+If setup values are needed, ask plainly using exact env var or option names. For example: DB_NAME, DB_USER, DB_PASSWORD, DB_HOST, DB_PORT, AUTH_SUPABASE_URL, AUTH_SUPABASE_PUBLISHABLE_KEY, APP_PUBLIC_URL.
+
+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 for this cycle and any new decisions surrounded by these exact markers:
+
+[plan]
+<implementation plan in Markdown>
+[/plan]
+
+[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/pr_failure.md

@@ -12,4 +12,17 @@ Failure output:
 
 {{doctor_output}}
 
-Diagnose the failure and fix only what is required in this worktree. Do not push, open a PR, merge, or remove the worktree unless JSKIT Studio explicitly instructs it.
+Diagnose the failure and fix only what is required in this worktree.
+
+Check for:
+
+- missing or wrong GitHub remote
+- missing GitHub auth
+- branch push failure
+- PR body/title issue
+- stale local git state
+- rejected merge or failing required checks
+
+Use repository-portable repairs only. Do not hard-code local paths or credentials. Do not create a parallel manual workflow around the JSKIT session.
+
+Do not push, open a PR, merge, or remove the worktree unless JSKIT Studio or the JSKIT session step explicitly instructs it. Report root cause, changed files, commands run, and remaining risk.

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

@@ -1,22 +1,84 @@
-Review pass {{review_pass}} for session {{session_id}}.
+Review changes for session {{session_id}}.
 
-{{review_pass_note}}
+Review pass: {{review_pass_number}}.
 
-Changed files from the latest commit:
+Changed files in the current session worktree:
 
 {{changed_files}}
 
-Check through the changed code and see if the changes are done without problems:
+Review the current worktree changes, but do not silently fix everything you find unless Studio explicitly asks you to resolve selected findings.
 
-- slop
-- repeated code
-- ownership issues
-- repeated helpers
-- fragmented functions
-- unnecessary complications
-- tricky code
-- missing tests
-- weak verification
-- JSKIT convention violations
+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.
 
-Once you are done, provide a list ordered by priority, with a proposal on how to fix each important issue. If there are no important findings, say so explicitly and list any residual risk.
+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
+   - broken flows, missing route wiring, missing migrations, or stale generated metadata
+   - 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 `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?
+   - is direct app-owned knex usage limited to generated CRUD packages or explicit weird-custom feature lanes?
+   - are surface, route, ownership, package metadata, and migration choices aligned with JSKIT conventions?
+3. UI standards review
+   - user-facing screens follow Material Design and Vuetify best practices
+   - list screens have clear hierarchy, actions, density, empty states, and table/list patterns
+   - view and edit/new screens have clear grouping, labels, helper text, validation, spacing, and action placement
+   - responsive layout, loading, disabled, success, and error states are coherent
+   - improve weak screens before sign-off when the fix is scoped
+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 `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 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,9 +1,27 @@
-User check {{review_pass}} for session {{session_id}}.
+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.
 
-Ask the user to test the changed behavior in the app and report whether it works as intended.
+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:
 
-If the user finds a problem, diagnose it and fix it in this worktree. If the behavior works, tell the user to run:
+npx --no-install jskit session {{session_id}} step --user-check passed
 
-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.