@jskit-ai/agent-docs 0.1.32 → 0.1.34

package/guide/agent/app-setup/initial-scaffolding.md

@@ -30,6 +30,19 @@ npm install
 
 After that promotion, the overwritten app `AGENTS.md` stays deliberately small. Use `jskit session` for issue-driven work; session state and prompts live under `.jskit/sessions/` in the target app.
 
+Issue sessions are executable workflow state, not prose instructions. The important durable files are:
+
+- `issue.md` and `issue_title` for the approved GitHub issue.
+- `plan_details.md` for the confirmed implementation details gathered before planning.
+- `plan.md` for the approved implementation plan.
+- `agent_decisions.md` for concise decisions and why they were made.
+- `.jskit/APP_BLUEPRINT.md` for durable app/product/architecture memory that grows across issues.
+- `review_passes/`, `checks/`, `ui_checks/`, and `command_log.jsonl` for review, verification, UI check, and command receipts.
+
+The Deep UI Check steps use the saved issue classification: server-only work can be skipped with a receipt, possible UI work can be skipped only with an explicit reason, and definite UI work must run. If the User Check fails, JSKIT starts a new cycle under `cycles/cycle_###/` and cycle-scoped receipts under `steps/cycle_###/`; do not delete older cycle receipts.
+
+Studio and other tools should read `jskit session <session_id> --json` rather than scraping those files directly. Manual agents should follow the current `jskit session <session_id> step` output and avoid recreating the old workboard workflow.
+
 After creating the real app scaffolding (the base shell, not the seed wrapper), you will need to run `npm install` to install dependencies.
 
 If you already know you want a small non-workspace baseline right after the scaffold, this is the shortest reproducible path:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/reference/autogen/tooling/jskit-cli.md

@@ -453,6 +453,14 @@ Local functions
 Exports
 - `createHealthCommands(ctx = {})`
 
+### `src/server/commandHandlers/helperMap.js`
+Exports
+- `createHelperMapCommands(ctx = {})`
+Local functions
+- `writeJson(stdout, payload)`
+- `writeErrors(stdout, payload)`
+- `writeHelperMapText(stdout, payload)`
+
 ### `src/server/commandHandlers/list.js`
 Exports
 - `createListCommands(ctx = {})`
@@ -673,6 +681,7 @@ Local functions
 - `resolveTextInput({ codePrefix, fileOption, inlineOptions = {}, io = {}, repairCommand, cwd, stdinOption, textOption, sessionId })`
 - `resolveStepInputs({ inlineOptions = {}, io = {}, cwd, sessionId })`
 - `normalizeStepOptions(inlineOptions = {})`
+- `resolveListArchiveOption(options = {})`
 
 ### `src/server/commandHandlers/shared.js`
 Exports
@@ -764,6 +773,36 @@ Local functions
 - `printTopLevelHelp(stream = process.stderr)`
 - `printCommandHelp(stream = process.stderr, command = "")`
 
+### `src/server/helperMap.js`
+Exports
+- `HELPER_MAP_JSON_RELATIVE_PATH`
+- `HELPER_MAP_MARKDOWN_RELATIVE_PATH`
+- `buildHelperMap({ targetRoot })`
+- `readHelperMap({ targetRoot })`
+- `updateHelperMap({ targetRoot })`
+Local functions
+- `pathExists(filePath)`
+- `readJsonFile(filePath)`
+- `normalizePackageDependencies(packageJson = {})`
+- `classifySymbol(name = "")`
+- `createExportAnalysisProject()`
+- `kindFromDeclaration(declaration, exportName = "")`
+- `addSymbol(symbols, symbol)`
+- `extractExportedSymbols(sourceFile)`
+- `extractVueScriptSource(source = "", filePath = "")`
+- `addCodeFileToProject(project, file)`
+- `walkCodeFiles(rootPath, relativeRoot = "")`
+- `collectAppExports(targetRoot)`
+- `flattenPackageExports(exportsField)`
+- `collectJskitPackageExports(targetRoot, packageJson = {})`
+- `renderExportList(symbols = [])`
+- `renderHelperMapMarkdown(map)`
+
+### `src/server/helperMapPaths.js`
+Exports
+- `HELPER_MAP_JSON_RELATIVE_PATH`
+- `HELPER_MAP_MARKDOWN_RELATIVE_PATH`
+
 ### `src/server/index.js`
 Exports
 - `runCli`
@@ -775,17 +814,23 @@ Exports
 - `STEP_IDS`
 - `STEP_PRECONDITION_NAMES`
 - `abandonSession({ targetRoot = process.cwd(), sessionId } = {})`
+- `adoptDependenciesInstalled({ targetRoot = process.cwd(), sessionId, message = "" } = {})`
 - `adoptCodexThreadId({ targetRoot = process.cwd(), sessionId, codexThreadId } = {})`
 - `buildSessionResponse`
 - `buildSessionErrorResponse`
 - `createSession({ targetRoot = process.cwd(), sessionId = "", now = new Date() } = {})`
 - `createSessionId`
+- `extractIssueTitle(value = "")`
 - `extractIssueText(value = "")`
+- `extractPlanDetails(value = "")`
+- `extractPlanText(value = "")`
 - `inspectSession({ targetRoot = process.cwd(), sessionId } = {})`
+- `inspectSessionDiff({ targetRoot = process.cwd(), sessionId } = {})`
 - `inspectSessionDetails({ targetRoot = process.cwd(), sessionId } = {})`
 - `isValidSessionId`
-- `listSessions({ targetRoot = process.cwd() } = {})`
+- `listSessions({ targetRoot = process.cwd(), archive = "active" } = {})`
 - `renderTemplate`
+- `recordDependenciesInstalled(paths, { message = "Installed Node dependencies in the session worktree.", preconditions = [] } = {})`
 - `resolveSessionPaths`
 - `runSessionStep({ targetRoot = process.cwd(), sessionId, options = {} } = {})`
 Local functions
@@ -793,44 +838,133 @@ Local functions
 - `invalidSessionIdResponse({ targetRoot, sessionId })`
 - `existingSessionContext({ targetRoot = process.cwd(), sessionId } = {})`
 - `withExistingSession(input, handler)`
+- `extractMarkedText(value = "", marker = "")`
+- `extractIssueCategory(value = "")`
+- `extractUiImpact(value = "")`
+- `extractAgentDecisions(value = "")`
+- `normalizeIssueCategory(value = "")`
+- `normalizeUiImpact(value = "")`
+- `writePromptArtifact(paths, fileName, prompt)`
+- `commandText(command, args = [])`
+- `commandOutputSummary(output = "")`
+- `appendCommandLog(paths, { args = [], command, cwd = "", kind = "command", result } = {})`
+- `runLoggedCommand(paths, kind, command, args = [], options = {})`
+- `readIssueMetadata(paths)`
+- `writeIssueMetadata(paths, metadata = {})`
+- `readGithubComments(paths)`
+- `writeGithubComments(paths, comments = {})`
+- `commentOnIssueOnce(paths, { bodyFile, issueUrl, purpose })`
+- `appendAgentDecisions(paths, decisions = "")`
+- `appendAgentDecisionsInput(paths, options = {})`
+- `recordIssueInAgentDecisions(paths, issueUrl = "")`
+- `issueMetadataFromUrl(issueUrl = "")`
+- `nextCycleNumber(cycle = "001")`
+- `normalizeArchiveFilter(archive = "active")`
 - `emptySessionDetails(response)`
+- `removeEmptyStaleWorktreeDirectory(paths)`
 - `createWorktree(paths, _options = {}, context = {})`
+- `parsePackageManager(value = "")`
+- `hasWorktreeFile(worktree, fileName)`
+- `dependencyInstallCommandForWorktree(worktree)`
+- `installDependencies(paths, _options = {}, context = {})`
 - `renderIssuePrompt(paths, options = {})`
 - `draftIssue(paths, options = {})`
 - `titleFromIssue(issueText)`
 - `createIssue(paths, _options = {}, context = {})`
-- `renderImplementationPrompt(paths)`
+- `renderPlanDetailsPrompt(paths, _options = {}, context = {})`
+- `savePlanDetails(paths, options = {}, context = {})`
+- `makePlan(paths, options = {}, context = {})`
+- `renderPlanExecutionPrompt(paths, _options = {}, context = {})`
+- `renderPlanFineTuningPrompt(paths, _options = {}, context = {})`
 - `worktreeStatus(worktree)`
-- `detectChanges(paths)`
+- `untrackedFiles(worktree)`
+- `untrackedFileDiff(worktree, filePath)`
+- `untrackedFilesDiff(worktree)`
+- `acceptImplementationChanges(paths)`
 - `commitWorktree(paths, { message, allowNoChanges = false } = {})`
 - `commitImplementation(paths)`
 - `changedFilesFromLastCommit(paths)`
-- `reviewPromptStepId(passNumber)`
-- `renderReviewPrompt(paths, passNumber)`
-- `reviewChangesStepId(passNumber)`
-- `detectAndCommitReviewChanges(paths, passNumber)`
-- `userCheckStepId(passNumber)`
-- `userCheck(paths, passNumber, options = {})`
+- `changedFilesSinceBase(paths)`
+- `nextReviewPassNumber(pass = "")`
+- `readCurrentReviewPass(paths)`
+- `writeCurrentReviewPass(paths, pass)`
+- `resolveReviewPassForPrompt(paths)`
+- `writeReviewPassJson(paths, pass, fileName, payload)`
+- `currentHead(paths)`
+- `renderReviewPrompt(paths)`
+- `acceptReviewChanges(paths, options = {})`
+- `commitReviewChanges(paths)`
+- `runAutomatedChecks(paths, { stepId, label })`
+- `readCheckResult(paths, stepId)`
+- `maybeCommitCheckRepair(paths, { label, stepId })`
+- `uiCheckAcceptStepId(stepId)`
+- `uiCheckCommitStepId(stepId)`
+- `uiCheckSourceStepId(stepId)`
+- `uiCheckLabelForStep(stepId)`
+- `writeUiCheckJson(paths, fileName, payload)`
+- `runDeepUiCheck(paths, { stepId, label, phase }, options = {}, context = {})`
+- `acceptUiCheckChanges(paths, { stepId }, _options = {}, context = {})`
+- `commitUiCheckChanges(paths, { stepId }, _options = {}, context = {})`
+- `userCheck(paths, options = {})`
+- `updateBlueprint(paths, options = {}, context = {})`
 - `readPackageJson(root)`
 - `doctorCommandForWorktree(worktree)`
 - `runDoctor(paths)`
-- `pushBranch(paths)`
+- `maybeCommitDoctorRepair(paths)`
+- `commitLinesSinceBase(paths)`
+- `readCheckSummaries(paths)`
+- `readUiCheckSummaries(paths)`
+- `readReviewPassSummaries(paths)`
+- `createFinalReport(paths, _options = {}, context = {})`
 - `issueNumberFromUrl(issueUrl)`
+- `parseJsonObject(value)`
+- `readPrState(paths, prUrl)`
+- `readCurrentBranchPrState(paths)`
+- `prStateIsMerged(prState)`
+- `prStateIsClosed(prState)`
+- `currentTargetBranch(targetRoot)`
+- `assertTargetRootCleanForBaseUpdate(paths)`
+- `removeSessionWorktree(paths)`
+- `writePrOutcome(paths, outcome)`
+- `assertTargetRootCanUpdateBase(paths, branch)`
+- `assertTargetBaseCanFastForward(paths, branch)`
+- `updateLocalBaseBranch(paths, baseBranch = "")`
+- `updateHelperMapBeforePr(paths)`
 - `createPr(paths)`
-- `mergePr(paths)`
-- `removeWorktree(paths)`
+- `closePrWithoutMerge(paths, prUrl, options = {})`
+- `finalizePr(paths, options = {})`
 - `finishSession(paths)`
 - `runNamedPreconditions(paths, names = [])`
 
+### `src/server/sessionRuntime/appReadiness.js`
+Exports
+- `inspectReadyJskitAppRoot(rootPath)`
+Local functions
+- `pathExists(filePath)`
+- `directoryExists(filePath)`
+
 ### `src/server/sessionRuntime/constants.js`
 Exports
 - `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`
+- `PLAN_EXECUTION_CODEX_HANDOFF`
+- `PLAN_FINE_TUNING_CODEX_HANDOFF`
+- `REVIEW_EXECUTION_CODEX_HANDOFF`
+- `DEEP_UI_CHECK_CODEX_HANDOFF`
+- `BLUEPRINT_CODEX_HANDOFF`
 - `SESSION_STATE_RELATIVE_PATH`
+Local functions
+- `codexHandoff(expectedOutput, { autoInject = false, promptActionLabel = "" } = {})`
+- `defineStep({ buttonLabel, codex = undefined, description, id, input = INPUT_NONE, kind = "automatic", label, nextCommandTemplate = "jskit session {{session_id}} step", preconditions = [], utilityActions = [], displayGroupId = "", displayGroupLabel = "" })`
 
 ### `src/server/sessionRuntime/io.js`
 Exports
@@ -860,20 +994,35 @@ Local functions
 ### `src/server/sessionRuntime/preconditions.js`
 Exports
 - `applyPreconditions(paths, checks = [])`
+- `assertActiveCycleExists(paths)`
+- `assertActiveCycleUserCheckPassed(paths)`
+- `assertBlueprintUpdateSatisfied(paths)`
+- `assertDeepUiCheckSatisfied(paths)`
+- `assertDeepUiRecheckSatisfied(paths)`
+- `assertDependenciesInstalled(paths)`
+- `assertFinalReportExists(paths)`
 - `assertGhAuth(targetRoot)`
 - `assertGitCurrentBranch(targetRoot)`
 - `assertGitRepository(targetRoot)`
 - `assertGithubOrigin(targetRoot)`
-- `assertIssueArtifacts(paths)`
+- `assertIssueMetadataExists(paths)`
 - `assertIssueTextExists(paths)`
+- `assertIssueUrlExists(paths)`
+- `assertPostReviewChecksPassed(paths)`
+- `assertPreReviewChecksPassed(paths)`
+- `assertPlanDetailsExists(paths)`
+- `assertPlanTextExists(paths)`
 - `assertPrUrlExists(paths)`
+- `assertReadyJskitApp(paths)`
 - `assertSessionExists(paths)`
 - `assertTargetRootWritable(targetRoot)`
 - `assertWorktreeExists(paths)`
 - `ensureStudioGitExclude(targetRoot)`
-- `hasWorktree(paths)`
+- `hasWorktree`
 Local functions
 - `resolveGitCommonDirectory(targetRoot)`
+- `pathExists(filePath)`
+- `assertActiveCycleStepReceipt(paths, { code, id, message, stepId })`
 
 ### `src/server/sessionRuntime/promptRenderer.js`
 Exports
@@ -884,20 +1033,61 @@ Exports
 ### `src/server/sessionRuntime/responses.js`
 Exports
 - `buildSessionErrorResponse({ targetRoot = process.cwd(), sessionId = "", code, message, repairCommand = "", status = SESSION_STATUS.BLOCKED, preconditions = [], errors = undefined } = {})`
-- `buildSessionResponse(paths, { ok = true, errors = [], preconditions = [], prompt = undefined, status = undefined } = {})`
+- `buildSessionResponse(paths, { codex = undefined, ok = true, errors = [], preconditions = [], prompt = undefined, status = undefined } = {})`
+- `buildStepDefinitions()`
 - `createError({ code, message, repairCommand = "" })`
 - `createPrecondition({ id, ok, message })`
 - `failSession(paths, { code, message, repairCommand = "", preconditions = [], status = SESSION_STATUS.BLOCKED, prompt = "" })`
 - `markCurrentStep(paths, stepId)`
 - `markStatus(paths, status)`
+- `normalizeReviewPassNumber(value = "")`
+- `readActiveCycle(paths)`
 - `readReceiptSteps(paths)`
+- `readReviewPasses(paths)`
 - `readSessionArtifacts(paths)`
+- `reviewPassDirectoryName(pass = DEFAULT_REVIEW_PASS)`
+- `reviewPassRoot(paths, pass)`
+- `writeActiveCycle(paths, cycle)`
+- `writeCycleReceipt(paths, receiptName, message, { cycle = "" } = {})`
 - `writeReceipt(paths, stepId, message)`
 Local functions
-- `readCompletedSteps(sessionRoot)`
+- `normalizeStepId(stepId)`
+- `stepIndex(stepId)`
+- `normalizeKnownStepIds(stepIds = [])`
+- `stepCanExposeStoredPrompt(stepId)`
+- `normalizeCycleNumber(value = "")`
+- `cycleDirectoryName(cycle = DEFAULT_ACTIVE_CYCLE)`
+- `isCycleStepId(stepId = "")`
+- `readWorkflowVersion(paths)`
+- `cycleStepsRoot(paths, cycle)`
+- `cycleRoot(paths, cycle)`
+- `parseJsonFileIfExists(filePath)`
+- `readReviewPassNumbers(paths)`
+- `readReviewPassInfo(paths, pass)`
+- `readPromptForStep(paths, stepId)`
+- `readStepFileNames(stepsRoot)`
+- `readCompletedSteps(paths)`
+- `applyReviewPassCompletionOverlay(paths, completedSteps = [])`
+- `readCycleInfo(paths, cycle)`
+- `readCycles(paths, activeCycle)`
+- `readStructuredChecks(paths)`
+- `readStructuredUiChecks(paths)`
+- `readWorktreeStatus(paths, worktreeReady)`
 - `resolveNextStep(completedSteps = [])`
+- `cloneContractValue(value)`
+- `publicStepDefinition(step, index)`
+- `stepIsRetryableWhenBlocked(stepId)`
+- `stepIsConditional(stepId)`
+- `skipReasonForStep(stepId, artifacts = {})`
+- `buildCurrentStepAction(stepId, artifacts = {})`
+- `buildCodexHandoff(stepId)`
 - `buildNextCommand(sessionId, stepId)`
 
+### `src/server/sessionRuntime/worktrees.js`
+Exports
+- `hasWorktree(paths = {})`
+- `parseGitWorktreeList(output = "")`
+
 ### `src/server/shared/cliError.js`
 Exports
 - `createCliError(message, { showUsage = false, exitCode = 1, renderUsage = null } = {})`

package/templates/app/AGENTS.md

@@ -1,17 +1,13 @@
 # App Agent Instructions
 
-JSKIT issue work is driven by the executable session workflow.
+Use JSKIT sessions for issue work.
 
 Use:
 
-- `jskit session` to list existing sessions.
-- `jskit session create` to start a new issue session.
-- `jskit session <session_id>` to inspect durable session state.
-- `jskit session <session_id> step` to run the next workflow step or get the next prompt.
-- `jskit session <session_id> step --json` when a tool or UI needs machine-readable state.
+- `jskit session`
+- `jskit session create`
+- `jskit session <session_id>`
+- `jskit session <session_id> step`
+- `jskit session <session_id> step --json` for tools and UIs
 
-Do not invent a parallel manual issue workflow. Follow the current session step output.
-
-If dependencies are missing, install them first. If `npm install` is run while this app uses local JSKIT checkout links, run `npm run devlinks` immediately afterward.
-
-For JSKIT implementation details, use package docs, generated references, and `node_modules/@jskit-ai/agent-docs/patterns/INDEX.md` only as technical references. They are not the issue workflow source of truth.
+Follow the current session step output and prompt. Do not invent a parallel manual issue workflow.