knoxis-helper 1.8.2 → 1.8.3

package/lib/knoxis-interactive-pair.js

@@ -379,7 +379,10 @@ async function runKitMode(kitMode, task, identity, scaffoldResult) {
       workspace: identity.workspace,
       userId: identity.userId,
       workspaceId: identity.workspaceId,
-      parentTaskId: (identity.taskIds && identity.taskIds.length) ? identity.taskIds[0] : null
+      parentTaskId: (identity.taskIds && identity.taskIds.length) ? identity.taskIds[0] : null,
+      // Auto-doc opt-in flows through env var since the interactive runner
+      // sources its identity from the QIG portal rather than CLI args.
+      integrate: process.env.KNOXIS_INTEGRATE === 'true' || process.env.KNOXIS_INTEGRATE === '1'
     });
   } catch (e) {
     console.error('Kit template error: ' + e.message);

package/lib/knoxis-pair-program.js

@@ -804,7 +804,11 @@ async function run() {
       pattern: recoveryPattern,
       productSlug: args['product-slug'] || null,
       projectSlug: args['project-slug'] || null,
-      workspace
+      workspace,
+      // Operator opt-in for auto-doc generation. When --integrate is passed
+      // alongside --mode feature-kickoff, the kickoff template appends a
+      // phase-integrate phase that the session-end ritual will run later.
+      integrate: Boolean(args.integrate)
     });
     scheduledSteps = [{
       key: tpl.key,

package/lib/templates/feature-kickoff.js

@@ -8,6 +8,11 @@
 // docs/features/<slug>/. Multiple features can coexist; each is independently
 // trackable from the QIG dashboard via its manifest.json.
 //
+// Canonical structural constraints (slug pattern, phase counts, manifest shape)
+// live in ./kickoff-schema.json and are also consumed by the server-side
+// KickoffPrepService that turns meeting transcripts into kickoff-ready JSON.
+// Keep this file's prose in sync with that schema if you change the numbers.
+//
 // State machine (similar shape to resume.js, autonomous-first):
 //   A: docs/features/<slug>/ missing                        → write the roadmap
 //   B: directory exists with unanswered _(fill in)_ entries → wait
@@ -93,6 +98,36 @@ touches. Steps must be small enough to ship in one pair-program session.
 **Don't pad.** A 4-step feature is fine. A 30-step feature with 3 phases of
 filler is not.
 
+### Optional final phase: \`phase-integrate\` (operator opt-in)
+
+If the session header above includes \`Integrate: yes\`, append one extra
+phase as the **last phase** of the feature, with this exact shape (id is
+load-bearing — the auto-doc generator looks for it):
+
+\`\`\`json
+{
+  "id": "phase-integrate",
+  "title": "Integrate (auto-doc)",
+  "goal": "Generate the public-contract API doc and register it for the chatbot",
+  "done_when": "docs/features/<slug>/PUBLIC_API.md exists and the integration-docs index has been notified",
+  "status": "pending",
+  "steps": [
+    { "id": "phase-integrate-step-1", "action": "Generate PUBLIC_API.md from manifest + live OpenAPI", "touches": "docs/features/<slug>/PUBLIC_API.md", "status": "pending" },
+    { "id": "phase-integrate-step-2", "action": "POST the doc to the backend integration-docs index for vectorization", "touches": "/api/public/integration-docs/index", "status": "pending" }
+  ]
+}
+\`\`\`
+
+Do NOT include \`phase-integrate\` when the session header does not say
+\`Integrate: yes\`. This is opt-in only — features that don't ship a public
+contract should not have this phase, and adding it half-heartedly creates
+half-baked docs in the vector store.
+
+When the operator opts in, mirror the phase into ROADMAP.md (add it to the
+phases list) and PHASES.md (with the two checkbox steps). The session-end
+ritual auto-detects \`phase-integrate\` as the eligible-pending phase and runs
+the doc generator without an extra command.
+
 ## Step 4 — Capture genuine open questions only
 
 If something truly cannot be decided autonomously (missing API decision,
@@ -306,7 +341,8 @@ function buildFeatureKickoffPrompt({
   workspace,
   userId,
   workspaceId,
-  parentTaskId
+  parentTaskId,
+  integrate
 } = {}) {
   const header = ['Mode: feature-kickoff'];
   if (productSlug) header.push(`Product: ${productSlug}`);
@@ -315,6 +351,7 @@ function buildFeatureKickoffPrompt({
   if (userId) header.push(`User ID: ${userId}`);
   if (workspaceId) header.push(`Workspace ID: ${workspaceId}`);
   if (parentTaskId) header.push(`Parent task ID: ${parentTaskId}`);
+  if (integrate) header.push('Integrate: yes');
   if (taskDescription) header.push(`Feature description (use as-is for the title and summary):\n${taskDescription}`);
   const ctx = `Session context:\n${header.join('\n')}\n\n`;
   return ctx + FEATURE_KICKOFF_BODY;

package/lib/templates/index.js

@@ -2,6 +2,7 @@
 
 const kickoff = require('./kickoff');
 const featureKickoff = require('./feature-kickoff');
+const featureIntegrate = require('./integrate');
 const resume = require('./resume');
 const sessionEnd = require('./session-end');
 const recovery = require('./recovery');
@@ -10,6 +11,7 @@ const codingRuleset = require('./coding-ruleset');
 const MODES = {
   kickoff,
   'feature-kickoff': featureKickoff,
+  'feature-integrate': featureIntegrate,
   resume,
   'session-end': sessionEnd,
   recovery

package/lib/templates/integrate.js

@@ -0,0 +1,252 @@
+'use strict';
+
+// Feature Integrate — single-shot, autonomous (v1)
+//
+// Operator opt-in: a feature includes a phase with id "phase-integrate" at
+// kickoff time, signaling that this feature ships a public-contract surface.
+// When all preceding phases are marked "done" and phase-integrate is the
+// next-pending phase, this template generates docs/features/<slug>/PUBLIC_API.md
+// from the live OpenAPI spec + the feature's manifest, marks phase-integrate
+// done, and (when the backend is reachable) posts the doc to the vectorizer
+// at /api/public/integration-docs/index so the chatbot can serve it as
+// integration guidance.
+//
+// State machine:
+//   A: PUBLIC_API.md missing or feature manifest changed since last write → write the doc
+//   B: PUBLIC_API.md present and manifest unchanged                         → no-op (idempotent re-run)
+//   C: phase-integrate is not pending or prior phases incomplete            → halt with a one-line note
+
+const FEATURE_INTEGRATE_BODY = `# Feature Integrate (single-shot, autonomous)
+
+You are running in single-shot mode. You produce one response and the process
+exits. Your job is to take the operator's feature slug (in the session header
+above), generate \`docs/features/<slug>/PUBLIC_API.md\` from the live API
+surface, mark the feature's \`phase-integrate\` step done, and (best-effort)
+register the doc with the backend so it can be vectorized for the chatbot.
+
+This is **a doc generation pass** — do not change application code, controllers,
+or any file outside \`docs/features/<slug>/\`.
+
+## Step 0 — Resolve the feature slug
+
+The slug is in the session header (\`Feature slug: <slug>\`). If absent, abort
+with a one-line note: "Feature integrate requires --prompt <slug>."
+
+Verify \`docs/features/<slug>/\` exists and contains \`manifest.json\`. If not,
+abort: "No feature found at docs/features/<slug>/. Run feature-kickoff first."
+
+## Step 1 — Confirm the operator opted in
+
+Open \`docs/features/<slug>/manifest.json\`. Look for a phase with
+\`id: "phase-integrate"\`.
+
+- **Not found** → halt: "This feature did not opt into integrate phase. To
+  enable, re-run feature-kickoff with the --integrate flag, or hand-edit
+  manifest.json to add a phase with id 'phase-integrate'."
+- **Found and \`status: "done"\` already** → State B → check whether
+  \`PUBLIC_API.md\` exists. If yes, idempotent no-op: print "PUBLIC_API.md
+  already up to date." If no, treat as State A.
+- **Found, \`status: "pending"\`, prior phases all \`status: "done"\`** → State A.
+  Continue.
+- **Found, \`status: "pending"\`, prior phases NOT all done** → State C → halt:
+  "phase-integrate is not yet eligible — phases X, Y, Z still pending."
+
+## Step 2 — Identify the public surface this feature shipped
+
+From \`manifest.json\`, walk every \`phases[].steps[].touches\` value.
+
+Filter to **Java files under \`src/main/java/com/yourcompany/voice/controller/\`**
+or any file whose path contains \`/controller/\`. These are the candidates for
+the public surface.
+
+For each touched controller file:
+- Read its \`@RequestMapping\` base path.
+- Read its \`@PostMapping\`, \`@GetMapping\`, \`@PutMapping\`, \`@DeleteMapping\`
+  annotations to enumerate routes.
+- Note the request body shape (look for \`@RequestBody\`, \`@RequestParam\`,
+  \`@RequestPart\` types).
+- Note the return type and any \`@Operation(summary=...)\` Swagger annotation
+  for prose.
+
+If a step's \`touches\` field references a non-controller file (service, DTO,
+config), skip it. Only the public-contract surface goes in PUBLIC_API.md.
+
+If after filtering you have zero controllers, this feature does not ship a
+public contract — abort: "No controllers in manifest's touched files; nothing
+to document. Use a different doc kind for this feature."
+
+## Step 3 — Fetch the live OpenAPI spec (best effort)
+
+Hit \`http://localhost:8080/v3/api-docs\` (Spring's default) and parse the JSON.
+If the backend is not running locally, look for an env var \`OPENAPI_URL\` and
+use that. If neither is reachable, skip live OpenAPI and rely solely on the
+controller source you read in Step 2 — the doc just won't include exact
+response schemas, only the route + summary + request body shape.
+
+For each route from Step 2, look up the matching path in the OpenAPI spec
+(\`paths.<basePath><route>\`) and pull:
+- \`summary\` and \`description\`
+- request schema (\`requestBody.content."application/json".schema\`)
+- response schema (\`responses."200".content.*.schema\`)
+- error responses
+
+## Step 4 — Generate \`docs/features/<slug>/PUBLIC_API.md\`
+
+Use this skeleton, populated from Steps 2–3. Keep it tight; integrators will
+read this in 60 seconds.
+
+\`\`\`markdown
+---
+feature_slug: <slug>
+generated_at: <ISO date>
+api_kind: public-contract
+---
+
+# <Feature Title> — Public API
+
+<2–3 sentence summary from manifest.feature_title + manifest.proposedSummary
+or the feature's ROADMAP.md Summary section.>
+
+**Base URL (deployed):** \`<from PUBLIC_VOICE_API.md or operator-known\`
+
+## 60-second quickstart
+
+\\\`\\\`\\\`bash
+# <smallest curl that exercises the headline endpoint>
+\\\`\\\`\\\`
+
+## Endpoints
+
+| Path | Method | Use when |
+|---|---|---|
+<one row per route from Step 2-3>
+
+## Authentication
+
+<Same shared-key pattern as PUBLIC_VOICE_API.md if these endpoints sit behind
+PublicVoiceGuard, or whatever the controllers actually enforce.>
+
+## <One section per endpoint>
+
+### Request
+\\\`\\\`\\\`json
+<request schema, example values>
+\\\`\\\`\\\`
+
+### Response
+\\\`\\\`\\\`json
+<response schema, example values>
+\\\`\\\`\\\`
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+<rows>
+
+## Error reference
+
+<reuse the standard envelope; reference codes the controllers actually emit>
+
+## Limits and defaults
+
+<rate limits, concurrency caps, etc. if known>
+
+## Need anything
+
+<Match the footer style in docs/PUBLIC_VOICE_API.md.>
+\`\`\`
+
+**Don't pad.** If a section has nothing to say, leave it out. Match the tone
+of the existing \`docs/PUBLIC_VOICE_API.md\` (terse, integrator-focused, no
+filler).
+
+## Step 5 — Mark phase-integrate done in the manifest
+
+Update \`docs/features/<slug>/manifest.json\`:
+- The phase with \`id: "phase-integrate"\` → \`status: "done"\`
+- All steps within that phase → \`status: "done"\`
+- If \`current_phase\` was \`phase-integrate\`, advance it to \`null\` (or to
+  the next pending phase if any exist after integrate).
+
+Mirror the change into \`docs/features/<slug>/STATUS.md\` (check off the box).
+Mirror into \`docs/features/<slug>/PHASES.md\` (\`- [x]\` for the integrate
+steps).
+
+## Step 6 — Best-effort: register the doc with the backend vectorizer
+
+POST the generated markdown to the backend's integration-docs index endpoint:
+
+\`\`\`bash
+curl -s -X POST "$BACKEND/api/public/integration-docs/index" \\
+  -H "Content-Type: application/json" \\
+  -H "X-Tenant-Id: $TENANT" \\
+  -H "X-Public-Voice-Key: $KEY" \\
+  -d '{"slug": "<slug>", "markdown": "<contents>"}'
+\`\`\`
+
+Read \`BACKEND\` from env or default to \`http://localhost:8080\`. Read
+\`TENANT\` from env (\`KNOXIS_TENANT_ID\`) — if missing, skip vectorization
+with a one-line note "Skipped vectorization: KNOXIS_TENANT_ID not set."
+Read \`KEY\` from env \`PUBLIC_VOICE_API_SHARED_KEY\` (optional).
+
+If the curl returns non-2xx, do not fail — the doc was still written to disk.
+Print one line: "Vectorize call returned <code>; doc was generated. The
+operator can re-run vectorization manually."
+
+## Step 7 — Output for the operator
+
+End with a copyable block:
+
+\`\`\`
+Feature integrate complete: <slug>
+
+Files written:
+  docs/features/<slug>/PUBLIC_API.md
+  docs/features/<slug>/manifest.json (phase-integrate → done)
+  docs/features/<slug>/STATUS.md (checkbox)
+  docs/features/<slug>/PHASES.md (checkboxes)
+
+Vectorization: <success | skipped | failed>
+
+Next: the doc is ready to share with integrators and (when registered) to
+serve via the chatbot's "I need a feature for X" intent.
+\`\`\`
+
+## Non-negotiables
+
+- Write \`PUBLIC_API.md\` to disk. Do not describe what you would write.
+- Match the tone and structure of \`docs/PUBLIC_VOICE_API.md\` and
+  \`docs/PUBLIC_SPEAKER_API.md\` — these are the canonical examples.
+- Keep \`manifest.json\` consistent with the three MD files at all times.
+- Do not modify application code (no edits to anything outside
+  \`docs/features/<slug>/\`).
+- One feature per run. The slug is final for this run.
+- Idempotent. Re-running with PUBLIC_API.md already up to date is a no-op.
+
+---
+
+`;
+
+function buildFeatureIntegratePrompt({
+  taskDescription,
+  productSlug,
+  projectSlug,
+  workspace,
+  userId,
+  workspaceId
+} = {}) {
+  const header = ['Mode: feature-integrate'];
+  if (productSlug) header.push(`Product: ${productSlug}`);
+  if (projectSlug) header.push(`Project: ${projectSlug}`);
+  if (workspace) header.push(`Workspace: ${workspace}`);
+  if (userId) header.push(`User ID: ${userId}`);
+  if (workspaceId) header.push(`Workspace ID: ${workspaceId}`);
+  if (taskDescription) header.push(`Feature slug: ${taskDescription}`);
+  const ctx = `Session context:\n${header.join('\n')}\n\n`;
+  return ctx + FEATURE_INTEGRATE_BODY;
+}
+
+module.exports = {
+  title: 'Feature Integrate',
+  body: FEATURE_INTEGRATE_BODY,
+  buildPrompt: buildFeatureIntegratePrompt
+};

package/lib/templates/kickoff-schema.json

@@ -0,0 +1,75 @@
+{
+  "version": "1.0",
+  "description": "Single source of truth for the feature-kickoff phase shape. Shared by scripts/knoxis-helper/lib/templates/feature-kickoff.js (operator-facing prompt) and src/main/java/com/yourcompany/voice/service/kickoffprep/* (server-side meeting → kickoff-prep generator). Both read these constraints to keep the JSON shape consistent and prevent drift.",
+
+  "slug": {
+    "pattern": "^[a-z0-9][a-z0-9-]{0,39}$",
+    "maxLength": 40,
+    "rules": [
+      "Lowercase alphanumeric and dashes only.",
+      "Max 40 characters.",
+      "Semantically descriptive of the feature.",
+      "Do not include the words 'feature' or 'task'."
+    ],
+    "examples": [
+      { "description": "Add real-time notification toasts", "slug": "realtime-notification-toasts" },
+      { "description": "Replace polling with SSE on the dashboard", "slug": "dashboard-sse-replacement" }
+    ]
+  },
+
+  "phases": {
+    "minCount": 3,
+    "maxCount": 6,
+    "stepsPerPhase": { "min": 2, "max": 6 },
+    "rules": [
+      "Phases run sequentially.",
+      "Each phase has a clear 'done when' criterion.",
+      "Each step is one imperative-voice action plus the file(s) or surface it touches.",
+      "Steps must be small enough to ship in one pair-program session.",
+      "Don't pad. A 4-step feature is fine. A 30-step feature with 3 phases of filler is not."
+    ],
+    "defaultShape": [
+      { "title": "Discovery",      "goal": "Read existing code, find integration points, list constraints" },
+      { "title": "Design",         "goal": "Data model / API contract / UI shape decisions" },
+      { "title": "Implementation", "goal": "Commit-sized steps, each touching named files" },
+      { "title": "Testing",        "goal": "Unit / integration / manual coverage" },
+      { "title": "Rollout",        "goal": "Feature flag, docs, telemetry, deprecations" }
+    ]
+  },
+
+  "openQuestions": {
+    "guidance": "Capture genuine open questions only. Most 'questions' are decisions you should make and capture in DECISIONS instead. If you write more than 3 pending questions you are over-using this.",
+    "softMax": 3
+  },
+
+  "manifestShape": {
+    "feature_slug": "string (matches slug.pattern)",
+    "feature_title": "string",
+    "parent_task_id": "string | null",
+    "workspace_id": "string | null",
+    "user_id": "string | null",
+    "product_slug": "string | null",
+    "project_slug": "string | null",
+    "kicked_off_at": "ISO timestamp",
+    "status": "planning | blocked | in-progress | done",
+    "current_phase": "string (phase id, e.g. phase-1)",
+    "phases": [
+      {
+        "id": "string (phase-{n})",
+        "title": "string",
+        "goal": "string",
+        "done_when": "string",
+        "status": "pending | in-progress | done",
+        "steps": [
+          {
+            "id": "string (phase-{n}-step-{m})",
+            "action": "string (imperative)",
+            "touches": "string (file or surface)",
+            "status": "pending | in-progress | done"
+          }
+        ]
+      }
+    ],
+    "definition_of_done": ["string"]
+  }
+}

package/lib/templates/session-end.js

@@ -345,6 +345,68 @@ For specific archetypes, populate \`archetype_specific_data\`:
 
 Show me. Ask: "Paste this into the portal, or wait for portal MCP to upload it automatically (if live)?"
 
+## Step 9.5 — Auto-integrate eligible features (opt-in features only)
+
+**Orientation:** "If any feature in this project opted into auto-doc generation
+by including a \`phase-integrate\` phase, and that phase is now eligible to
+run, generate its public API doc here so the next session opens with it
+already shipped."
+
+For each \`docs/features/*/manifest.json\`, check whether **all three** are true:
+
+1. A phase exists with \`id: "phase-integrate"\`.
+2. That phase's \`status\` is \`"pending"\`.
+3. Every phase before it has \`status: "done"\`.
+
+If no manifest meets all three, say "No features are eligible for auto-integrate
+this session." and skip to Step 10.
+
+For each eligible feature, run the integrate playbook autonomously (you do not
+need a separate command — execute the steps inline now):
+
+1. Read the controllers listed in the feature's \`phases[].steps[].touches\` —
+   anything under \`src/main/java/com/yourcompany/voice/controller/\`.
+2. (Best effort) Fetch \`http://localhost:8080/v3/api-docs\` to enrich with live
+   request/response schemas. If unreachable, skip and use the controller source
+   directly. Don't fail the step on this.
+3. Generate \`docs/features/<slug>/PUBLIC_API.md\` matching the structure and
+   tone of \`docs/PUBLIC_VOICE_API.md\` and \`docs/PUBLIC_SPEAKER_API.md\`.
+   Sections: title + 2-3 sentence summary, 60-second quickstart, endpoint
+   table, authentication, per-endpoint request/response, error reference,
+   limits, footer.
+4. Update the feature's \`manifest.json\`: \`phase-integrate\` → \`status: "done"\`,
+   each step within → \`status: "done"\`, advance \`current_phase\` past it.
+5. Mirror the status changes into \`docs/features/<slug>/STATUS.md\` and
+   \`docs/features/<slug>/PHASES.md\` (check the boxes).
+6. **Best-effort vectorization.** If \`KNOXIS_TENANT_ID\` is set in the
+   environment, POST the generated markdown to:
+
+   \`\`\`
+   POST $BACKEND/api/public/integration-docs/index
+   Headers: Content-Type: application/json
+            X-Tenant-Id: $KNOXIS_TENANT_ID
+            X-Public-Voice-Key: $PUBLIC_VOICE_API_SHARED_KEY (if set)
+   Body:    { "slug": "<slug>", "markdown": "<file contents>" }
+   \`\`\`
+
+   Default \`BACKEND\` to \`http://localhost:8080\`. If the call fails with a
+   non-2xx, **don't fail the session** — note "Vectorization deferred (HTTP
+   <code>); operator can re-run via knoxis-helper --mode feature-integrate
+   --prompt <slug>." and move on. The doc is on disk regardless.
+
+For each feature you processed, output:
+
+\`\`\`
+Auto-integrated: <slug>
+  PUBLIC_API.md: <created | refreshed>
+  manifest.json: phase-integrate → done
+  Vectorization:  <success | skipped (no tenant) | deferred (HTTP <code>)>
+\`\`\`
+
+Do not run integrate logic on features where the conditions aren't met. Don't
+add a \`phase-integrate\` to features that didn't have one — operator opt-in
+is sticky.
+
 ## Step 10 — Final summary
 
 Print a one-paragraph summary:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knoxis-helper",
-  "version": "1.8.2",
+  "version": "1.8.3",
   "description": "Local helper for Knoxis pair programming - connects your machine to Knoxis on qig.ai",
   "bin": {
     "knoxis-helper": "./bin/knoxis-helper.js"