@ashlr/hub 2.2.0

package/dist/core/goals/planner.js

@@ -0,0 +1,233 @@
+/**
+ * planner.ts — M28: deterministic-by-default decomposition of an OBJECTIVE
+ * into ordered MILESTONES, and per-milestone spec authoring.
+ *
+ * SAFETY / DESIGN (see docs/contracts/CONTRACT-M28.md):
+ *  - LOCAL-FIRST: decomposeGoal is DETERMINISTIC by default (a heuristic split
+ *    — NO LLM, ZERO network). Optional LLM-assisted refinement routes ONLY
+ *    through getActiveClient(cfg, { allowCloud }) — local Ollama/LM Studio
+ *    unless --allow-cloud + a configured key (mirrors M25/M26/M27). The default
+ *    path makes ZERO non-localhost connections.
+ *  - BOUNDED: the number of milestones is hard-capped by maxMilestones.
+ *  - NO OUTWARD ACTION: planning NEVER runs a swarm, NEVER touches a user repo
+ *    working tree, NEVER pushes/PRs/deploys. planMilestoneSpec authors a spec
+ *    via spec-store (writes ONLY under the spec store, never a user tree).
+ *  - No new runtime deps; node builtins + existing modules only.
+ */
+import { createHash } from 'node:crypto';
+import { authorSpec } from '../spec/spec-store.js';
+import { getActiveClient } from '../run/provider-client.js';
+/**
+ * FIXED stable epoch for decomposed-but-not-yet-persisted milestones. Using a
+ * constant (NOT Date.now()) keeps decomposeGoal byte-identical across runs for
+ * a given input — the determinism the contract + tests require. The store
+ * stamps real timestamps when it materializes a milestone (addMilestone).
+ */
+const STABLE_EPOCH = '1970-01-01T00:00:00.000Z';
+/** Lowercase, hyphenated, alnum-only slug (mirrors the store/spec-store slug). */
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .trim()
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .slice(0, 32)
+        .replace(/-$/, '');
+}
+/**
+ * Deterministic, unique-within-the-objective milestone id derived from the
+ * order + title (+ a short content hash). Stable across runs; no clock, no
+ * randomness. The store replaces this with its own `${goalId}-m<order>` id on
+ * persistence — this id only needs to be unique within a single decompose call.
+ */
+function stableMilestoneId(order, title) {
+    const hash = createHash('sha256').update(`${order}:${title}`).digest('hex').slice(0, 6);
+    const slug = slugify(title) || 'milestone';
+    return `m${order}-${slug}-${hash}`;
+}
+// ---------------------------------------------------------------------------
+// Bounds
+// ---------------------------------------------------------------------------
+/** Hard default cap on milestones produced from one objective. */
+const DEFAULT_MAX_MILESTONES = 8;
+/** Absolute ceiling regardless of caller-supplied maxMilestones. */
+const HARD_MAX_MILESTONES = 16;
+/** Standard phase scaffold applied to a single-clause objective (no explicit steps). */
+const STANDARD_PHASES = [
+    { title: 'Design', detail: 'Clarify scope, constraints, and acceptance criteria.' },
+    { title: 'Implement', detail: 'Build the core functionality to satisfy the objective.' },
+    { title: 'Test', detail: 'Add focused tests and verify behavior end-to-end.' },
+    { title: 'Document', detail: 'Document the change and update any relevant references.' },
+];
+// ---------------------------------------------------------------------------
+// decomposeGoal
+// ---------------------------------------------------------------------------
+/**
+ * Decompose a high-level `objective` into an ordered list of Milestones.
+ *
+ * DEFAULT (local, deterministic): split the objective into a bounded sequence
+ * of ordered milestones using a pure heuristic (numbered-list / "then" /
+ * sentence segmentation, plus a standard scaffold of phases when the objective
+ * is a single clause). NO model is called; ZERO network.
+ *
+ * OPTIONAL (opts.allowCloud): refine the deterministic split's titles/details
+ * via getActiveClient(cfg, { allowCloud }) — local-first; cloud only with a
+ * configured key. Refinement NEVER increases the count beyond the cap and
+ * falls back to the deterministic split on any model error.
+ *
+ * Returns plain Milestone[] (status 'pending', specId/swarmId/proposalId null,
+ * order assigned 0..n). Does NOT persist — the caller (store.addMilestone /
+ * the CLI `goals plan`) materializes them. Bounded by
+ * min(opts.maxMilestones ?? DEFAULT_MAX_MILESTONES, HARD_MAX_MILESTONES).
+ * Never throws.
+ */
+export async function decomposeGoal(objective, cfg, opts) {
+    const cap = Math.max(1, Math.min(opts?.maxMilestones ?? DEFAULT_MAX_MILESTONES, HARD_MAX_MILESTONES));
+    const deterministic = deterministicSplit(objective, cap);
+    let parts = deterministic;
+    // OPTIONAL local-first refinement. Default path NEVER reaches here.
+    if (opts?.allowCloud) {
+        try {
+            const refined = await refineWithModel(objective, deterministic, cfg, true);
+            // COUNT-PRESERVING: a refinement that changes the milestone count is
+            // discarded (we keep the deterministic split). This keeps the plan's
+            // shape under the human's control and guards against a hallucinated
+            // expansion/collapse.
+            parts = refined.length === deterministic.length ? refined : deterministic;
+        }
+        catch {
+            // Any model error => keep the deterministic split (local-first fallback).
+            parts = deterministic;
+        }
+    }
+    return parts.slice(0, cap).map((p, i) => ({
+        id: stableMilestoneId(i, p.title),
+        title: p.title,
+        detail: p.detail,
+        order: i,
+        status: 'pending',
+        specId: null,
+        swarmId: null,
+        proposalId: null,
+        createdAt: STABLE_EPOCH,
+        updatedAt: STABLE_EPOCH,
+    }));
+}
+/**
+ * Pure, deterministic, local-only split of an objective into <= cap milestone
+ * titles. NO model, NO network. Stable across runs for a given input.
+ *
+ * Strategy (first that yields >1 segment wins):
+ *   1. Numbered / bulleted list items ("1.", "2)", "- ", "* ").
+ *   2. Explicit step separators ("then", ";", newline).
+ *   3. Sentence boundaries.
+ *   4. Single clause => the STANDARD_PHASES scaffold.
+ */
+function deterministicSplit(objective, cap) {
+    const text = objective.trim();
+    if (text.length === 0) {
+        return STANDARD_PHASES.slice(0, cap);
+    }
+    // 1. Numbered / bulleted list items.
+    const listItems = text
+        .split(/\r?\n/)
+        .map((l) => l.replace(/^\s*(?:\d+[.)]|[-*])\s+/, '').trim())
+        .filter((l) => l.length > 0);
+    const hadListMarkers = /(?:^|\n)\s*(?:\d+[.)]|[-*])\s+/.test(text);
+    if (hadListMarkers && listItems.length > 1) {
+        return toParts(listItems, cap);
+    }
+    // 2. Explicit step separators: " then ", " finally ", " next ", ";", newlines.
+    const stepParts = text
+        .split(/\s*;\s*|\s+then\s+|\s+finally\s+|\s+next\s+|\r?\n+/i)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (stepParts.length > 1) {
+        return toParts(stepParts, cap);
+    }
+    // 3. Sentence boundaries.
+    const sentences = text
+        .split(/(?<=[.!?])\s+/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (sentences.length > 1) {
+        return toParts(sentences, cap);
+    }
+    // 4. Single clause => standard phase scaffold.
+    return STANDARD_PHASES.slice(0, cap);
+}
+/** Build {title, detail} parts from raw segments: title is the segment trimmed to a short line. */
+function toParts(segments, cap) {
+    return segments.slice(0, cap).map((seg) => {
+        const clean = seg.replace(/^[.\s]+/, '').replace(/[.\s]+$/, '');
+        const title = clean.length > 72 ? `${clean.slice(0, 69)}...` : clean;
+        return { title: title || 'Milestone', detail: clean };
+    });
+}
+/**
+ * OPTIONAL refinement of the deterministic split via the active local-first
+ * provider. Returns refined parts on success, or throws (the caller falls back
+ * to the deterministic split). NEVER increases the count beyond `cap`. The
+ * provider chain is local unless allowCloud + a configured key (enforced by
+ * getActiveClient itself).
+ */
+async function refineWithModel(objective, parts, cfg, allowCloud) {
+    const client = await getActiveClient(cfg, { allowCloud });
+    const sys = 'You refine a software objective into a concise, ordered list of milestones. ' +
+        'Return STRICT JSON: an array of objects {"title": string, "detail": string}. ' +
+        `Return EXACTLY ${parts.length} items, in the same order. No prose, no code fences.`;
+    const usr = `Objective:\n${objective}\n\n` +
+        `Current draft milestones (refine titles/details, keep ordering, do not add count):\n` +
+        parts.map((p, i) => `${i + 1}. ${p.title} — ${p.detail}`).join('\n');
+    const res = await client.chat([
+        { role: 'system', content: sys },
+        { role: 'user', content: usr },
+    ]);
+    const parsed = JSON.parse(stripFences(res.content));
+    if (!Array.isArray(parsed))
+        throw new Error('model did not return an array');
+    const refined = parsed
+        .filter((x) => typeof x === 'object' && x !== null && typeof x.title === 'string')
+        .map((x) => ({ title: String(x.title), detail: String(x.detail ?? '') }));
+    if (refined.length === 0)
+        throw new Error('model returned no usable milestones');
+    return refined;
+}
+/** Strip an accidental ```json fence the model might wrap JSON in. */
+function stripFences(s) {
+    return s
+        .trim()
+        .replace(/^```(?:json)?\s*/i, '')
+        .replace(/\s*```$/i, '')
+        .trim();
+}
+// ---------------------------------------------------------------------------
+// planMilestoneSpec
+// ---------------------------------------------------------------------------
+/**
+ * Author (or link) a versioned SpecArtifact for a single milestone of a goal.
+ *
+ * Delegates to spec-store.authorSpec(goal-derived-prompt, cfg, { project }),
+ * which is local-first and idempotent (v1 is reused if it already exists).
+ * The authored spec is scoped to the goal's `project` when set. Returns the
+ * SpecArtifact so the caller can persist milestone.specId = artifact.id via
+ * store.updateMilestoneStatus.
+ *
+ * NEVER runs a swarm and NEVER touches a user repo working tree — authorSpec
+ * only writes to the spec store (project/.ashlr/specs or ~/.ashlr/specs).
+ *
+ * LOCAL-FIRST: `opts.allowCloud` is threaded straight into authorSpec and
+ * defaults to FALSE, so the no-flag `goals plan` path can NEVER reach a cloud
+ * provider for spec authoring even when a cloud provider sits in the configured
+ * providerChain (closing the default-path cloud-egress gap). Cloud authoring
+ * happens ONLY when the user explicitly passed --allow-cloud.
+ */
+export async function planMilestoneSpec(goal, milestone, cfg, opts) {
+    const goalText = `${goal.objective} — milestone: ${milestone.title}\n${milestone.detail}`;
+    return authorSpec(goalText, cfg, {
+        ...(goal.project ? { project: goal.project } : {}),
+        allowCloud: opts?.allowCloud ?? false,
+    });
+}
+//# sourceMappingURL=planner.js.map

package/dist/core/goals/planner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.js","sourceRoot":"","sources":["../../../src/core/goals/planner.ts"],"names":[],"mappings":"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"}

package/dist/core/goals/store.d.ts

@@ -0,0 +1,128 @@
+/**
+ * store.ts — M28: Goal record persistence for `ashlr goals`.
+ *
+ * Persists one Goal per file at ~/.ashlr/goals/<id>.json (atomic write-then-
+ * rename), mirroring the learn/quality/inbox store pattern.
+ *
+ * GUARDRAILS (paramount — see docs/contracts/CONTRACT-M28.md):
+ *  - PURE PERSISTENCE / READ-MOSTLY: this module NEVER runs a swarm, NEVER
+ *    authors a spec, NEVER touches a user repo working tree, NEVER emits an
+ *    outward action (no applyProposal, no setStatus(approved), no git push, no
+ *    createPr, no deploy). It only reads/writes JSON under ~/.ashlr/goals/.
+ *  - LOCAL-FIRST: writes ONLY under ~/.ashlr/goals/. Zero network.
+ *  - Atomic write: <id>.json.tmp then rename (POSIX-atomic).
+ *  - Never throws on read paths: list/load swallow errors and return safe
+ *    defaults ([] / null) so callers remain unblocked.
+ *  - No secrets stored: Goal/Milestone carry metadata + ids only.
+ *  - No new runtime deps; node builtins only.
+ */
+import type { Goal, GoalStatus, Milestone, MilestoneStatus } from '../types.js';
+import { goalsDir } from '../config.js';
+export { goalsDir };
+/**
+ * Create a new Goal from an objective, persist it, and return it.
+ *
+ * Assigns a fresh id, status 'planning', empty milestones, and createdAt/
+ * updatedAt timestamps. `project` (when given) MUST already be a resolved,
+ * ENROLLED absolute repo path — enrollment is enforced by the CLI/advance
+ * path, NOT here; this is pure persistence.
+ *
+ * NEVER runs a swarm, authors a spec, or emits an outward action. Best-effort
+ * persistence (returns the in-memory Goal even if the write fails).
+ */
+export declare function createGoal(objective: string, opts?: {
+    project?: string | null;
+    now?: string;
+}): Goal;
+/**
+ * Load a single Goal by id. Returns null when absent, unreadable, or malformed.
+ * Read-only. Never throws.
+ */
+export declare function loadGoal(id: string): Goal | null;
+/**
+ * List all persisted Goals, most-recent first by updatedAt (bounded MAX_LIST).
+ * Skips .tmp sidecars and unreadable/corrupt files. Read-only. Never throws.
+ */
+export declare function listGoals(filter?: {
+    status?: GoalStatus;
+}): Goal[];
+/**
+ * Persist a Goal record atomically (tmp-write + rename). Bumps updatedAt.
+ * Best-effort; never throws (mirrors the swarm/inbox stores).
+ */
+export declare function saveGoal(goal: Goal, opts?: {
+    now?: string;
+}): void;
+/**
+ * Delete a Goal record by id. Idempotent — deleting an absent goal is a no-op.
+ * Pure FS under ~/.ashlr/goals; never touches a user repo. Never throws.
+ */
+export declare function deleteGoal(id: string): void;
+/**
+ * Append a new Milestone to a Goal (status 'pending', specId/swarmId/proposalId
+ * null) at the end of the current order. Returns the updated Goal, or null if
+ * the goal does not exist. Used by planner.decomposeGoal to materialize a plan.
+ */
+export declare function addMilestone(goalId: string, milestone: Pick<Milestone, 'title' | 'detail'>, opts?: {
+    now?: string;
+}): Goal | null;
+/**
+ * Set a milestone's status (and optionally link swarmId/proposalId/specId).
+ * This is the ONLY way the advance path records progress (pending ->
+ * in-progress -> proposed, or -> blocked). Returns the updated Goal, or null
+ * if not found.
+ *
+ * NOTE: this mutates the M28 Goal record ONLY — it NEVER calls inbox setStatus
+ * and NEVER approves/applies the linked proposal.
+ */
+export declare function updateMilestoneStatus(goalId: string, milestoneId: string, status: MilestoneStatus, link?: {
+    swarmId?: string | null;
+    proposalId?: string | null;
+    specId?: string | null;
+    now?: string;
+}): Goal | null;
+/**
+ * Clear ALL of a goal's milestones, returning it to a fresh, unplanned state
+ * (status re-rolled to 'planning'). Used by the CLI `goals plan --replace` to
+ * support an explicit, destructive re-plan WITHOUT duplicating the milestone
+ * set. Pure local edit under ~/.ashlr/goals — never runs a swarm, never touches
+ * a user repo, never approves/applies a proposal. Returns the updated Goal, or
+ * null if not found.
+ */
+export declare function clearMilestones(goalId: string, opts?: {
+    now?: string;
+}): Goal | null;
+/**
+ * Reorder a goal's milestones to match the given id sequence (any ids omitted
+ * keep their relative order after the listed ones). Rewrites `order` keys and
+ * re-sorts. Returns the updated Goal, or null if not found.
+ */
+export declare function reorderMilestones(goalId: string, orderedIds: string[], opts?: {
+    now?: string;
+}): Goal | null;
+/**
+ * Pause a single milestone (status 'paused') or, when milestoneId is omitted,
+ * pause the WHOLE goal (goal.status 'paused' — no milestone advances). A paused
+ * milestone is skipped by nextActionableMilestone(). Returns updated Goal/null.
+ */
+export declare function pauseMilestone(goalId: string, milestoneId?: string, opts?: {
+    now?: string;
+}): Goal | null;
+/**
+ * Resume a milestone back to 'pending' or, when milestoneId is omitted, resume
+ * the WHOLE goal (re-roll goal.status). A milestone is resumable when it is
+ * 'paused' (human steering) OR 'blocked' (a prior advance that threw / needs
+ * recovery) — both transition back to 'pending' so it can be re-advanced. This
+ * is the recovery path out of the 'blocked' state the advance error-handler
+ * sets. Returns updated Goal/null.
+ */
+export declare function resumeMilestone(goalId: string, milestoneId?: string, opts?: {
+    now?: string;
+}): Goal | null;
+/**
+ * Skip a milestone permanently (status 'skipped'); it is excluded from progress
+ * denominators and never advanced. Returns updated Goal, or null if not found.
+ */
+export declare function skipMilestone(goalId: string, milestoneId: string, opts?: {
+    now?: string;
+}): Goal | null;