@jskit-ai/jskit-cli 0.2.81 → 0.2.82

package/src/server/sessionRuntime/constants.js

@@ -13,7 +13,19 @@ const SESSION_STATUS = Object.freeze({
 
 const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}(?:-[a-z0-9]{4})?$/u;
 const SESSION_STATE_RELATIVE_PATH = ".jskit/sessions";
+const SESSION_WORKFLOW_VERSION = "6";
+const REVIEW_PASS_LIMIT = 0;
 const PROMPT_DIRECTORY = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "prompts");
+const JSKIT_CLI_SHELL_COMMAND = "npx --no-install jskit";
+const JSKIT_CLI_SHELL_RULE = [
+  "Shell command rule:",
+  "",
+  `- When running JSKIT CLI commands from the shell, use \`${JSKIT_CLI_SHELL_COMMAND} ...\`.`,
+  "- Do not run bare `jskit ...` unless you are inside an npm script where `node_modules/.bin` is on PATH.",
+  "- Do not run `npx jskit ...` without `--no-install`; it may fetch packages instead of using this app's installed CLI.",
+  "- If `npx --no-install jskit ...` is unavailable, continue with filesystem inspection when possible and report that the local JSKIT CLI is missing."
+].join("\n");
+const DEFAULT_NEXT_COMMAND_TEMPLATE = `${JSKIT_CLI_SHELL_COMMAND} session {{session_id}} step`;
 
 const INPUT_NONE = Object.freeze({ type: "none" });
 const ISSUE_TITLE_INPUT = Object.freeze({
@@ -72,6 +84,50 @@ const PLAN_OUTPUT = Object.freeze({
   multiline: true,
   required: true
 });
+const ISSUE_DETAILS_INPUT = Object.freeze({
+  extract: "issue_details",
+  formatHint: "markdown",
+  label: "Confirmed issue details",
+  multiline: true,
+  name: "issueDetails",
+  required: true,
+  type: "text"
+});
+const ISSUE_DETAILS_OUTPUT = Object.freeze({
+  extract: "issue_details",
+  field: "issueDetails",
+  formatHint: "markdown",
+  label: "Issue details",
+  multiline: true,
+  required: true
+});
+const ISSUE_CATEGORY_OUTPUT = Object.freeze({
+  extract: "issue_category",
+  field: "issueCategory",
+  formatHint: "text",
+  label: "Issue category",
+  options: Object.freeze([
+    Object.freeze({ label: "Client", value: "client" }),
+    Object.freeze({ label: "Server", value: "server" }),
+    Object.freeze({ label: "Client and server", value: "client_server" }),
+    Object.freeze({ label: "Tooling", value: "tooling" }),
+    Object.freeze({ label: "Unknown", value: "unknown" })
+  ]),
+  required: true
+});
+const UI_IMPACT_OUTPUT = Object.freeze({
+  extract: "ui_impact",
+  field: "uiImpact",
+  formatHint: "text",
+  label: "UI impact",
+  options: Object.freeze([
+    Object.freeze({ label: "No UI impact", value: "none" }),
+    Object.freeze({ label: "Possible UI impact", value: "possible" }),
+    Object.freeze({ label: "Definite UI impact", value: "definite" }),
+    Object.freeze({ label: "Unknown", value: "unknown" })
+  ]),
+  required: true
+});
 const USER_CHECK_INPUT = Object.freeze({
   label: "User check result",
   name: "userCheck",
@@ -99,11 +155,31 @@ function codexHandoff(expectedOutput, {
 
 const PLAN_EXECUTION_CODEX_HANDOFF = codexHandoff([], {
   autoInject: true,
-  promptActionLabel: "Execute plan"
+  promptActionLabel: "Get Codex to execute plan"
+});
+const ISSUE_DETAILS_CODEX_HANDOFF = codexHandoff([
+  ISSUE_CATEGORY_OUTPUT,
+  UI_IMPACT_OUTPUT,
+  ISSUE_DETAILS_OUTPUT
+], {
+  autoInject: true,
+  promptActionLabel: "Start details conversation"
 });
 const REVIEW_EXECUTION_CODEX_HANDOFF = codexHandoff([], {
   autoInject: true,
-  promptActionLabel: "Start review"
+  promptActionLabel: "Run deslop"
+});
+const DEEP_UI_CHECK_CODEX_HANDOFF = codexHandoff([], {
+  autoInject: true,
+  promptActionLabel: "Run Deep UI check"
+});
+const AUTOMATED_CHECK_REPAIR_CODEX_HANDOFF = codexHandoff([], {
+  autoInject: true,
+  promptActionLabel: "Run automated checks"
+});
+const BLUEPRINT_CODEX_HANDOFF = codexHandoff([], {
+  autoInject: true,
+  promptActionLabel: "Update blueprint"
 });
 
 function defineStep({
@@ -114,20 +190,26 @@ function defineStep({
   input = INPUT_NONE,
   kind = "automatic",
   label,
-  nextCommandTemplate = "jskit session {{session_id}} step",
+  nextCommandTemplate = DEFAULT_NEXT_COMMAND_TEMPLATE,
   preconditions = [],
-  utilityActions = []
+  requiresExplicitRun = false,
+  utilityActions = [],
+  displayGroupId = "",
+  displayGroupLabel = ""
 }) {
   return Object.freeze({
     buttonLabel,
     codex,
     description,
+    displayGroupId,
+    displayGroupLabel,
     id,
     input,
     kind,
     label,
     nextCommandTemplate,
     preconditions: Object.freeze([...preconditions]),
+    requiresExplicitRun,
     utilityActions: Object.freeze([...utilityActions])
   });
 }
@@ -135,27 +217,27 @@ function defineStep({
 const STEP_DEFINITIONS = Object.freeze([
   defineStep({
     buttonLabel: "Create session",
-    description: "Create the filesystem-backed session record.",
+    description: "JSKIT creates the filesystem-backed session record and initial receipt.",
     id: "session_created",
     label: "Session created"
   }),
   defineStep({
     buttonLabel: "Create worktree",
-    description: "Create the isolated branch and worktree for this session.",
+    description: "JSKIT creates the isolated Git branch and session worktree where Codex will work.",
     id: "worktree_created",
     label: "Worktree created",
     preconditions: ["session_exists", "git_repository", "git_current_branch"]
   }),
   defineStep({
     buttonLabel: "Install dependencies",
-    description: "Install Node dependencies inside the session worktree before Codex starts.",
+    description: "JSKIT installs Node dependencies inside the session worktree before Codex starts.",
     id: "dependencies_installed",
     label: "Dependencies installed",
     preconditions: ["session_exists", "worktree_exists"]
   }),
   defineStep({
-    buttonLabel: "Submit prompt to Codex",
-    description: "Capture the initial change request and send it to Codex to draft a GitHub issue.",
+    buttonLabel: "Set initial prompt",
+    description: "User describes the requested change; JSKIT records it and prepares the Codex issue-drafting prompt.",
     id: "issue_prompt_rendered",
     input: Object.freeze({
       label: "What should change?",
@@ -167,129 +249,168 @@ const STEP_DEFINITIONS = Object.freeze([
     }),
     kind: "human_input",
     label: "Initial issue prompt",
-    nextCommandTemplate: "jskit session {{session_id}} step --prompt \"<what should change>\"",
-    preconditions: ["session_exists"]
+    nextCommandTemplate: `${JSKIT_CLI_SHELL_COMMAND} session {{session_id}} step --prompt "<what should change>"`,
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app"]
   }),
   defineStep({
-    buttonLabel: "Save issue draft",
+    buttonLabel: "Finalise issue",
     codex: codexHandoff([
       ISSUE_TITLE_OUTPUT,
       ISSUE_TEXT_OUTPUT
-    ]),
-    description: "Save the approved issue title and body drafted by Codex.",
+    ], {
+      autoInject: true,
+      promptActionLabel: "Get Codex to create issue text"
+    }),
+    description: "Codex drafts the issue title and body; user reviews or edits them; JSKIT saves the approved draft.",
     id: "issue_drafted",
     input: ISSUE_DRAFT_INPUT,
     kind: "codex_output",
     label: "Issue drafted",
-    nextCommandTemplate: "jskit session {{session_id}} step --issue -",
-    preconditions: ["session_exists"]
+    nextCommandTemplate: `${JSKIT_CLI_SHELL_COMMAND} session {{session_id}} step --issue -`,
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app"]
   }),
   defineStep({
-    buttonLabel: "Create GitHub issue",
-    description: "Create the GitHub issue from the approved draft.",
+    buttonLabel: "Create issue",
+    description: "JSKIT creates the GitHub issue from the approved draft and records the issue URL.",
     id: "issue_created",
     label: "Issue created",
-    preconditions: ["session_exists", "issue_text_exists", "github_auth", "github_origin"]
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_text_exists", "github_auth", "github_origin"],
+    requiresExplicitRun: false
   }),
   defineStep({
-    buttonLabel: "Execute plan",
-    codex: codexHandoff(PLAN_OUTPUT),
-    description: "Save the approved implementation plan, comment it on the GitHub issue, and submit it to Codex.",
+    buttonLabel: "Save issue details",
+    codex: ISSUE_DETAILS_CODEX_HANDOFF,
+    description: "Codex finalises with user issue details and classification; user reviews or edits final outcome; JSKIT saves the confirmed details.",
+    displayGroupId: "issue_details",
+    displayGroupLabel: "Get issue details",
+    id: "issue_details_gathered",
+    input: ISSUE_DETAILS_INPUT,
+    kind: "codex_output",
+    label: "Issue details gathered",
+    nextCommandTemplate: `${JSKIT_CLI_SHELL_COMMAND} session {{session_id}} step --issue-details -`,
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_text_exists", "issue_url_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Save plan",
+    codex: codexHandoff(PLAN_OUTPUT, {
+      autoInject: true,
+      promptActionLabel: "Get Codex to create plan"
+    }),
+    description: "Codex writes an implementation plan for the active cycle; cycle 001 plans from the issue, later cycles plan from user rework notes.",
     id: "plan_made",
     input: PLAN_INPUT,
     kind: "codex_output",
-    label: "Plan execution",
-    nextCommandTemplate: "jskit session {{session_id}} step --plan -",
-    preconditions: ["session_exists", "issue_text_exists", "issue_url_exists", "worktree_exists"]
+    label: "Plan made",
+    nextCommandTemplate: `${JSKIT_CLI_SHELL_COMMAND} session {{session_id}} step --plan -`,
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_text_exists", "issue_url_exists", "issue_details_exists", "issue_metadata_exists", "active_cycle_exists"]
   }),
   defineStep({
-    buttonLabel: "Accept changes",
-    description: "Review the worktree diff and accept the changes as ready to commit.",
-    id: "implementation_changes_accepted",
-    kind: "user_check",
-    label: "Changes accepted",
-    preconditions: ["session_exists", "worktree_exists"],
-    utilityActions: Object.freeze([
-      Object.freeze({
-        id: "session_diff",
-        kind: "diff",
-        label: "Review changes",
-        nextCommandTemplate: "jskit session {{session_id}} diff"
-      })
-    ])
+    buttonLabel: "Get Codex to execute plan",
+    codex: PLAN_EXECUTION_CODEX_HANDOFF,
+    description: "JSKIT sends the active cycle plan to Codex; Codex implements it; Studio advances when Codex finishes.",
+    id: "plan_executed",
+    kind: "codex_prompt",
+    label: "Plan executed",
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_text_exists", "issue_url_exists", "issue_details_exists", "issue_metadata_exists", "active_cycle_exists", "plan_text_exists"]
   }),
   defineStep({
-    buttonLabel: "Commit implementation",
-    description: "Commit the accepted implementation changes in the session worktree.",
-    id: "implementation_changes_committed",
-    label: "Changes committed",
-    preconditions: ["session_exists", "worktree_exists"]
+    buttonLabel: "Run Deep UI check",
+    codex: DEEP_UI_CHECK_CODEX_HANDOFF,
+    description: "JSKIT asks Codex for a focused UI quality pass when the issue affects UI, or records a skip receipt when it does not.",
+    id: "deep_ui_check_run",
+    kind: "codex_prompt",
+    label: "Deep UI check run",
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists"]
   }),
   defineStep({
-    buttonLabel: "Start review",
-    description: "Submit the code review prompt to Codex for the committed changes.",
+    buttonLabel: "Run deslop",
+    codex: REVIEW_EXECUTION_CODEX_HANDOFF,
+    description: "JSKIT sends the current implementation to Codex for a review/deslop pass; Codex reports findings and applies the selected cleanup.",
+    displayGroupId: "review_deslop",
+    displayGroupLabel: "Review/deslop",
     id: "review_prompt_rendered",
     kind: "codex_prompt",
-    label: "Review execution",
-    preconditions: ["session_exists", "worktree_exists"]
+    label: "Review/deslop",
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists", "deep_ui_check_satisfied"]
   }),
   defineStep({
-    buttonLabel: "Accept review changes",
-    description: "Review the post-review worktree diff and accept it as ready to commit.",
+    buttonLabel: "I am done",
+    description: "User confirms the review/deslop loop is done; JSKIT records the loop result without committing yet.",
+    displayGroupId: "review_deslop",
+    displayGroupLabel: "Review/deslop",
     id: "review_changes_accepted",
     kind: "user_check",
-    label: "Review changes accepted",
-    preconditions: ["session_exists", "worktree_exists"],
-    utilityActions: Object.freeze([
-      Object.freeze({
-        id: "session_diff",
-        kind: "diff",
-        label: "Review changes",
-        nextCommandTemplate: "jskit session {{session_id}} diff"
-      })
-    ])
+    label: "Review/deslop",
+    nextCommandTemplate: `${JSKIT_CLI_SHELL_COMMAND} session {{session_id}} step --review-findings-remaining false`,
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists", "deep_ui_check_satisfied"]
   }),
   defineStep({
-    buttonLabel: "Commit review changes",
-    description: "Commit accepted review changes, or record that no review changes were needed.",
-    id: "review_changes_committed",
-    label: "Review changes committed",
-    preconditions: ["session_exists", "worktree_exists"]
+    buttonLabel: "Run automated checks",
+    codex: AUTOMATED_CHECK_REPAIR_CODEX_HANDOFF,
+    description: "JSKIT asks Codex to run automated checks in the worktree, fix failures, and report the final result.",
+    id: "automated_checks_run",
+    kind: "codex_prompt",
+    label: "Automated checks",
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists", "deep_ui_check_satisfied"]
   }),
   defineStep({
     buttonLabel: "Save user check",
-    description: "Record whether the user’s manual check passed.",
+    description: "User manually checks the result; JSKIT records pass or collects rework notes for another plan cycle.",
     id: "user_check_completed",
     input: USER_CHECK_INPUT,
     kind: "user_check",
     label: "User check",
-    nextCommandTemplate: "jskit session {{session_id}} step --user-check passed",
-    preconditions: ["session_exists"]
+    nextCommandTemplate: `${JSKIT_CLI_SHELL_COMMAND} session {{session_id}} step --user-check passed`,
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists", "automated_checks_passed", "deep_ui_check_satisfied"]
+  }),
+  defineStep({
+    buttonLabel: "Commit accepted changes",
+    description: "JSKIT commits the user-accepted session changes in the session worktree.",
+    id: "changes_committed",
+    label: "Changes committed",
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "issue_url_exists", "github_auth", "active_cycle_exists", "automated_checks_passed", "deep_ui_check_satisfied", "active_cycle_user_check_passed"]
+  }),
+  defineStep({
+    buttonLabel: "Update blueprint",
+    codex: BLUEPRINT_CODEX_HANDOFF,
+    description: "JSKIT asks Codex to update durable app memory from the accepted work; Codex edits .jskit/APP_BLUEPRINT.md; JSKIT records and commits the update.",
+    id: "blueprint_updated",
+    kind: "codex_prompt",
+    label: "Blueprint updated",
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists", "automated_checks_passed", "deep_ui_check_satisfied", "active_cycle_user_check_passed", "accepted_changes_committed"]
   }),
   defineStep({
     buttonLabel: "Run verification",
-    description: "Run the project verification command in the session worktree.",
+    description: "JSKIT runs the final project verification command in the session worktree and records the result.",
     id: "doctor_run",
     label: "Verification run",
-    preconditions: ["session_exists", "worktree_exists"]
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists", "automated_checks_passed", "deep_ui_check_satisfied", "active_cycle_user_check_passed", "accepted_changes_committed", "blueprint_update_satisfied"]
+  }),
+  defineStep({
+    buttonLabel: "Create final report",
+    description: "JSKIT creates the deterministic final session report and comments it on the GitHub issue.",
+    id: "final_report_created",
+    label: "Final report created",
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists", "automated_checks_passed", "deep_ui_check_satisfied", "active_cycle_user_check_passed", "accepted_changes_committed", "blueprint_update_satisfied"]
   }),
   defineStep({
     buttonLabel: "Push branch and create PR",
-    description: "Push the session branch to origin and create a GitHub pull request.",
+    description: "JSKIT pushes the session branch to origin, creates or reuses the GitHub pull request, and records the PR URL.",
     id: "pr_created",
     label: "Branch pushed, PR created",
-    preconditions: ["session_exists", "worktree_exists"]
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists", "automated_checks_passed", "deep_ui_check_satisfied", "active_cycle_user_check_passed", "accepted_changes_committed", "blueprint_update_satisfied", "final_report_exists"]
   }),
   defineStep({
-    buttonLabel: "Merge PR and remove worktree",
-    description: "Merge the pull request, close the GitHub issue, and remove the session worktree.",
-    id: "pr_merged",
-    label: "PR merged, worktree removed",
-    preconditions: ["session_exists", "pr_url_exists", "worktree_exists"]
+    buttonLabel: "Merge PR",
+    description: "User chooses whether JSKIT merges the pull request or finishes without merge; JSKIT then removes the session worktree.",
+    id: "pr_finalized",
+    label: "PR finalized, worktree removed",
+    preconditions: ["session_exists", "pr_url_exists", "worktree_exists"],
+    requiresExplicitRun: true
   }),
   defineStep({
     buttonLabel: "Finish session",
-    description: "Write the final receipt and archive the completed session.",
+    description: "JSKIT writes the final receipt and archives the completed session.",
     id: "session_finished",
     label: "Session finished",
     preconditions: ["session_exists"]
@@ -299,6 +420,15 @@ const STEP_DEFINITIONS = Object.freeze([
 const STEP_IDS = Object.freeze(STEP_DEFINITIONS.map((step) => step.id));
 const STEP_LABEL_BY_ID = Object.freeze(Object.fromEntries(STEP_DEFINITIONS.map((step) => [step.id, step.label])));
 const STEP_DEFINITION_BY_ID = Object.freeze(Object.fromEntries(STEP_DEFINITIONS.map((step) => [step.id, step])));
+const CYCLE_STEP_IDS = Object.freeze([
+  "plan_made",
+  "plan_executed",
+  "deep_ui_check_run",
+  "review_prompt_rendered",
+  "review_changes_accepted",
+  "automated_checks_run",
+  "user_check_completed"
+]);
 const STEP_PRECONDITION_NAMES = Object.freeze(Object.fromEntries(
   STEP_DEFINITIONS
     .filter((step) => step.id !== "session_created")
@@ -309,12 +439,21 @@ export {
   PROMPT_DIRECTORY,
   SESSION_ID_PATTERN,
   SESSION_STATUS,
+  SESSION_WORKFLOW_VERSION,
+  REVIEW_PASS_LIMIT,
+  CYCLE_STEP_IDS,
   STEP_DEFINITION_BY_ID,
   STEP_DEFINITIONS,
   STEP_IDS,
   STEP_LABEL_BY_ID,
   STEP_PRECONDITION_NAMES,
+  ISSUE_DETAILS_CODEX_HANDOFF,
   PLAN_EXECUTION_CODEX_HANDOFF,
   REVIEW_EXECUTION_CODEX_HANDOFF,
+  DEEP_UI_CHECK_CODEX_HANDOFF,
+  AUTOMATED_CHECK_REPAIR_CODEX_HANDOFF,
+  BLUEPRINT_CODEX_HANDOFF,
+  JSKIT_CLI_SHELL_COMMAND,
+  JSKIT_CLI_SHELL_RULE,
   SESSION_STATE_RELATIVE_PATH
 };