@ai-content-space/loopx 0.2.7 → 0.2.9

package/skills/spec/SKILL.md

@@ -3,7 +3,7 @@ name: spec
 description: "Writes software design specs from already-clarified requirements, including solution approach, architecture outline, detailed design, tradeoffs, verification design, and handoff context. Not for unresolved requirements, PRD generation, implementation task planning, or code changes."
 when_to_use: "spec, design spec, technical design, design proposal, detailed design, architecture design, 设计方案, 概要设计, 详细设计, 技术方案"
 metadata:
-  version: "0.2.7"
+  version: "0.2.9"
 ---
 
 # loopx Spec
@@ -12,6 +12,17 @@ Turn clarified requirements into design documents. Do not invent missing require
 
 ## Inputs
 
+## Repo Specs And Memory Context
+
+Before using this skill in a repository, inspect loopx long-lived context when it exists:
+
+- If `docs/loopx/specs/` exists, inspect the directory names and filenames. If `docs/loopx/specs/index.md` exists, use it as a map, but do not require it. Read only specs relevant to the requested domain, affected files, workflow behavior, or named source document.
+- If `.loopx/memory/MEMORY.md` exists, read it as curated project memory before deciding what is already known.
+- If `.loopx/memory/index.jsonl` exists, use it only as a retrieval index for relevant active memory cards; do not treat it as an append-only log.
+- Treat current user instructions and the named source document as highest priority, `docs/loopx/specs/` as binding long-lived repo rules, and `.loopx/memory/` as advisory context. Memory is advisory and must not override current task instructions, approved source docs, or repo specs.
+
+Do not read every file under `docs/loopx/specs/` by default. Prefer relevant specs selected by filename, title, frontmatter such as `applies_to`, or the files/domains involved in the task.
+
 Use the user's PRD, external requirements document, or approved `clarify` output as the source of truth.
 
 Before writing, inspect relevant code and docs when the task touches an existing system. If a design question can be answered from the repo, answer it from evidence. If a material requirement, constraint, owner decision, or product behavior is still unclear, stop and route back to `clarify`.
@@ -63,14 +74,14 @@ The Markdown spec must include these sections:
 - `十、排期与规划`
 - `十一、QA`
 
-The `十、排期与规划` section must include a `Planning Handoff` subsection stating what `plan` may decide without re-opening design and what must return to `clarify` or `spec`.
+The `十、排期与规划` section must include a `Planning Handoff` subsection stating what `plan-to-exec` may decide without re-opening design and what must return to `clarify` or `spec`.
 
 ## Handoff
 
 After the spec is complete, recommend:
 
 ```text
-$plan docs/loopx/design/<需求名>需求设计文档.md
+$plan-to-exec docs/loopx/design/<需求名>需求设计文档.md
 ```
 
-Use `plan` only after the design document is internally consistent and all material requirements questions are resolved.
+Use `plan-to-exec` only after the design document is internally consistent and all material requirements questions are resolved.

package/skills/subagent-exec/SKILL.md

@@ -3,7 +3,7 @@ name: subagent-exec
 description: "Executes approved loopx implementation plans with fresh subagents per independent task and staged review. Not for planning, unclear requirements, or tightly coupled edits."
 when_to_use: "approved implementation plan, independent tasks, subagent execution, staged spec review, code quality review, parallel-capable execution"
 metadata:
-  version: "0.2.7"
+  version: "0.2.9"
 ---
 
 # Subagent Exec
@@ -283,7 +283,7 @@ Done!
 
 **Required workflow skills:**
 
-- **loopx:plan** - Creates the plan this skill executes
+- **loopx:plan-to-exec** - Creates the plan this skill executes
 - **loopx:review** - Code review template for reviewer subagents
 - **loopx:final-review** - Final whole-feature runtime and integration risk review
 - **loopx:finish** - Complete development after all tasks

package/skills/tdd/SKILL.md

@@ -3,7 +3,7 @@ name: tdd
 description: "Guides feature and bugfix implementation through a failing test before production code and red-green-refactor discipline. Not for generated files or throwaway prototypes."
 when_to_use: "tdd, failing test first, feature implementation, bugfix, regression test, red green refactor, 测试先行"
 metadata:
-  version: "0.2.7"
+  version: "0.2.9"
 ---
 
 # Test-Driven Development (TDD)

package/skills/verify/SKILL.md

@@ -3,7 +3,7 @@ name: verify
 description: "Requires fresh verification evidence before claiming work is complete, fixed, passing, review-ready, or ready to commit. Not for speculative confidence or stale results."
 when_to_use: "verify, completion claim, fixed claim, tests pass, review-ready, commit, fresh evidence, 验证, 完成前检查"
 metadata:
-  version: "0.2.7"
+  version: "0.2.9"
 ---
 
 # Verification Before Completion

package/src/cli.mjs

@@ -30,7 +30,7 @@ function usage() {
     '  loopx status [slug] [--json]',
     '  loopx next <slug> [--json]',
     '  loopx setup-context',
-    '  loopx install-skills [--target <codex|claude|all>] [--project] [--mode <copy|symlink>] [--dir <path>] [--yes] [--dry-run] [--json]',
+    '  loopx install-skills [--target <codex|claude|all>] [--project] [--mode <copy|symlink>] [--dir <path>] [--add-agent-guidance] [--yes] [--dry-run] [--json]',
     '  loopx doctor [--json]',
     '  loopx migrate',
     '  loopx repair-install',
@@ -60,6 +60,7 @@ async function promptInstallOptions() {
     const targetAnswer = (await rl.question('Install targets (codex, claude, all) [all]: ')).trim().toLowerCase();
     const projectAnswer = (await rl.question('Install Claude project skills instead of user skills? [y/N]: ')).trim().toLowerCase();
     const modeAnswer = (await rl.question('Install mode (copy, symlink) [copy]: ')).trim().toLowerCase();
+    const guidanceAnswer = (await rl.question('Add loopx guidance to Codex AGENTS.md / Claude CLAUDE.md? [y/N]: ')).trim().toLowerCase();
     const proceedAnswer = (await rl.question('Proceed? [y/N]: ')).trim().toLowerCase();
     if (proceedAnswer !== 'y' && proceedAnswer !== 'yes') {
       return null;
@@ -69,6 +70,7 @@ async function promptInstallOptions() {
       targets: target === 'all' ? ['codex', 'claude'] : [target],
       project: projectAnswer === 'y' || projectAnswer === 'yes',
       installMethod: modeAnswer === 'symlink' ? 'symlink' : 'copy',
+      agentGuidance: guidanceAnswer === 'y' || guidanceAnswer === 'yes',
     };
   } finally {
     rl.close();
@@ -83,6 +85,7 @@ function installOptionsFromArgs(options) {
     project: Boolean(options.get('--project')),
     installMethod: options.get('--mode') === 'symlink' ? 'symlink' : 'copy',
     dir: options.get('--dir'),
+    agentGuidance: Boolean(options.get('--add-agent-guidance') || options.get('--add-codex-agents-guidance')),
   };
 }
 
@@ -272,10 +275,10 @@ function humanMissingArtifactsText(status) {
 function humanNextAction(status) {
   const state = status.state || null;
   if (state?.current_stage === 'clarify') {
-    if (nextSkillCommand(state)?.startsWith('$plan ')) {
-      return `Follow $plan ${state.slug}.`;
+    if (nextSkillCommand(state)?.startsWith('$plan-to-exec ')) {
+      return `Follow $plan-to-exec ${state.slug}.`;
     }
-    return 'Finish clarification, then follow $plan when ready.';
+    return 'Finish clarification, then follow $plan-to-exec when ready.';
   }
   const payload = nextPayloadFromStatus(status, { human: true });
   if (payload.next_skill_command) {

package/src/context-manifest.mjs

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, resolve } from 'node:path';
 
+import { discoverLoopxContextArtifacts } from './loopx-context-artifacts.mjs';
 import { inspectWorkspaceContext, resolveWorkspaceContextPaths } from './workspace-context.mjs';
 
 export const CONTEXT_MANIFEST_SCHEMA_VERSION = 1;
@@ -64,6 +65,53 @@ function stableRows(rows) {
     .slice(0, MAX_MANIFEST_ROWS);
 }
 
+async function loopxRepoContextRows(cwd, stage, priorityStart) {
+  const artifacts = await discoverLoopxContextArtifacts(cwd);
+  const rows = [];
+  let priority = priorityStart;
+  if (artifacts.specsRoot) {
+    rows.push(row(cwd, {
+      stage,
+      kind: 'repo-specs',
+      path: artifacts.specsRoot,
+      reason: 'long_lived_loopx_specs_directory',
+      priority: priority++,
+      required: false,
+    }));
+  }
+  for (const spec of artifacts.specFiles) {
+    rows.push(row(cwd, {
+      stage,
+      kind: 'repo-spec',
+      path: spec.path,
+      reason: 'long_lived_loopx_spec',
+      priority: priority++,
+      required: false,
+    }));
+  }
+  if (artifacts.memorySummary) {
+    rows.push(row(cwd, {
+      stage,
+      kind: 'memory-summary',
+      path: artifacts.memorySummary.path,
+      reason: 'curated_loopx_project_memory',
+      priority: priority++,
+      required: false,
+    }));
+  }
+  if (artifacts.memoryIndex) {
+    rows.push(row(cwd, {
+      stage,
+      kind: 'memory-index',
+      path: artifacts.memoryIndex.path,
+      reason: 'curated_loopx_memory_retrieval_index',
+      priority: priority++,
+      required: false,
+    }));
+  }
+  return rows;
+}
+
 export async function writeContextManifest(path, rows) {
   const text = stableRows(rows).map((item) => JSON.stringify(item)).join('\n');
   await mkdir(dirname(path), { recursive: true });
@@ -141,6 +189,7 @@ export async function generateBuildContextManifest({ cwd, root, state, slug }) {
     row(cwd, { stage: 'build', kind: 'domain-context', path: contextPaths.domainGlossary, reason: 'domain_vocabulary', priority: 34, required: contextSetup.status !== 'missing' }),
     row(cwd, { stage: 'build', kind: 'agent-domain', path: contextPaths.agentDomain, reason: 'agent_context_rules', priority: 35, required: false }),
     row(cwd, { stage: 'build', kind: 'workspace-config', path: join(cwd, '.loopx', 'config.json'), reason: 'project_rules_spec_sources_and_verification_commands', priority: 36, required: false }),
+    ...await loopxRepoContextRows(cwd, 'build', 37),
   ];
   const manifestPath = buildContextManifestPath(root);
   await writeContextManifest(manifestPath, rows);
@@ -163,7 +212,8 @@ export async function generateReviewContextManifest({ cwd, root, state, slug })
     row(cwd, { stage: 'review', kind: 'build-support', path: join(root, 'build-support'), reason: 'build_gate_evidence', priority: 30, required: false }),
     row(cwd, { stage: 'review', kind: 'agent-domain', path: contextPaths.agentDomain, reason: 'agent_context_rules', priority: 31, required: false }),
     row(cwd, { stage: 'review', kind: 'workspace-config', path: join(cwd, '.loopx', 'config.json'), reason: 'project_rules_spec_sources_and_verification_commands', priority: 32, required: false }),
-    row(cwd, { stage: 'review', kind: 'state', path: join(root, 'state.json'), reason: 'workflow_state', priority: 40 }),
+    ...await loopxRepoContextRows(cwd, 'review', 33),
+    row(cwd, { stage: 'review', kind: 'state', path: join(root, 'state.json'), reason: 'workflow_state', priority: 60 }),
   ];
   const manifestPath = reviewContextManifestPath(root);
   await writeContextManifest(manifestPath, rows);

package/src/install-discovery.mjs

@@ -17,7 +17,7 @@ const PROJECT_ROOT = resolve(MODULE_DIR, '..');
 const LOOPX_SKILLS = [
   'clarify',
   'spec',
-  'plan',
+  'plan-to-exec',
   'subagent-exec',
   'exec',
   'review',
@@ -49,6 +49,18 @@ const LOOPX_MANAGED_SCRIPT_ITEMS = [
     targetRelativePath: '.claude/hooks/loopx-workflow-hook.mjs',
   },
 ];
+const LOOPX_AGENT_GUIDANCE_BLOCK_ID = 'specs-and-memory-context';
+const LOOPX_AGENT_GUIDANCE_HEADING = '## loopx Specs And Memory';
+const LOOPX_AGENT_GUIDANCE_CONTENT = [
+  LOOPX_AGENT_GUIDANCE_HEADING,
+  '',
+  'When working in a repository that uses loopx:',
+  '',
+  '- If `docs/loopx/specs/` exists, inspect relevant specs before clarify, spec, plan, implementation, or review. Use `docs/loopx/specs/index.md` as a map when present, but do not require it.',
+  '- If `.loopx/memory/MEMORY.md` exists, read it as curated project memory.',
+  '- If `.loopx/memory/index.jsonl` exists, use it only to find relevant active memory cards.',
+  '- Treat current user instructions and named source documents as highest priority, repo specs as binding long-lived rules, and memory as advisory context.',
+].join('\n');
 const LOOPX_GOVERNED_SOURCE_ITEMS = [
   {
     name: 'loopx-plugin-manifest',
@@ -128,6 +140,19 @@ export function getClaudeSettingsPath(env = process.env) {
   return resolve(env.LOOPX_CLAUDE_SETTINGS_PATH || join(home, '.claude', 'settings.json'));
 }
 
+export function getCodexAgentsPath(env = process.env) {
+  const home = resolve(env.LOOPX_HOME || env.HOME || process.cwd());
+  return resolve(env.LOOPX_CODEX_AGENTS_PATH || join(home, '.codex', 'AGENTS.md'));
+}
+
+export function getClaudeAgentsPath(env = process.env, options = {}) {
+  if (options.project === true) {
+    return resolve(env.LOOPX_INSTALL_CWD || process.cwd(), 'CLAUDE.md');
+  }
+  const home = resolve(env.LOOPX_HOME || env.HOME || process.cwd());
+  return resolve(env.LOOPX_CLAUDE_AGENTS_PATH || join(home, '.claude', 'CLAUDE.md'));
+}
+
 export function getSkillLockPath(env = process.env) {
   return resolve(env.LOOPX_SKILL_LOCK_PATH || join(getAgentsRoot(env), '.skill-lock.json'));
 }
@@ -454,6 +479,85 @@ async function removeInstalledFile(path) {
   await rm(path, { force: true });
 }
 
+function managedBlockMarkers(id) {
+  return {
+    start: `<!-- loopx:managed:block ${id} -->`,
+    end: `<!-- /loopx:managed:block ${id} -->`,
+  };
+}
+
+function renderManagedBlock(id, content) {
+  const markers = managedBlockMarkers(id);
+  return `${markers.start}\n${content.trim()}\n${markers.end}`;
+}
+
+function managedBlockPattern(id) {
+  const escaped = String(id).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`<!--\\s*loopx:managed:block\\s+${escaped}\\s*-->[\\s\\S]*?<!--\\s*\\/loopx:managed:block\\s+${escaped}\\s*-->`);
+}
+
+function upsertManagedBlock(existing, id, content) {
+  const nextBlock = renderManagedBlock(id, content);
+  const pattern = managedBlockPattern(id);
+  if (pattern.test(existing)) {
+    const nextContent = existing.replace(pattern, nextBlock);
+    return {
+      content: nextContent,
+      changed: nextContent !== existing,
+      existed: true,
+    };
+  }
+  const trimmed = existing.trimEnd();
+  const contentWithBlock = trimmed
+    ? `${trimmed}\n\n${nextBlock}\n`
+    : `${nextBlock}\n`;
+  return {
+    content: contentWithBlock,
+    changed: true,
+    existed: false,
+  };
+}
+
+export async function installAgentGuidanceFile(path, options = {}) {
+  const content = options.content || LOOPX_AGENT_GUIDANCE_CONTENT;
+  const id = options.id || LOOPX_AGENT_GUIDANCE_BLOCK_ID;
+  const existing = existsSync(path) ? await readFile(path, 'utf8') : '';
+  const existed = existsSync(path);
+  const next = upsertManagedBlock(existing, id, content);
+  if (!next.changed) {
+    return { status: 'already-current', path };
+  }
+  await ensureDir(dirname(path));
+  await writeFile(path, `${next.content.replace(/\s+$/, '')}\n`);
+  return {
+    status: next.existed ? 'updated' : (existed ? 'installed' : 'created'),
+    path,
+  };
+}
+
+function agentGuidanceEnabled(options = {}) {
+  return Boolean(options.agentGuidance || options.codexAgentsGuidance);
+}
+
+export async function installAgentGuidance(env = process.env, options = {}) {
+  const target = options.target || env.LOOPX_INSTALL_TARGET || 'codex';
+  const enabled = agentGuidanceEnabled(options);
+  const result = {};
+  if (target === 'codex' || target === 'all') {
+    const path = getCodexAgentsPath(env);
+    result.codex = enabled
+      ? await installAgentGuidanceFile(path)
+      : { status: 'recommended', path };
+  }
+  if (target === 'claude' || target === 'all') {
+    const path = getClaudeAgentsPath(env, options);
+    result.claude = enabled
+      ? await installAgentGuidanceFile(path)
+      : { status: 'recommended', path };
+  }
+  return result;
+}
+
 async function canonicalTargetOwnership(skillName, env = process.env, options = {}) {
   const targetDir = installedSkillDir(skillName, env);
   const sourceDir = skillSourceDir(skillName, env, options.skillSourceRoot);
@@ -736,11 +840,16 @@ export async function installBundledSkills(env = process.env, options = {}) {
     items: nextTemplateItems,
   });
   const templateGovernance = await inspectTemplateGovernance(baselinePath);
+  const agentGuidance = await installAgentGuidance(env, {
+    ...options,
+    target: options.target || env.LOOPX_INSTALL_TARGET || 'codex',
+  });
   return {
     ok: conflicts.length === 0,
     installed,
     conflicts,
     skipped,
+    agentGuidance,
     templateGovernance,
     inspection: await inspectInstallState(env),
   };

package/src/loopx-context-artifacts.mjs

@@ -0,0 +1,114 @@
+import { existsSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { basename, join, relative, resolve } from 'node:path';
+
+const MAX_SPEC_CONTEXT_FILES = 12;
+
+function displayPath(cwd, path) {
+  const rel = relative(cwd, path);
+  return rel && !rel.startsWith('..') ? rel : path;
+}
+
+function normalizeChangedFiles(files = []) {
+  return Array.isArray(files)
+    ? files.map((file) => String(file || '').trim()).filter(Boolean)
+    : [];
+}
+
+async function listMarkdownFiles(root) {
+  if (!existsSync(root)) {
+    return [];
+  }
+  const found = [];
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(path);
+        continue;
+      }
+      if (entry.isFile() && /\.md$/i.test(entry.name)) {
+        found.push(path);
+      }
+    }
+  }
+  await walk(root);
+  return found;
+}
+
+function pathParts(value) {
+  return String(value || '')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((part) => part.length >= 3);
+}
+
+function frontmatterAppliesTo(text) {
+  if (!String(text || '').startsWith('---\n')) {
+    return [];
+  }
+  const end = text.indexOf('\n---\n', 4);
+  if (end === -1) {
+    return [];
+  }
+  const lines = text.slice(4, end).split('\n');
+  const values = [];
+  let inAppliesTo = false;
+  for (const line of lines) {
+    if (/^applies_to:\s*$/.test(line)) {
+      inAppliesTo = true;
+      continue;
+    }
+    if (inAppliesTo && /^\s+-\s+/.test(line)) {
+      values.push(line.replace(/^\s+-\s+/, '').trim().replace(/^['"]|['"]$/g, ''));
+      continue;
+    }
+    if (inAppliesTo && /^\S/.test(line)) {
+      inAppliesTo = false;
+    }
+  }
+  return values.filter(Boolean);
+}
+
+function appliesToChangedFile(pattern, changedFile) {
+  const normalizedPattern = String(pattern || '').replace(/\*\*?\/?/g, '').replace(/\/+$/, '');
+  const normalizedFile = String(changedFile || '');
+  return normalizedPattern && normalizedFile.includes(normalizedPattern);
+}
+
+async function specRecord(cwd, path, changedFiles) {
+  const text = await readFile(path, 'utf8');
+  const appliesTo = frontmatterAppliesTo(text);
+  const stemParts = pathParts(basename(path, '.md'));
+  const changedParts = new Set(changedFiles.flatMap(pathParts));
+  const filenameMatch = stemParts.some((part) => changedParts.has(part));
+  const appliesToMatch = appliesTo.some((pattern) => changedFiles.some((file) => appliesToChangedFile(pattern, file)));
+  const isIndex = /(^|\/)index\.md$/i.test(path);
+  const isInbox = /(^|\/)inbox\.md$/i.test(path);
+  return {
+    path: displayPath(cwd, path),
+    appliesTo,
+    relevant: isIndex || isInbox || filenameMatch || appliesToMatch || changedFiles.length === 0,
+  };
+}
+
+export async function discoverLoopxContextArtifacts(cwd, options = {}) {
+  const root = resolve(cwd);
+  const changedFiles = normalizeChangedFiles(options.changedFiles);
+  const specsRootPath = join(root, 'docs', 'loopx', 'specs');
+  const specPaths = await listMarkdownFiles(specsRootPath);
+  const records = await Promise.all(specPaths.map((path) => specRecord(root, path, changedFiles)));
+  const relevantSpecs = records
+    .filter((record) => record.relevant)
+    .sort((left, right) => left.path.localeCompare(right.path))
+    .slice(0, MAX_SPEC_CONTEXT_FILES);
+  const memorySummaryPath = join(root, '.loopx', 'memory', 'MEMORY.md');
+  const memoryIndexPath = join(root, '.loopx', 'memory', 'index.jsonl');
+  return {
+    specsRoot: existsSync(specsRootPath) ? displayPath(root, specsRootPath) : null,
+    specFiles: relevantSpecs,
+    memorySummary: existsSync(memorySummaryPath) ? { path: displayPath(root, memorySummaryPath) } : null,
+    memoryIndex: existsSync(memoryIndexPath) ? { path: displayPath(root, memoryIndexPath) } : null,
+  };
+}

package/src/next-skill.mjs

@@ -9,7 +9,7 @@ export function nextSkillCommand(state) {
     && state.clarify_decision_boundaries_resolved === true
     && state.clarify_pressure_pass_complete === true
   ) {
-    return `$plan ${state.slug}`;
+    return `$plan-to-exec ${state.slug}`;
   }
   if (state.current_stage === 'done'
     && state.completion_confirmed === true) {
@@ -51,7 +51,7 @@ export function nextSkillCommand(state) {
     && state.review_verdict === 'request-changes'
     && state.requested_transition === 'review->plan'
     && state.approval?.rollback === 'approved') {
-    return `$plan ${state.slug}`;
+    return `$plan-to-exec ${state.slug}`;
   }
   if (state.current_stage === 'review'
     && state.review_verdict === 'request-changes'

package/src/project-discovery.mjs

@@ -67,6 +67,7 @@ async function discoverSpecSources(cwd) {
     candidate(join(cwd, 'specs'), 'specs'),
     candidate(join(cwd, 'docs', 'changes'), 'docs/changes'),
     candidate(join(cwd, 'docs', 'specs'), 'docs/specs'),
+    candidate(join(cwd, 'docs', 'loopx', 'specs'), 'docs/loopx/specs'),
     candidate(join(cwd, 'docs', 'adr'), 'docs/adr'),
     candidate(join(cwd, 'docs', 'rfcs'), 'docs/rfcs'),
   ]);

package/src/workflow.mjs

@@ -20,6 +20,7 @@ import { inspectProjectConventions } from './project-discovery.mjs';
 import { createDefaultReviewAdapter } from './review-runtime.mjs';
 import { appendWorkspaceJournal } from './workspace-memory.mjs';
 import { inspectWorkspaceContext, setupWorkspaceContext } from './workspace-context.mjs';
+import { discoverLoopxContextArtifacts } from './loopx-context-artifacts.mjs';
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const WORKSPACE_SCHEMA_VERSION = 1;
@@ -325,9 +326,6 @@ function compactPlanningText(text, { html = false } = {}) {
 async function readPlanSourceText(cwd, state, sourceSpecPath) {
   const sourceText = await readFile(sourceSpecPath, 'utf8');
   const sourceDocumentPaths = sourceDocumentPathsFromSpecAndState(sourceSpecPath, sourceText, state);
-  if (sourceDocumentPaths.length === 0) {
-    return { sourceText, sourceDocumentPaths: [] };
-  }
 
   const parts = [sourceText.trimEnd()];
   const loaded = [];
@@ -350,6 +348,11 @@ async function readPlanSourceText(cwd, state, sourceSpecPath) {
       break;
     }
   }
+  const repoContext = await readLoopxRepoContextText(cwd, sourceSpecPath);
+  if (repoContext.text) {
+    parts.push(repoContext.text);
+    loaded.push(...repoContext.paths);
+  }
 
   return {
     sourceText: parts.join('\n\n').slice(0, MAX_PLAN_SOURCE_BUNDLE_CHARS),
@@ -357,6 +360,47 @@ async function readPlanSourceText(cwd, state, sourceSpecPath) {
   };
 }
 
+async function readLoopxRepoContextText(cwd, sourceSpecPath) {
+  const artifacts = await discoverLoopxContextArtifacts(cwd, {
+    changedFiles: [relative(cwd, sourceSpecPath)],
+  });
+  const paths = [
+    ...artifacts.specFiles.map((item) => item.path),
+    artifacts.memorySummary?.path,
+  ].filter(Boolean);
+  if (paths.length === 0) {
+    return { text: '', paths: [] };
+  }
+  const sections = [];
+  const loaded = [];
+  for (const display of paths) {
+    const absolute = resolve(cwd, display);
+    if (!existsSync(absolute)) {
+      continue;
+    }
+    const raw = await readFile(absolute, 'utf8');
+    loaded.push(absolute);
+    sections.push([
+      `# loopx context: ${display}`,
+      '',
+      compactPlanningText(raw),
+    ].join('\n'));
+  }
+  if (sections.length === 0) {
+    return { text: '', paths: [] };
+  }
+  return {
+    text: [
+      '# loopx Repo Specs And Memory Context',
+      '',
+      'Current task instructions and named source documents have priority. Repo specs are binding long-lived rules. Memory is advisory.',
+      '',
+      ...sections,
+    ].join('\n\n'),
+    paths: loaded,
+  };
+}
+
 function frontmatterBlock(values) {
   const lines = ['---'];
   for (const [key, value] of Object.entries(values)) {
@@ -3131,8 +3175,8 @@ function recommendedAction(state, legacy = false) {
   switch (state.current_stage) {
     case STAGES.CLARIFY:
       return state.approval.plan === APPROVAL_STATES.APPROVED
-        ? `Follow $plan ${state.slug}.`
-        : 'Finish clarification, then follow $plan when ready.';
+        ? `Follow $plan-to-exec ${state.slug}.`
+        : 'Finish clarification, then follow $plan-to-exec when ready.';
     case STAGES.PLAN:
       if (Array.isArray(state.plan_blockers) && state.plan_blockers.length > 0) {
         return 'Run loopx plan to continue the planning review loop until architect, critic, and planning artifact blockers are cleared.';
@@ -3356,7 +3400,7 @@ function nextCommandForRollbackTarget(slug, target) {
   return [
     'Next:',
     `loopx approve ${slug} --from review --to plan`,
-    `$plan ${slug}`,
+    `$plan-to-exec ${slug}`,
   ].join('\n');
 }
 
@@ -3936,7 +3980,7 @@ export async function planStage(cwd, slug, options = {}) {
     && state.approval.plan === APPROVAL_STATES.APPROVED;
   if (!options.directSpecPath) {
     if (consumesReviewPlan || resumesConsumedReviewPlan || resumesClarifyPlan) {
-      // A no-go review or a blocked planning run may route back to plan; the printed Next command is $plan.
+      // A no-go review or a blocked planning run may route back to plan; the printed Next command is $plan-to-exec.
     } else {
       ensureApprovedTransition(state, TRANSITIONS.CLARIFY_TO_PLAN, 'plan');
     }