@cspeach/cli 0.9.0 → 1.1.0

package/dist/projects/save-command.js

@@ -1,3 +1,5 @@
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
 import { extractSpecGap } from './extract-spec-gap.js';
 import { extractDesign } from './extract-design.js';
 import { extractEstimate } from './extract-estimate.js';
@@ -7,9 +9,14 @@ import { extractModernizeResult } from './extract-modernize.js';
 import { extractTestCoverage } from './extract-test-coverage.js';
 import { extractPlan } from './extract-plan.js';
 import { buildEnvelope } from './build.js';
+import { buildPlanRevision } from './plan-run.js';
+import { parsePlanContent } from './plan-schema.js';
+import { validateEnvelope } from './validate.js';
+import { readProjectFile } from './status.js';
 import { saveProject } from './save.js';
 import { renderEmailTemplate } from './email-template.js';
-import { ensureWorkspace } from './workspace.js';
+import { writePlanHandover } from './handover-md.js';
+import { ensureWorkspace, resolveWorkspacePath } from './workspace.js';
 const SKILL_REGISTRY = {
     'abap-spec-gap': {
         artefactType: 'spec-gap',
@@ -30,16 +37,19 @@ const SKILL_REGISTRY = {
         artefactType: 'upgrade-scan',
         extract: (md) => extractUpgradeScan(md),
         itemNoun: 'findings',
+        manifestMarker: 'upgrade-manifest',
     },
     'abap-upgrade-fix': {
         artefactType: 'upgrade-progress',
         extract: (md) => extractUpgradeProgress(md),
         itemNoun: 'fixes',
+        manifestMarker: 'upgrade-manifest',
     },
     'abap-upgrade-verify': {
         artefactType: 'upgrade-report',
         extract: (md) => extractUpgradeReport(md),
         itemNoun: 'regressions',
+        manifestMarker: 'upgrade-manifest',
     },
     'abap-upgrade-merge': {
         // Merge produces a NEW upgrade-progress (consolidated) — same shape
@@ -47,11 +57,13 @@ const SKILL_REGISTRY = {
         artefactType: 'upgrade-progress',
         extract: (md) => extractUpgradeProgress(md),
         itemNoun: 'fixes',
+        manifestMarker: 'upgrade-manifest',
     },
     'abap-cca': {
         artefactType: 'cca-assessment',
         extract: (md) => extractCcaAssessment(md),
         itemNoun: 'classifications',
+        manifestMarker: 'cca-manifest',
     },
     'abap-cca-merge': {
         // Merge produces a NEW cca-assessment (consolidated) — same shape as
@@ -59,36 +71,221 @@ const SKILL_REGISTRY = {
         artefactType: 'cca-assessment',
         extract: (md) => extractCcaAssessment(md),
         itemNoun: 'classifications',
+        manifestMarker: 'cca-manifest',
     },
     'abap-modernize': {
         artefactType: 'modernize-result',
         extract: (md) => extractModernizeResult(md),
         itemNoun: 'modernizations',
+        manifestMarker: 'modernize-manifest',
     },
     'abap-test': {
         artefactType: 'test-coverage',
         extract: (md) => extractTestCoverage(md),
         itemNoun: 'tests',
+        manifestMarker: 'test-coverage-manifest',
     },
     'abap-plan': {
-        // 2026-06-06 B3: Mode 1 (create) save only. Mode 2 (--resume) turns
+        // 2026-06-06 B3: Mode 1 (create) save. Mode 2 (--resume) turns
         // suppress this hook (RunTurnParams.suppressSaveHook) and persist a
         // REVISION of the existing envelope via commands/plan-resume.ts.
+        // C1 (2026-06-11, D30): this generic path ALSO builds a revision when a
+        // prior envelope with the same title exists in the workspace — a steered
+        // "save the project file" must never fork a new identity off an existing
+        // version chain (the 49dd duplicate). The dispatch in runSaveCommand
+        // special-cases artefactType 'plan'; this `extract` is the no-prior
+        // fallback shape only.
         artefactType: 'plan',
         extract: (md) => extractPlan(md),
         itemNoun: 'phases',
-        manifestMarker: 'csforge:plan-manifest',
+        manifestMarker: 'plan-manifest',
     },
 };
+/**
+ * C1 (2026-06-11, defect D22) — map an inline artifact-manifest block in the
+ * assistant output to the SKILL_REGISTRY key that knows how to extract it.
+ * Used by the post-turn save hook (agent/loop.ts:maybeOfferSave) as the
+ * fallback trigger when the routed-skill LABEL would not fire: a misrouted
+ * turn that still emitted a recognizable manifest must not silently lose the
+ * artifact. Returns null when no recognizable manifest is present (prose-only
+ * artefacts — spec-gap / design / estimate — have no inline marker and stay
+ * label-triggered).
+ *
+ * The upgrade marker is shared by three artefact shapes; the `artefact:` line
+ * inside the block disambiguates which extractor (registry skill) applies.
+ */
+export function detectArtifactSkill(markdown) {
+    // E2 dual-read: accept both the legacy `csforge:` and current `cspeach:`
+    // marker prefixes (legacy acceptance is permanent).
+    if (/<!--\s*(?:csforge|cspeach):plan-manifest\b/.test(markdown))
+        return 'abap-plan';
+    if (/<!--\s*(?:csforge|cspeach):cca-manifest\b/.test(markdown))
+        return 'abap-cca';
+    if (/<!--\s*(?:csforge|cspeach):modernize-manifest\b/.test(markdown))
+        return 'abap-modernize';
+    if (/<!--\s*(?:csforge|cspeach):test-coverage-manifest\b/.test(markdown))
+        return 'abap-test';
+    const up = /<!--\s*(?:csforge|cspeach):upgrade-manifest\s*\n([\s\S]*?)\n\s*-->/.exec(markdown);
+    if (up) {
+        const art = /(?:^|\n)\s*artefact:\s*(\S+)/.exec(up[1] ?? '');
+        switch (art?.[1]) {
+            case 'upgrade-scan': return 'abap-upgrade-scan';
+            case 'upgrade-progress': return 'abap-upgrade-fix';
+            case 'upgrade-report': return 'abap-upgrade-verify';
+            default: return null; // marker present, artefact unknown — extractor would reject it anyway
+        }
+    }
+    return null;
+}
+// Same block grammar as extract-plan.ts:MANIFEST_RE (last block wins).
+// E2 dual-read: accept both the legacy `csforge:` and current `cspeach:` prefixes.
+const PLAN_MANIFEST_RE = /<!--\s*(?:csforge|cspeach):plan-manifest\s*\n([\s\S]*?)\n\s*-->/g;
+/**
+ * Cheap title peek into the LAST plan-manifest block — needed BEFORE the full
+ * extract because compact manifests can only be expanded against the prior
+ * envelope, and the prior envelope is found by title. Returns null on any
+ * malformation (the full extract then reports the precise error).
+ */
+export function peekPlanManifestTitle(markdown) {
+    const re = new RegExp(PLAN_MANIFEST_RE.source, PLAN_MANIFEST_RE.flags);
+    let m;
+    let last = null;
+    while ((m = re.exec(markdown)) !== null)
+        last = m;
+    if (!last)
+        return null;
+    try {
+        const parsed = JSON.parse(last[1]);
+        return typeof parsed.title === 'string' && parsed.title.trim().length > 0
+            ? parsed.title.trim()
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * C1 (2026-06-11, defect D30 — the 49dd duplicate) — find the existing plan
+ * envelope a generic save should REVISE instead of forking a new identity.
+ *
+ * Match key: artefactType 'plan' + same title (trimmed, case-insensitive —
+ * the title is model-emitted and may drift in casing). Among matches the
+ * HIGHEST version wins (lastEditedAt breaks ties); when a past duplicate
+ * already split the family into two ids, this picks the longer (real) chain,
+ * so subsequent saves heal onto it instead of extending the fork.
+ *
+ * Non-recursive scan of `dir` (the workspace folder where saves land);
+ * unreadable/invalid files are skipped — resolution is best-effort, never
+ * fatal to the save.
+ */
+export function resolvePriorPlanEnvelope(title, dir) {
+    if (!title)
+        return null;
+    const want = title.trim().toLowerCase();
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    let best = null;
+    for (const name of names) {
+        if (!name.endsWith('.cspeach.json'))
+            continue;
+        const full = join(dir, name);
+        let env;
+        try {
+            env = readProjectFile(full);
+        }
+        catch {
+            continue;
+        }
+        if (env.artefactType !== 'plan')
+            continue;
+        if (env.title.trim().toLowerCase() !== want)
+            continue;
+        if (!best
+            || env.version > best.envelope.version
+            || (env.version === best.envelope.version && env.lastEditedAt > best.envelope.lastEditedAt)) {
+            best = { path: full, envelope: env };
+        }
+    }
+    return best;
+}
 export async function runSaveCommand(args) {
     const spec = SKILL_REGISTRY[args.skillName];
     if (!spec)
         return null;
+    // C1 (D30): a plan save must continue an existing version chain when one is
+    // resolvable. The prior is found by manifest title BEFORE extraction, both
+    // to decide new-vs-revision and because a COMPACT manifest (statuses +
+    // changed map) can only be expanded against the prior content. The scan is
+    // strictly READ-ONLY (resolveWorkspacePath, not ensureWorkspace): nothing
+    // before the user's confirm may mkdir the workspace or touch .gitignore as
+    // a side effect — a missing workspace dir simply means no prior
+    // (resolvePriorPlanEnvelope treats an unreadable dir as "no matches").
+    let prior = null;
+    let priorContent;
+    if (spec.artefactType === 'plan') {
+        const peekedTitle = peekPlanManifestTitle(args.skillOutput);
+        if (peekedTitle) {
+            let scanDir;
+            try {
+                scanDir = await resolveWorkspacePath();
+            }
+            catch {
+                scanDir = args.cwd;
+            }
+            prior = resolvePriorPlanEnvelope(peekedTitle, scanDir);
+            if (prior) {
+                const pc = parsePlanContent(prior.envelope.content);
+                if (pc.ok) {
+                    priorContent = pc.content;
+                }
+                else {
+                    // Prior exists but its content no longer parses — revising it would
+                    // propagate corruption. Fall back to a fresh envelope and say so.
+                    args.log(`[save] existing plan '${prior.envelope.title}' has invalid content (${pc.errors[0] ?? 'schema error'}) — saving a NEW envelope instead of a revision.`);
+                    prior = null;
+                }
+            }
+        }
+    }
     let extract;
+    let planExtract = null;
     try {
-        extract = spec.extract(args.skillOutput);
+        if (spec.artefactType === 'plan') {
+            planExtract = extractPlan(args.skillOutput, priorContent);
+            extract = planExtract;
+        }
+        else {
+            extract = spec.extract(args.skillOutput);
+        }
     }
     catch (e) {
+        // C1 residual D22 — the label IS in the registry but WRONG for the output
+        // (e.g. a plan manifest under an 'abap-design' label): the label's
+        // extractor throws, and bailing here would silently lose an artifact that
+        // carries a complete, recognizable manifest. If the manifest resolves to
+        // a DIFFERENT registry skill, retry the save under that skill. Skipped
+        // when both skills share the same manifest-marker family (abap-cca-merge
+        // ↔ abap-cca, abap-upgrade-merge ↔ abap-upgrade-fix): the family
+        // extractor already ran and failed, and re-dispatching would only launder
+        // merge provenance onto the non-merge skill — keep the label's failure.
+        const detected = detectArtifactSkill(args.skillOutput);
+        if (detected && detected !== args.skillName) {
+            const detectedSpec = SKILL_REGISTRY[detected];
+            const sameFamily = detectedSpec?.manifestMarker !== undefined
+                && detectedSpec.manifestMarker === spec.manifestMarker;
+            if (detectedSpec && !sameFamily) {
+                args.log(`[save] output is a ${detected} artifact, not ${args.skillName} — saving as ${detected}`);
+                // Recursion is bounded: if the retry's extract fails too, the
+                // re-detected skill equals args.skillName and we fall through to the
+                // loud-failure path below instead of recursing again.
+                return runSaveCommand({ ...args, skillName: detected });
+            }
+        }
         if (spec.manifestMarker && args.skillOutput.includes(spec.manifestMarker)) {
             args.log('');
             args.log(`[save] ${args.skillName}: a ${spec.manifestMarker} block IS present but failed to parse — artefact NOT saved.`);
@@ -97,26 +294,57 @@ export async function runSaveCommand(args) {
         }
         return null;
     }
+    // C1 review fix — name the revision target BEFORE the confirm so the user
+    // knows what a 'y' will do. Log line only, deliberately NOT a second
+    // question: the B5 headless contract (below) allows at most one prompt.
+    if (planExtract && prior) {
+        const priorFilename = prior.path.split(/[\\\/]/).pop();
+        args.log(`[save] this will save as v${prior.envelope.version + 1} of existing plan '${prior.envelope.title}' (${priorFilename})`);
+    }
+    // CONTRACT (B5): runSaveCommand may ask the user at most ONE question —
+    // this save confirm. The headless path in loop.ts (maybeOfferSave) installs
+    // a prompt that blanket-answers 'y' to WHATEVER it is asked; any second
+    // question added here would silently receive 'y' too. If you need another
+    // prompt, give maybeOfferSave's headless prompt a question-aware answer
+    // first.
     const answer = (await args.prompt('Save as project file? [y/N]: ')).trim().toLowerCase();
     if (answer !== 'y' && answer !== 'yes')
         return null;
-    const env = buildEnvelope({
-        artefactType: spec.artefactType,
-        extract,
-        author: args.author,
-        source: {
-            skill: args.skillName,
-            skillVersion: args.skillVersion,
-            input: args.skillInput,
-            tokensUsed: args.tokensUsed,
-            model: args.model,
-        },
-        promotedFrom: args.promotedFrom ?? null,
-    });
-    // Save into the workspace folder (~/CSPeach by default), not cwd. Falls
-    // back to args.cwd if the workspace can't be created (e.g. permission
-    // error on the home directory) — saving SOMEWHERE is better than losing
-    // the artefact.
+    let env;
+    if (planExtract && prior) {
+        // C1 (D30) — the 49dd duplicate: the generic save used to mint a fresh
+        // envelope id even when the same plan already lived in the workspace,
+        // forking the version chain. With a resolvable prior, the save IS a
+        // revision: same id, version+1, history appended (buildPlanRevision —
+        // the exact path /abap-plan --resume persistence uses).
+        env = buildPlanRevision(prior.envelope, planExtract, args.author, new Date().toISOString());
+        // JSON round-trip simulates disk serialization for the validator.
+        const check = validateEnvelope(JSON.parse(JSON.stringify(env)));
+        if (!check.ok) {
+            args.log(`[save] plan revision failed validation (${check.error.message}) — artefact NOT saved.`);
+            return null;
+        }
+    }
+    else {
+        env = buildEnvelope({
+            artefactType: spec.artefactType,
+            extract,
+            author: args.author,
+            source: {
+                skill: args.skillName,
+                skillVersion: args.skillVersion,
+                input: args.skillInput,
+                tokensUsed: args.tokensUsed,
+                model: args.model,
+            },
+            promotedFrom: args.promotedFrom ?? null,
+        });
+    }
+    // Saves land in the workspace folder, not cwd — created only NOW, after
+    // the user confirmed (declined saves and conversational turns leave no
+    // mkdir/.gitignore side effects). Falls back to args.cwd if the workspace
+    // can't be created (e.g. permission error on the home directory) — saving
+    // SOMEWHERE is better than losing the artefact.
     let outDir;
     try {
         outDir = await ensureWorkspace();
@@ -125,7 +353,17 @@ export async function runSaveCommand(args) {
         outDir = args.cwd;
     }
     const path = await saveProject(env, { cwd: outDir });
+    // Task 8 follow-up (fix-wave): a plan envelope saved through the GENERIC
+    // save path (Mode 1 create AND a steered revision, C1/D30) must regenerate
+    // the markdown handover projection too — otherwise an authoring-session
+    // save leaves a stale or missing projection until the first --resume write.
+    // Best-effort by design (writePlanHandover logs one dim line on failure).
+    if (spec.artefactType === 'plan')
+        writePlanHandover(path, args.log);
     args.log(`Saved: ${path}`);
+    if (planExtract && prior) {
+        args.log(`(revision v${env.version} of the existing plan — version chain preserved, no new id)`);
+    }
     args.log(`Share at: https://cspeach.dev/edit`);
     args.log('');
     args.log(renderEmailTemplate({

package/dist/projects/status.js

@@ -23,7 +23,7 @@ const STATUS_BY_TYPE = {
     'estimate': ['confirmed', 'disputed', 'deferred'],
     'cca': ['keep', 'fix', 'retire', 'redesign'],
     'incident': ['pending', 'done'],
-    'plan': ['validated', 'todo', 'designing', 'building', 'verifying', 'blocked'],
+    'plan': ['validated', 'validated-with-waiver', 'todo', 'designing', 'building', 'verifying', 'blocked'],
 };
 const PRIMARY_BY_TYPE = {
     'spec-gap': 'answered',
@@ -120,6 +120,8 @@ export function renderStatus(env) {
 function displayStatus(s) {
     if (s === 'n-a')
         return 'n/a';
+    if (s === 'validated-with-waiver')
+        return 'validated* (waived)';
     return s;
 }
 function formatDate(iso) {

package/dist/projects/validate.js

@@ -19,7 +19,7 @@ const STATUS_BY_TYPE = {
     'cca-assessment': ['open', 'reviewed', 'classified', 'archived'],
     'modernize-result': ['applied', 'skipped', 'failed', 'pending'],
     'test-coverage': ['generated', 'skipped', 'failed', 'pending'],
-    'plan': ['todo', 'designing', 'building', 'verifying', 'validated', 'blocked'],
+    'plan': ['todo', 'designing', 'building', 'verifying', 'validated', 'validated-with-waiver', 'blocked'],
 };
 const REQUIRED_TOP_LEVEL = [
     'schemaVersion', 'artefactType', 'id', 'title',

package/dist/projects/workspace.js

@@ -90,6 +90,24 @@ function maybeAddToGitignore(workspaceDir) {
         // still works, the user just has to ignore it manually.
     }
 }
+/**
+ * Resolve the workspace folder PATH without creating it. Same resolution
+ * order as ensureWorkspace (config override > project-rooted default) but
+ * strictly read-only: no mkdir, no .gitignore append. For callers that only
+ * need to LOOK at the workspace — e.g. the pre-confirm prior-plan scan in
+ * save-command.ts, which must not leave filesystem side effects before the
+ * user says yes to the save.
+ */
+export async function resolveWorkspacePath() {
+    const cfg = await loadConfig();
+    const configured = cfg.workspace_folder?.trim();
+    return resolveTarget(configured);
+}
+function resolveTarget(configured) {
+    return configured && configured.length > 0
+        ? expandHome(configured)
+        : defaultWorkspaceFor(process.cwd());
+}
 /**
  * Resolve the workspace folder path, creating it if missing.
  * Returns the absolute path. Idempotent.
@@ -97,9 +115,7 @@ function maybeAddToGitignore(workspaceDir) {
 export async function ensureWorkspace() {
     const cfg = await loadConfig();
     const configured = cfg.workspace_folder?.trim();
-    const target = configured && configured.length > 0
-        ? expandHome(configured)
-        : defaultWorkspaceFor(process.cwd());
+    const target = resolveTarget(configured);
     const justCreated = !existsSync(target);
     if (justCreated) {
         mkdirSync(target, { recursive: true });
@@ -159,7 +175,8 @@ export function listProjectFilesSync(workspace) {
         for (const name of entries) {
             const isEnvelope = name.endsWith('.cspeach.json');
             const isText = isTextFilename(name);
-            if (!isEnvelope && !isText)
+            const isDoc = isDocFilename(name);
+            if (!isEnvelope && !isText && !isDoc)
                 continue;
             const full = join(workspace, name);
             const stat = statSync(full);
@@ -167,7 +184,7 @@ export function listProjectFilesSync(workspace) {
                 continue;
             out.push({
                 filename: name,
-                kind: isEnvelope ? 'envelope' : 'text',
+                kind: isEnvelope ? 'envelope' : isDoc ? 'doc' : 'text',
                 mtimeMs: stat.mtimeMs,
             });
         }
@@ -190,10 +207,31 @@ function expandHome(p) {
 }
 /** File suffixes recognised as text-input candidates for skills. */
 const TEXT_SUFFIXES = ['.txt', '.md'];
-function isTextFilename(name) {
+/**
+ * Whether `name` is a text-input candidate (.txt / .md). Exported so the
+ * @<file> picker (at-picker.ts) reuses the exact same suffix rule instead
+ * of duplicating it.
+ */
+export function isTextFilename(name) {
     const lower = name.toLowerCase();
     return TEXT_SUFFIXES.some((s) => lower.endsWith(s));
 }
+/** File suffixes recognised as binary document inputs (read via extraction). */
+const DOC_SUFFIXES = ['.docx', '.pdf'];
+/**
+ * Whether `name` is a binary document input (.docx / .pdf). Listed and pickable
+ * like text inputs, but ingested via document extraction (the same path
+ * read_document uses) rather than read as UTF-8 text — so a picked Word/PDF
+ * spec just works as skill input.
+ */
+export function isDocFilename(name) {
+    const lower = name.toLowerCase();
+    return DOC_SUFFIXES.some((s) => lower.endsWith(s));
+}
+/** Any user-droppable skill input the @<file> picker should surface. */
+export function isAttachableFilename(name) {
+    return isTextFilename(name) || isDocFilename(name);
+}
 /**
  * List supported workspace files (.cspeach.json envelopes AND .txt/.md
  * text inputs), parsed for a tiny metadata summary. Sorted by mtime
@@ -210,7 +248,8 @@ export async function listProjectFiles() {
     for (const name of entries) {
         const isEnvelope = name.endsWith('.cspeach.json');
         const isText = isTextFilename(name);
-        if (!isEnvelope && !isText)
+        const isDoc = isDocFilename(name);
+        if (!isEnvelope && !isText && !isDoc)
             continue;
         const path = join(ws, name);
         const stat = statSync(path);
@@ -244,11 +283,11 @@ export async function listProjectFiles() {
             });
         }
         else {
-            // text — no envelope metadata, just the file presence
+            // text / doc — no envelope metadata, just the file presence
             out.push({
                 path,
                 filename: name,
-                kind: 'text',
+                kind: isDoc ? 'doc' : 'text',
                 artefactType: 'unknown',
                 version: null,
                 title: null,
@@ -336,14 +375,96 @@ export function resolveAtToken(args) {
     }
     return { kind: 'ambiguous', matches };
 }
+/**
+ * Whether `token` is a BARE name (no path semantics) — the only case the
+ * cwd fallback applies to. Absolute paths and relative paths (./, ../, or
+ * containing a separator) already resolve verbatim in resolveAtToken.
+ */
+function isBareToken(token) {
+    if (isAbsolute(token))
+        return false;
+    if (token.startsWith('./') || token.startsWith('../') || token.startsWith('.\\') || token.startsWith('..\\')) {
+        return false;
+    }
+    if (token.includes('/') || token.includes('\\'))
+        return false;
+    return true;
+}
+/**
+ * Substring-match a BARE token against the .txt/.md/.docx/.pdf files directly
+ * in `cwd` (non-recursive). Mirrors the workspace matching rule:
+ *   - exactly one match → { kind: 'path', path: join(cwd, filename) }
+ *   - multiple matches  → { kind: 'ambiguous', matches }
+ *   - none              → null (caller keeps the original notFound)
+ *
+ * Never throws — an unreadable cwd yields null. Exported for direct unit
+ * testing of the fallback in isolation from ensureWorkspace I/O.
+ */
+export function resolveBareTokenInCwd(token, cwd) {
+    let entries;
+    try {
+        entries = readdirSync(cwd);
+    }
+    catch {
+        return null;
+    }
+    const lower = token.toLowerCase();
+    const matchedFiles = [];
+    for (const name of entries) {
+        if (name.startsWith('.'))
+            continue;
+        if (!isAttachableFilename(name))
+            continue;
+        if (!name.toLowerCase().includes(lower))
+            continue;
+        const path = join(cwd, name);
+        let stat;
+        try {
+            stat = statSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        matchedFiles.push({
+            path,
+            filename: name,
+            kind: isDocFilename(name) ? 'doc' : 'text',
+            artefactType: 'unknown',
+            version: null,
+            title: null,
+            sizeBytes: stat.size,
+            mtimeMs: stat.mtimeMs,
+        });
+    }
+    if (matchedFiles.length === 1) {
+        return { kind: 'path', path: matchedFiles[0].path };
+    }
+    if (matchedFiles.length > 1) {
+        return { kind: 'ambiguous', matches: matchedFiles };
+    }
+    return null;
+}
 /**
  * High-level resolver — combines listProjectFiles + resolveAtToken into a
  * single async call. Callers in promote-command, status, etc. use this.
+ *
+ * Bug #4: when a BARE token doesn't match anything in the workspace, fall
+ * back to matching .txt/.md files in `cwd` before reporting notFound. This
+ * lets a user drop a spec file next to their project and reference it with
+ * a plain `@spec.txt` instead of an absolute path.
  */
 export async function resolveAtTokenAsync(token, cwd) {
     const workspace = await ensureWorkspace();
     const files = await listProjectFiles();
-    return resolveAtToken({ token, cwd, workspace, files });
+    const result = resolveAtToken({ token, cwd, workspace, files });
+    if (result.kind === 'notFound' && isBareToken(token)) {
+        const cwdResult = resolveBareTokenInCwd(token, cwd);
+        if (cwdResult)
+            return cwdResult;
+    }
+    return result;
 }
 /**
  * Format `listProjectFiles` output as a human-readable block for the
@@ -362,7 +483,7 @@ export function formatProjectFileList(files, workspace) {
         const ageStr = relativeTime(now - f.mtimeMs);
         const meta = f.kind === 'envelope'
             ? `${f.artefactType.padEnd(9)} v${f.version ?? '?'}`
-            : `text       ${formatBytes(f.sizeBytes).padStart(7)}`;
+            : `${f.kind.padEnd(9)} ${formatBytes(f.sizeBytes).padStart(7)}`;
         lines.push(`  ${f.filename}  —  ${meta}  ${ageStr}`);
     }
     lines.push('');
@@ -439,8 +560,10 @@ export async function expandTextFileAttachments(userMessage, cwd, log) {
         if (resolved.kind !== 'path')
             continue;
         const path = resolved.path;
-        if (!isTextFilename(path))
-            continue;
+        const asText = isTextFilename(path);
+        const asDoc = isDocFilename(path);
+        if (!asText && !asDoc)
+            continue; // envelopes / unknown → left for --from/--status
         // Only ingest if the file exists. Missing files are just left as
         // literal @<token> in the message (the LLM gets to see them too).
         if (!existsSync(path)) {
@@ -448,19 +571,40 @@ export async function expandTextFileAttachments(userMessage, cwd, log) {
                 log(`(attached @${token} not found in workspace — left as literal)`);
             continue;
         }
+        const filename = path.split(/[\\\/]/).pop() ?? token;
         let content;
-        try {
-            content = readFileSync(path, 'utf8');
+        if (asDoc) {
+            // .docx/.pdf — extract text the same way read_document does, so a picked
+            // Word/PDF spec becomes inline skill input with no separate tool call.
+            try {
+                const buf = readFileSync(path);
+                const ext = path.toLowerCase().endsWith('.pdf') ? '.pdf' : '.docx';
+                const { extractDocument } = await import('../tools/filesystem/extract-document.js');
+                const res = await extractDocument(buf, ext, { maxPages: 150 });
+                content = res.text;
+                if (log)
+                    for (const w of res.warnings)
+                        log(`(${filename}: ${w})`);
+            }
+            catch (err) {
+                if (log)
+                    log(`(could not read @${token}: ${err.message})`);
+                continue;
+            }
         }
-        catch (err) {
-            if (log)
-                log(`(could not read @${token}: ${err.message})`);
-            continue;
+        else {
+            try {
+                content = readFileSync(path, 'utf8');
+            }
+            catch (err) {
+                if (log)
+                    log(`(could not read @${token}: ${err.message})`);
+                continue;
+            }
         }
         if (content.length > MAX_TEXT_FILE_CHARS) {
             content = content.slice(0, MAX_TEXT_FILE_CHARS) + '\n... [truncated, file exceeds 64 KB]';
         }
-        const filename = path.split(/[\\\/]/).pop() ?? token;
         const replacement = `<attached file="${filename}">\n${content}\n</attached>`;
         substitutions.push({ index, matchLen: match.length, replacement });
         if (log)