@ai-content-space/loopx 0.2.8 → 0.2.9

package/src/install-discovery.mjs

@@ -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/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)) {