@higrowth/cli 0.3.2 → 0.3.3

package/dist/index.js

@@ -703,7 +703,7 @@ just say which one \u2014 you don't have to redo the whole interview."*
 // src/skills/marketing-strategy.ts
 var MARKETING_STRATEGY = `---
 name: higrowth-marketing-strategy
-description: Helps the user interpret a Higrowth diagnostic, choose a bounded scoped-plan area, and shape the next 2-4 week sprint. Use when the user wants to talk through their report, decide what to ship, ask what can be fixed in an area, or plan.
+description: Helps the user interpret a Higrowth diagnostic, choose a bounded scoped-plan area, review imagination hypotheses, and shape the next 2-4 week sprint. Use when the user wants to talk through their report, decide what to ship, ask what can be fixed in an area, or plan.
 allowed-tools: mcp__higrowth__execute_typescript
 ---
 
@@ -725,7 +725,20 @@ Plans are not giant backlogs. A good plan is a scoped intervention:
 one topic area, page cluster, gap type, or conversion slice with enough
 evidence to act and narrow enough boundaries to avoid conflicting work.
 
-Rank by **leverage and executability**, not raw opportunity count.
+The planning stack has four layers:
+
+1. **Answer map** \u2014 what questions the site answers for which persona
+   and decision stage.
+2. **Decision candidates** \u2014 executable moves grounded in answer cells,
+   gaps, GSC, GA, strategy, and conflict checks.
+3. **Imagination candidates** \u2014 adjacent hypotheses HG can infer from
+   weak or missing answers. They are ideas only.
+4. **Scoped plans** \u2014 a small selected scope that generates execution
+   items from decision candidates.
+
+Rank by **leverage, evidence, and executability**, not raw opportunity count.
+Never create work orders directly from imagination candidates. Promote
+good imagination candidates into decision candidates first, then plan.
 
 ## The conversation
 
@@ -745,41 +758,142 @@ Anything missing or recently changed?"*
 Use the answer to steer scope selection. Recent launches, product
 changes, seasonality, and sales priorities should shape what you plan.
 
-### Step 2 \u2014 Choose a bounded area
+### Step 2 \u2014 Resolve the topic or area
 
 If the user named an area, use it as the scope query. If not, help them
 pick one from the diagnostic: a pillar, subtopic, page cluster, gap type,
 or conversion issue.
 
+Find the most likely topic/pillar id before generating plans. Use the
+current API surface available in the MCP harness; if the harness exposes
+topic search, use it. If not, use scoped candidates with the user's query
+and read the returned \`topicId\`.
+
 \`\`\`ts
 const q = userIntent || 'highest leverage scoped fixes';
+const firstPass = await api.get(
+  \`/api/entities/\${entityId}/plan-scopes/candidates?q=\${encodeURIComponent(q)}&limit=8&maxItems=8\`
+);
+const topicId = firstPass.candidates.find(c => c.topicId)?.topicId;
+\`\`\`
+
+### Step 3 \u2014 Check source signal before planning
+
+Do not jump straight to a plan if the answer map and decision registry
+are empty. HG should reason from the rich signal it already gathered.
+
+\`\`\`ts
+const answerSummary = topicId
+  ? await api.get(\`/api/entities/\${entityId}/answer-map/summary?topicId=\${topicId}\`)
+  : null;
+console.log(answerSummary?.summary);
+\`\`\`
+
+If the summary has no cells, compute it:
+
+\`\`\`ts
+if (topicId && (!answerSummary || answerSummary.summary.totalCells === 0)) {
+  await api.post(\`/api/entities/\${entityId}/answer-map/compute\`, {
+    topicId,
+    limit: 500,
+  });
+}
+\`\`\`
+
+Then refresh decision candidates for the topic or page slice:
+
+\`\`\`ts
+await api.post(\`/api/entities/\${entityId}/decision-candidates/refresh\`, {
+  topicId,
+  limit: 500,
+});
+
+const decisions = await api.get(
+  \`/api/entities/\${entityId}/decision-candidates?topicId=\${topicId}&status=candidate&limit=50\`
+);
+console.log(decisions.candidates.slice(0, 10));
+\`\`\`
+
+If answer-map compute still returns little or no signal, say so. The
+right prerequisite may be a scan, GSC/GA connection, KB population, or
+pillar analysis. Do not fabricate a strategic plan from thin data.
+
+### Step 4 \u2014 Use imagination only when useful
+
+When the user asks "what else could we do here?", "what are we missing?",
+or the decision registry feels too narrow, generate imagination
+candidates. This is HG's ideation layer: adjacent questions and content
+angles extrapolated from answer-map gaps.
+
+\`\`\`ts
+const imagination = await api.post(
+  \`/api/entities/\${entityId}/imagination-candidates/generate\`,
+  { topicId, limit: 20 }
+);
+console.log(imagination.candidates);
+\`\`\`
+
+Review these critically with the user. Reject weak, duplicate, or noisy
+hypotheses:
+
+\`\`\`ts
+await api.post(\`/api/entities/\${entityId}/imagination-candidates/\${id}/reject\`, {
+  reason: 'Duplicate of an existing page angle',
+});
+\`\`\`
+
+Promote only the best 1-3 ideas. Promotion creates decision candidates;
+it still does not create work orders or plan items.
+
+\`\`\`ts
+const promoted = await api.post(
+  \`/api/entities/\${entityId}/imagination-candidates/\${id}/promote\`
+);
+console.log(promoted.candidate);
+\`\`\`
+
+After promotion, re-run scoped candidates so promoted ideas can compete
+with observed-gap candidates.
+
+### Step 5 \u2014 Choose a bounded scope
+
+\`\`\`ts
 const candidates = await api.get(
-  \`/api/entities/\${entityId}/plan-scopes/candidates?q=\${encodeURIComponent(q)}&limit=6&maxItems=8\`
+  \`/api/entities/\${entityId}/plan-scopes/candidates?q=\${encodeURIComponent(q)}&limit=8&maxItems=8\`
 );
 \`\`\`
 
 Show the top 3 candidates with:
 - label
 - scope type
-- pages and gaps included
+- pages, gaps, answer cells, and decision candidates included
+- personas and decision stages if present
 - expected outcome
 - conflict state and warnings
 - why you prefer one
 
+Prefer scopes that are:
+- decision-backed
+- page-bounded or small topic-bounded
+- clear about persona x decision stage x question
+- conflict-clear
+- commercially or strategically meaningful
+
 If every candidate is weak, broaden the query once. If candidates are
 still thin, say the source data is missing and suggest the prerequisite
-connection or scan.
+connection, scan, or KB work.
 
-### Step 3 \u2014 Inspect conflicts before committing
+### Step 6 \u2014 Inspect conflicts before committing
 
 Never stage a scope blindly. Use preview when the user is leaning toward
 a candidate or asks why it is safe.
 
+Convert the candidate to a full scope without dropping the evidence
+bindings:
+
 \`\`\`ts
-const selected = candidates.candidates[0];
-const preview = await api.post(\`/api/entities/\${entityId}/plan-scopes/preview\`, {
-  selectedBy: 'agent',
-  scope: {
+function toScope(selected) {
+  return {
     version: 1,
     selectedAt: new Date().toISOString(),
     selectedBy: 'agent',
@@ -791,12 +905,29 @@ const preview = await api.post(\`/api/entities/\${entityId}/plan-scopes/preview\
     subtopicIds: selected.subtopicIds,
     pageIds: selected.pageIds,
     gapIds: selected.gapIds,
+    answerCellIds: selected.answerCellIds ?? [],
+    decisionCandidateIds: selected.decisionCandidateIds ?? [],
+    primaryPersonaIds: selected.primaryPersonaIds ?? [],
+    decisionStages: selected.decisionStages ?? [],
+    scopeThesis: selected.scopeThesis ?? null,
     analysisTypes: selected.analysisTypes,
-    includedSignals: ['gap_inventory', ...selected.analysisTypes],
+    includedSignals: [
+      'gap_inventory',
+      'answer_map',
+      'decision_candidates',
+      ...selected.analysisTypes,
+    ],
     excludedAdjacentScopes: [],
     reasonForScope: selected.whyThisScope,
     expectedOutcome: selected.expectedOutcome,
-  },
+  };
+}
+
+const selected = candidates.candidates[0];
+const preview = await api.post(\`/api/entities/\${entityId}/plan-scopes/preview\`, {
+  selectedBy: 'agent',
+  userIntent: q,
+  scope: toScope(selected),
 });
 \`\`\`
 
@@ -806,7 +937,20 @@ the overlap and pick another scope.
 If preview returns warnings, ask for explicit user acceptance before
 creating. Warnings are allowed only when the user understands the overlap.
 
-### Step 4 \u2014 Create the scoped plan
+### Step 7 \u2014 Clean old plans only with approval
+
+If the user says old plans are conflicting, list them first and ask
+before deleting. Do not silently remove plans.
+
+\`\`\`ts
+const existing = await api.get(\`/api/plans?entityId=\${entityId}\`);
+console.log(existing.plans.map(p => ({ id: p.id, name: p.name, status: p.status })));
+
+// After explicit user approval:
+await Promise.all(existing.plans.map(p => api.delete(\`/api/plans/\${p.id}\`)));
+\`\`\`
+
+### Step 8 \u2014 Create the scoped plan
 
 Create from the selected scope. Do not use legacy topic-plan or
 opportunity-basket endpoints.
@@ -823,7 +967,7 @@ const plan = await api.post(\`/api/entities/\${entityId}/plans/from-scope\`, {
 });
 \`\`\`
 
-### Step 5 \u2014 Generate scoped items
+### Step 9 \u2014 Generate scoped items
 
 \`\`\`ts
 const generation = await api.post(\`/api/plans/\${plan.plan.id}/generate-scoped\`);
@@ -831,14 +975,24 @@ console.log(generation);
 \`\`\`
 
 Generation must stay inside the selected scope. It should claim only
-the gaps and pages in the scope, carry conflict warnings into the audit,
-and return deferred or not-recommended items instead of stretching the
-scope to look productive.
+the gaps and pages in the scope, cite \`decisionCandidateIds\`, carry
+conflict warnings into the audit, and return deferred or not-recommended
+items instead of stretching the scope to look productive.
+
+After generation, read the plan and verify it stayed grounded:
+
+\`\`\`ts
+const detail = await api.get(\`/api/plans/\${plan.plan.id}\`);
+console.log(detail.items.map(i => ({
+  title: i.title,
+  bundle: i.bundleJson,
+})));
+\`\`\`
 
-After generation, send the user to the plan detail. Explain what to
-review and which first 1-3 items are safest to move into execution.
+Explain what to review and which first 1-3 items are safest to move into
+execution.
 
-### Step 6 \u2014 Set expectations
+### Step 10 \u2014 Set expectations
 
 End with reality:
 
@@ -849,20 +1003,29 @@ End with reality:
 ## Strong opinions to bring
 
 - **One bounded scope per plan.** Always.
+- **Decision candidates are the execution menu.** If a plan ignores them,
+  stop and investigate.
+- **Imagination is hypothesis generation.** Promote it before planning;
+  never execute it directly.
 - **Prefer conflict-clear scopes.** Warning scopes require explicit user acceptance.
-- **Use the signal, not the URL.** Match on topic, page summaries, gap evidence,
-  GSC, GA, AEO, conversion, and strategy context.
+- **Use the signal, not the URL.** Match on topic, page summaries, answer
+  cells, gap evidence, GSC, GA, AEO, conversion, and strategy context.
 - **Small is fine.** A plan with 3 high-confidence page items can beat a giant backlog.
 - **Don't promise CTR lift in week 1.** The data takes 14 days.
 - **Inconclusive is not failed.** Many outcomes need another window.
-- **Archive old/conflicting plans.** Open-ended plans become graveyards.
+- **Archive old/conflicting plans only with approval.** Open-ended plans
+  become graveyards, but deleting them is still destructive.
 
 ## What success looks like
 
+- Source signal checked
+- Decision candidates refreshed
+- Imagination candidates reviewed when useful
 - One bounded scope picked
 - Conflicts reviewed
 - One scoped plan created
 - Scoped generation run
+- Generated items cite decision candidates
 - First execution items are obvious
 - User knows when to come back: 14 days for outcomes, sooner for approvals
 
@@ -874,7 +1037,12 @@ End with reality:
   or \`POST /api/plans/:id/generate-topic\`.
 - Don't sort opportunities by score and list the top 10. That's not strategy.
 - Don't let URLs alone classify scope. Use the evidence Higrowth gathered.
+- Don't drop \`answerCellIds\`, \`decisionCandidateIds\`, \`primaryPersonaIds\`,
+  \`decisionStages\`, or \`scopeThesis\` when previewing or creating a scope.
 - Don't create a plan that overlaps blocked active work.
+- Don't create work orders from imagination candidates.
+- Don't run a new scan by default. Check answer map, decision candidates,
+  GSC, GA, and KB first; scan only when source signal is missing or stale.
 - Don't gloss over the KB. If the KB is empty, stop and run the
   populate-kb playbook first. Strategy without KB context is generic.
 `;
@@ -1305,7 +1473,7 @@ function beginUpdateCheck(currentVersion) {
 // package.json
 var package_default = {
   name: "@higrowth/cli",
-  version: "0.3.2",
+  version: "0.3.3",
   description: "Higrowth CLI \u2014 log in via browser, install Claude Code / Codex skills, manage the MCP connection.",
   type: "module",
   license: "Apache-2.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@higrowth/cli",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Higrowth CLI — log in via browser, install Claude Code / Codex skills, manage the MCP connection.",
   "type": "module",
   "license": "Apache-2.0",