ticlawk 0.1.17-dev.2 → 0.1.17-dev.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticlawk",
-  "version": "0.1.17-dev.2",
+  "version": "0.1.17-dev.4",
   "description": "Local connector that links agent harnesses (Claude Code, Codex, OpenClaw, opencode, Pi) to the Ticlawk mobile app.",
   "type": "module",
   "main": "ticlawk.mjs",

package/src/runtimes/_shared/goal-step-prompt.mjs

@@ -15,9 +15,9 @@ import { buildEnvelopeTarget, buildCharterBlock } from './wake-prompt.mjs';
 const STEP_GUIDES = {
   gap_analysis: {
     title: 'GAP ANALYSIS',
-    body: `Compare the current state of the work against the goal and success criteria. Read whatever you need (charter, dashboard, task board, repo, prior messages) to judge where things actually stand.
+    body: `Compare the current state of the work against the goal and success criteria. Read whatever you need (charter, dashboard, task board, repo, prior messages) to judge where things actually stand. The dashboard is the owner's at-a-glance visualization of how far this goal has progressed — this step owns keeping it true to reality: if a durable goal has no dashboard yet, create it (\`ticlawk dashboard set\`); if overall progress has moved materially, refresh its content/data. See SURFACES.md.
 - If there is concrete executable work toward the goal, first make sure the next unit exists as a task (create/assign it with \`ticlawk task ...\` when a task fits), then report outcome=gap.
-- If the goal/milestone is fully met with no meaningful gap, report outcome=no_gap.
+- If the goal/milestone is fully met with no meaningful gap, make sure the dashboard reflects the completed state, publish a final-result briefing for the owner (\`ticlawk briefing publish --mode info\`), then report outcome=no_gap.
 - If closing the gap depends on a future or external state that nobody can act on right now, schedule a reminder for the resume condition, then report outcome=wait.`,
     outcomes: ['gap', 'no_gap', 'wait'],
   },
@@ -25,7 +25,7 @@ const STEP_GUIDES = {
     title: 'EXECUTE',
     body: `Do the next concrete unit of work toward the goal (or drive the current task to completion). Send interim updates with \`ticlawk message send --phase progress\` as you go.
 - When the unit of work is finished and ready to be checked, report outcome=task_completed.
-- If you cannot proceed without an owner approval, decision, or permission, park ONE canonical approval with \`ticlawk approval request --title "<what you need approved>" [--detail "<context>"]\`, tell the owner what you need and why with \`ticlawk message send\`, then report outcome=needs_approval. The owner's approval (button or a natural-language reply) resumes you automatically.
+- If you cannot proceed without an owner approval, decision, or permission, park ONE canonical approval with \`ticlawk approval request --title "<what you need approved>" [--detail "<context>"]\`, surface the decision to the owner with a briefing (\`ticlawk briefing publish --mode approval\`) saying what you need and why, then report outcome=needs_approval. The owner's approval (button or a natural-language reply) resumes you automatically.
 - If you are blocked by something else (missing input, external failure, a needed resource), explain it to the owner, then report outcome=blocked.`,
     outcomes: ['task_completed', 'needs_approval', 'blocked'],
   },
@@ -77,7 +77,7 @@ export function buildGoalStepPrompt(msg) {
       `When the step is done, advance the state machine by running EXACTLY ONE report:`,
       `  ${reportCmd}`,
       ``,
-      `Reporting the outcome is what continues the loop: a running next state arrives as a fresh step, and the loop parks itself when there is no gap or it must wait. Send owner-facing updates with \`ticlawk message send --target ${target} --phase progress\` (use --phase final only when the loop reaches no_gap/wait/blocked-on-owner). Report exactly once; do not loop inside this single turn.`,
+      `Reporting the outcome is what continues the loop: a running next state arrives as a fresh step, and the loop parks itself when there is no gap or it must wait. Reach the owner only through the surface this step names (\`ticlawk message send --target ${target}\` for chat, plus \`briefing publish\`/\`dashboard set\` where the step calls for them; see \`SURFACES.md\`). Any owner-facing text — chat, briefing, or dashboard — is for the owner in their language: say what changed, why it matters, and what (if anything) they must do; never expose internal task titles, file paths, step numbers, or harness tokens. Report exactly once; do not loop inside this single turn.`,
       `[/goal_step]`,
     ].join('\n'));
   } else {

package/src/runtimes/_shared/standing-prompt.mjs

@@ -31,7 +31,7 @@ Read other local files only when the current work clearly needs them.`;
 function buildGoalLaneStandingPrompt(_ctx = {}) {
   return `You are executing one backend goal-loop step for this conversation, dispatched by the system — not a message from a person. Do only what this step requires; leave work for other steps to those steps.
 
-Your normal output is private and reaches no one. When the step calls for an owner-facing update, send it with \`ticlawk message send --target <target> --phase progress|final\`. Read \`MEMORY.md\` only if the step needs durable context.`;
+Your normal output is private and reaches no one. The owner is reached only through Ticlawk surfaces: \`ticlawk message send\` (chat update), \`ticlawk briefing publish\` (active notification/decision), \`ticlawk dashboard set\` (goal-level report). The step tells you which one to use; \`SURFACES.md\` holds the rules for each. Read \`SURFACES.md\` or \`MEMORY.md\` only if the step needs them.`;
 }
 
 function isGoalLane(ctx = {}) {

package/src/runtimes/_shared/wake-prompt.mjs

@@ -84,8 +84,23 @@ export function buildGroupContextBlock(msg) {
 
 export function buildCharterBlock(msg) {
   const charter = (msg.conversation_charter || '').trim();
-  if (!charter) return '';
   const conversationId = msg.conversation_id || '';
+
+  // No charter yet: the goal loop has never been bootstrapped. A transition
+  // cannot arrive before a goal exists, and only the goal-authority agent may
+  // start one — so give that agent (and only it) the bootstrap path. Without
+  // this, a conversation's FIRST goal can never reach the goal lane, because
+  // the steady-state guidance below is gated on a charter already existing.
+  if (!charter) {
+    if (msg.reason === 'transition' || !hasGoalAuthority(msg)) return '';
+    return promptBlock(`
+[conversation_goal]
+This conversation has no goal charter yet, so the backend goal loop is not running.
+If this message sets a goal for this conversation, capture it as the charter — the goal and what "done" looks like, in the owner's words — with \`ticlawk charter set --conversation ${conversationId}\` (body on stdin), then run \`ticlawk goal changed --conversation ${conversationId}\` to start the goal loop. Otherwise handle the message normally. See GOAL_AUTHORITY.md.
+[/conversation_goal]
+`);
+  }
+
   // The goal lane (transition deliveries) executes against the charter; its
   // per-step instructions come from the goal-step prompt, so here the charter
   // is just the goal/success spec. The chat lane must NOT run the loop — it