@jskit-ai/jskit-cli 0.2.85 → 0.2.87

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.85",
+  "version": "0.2.87",
   "description": "Bundle and package orchestration CLI for JSKIT apps.",
   "type": "module",
   "files": [
@@ -20,9 +20,9 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/jskit-catalog": "0.1.84",
-    "@jskit-ai/kernel": "0.1.76",
-    "@jskit-ai/shell-web": "0.1.75",
+    "@jskit-ai/jskit-catalog": "0.1.86",
+    "@jskit-ai/kernel": "0.1.78",
+    "@jskit-ai/shell-web": "0.1.77",
     "@vue/compiler-sfc": "^3.5.29",
     "ts-morph": "^28.0.0"
   },

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

@@ -13,7 +13,8 @@ Run the command in the session worktree. If it fails, diagnose the root cause, f
 Rules:
 
 - Fix the underlying cause. Do not remove checks, weaken verification, or hide failures to make the command pass.
-- Prefer JSKIT-owned helpers, generators, package seams, and documented commands over local hacks.
+- Prefer JSKIT-owned helpers, generators, package seams, agent docs, package descriptors, and documented commands over local hacks.
+- If a failure involves JSKIT architecture, generator ownership, CRUD, surfaces, placements, client/server contracts, or UI verification, read the relevant docs under `node_modules/@jskit-ai/agent-docs/` or `packages/agent-docs/` before repairing it.
 - Use `npx --no-install jskit ...` for JSKIT CLI commands you run directly from the shell.
 - Keep fixes scoped to the current issue, issue details, and active plan.
 - Do not create commits, branches, issues, pull requests, merges, or worktree cleanup. JSKIT session owns those steps.

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

@@ -16,6 +16,8 @@ Changed files since the session base:
 
 Run a focused UI quality pass for the current worktree. If this is not UI-impacting after inspection, say exactly why and do not edit files. If the issue touches UI, inspect the changed routes, views, components, placements, layouts, and styles.
 
+Before changing user-facing JSKIT UI, read the relevant JSKIT agent docs when available: `node_modules/@jskit-ai/agent-docs/patterns/ui-testing.md`, `node_modules/@jskit-ai/agent-docs/patterns/page-scaffolding.md`, `node_modules/@jskit-ai/agent-docs/patterns/placements.md`, and `node_modules/@jskit-ai/agent-docs/patterns/surfaces.md`. If working inside the JSKIT monorepo or a devlinked sibling, use the equivalent `packages/agent-docs/...` paths.
+
 Check:
 
 - Material Design quality.

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

@@ -22,6 +22,8 @@ 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.
+- Before implementing JSKIT app structure, generators, CRUD, surfaces, placements, app setup, package-owned workflows, or UI verification paths, read the relevant JSKIT agent docs. Start with `node_modules/@jskit-ai/agent-docs/DISTR_AGENT.md`, `node_modules/@jskit-ai/agent-docs/guide/agent/index.md`, and `node_modules/@jskit-ai/agent-docs/patterns/INDEX.md` when present. If working inside the JSKIT monorepo or a devlinked sibling, use `packages/agent-docs/...` as the source-tree equivalent.
+- Read specific pattern docs before touching their lane, such as CRUD scaffolding/repository mapping, page scaffolding, surfaces, placements, client requests, live actions, generated UI contract tracking, and UI testing. Prefer these docs and package descriptors over reverse-engineering framework rules from source 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.

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

@@ -14,6 +14,7 @@ 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`.
+- Read JSKIT agent docs before inferring framework patterns from source. Start with `node_modules/@jskit-ai/agent-docs/DISTR_AGENT.md`, `node_modules/@jskit-ai/agent-docs/guide/agent/index.md`, and `node_modules/@jskit-ai/agent-docs/patterns/INDEX.md` when present. If working inside the JSKIT monorepo or a devlinked sibling, use `packages/agent-docs/...` as the source-tree equivalent. Then read the specific pattern docs that match the issue: CRUD, page scaffolding, surfaces, placements, client requests, live actions, generated UI contracts, or UI testing.
 - Ask follow-up questions until all important issue details are known.
 - Ask the user for whatever is still needed.
 - Ask for final confirmation before emitting final details.
@@ -27,6 +28,8 @@ For server-only work, confirm endpoint/command/job shape, request/response shape
 
 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 source files and docs appear to disagree, ask or record the discrepancy. Do not silently prefer code archaeology over package-owned JSKIT guide and pattern docs.
+
 When the details are confirmed, output only the final classification, details, and decision notes surrounded by these exact markers:
 
 [issue_category]

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

@@ -9,6 +9,7 @@ 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`.
+- Read JSKIT agent docs before inferring framework patterns from source. Start with `node_modules/@jskit-ai/agent-docs/DISTR_AGENT.md`, `node_modules/@jskit-ai/agent-docs/guide/agent/index.md`, and `node_modules/@jskit-ai/agent-docs/patterns/INDEX.md` when present. If working inside the JSKIT monorepo or a devlinked sibling, use `packages/agent-docs/...` as the source-tree equivalent. Then read only the relevant pattern docs for the request, such as CRUD, page scaffolding, surfaces, placements, client requests, live actions, or UI testing.
 - 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:
@@ -27,6 +28,7 @@ Preserve these JSKIT boundaries:
 - 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.
+- Prefer documented JSKIT guide and pattern docs over reverse-engineering framework architecture from source files. Use source inspection to understand this app and verify details, not as the first source of JSKIT design rules.
 - 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.

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

@@ -28,6 +28,10 @@ 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.
 
+Before deriving JSKIT architecture from source files, read the package-owned agent docs that apply to this work. Start with `node_modules/@jskit-ai/agent-docs/DISTR_AGENT.md`, `node_modules/@jskit-ai/agent-docs/guide/agent/index.md`, and `node_modules/@jskit-ai/agent-docs/patterns/INDEX.md` when present. If the worktree is the JSKIT monorepo or a devlinked sibling, use the equivalent `packages/agent-docs/...` paths. Then read the specific pattern docs needed for the lane, such as `patterns/crud-scaffolding.md`, `patterns/crud-repository-mapping.md`, `patterns/page-scaffolding.md`, `patterns/placements.md`, `patterns/surfaces.md`, `patterns/client-requests.md`, `patterns/live-actions.md`, `patterns/generated-ui-contract-tracking.md`, or `patterns/ui-testing.md`.
+
+If these docs are unavailable, continue with app inspection and say that the agent docs were unavailable. Do not compensate by inventing framework rules from isolated source files.
+
 Confirmed issue details:
 
 {{issue_details_text}}
@@ -50,6 +54,7 @@ Planning rules:
 - 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.
+- Base JSKIT lane and generator decisions on the agent docs and package descriptors first, then verify against the local codebase.
 - 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.

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

@@ -32,6 +32,7 @@ Use four passes:
    - broken flows, missing route wiring, missing migrations, or stale generated metadata
    - surface or entity ownership mistakes: public, user, workspace, workspace_user
 2. JSKIT review
+   - were relevant `@jskit-ai/agent-docs` guide or pattern docs consulted before inferring JSKIT architecture from source?
    - 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?

package/src/server/sessionRuntime.js

@@ -480,6 +480,20 @@ async function runSessionFinalizationGuard(paths, preconditions = []) {
   });
 }
 
+async function runSessionProvisioningHook(paths, {
+  preferredPackageManager = "",
+  preconditions = []
+} = {}) {
+  return runOptionalSessionPackageScript(paths, {
+    failureCode: "session_provision_failed",
+    failureMessage: `${SESSION_PROVISION_PACKAGE_SCRIPT} failed in the session worktree.`,
+    kind: "session_provision",
+    preferredPackageManager,
+    preconditions,
+    scriptName: SESSION_PROVISION_PACKAGE_SCRIPT
+  });
+}
+
 async function readIssueMetadata(paths) {
   const source = await readTextIfExists(path.join(paths.sessionRoot, "issue_metadata.json"));
   if (!source) {
@@ -945,13 +959,9 @@ async function installDependencies(paths, _options = {}, context = {}) {
       preconditions
     });
   }
-  const provisionResult = await runOptionalSessionPackageScript(paths, {
-    failureCode: "session_provision_failed",
-    failureMessage: `${SESSION_PROVISION_PACKAGE_SCRIPT} failed in the session worktree.`,
-    kind: "session_provision",
+  const provisionResult = await runSessionProvisioningHook(paths, {
     preferredPackageManager: command,
-    preconditions,
-    scriptName: SESSION_PROVISION_PACKAGE_SCRIPT
+    preconditions
   });
   if (!provisionResult.ok) {
     return provisionResult.response;
@@ -969,6 +979,7 @@ async function adoptDependenciesInstalled({
   message = ""
 } = {}) {
   return withExistingSession({ targetRoot, sessionId }, async (paths, context = {}) => {
+    const preconditions = context.preconditions || [];
     const artifacts = await readSessionArtifacts(paths);
     if (artifacts.nextStep !== "dependencies_installed") {
       return buildSessionResponse(paths, {
@@ -979,12 +990,21 @@ async function adoptDependenciesInstalled({
             message: `Cannot record dependencies for ${paths.sessionId}; current step is ${artifacts.nextStep || "complete"}.`
           })
         ],
-        preconditions: context.preconditions || []
+        preconditions
       });
     }
+    const provisionResult = await runSessionProvisioningHook(paths, {
+      preconditions
+    });
+    if (!provisionResult.ok) {
+      return provisionResult.response;
+    }
+    const receiptMessage = provisionResult.ran
+      ? `${normalizeText(message) || "Installed Node dependencies in the session worktree."}\n${SESSION_PROVISION_PACKAGE_SCRIPT} completed.`
+      : message;
     return recordDependenciesInstalled(paths, {
-      message,
-      preconditions: context.preconditions || []
+      message: receiptMessage,
+      preconditions
     });
   });
 }