document360-writer 0.5.73 → 0.5.75

package/dist/commands/catchup.d.ts

@@ -5,9 +5,10 @@ export type PendingSummary = {
     hints: number;
     requests: number;
     answers: number;
+    directives: number;
 };
-/** Deterministic local counts of queued work (hints + builder messages). Drift is network and is
-    checked by the agent via d360_sync_status inside the prompt, not here. */
+/** Deterministic local counts of queued work (hints + builder messages + owner directives). Drift is
+    network and is checked by the agent via d360_sync_status inside the prompt, not here. */
 export declare function pendingSummary(cwd: string): PendingSummary;
 /** A short human phrase for a pending summary, or null when nothing local is queued. */
 export declare function pendingLine(s: PendingSummary): string | null;

package/dist/commands/devhints.d.ts

@@ -13,8 +13,13 @@ import type { ReplContext } from '../repl.js';
  *   v6 → make the hand-off VISIBLE + state the boundary: the builder surfaces every hint drop in its
  *        reply (never silently) and NEVER writes/publishes the user docs itself — that's the docs agent's
  *        job. Keeps the dogfood/limitation signal honest and lets a human verify the hand-off happens.
+ *   v7 → owner→docs directives channel: when the human types `@d360-writer <directive>` in the builder's
+ *        session (a proactive doc ask like "document /review"), the builder APPENDS it as an `## [open]`
+ *        block to `.d360-writer/directives.md` (create if absent) and commits — it does NOT action it
+ *        (writing docs is the docs agent's job; it picks it up on its next /catch-up). The third comms
+ *        channel, alongside builder hints/messages and portal feedback.
  */
-export declare const DEVHINTS_VERSION = 6;
+export declare const DEVHINTS_VERSION = 7;
 /**
  * The committed protocol guide the SOURCE repo's coding agent follows. Self-contained because that
  * agent has none of d360-writer's context. Two parts: (1) a ONE-TIME architecture brief that onboards

package/dist/lib/nextActions.d.ts

@@ -1,4 +1,4 @@
-/** Inputs the decision needs, all already read from disk by the caller. */
+/** Inputs the decision needs, all already read from disk by the caller (see lib/readyState.ts). */
 export type ReadyInputs = {
     /** Configured + signed in + scope ok + Claude present. False ⇒ the setup ladder owns the screen. */
     ready: boolean;
@@ -6,15 +6,14 @@ export type ReadyInputs = {
     hasDocs: boolean;
     /** Count of articles in the category map for the active profile. */
     tracked: number;
-    /** `pendingLine(pendingSummary())` — e.g. "2 hints, 1 request", or null when nothing's queued. */
+    /** Builder queue WITHOUT directives — e.g. "2 hints, 1 request", or null when nothing's queued. */
     pendingText: string | null;
-    /** Planned articles (plan.json) not yet written — missing/empty files. >0 after an interrupted /write
-        (e.g. a crash mid-run) or a freshly-pinned plan with bodies still to generate. Drives the "pick up
-        where you left off" → /write lead so a half-done generation isn't buried under /audit + /pull. */
+    /** OPEN owner directives (.d360-writer/directives.md) — the owner's proactive doc asks. Ranked with
+        the builder queue (both are queued intent → /catch-up) but surfaced as their own bullet. */
+    directives: number;
+    /** Planned articles (plan.json) not yet written — missing/empty files. >0 after an interrupted /write. */
     pendingWrites: number;
-    /** Tracked articles changed locally since their sync base (local-ahead) — ready to /publish. Computed
-        cheaply + locally (countLocalAhead, no network). Drives the /publish lead so "ready to publish" isn't
-        buried under /audit, and stops the briefing falsely reading "all in sync" (dogfood s-244). */
+    /** Tracked articles changed locally since their sync base (local-ahead) — ready to /publish (s-244). */
     localAhead: number;
     /** Commits on HEAD since the last `/audit` marker (0 when never audited or not a git repo). */
     behind: number;
@@ -23,11 +22,52 @@ export type ReadyInputs = {
     /** Active profile/connection name, for the "N articles tracked for X" line. */
     profileName: string;
     /** Whether the caller may auto-run /audit (true only at launch — never on the post-turn refresh,
-        which would loop). When false, a would-be auto-audit degrades to offering /audit in the list. */
+        which would loop). When false, a would-be auto-audit degrades to recommending /audit. */
     allowAutoAudit: boolean;
+    /** devhintsStaleness(cwd).status — is the builder's dev↔docs protocol behind this package's? */
+    devhints: 'current' | 'stale' | 'unset';
+    /** The protocol version the builder last completed (for "you're on v6" copy). */
+    devhintsCompletedVersion?: number;
+    /** This package's protocol version (DEVHINTS_VERSION — passed in so the brain stays pure). */
+    devhintsToVersion?: number;
+    /** builderHasStarted(cwd) — an architecture brief exists. The brain leads /devhints ONLY when the
+        builder has started; the never-started case keeps the caller's full hand-off flow (copy prompt +
+        wait heartbeat) untouched. */
+    builderStarted: boolean;
+    /** The doc genre (appType) couldn't be auto-classified — the /genre picker is the fix. */
+    genreUnknown: boolean;
+};
+/** The one recommended action. `cmd` fills the ghost and runs on Tab→Enter; `prompt` is a free-text
+    ghost (e.g. cold-start "write the docs for this repo"). */
+export type Lead = {
+    kind: 'cmd';
+    cmd: string;
+    reason: string;
+} | {
+    kind: 'prompt';
+    text: string;
+    reason: string;
+};
+/** A true multi-choice — the ONLY thing rendered as a numbered list. */
+export type PickerSpec = {
+    title: string;
+    options: {
+        cmd: string;
+        desc: string;
+    }[];
+};
+export type Recommendation = {
+    /** Conversational transcript briefing (bullets + lead sentence + prose follow-ups), or null when
+        there is nothing worth printing (the caller's silent post-turn restores pass this through). */
+    note: string | null;
+    tone: 'info' | 'warn';
+    /** Null in the calm steady state (nothing to push), or when a picker owns the moment. */
+    lead: Lead | null;
+    /** Set only for true choices (today: the doc genre). */
+    picker: PickerSpec | null;
 };
 export type ReadyDecision = 
-/** Not in the ready state — the caller must leave the quick-list/ghost untouched (setup ladder owns it). */
+/** Not in the ready state — the caller must leave ghost/picker untouched (setup ladder owns it). */
 {
     kind: 'idle';
 }
@@ -36,24 +76,18 @@ export type ReadyDecision =
     kind: 'autoAudit';
     note: string;
 }
-/** No docs yet: cold-start. `note` is the transcript line, `ghost` the tab-fill, `options`/`title` the list. */
+/** The one recommendation for every other ready state. */
  | {
-    kind: 'noDocs';
-    note: string;
-    ghost: string;
-    title: string | null;
-    options: string[];
-}
-/** Docs exist: the steady-state next-actions. `note` is the launch transcript block; `title`+`options`
-    are the durable quick-list (also restored after every turn). */
- | {
-    kind: 'actions';
-    note: string;
-    title: string;
-    options: string[];
+    kind: 'recommend';
+    rec: Recommendation;
 };
+/** "⇥ tab to run /devhints · or just ask me anything…" — the input-placeholder hint that carries the
+    lead. Null for prompt-style leads (the ghost text itself renders in the input, as before). */
+export declare function ghostHintFor(lead: Lead): string | null;
+/** The one-sentence recommendation — used inside the briefing AND as the REPL's "Next:" line. */
+export declare function leadLine(lead: Lead): string;
 /**
- * Decide the next actions from already-gathered inputs. Pure — no I/O — so it's unit-tested and is the
- * one place option order + copy is defined. Mirrors the behavior the launch orientation had inline.
+ * Decide the next action from already-gathered inputs. Pure — no I/O — so it's unit-tested and is the
+ * one place the ladder + copy live.
  */
 export declare function decideReadyActions(i: ReadyInputs): ReadyDecision;

package/dist/lib/readyState.d.ts

@@ -0,0 +1,19 @@
+import type { ReadyInputs } from './nextActions.js';
+/** Should the first-run nudge point the user at /scope? True when scope is unset but a
+    large container exists, or when a bare large-container folder is the whole scope. */
+export declare function scopeLooksTooBroad(cwd: string, scope: string[] | undefined): boolean;
+/** True when the repo is ESTABLISHED — past first-run: docs already written, articles tracked, or a
+    builder hand-off (devhints) in place. A smart agent reads this state: first-run nudges like /scope
+    must NEVER fire on a mature project that has been documenting for weeks (s-228). Cheap on-disk reads. */
+export declare function projectIsEstablished(cwd: string, profileName?: string): boolean;
+/**
+ * Read every signal the brain ranks (see the ladder in nextActions.ts) from disk. Returns null when
+ * the repo has no config (or anything is unreadable) — the caller treats that as `idle` (the setup
+ * ladder owns the screen). `claudeMissing` and `genreUnknown` are caller-known state (the auth
+ * classification and the launch genre probe live with the UI), passed through untouched.
+ */
+export declare function gatherReadyInputs(cwd: string, profileName: string | undefined, opts: {
+    claudeMissing: boolean;
+    allowAutoAudit: boolean;
+    genreUnknown: boolean;
+}): ReadyInputs | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "document360-writer",
-  "version": "0.5.73",
+  "version": "0.5.75",
   "description": "Standalone documentation agent CLI. Reads your code, writes your docs. Specialized for Document360 publishing.",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
     "@inquirer/prompts": "^8.4.3",
     "commander": "^14.0.3",
     "diff": "^8.0.4",
-    "document360-engine": "^0.2.97",
+    "document360-engine": "^0.2.100",
     "ink": "^5.2.1",
     "picocolors": "^1.1.1",
     "react": "^18.3.1",