@popoverai/dotrequirements 0.25.0 → 0.26.1

package/dist/cli.js

@@ -64,7 +64,13 @@ program
     .action(wrapCommand(initCommand));
 program
     .command("link")
-    .description("Link local environment to an existing project")
+    .description("Link local environment to a cloud project (creating one when needed)")
+    .option("-y, --yes", "Non-interactive: resolve every decision from defaults or flags; never prompt")
+    .option("--json", "Machine-readable output (one JSON object on stdout)")
+    .option("--team <nameOrId>", "Use this team (implies --yes)")
+    .option("--connect <slug>", "Connect to this existing project (implies --yes)")
+    .option("--create", "Create a new project (implies --yes)")
+    .option("-n, --name <name>", "Project name for --create or rename")
     .action(wrapCommand(linkCommand));
 program
     .command("pull")
@@ -125,6 +131,7 @@ program
 program
     .command("ai-setup")
     .description("Configure MCP server for your AI assistant (Claude Code, Claude Desktop, etc.)")
+    .option("-a, --assistant <id>", "Configure for this assistant without prompting (e.g. claude-code)")
     .action(wrapCommand(aiSetupCommand));
 program
     .command("search <query>")

package/dist/codebase-to-spec/area-name.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Area-name slugging shared across the codebase-to-spec stages.
+ *
+ * The pack/specify/compose/present stages and the worker dispatch surface all
+ * derive cache and output file names from an area's display name; they agree on
+ * the slug by routing through this single helper.
+ */
+/**
+ * Convert an area name to a stable filesystem-safe identifier.
+ * E.g., "Reading & Editing Files" → "reading-editing-files"
+ */
+export declare function sanitizeAreaName(name: string): string;
+//# sourceMappingURL=area-name.d.ts.map

package/dist/codebase-to-spec/area-name.js

@@ -0,0 +1,18 @@
+/**
+ * Area-name slugging shared across the codebase-to-spec stages.
+ *
+ * The pack/specify/compose/present stages and the worker dispatch surface all
+ * derive cache and output file names from an area's display name; they agree on
+ * the slug by routing through this single helper.
+ */
+/**
+ * Convert an area name to a stable filesystem-safe identifier.
+ * E.g., "Reading & Editing Files" → "reading-editing-files"
+ */
+export function sanitizeAreaName(name) {
+    return (name
+        .replace(/[^A-Za-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .toLowerCase() || "area");
+}
+//# sourceMappingURL=area-name.js.map

package/dist/codebase-to-spec/cache.d.ts

@@ -44,8 +44,39 @@ export interface CachePaths {
      * lifecycle state inline. Distinct from the legacy outline-N.json files.
      */
     outline: string;
+    /**
+     * Persisted run-config marker (e.g., the isolation decision). Written once
+     * at pack time and read by later stages, so a choice like isolation is
+     * honored end-to-end without the caller resupplying it. See CTS-PRESENT-5.2.
+     */
+    runConfig: string;
 }
 export declare function cachePaths(projectRoot: string): CachePaths;
+/**
+ * Per-run configuration persisted in the cache so a decision made at one stage
+ * is honored by later stages. The isolation decision (CTS-PRESENT-5) lives here:
+ * pack records it once, and the present stage reads it rather than relying on
+ * the caller — or the orchestrating agent's memory — to carry it across the run.
+ */
+export interface RunConfig {
+    /**
+     * Whether this run is isolated from an existing `.requirements/` directory:
+     * the pack excluded it, and the present stage writes under `.requirements/cts/`.
+     */
+    isolated: boolean;
+}
+/**
+ * Read the persisted run-config. Returns a non-isolated default when the marker
+ * is absent (an older cache, or a run that never wrote one) or unreadable, so a
+ * missing marker can never silently isolate output.
+ */
+export declare function readRunConfig(projectRoot: string): RunConfig;
+/**
+ * Persist the run-config. Pack writes this on every invocation (with the current
+ * isolation value) so a re-pack without `--ignore-requirements` clears a stale
+ * isolated marker rather than leaving the prior run's choice in place.
+ */
+export declare function writeRunConfig(projectRoot: string, config: RunConfig): void;
 export declare function ensureCacheDir(projectRoot: string): CachePaths;
 /**
  * Remove all cached artifacts. Used by `--fresh`.

package/dist/codebase-to-spec/cache.js

@@ -10,7 +10,7 @@
  * - CTS-PACK-1: pack stage paths (overview.txt, source.txt)
  * - CTS-RESUME-1..4: per-stage cache detection
  */
-import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 export const CACHE_DIR_NAME = ".dotrequirements-cache";
 export function cachePaths(projectRoot) {
@@ -30,8 +30,36 @@ export function cachePaths(projectRoot) {
         specFinal: join(root, "spec-final.md"),
         pipelineSummary: join(root, "pipeline-summary.json"),
         outline: join(root, "outline.yaml"),
+        runConfig: join(root, "run-config.json"),
     };
 }
+const DEFAULT_RUN_CONFIG = { isolated: false };
+/**
+ * Read the persisted run-config. Returns a non-isolated default when the marker
+ * is absent (an older cache, or a run that never wrote one) or unreadable, so a
+ * missing marker can never silently isolate output.
+ */
+export function readRunConfig(projectRoot) {
+    const path = cachePaths(projectRoot).runConfig;
+    if (!existsSync(path))
+        return { ...DEFAULT_RUN_CONFIG };
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        return { isolated: parsed?.isolated === true };
+    }
+    catch {
+        return { ...DEFAULT_RUN_CONFIG };
+    }
+}
+/**
+ * Persist the run-config. Pack writes this on every invocation (with the current
+ * isolation value) so a re-pack without `--ignore-requirements` clears a stale
+ * isolated marker rather than leaving the prior run's choice in place.
+ */
+export function writeRunConfig(projectRoot, config) {
+    const paths = ensureCacheDir(projectRoot);
+    writeFileSync(paths.runConfig, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+}
 export function ensureCacheDir(projectRoot) {
     const paths = cachePaths(projectRoot);
     if (!existsSync(paths.root)) {

package/dist/codebase-to-spec/compose.d.ts

@@ -5,13 +5,15 @@
  * title, a summary paragraph from the outline, and one H2 section per area.
  * Each area section contains the partial's content.
  *
- * After assembly, schema validation runs over the document. Mechanical errors
- * (duplicate IDs within an area, etc.) trigger deterministic fixes; other
- * errors surface to the caller.
+ * After assembly, a deterministic renumbering pass rewrites each prefix's
+ * requirement IDs into a clean 1..N sequence (sweeping the ID-sequence scars
+ * specifier/edit rounds leave behind), then schema validation runs over the
+ * document. Errors validation can't resolve surface to the caller.
  *
  * Requirements covered:
  * - CTS-COMPOSE-1: Compose produces a single Markdown document from partials
  * - CTS-COMPOSE-2: Compose validates the resulting document and corrects mechanical errors
+ * - CTS-COMPOSE-3: Compose renumbers requirement IDs into a clean sequential order
  */
 import type { Outline } from "./schemas.js";
 export interface ComposeOptions {
@@ -43,7 +45,8 @@ export declare function assembleComposedDocument(outline: Outline, partialPathFo
     partialsMissing: number;
 };
 /**
- * Compose the spec and write it to disk. Validates the result.
+ * Compose the spec and write it to disk. Renumbers requirement IDs into a
+ * clean sequence (CTS-COMPOSE-3), then validates the result.
  */
 export declare function runCompose(options: ComposeOptions): ComposeResult;
 //# sourceMappingURL=compose.d.ts.map

package/dist/codebase-to-spec/compose.js

@@ -5,17 +5,20 @@
  * title, a summary paragraph from the outline, and one H2 section per area.
  * Each area section contains the partial's content.
  *
- * After assembly, schema validation runs over the document. Mechanical errors
- * (duplicate IDs within an area, etc.) trigger deterministic fixes; other
- * errors surface to the caller.
+ * After assembly, a deterministic renumbering pass rewrites each prefix's
+ * requirement IDs into a clean 1..N sequence (sweeping the ID-sequence scars
+ * specifier/edit rounds leave behind), then schema validation runs over the
+ * document. Errors validation can't resolve surface to the caller.
  *
  * Requirements covered:
  * - CTS-COMPOSE-1: Compose produces a single Markdown document from partials
  * - CTS-COMPOSE-2: Compose validates the resulting document and corrects mechanical errors
+ * - CTS-COMPOSE-3: Compose renumbers requirement IDs into a clean sequential order
  */
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { parseRequirementsFile } from "../schema/parser.js";
-import { sanitizeAreaName } from "./fan-out.js";
+import { sanitizeAreaName } from "./area-name.js";
+import { renumberRequirements } from "./renumber.js";
 /**
  * Read a partial file. If missing or marked as a missing-partial placeholder,
  * return null (caller will emit a stub section).
@@ -84,27 +87,13 @@ function escapeYamlString(s) {
     return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
 /**
- * Attempt to fix mechanical errors in a composed document.
- *
- * For v0, the simplest mechanical fix is duplicate IDs within an area —
- * we detect and renumber them sequentially. Position-path and Gherkin syntax
- * errors surface to the validator's caller; we don't auto-fix those because
- * the editor loop is better suited to it.
- */
-function fixMechanicalErrors(content) {
-    // Detect duplicate IDs (lines like "PREFIX-AREA-001: ...") within each area.
-    // For v0 we punt — the schema validator will catch them and the caller will
-    // surface to the user. Returning content unchanged keeps the contract: the
-    // function is a no-op for inputs without fixable errors.
-    return content;
-}
-/**
- * Compose the spec and write it to disk. Validates the result.
+ * Compose the spec and write it to disk. Renumbers requirement IDs into a
+ * clean sequence (CTS-COMPOSE-3), then validates the result.
  */
 export function runCompose(options) {
     const { outline, partialPathFor, composedPath } = options;
     const { content, partialsIncluded, partialsMissing } = assembleComposedDocument(outline, partialPathFor);
-    const finalContent = fixMechanicalErrors(content);
+    const finalContent = renumberRequirements(content);
     writeFileSync(composedPath, finalContent, "utf-8");
     // Validate
     let validationError;

package/dist/codebase-to-spec/dispatch.js

@@ -29,8 +29,8 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { findProjectRoot } from "../utils/project-settings.js";
+import { sanitizeAreaName } from "./area-name.js";
 import { cachePaths } from "./cache.js";
-import { sanitizeAreaName } from "./fan-out.js";
 import { EDITOR_PROMPT } from "./prompts/editor.js";
 import { PLANNER_INITIAL_PROMPT } from "./prompts/planner-initial.js";
 import { PLANNER_REVISE_PROMPT } from "./prompts/planner-revise.js";

package/dist/codebase-to-spec/present.d.ts

@@ -85,6 +85,15 @@ export declare function splitComposedSpec(composed: string, outline: Outline): M
  * We just read it and return it.
  */
 export declare function buildSingleFileDoc(composedSpec: string): string;
+/**
+ * Insert the run marker as a top-level frontmatter field (IMPORT-1.0).
+ *
+ * At push time, a valid marker on a newly-created document grants its rows
+ * `imported` authorship — exempt from the requirement limit (IMPORT-2).
+ * Returns the content unchanged when it has no frontmatter block (defensive;
+ * present output always has one).
+ */
+export declare function stampRunMarker(content: string, marker: string): string;
 /**
  * Build a per-area requirements document for split mode.
  */

package/dist/codebase-to-spec/present.js

@@ -16,8 +16,10 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { parseRequirementsFile } from "../schema/parser.js";
-import { sanitizeAreaName } from "./fan-out.js";
+import { generateRunMarker } from "../schema/run-marker.js";
+import { sanitizeAreaName } from "./area-name.js";
 import { promptOverwriteChoice } from "./interactive.js";
+import { renumberRequirements } from "./renumber.js";
 export const AREA_SPLIT_THRESHOLD = 5;
 /**
  * Resolve the output path(s) the present stage would write to.
@@ -113,6 +115,20 @@ export function splitComposedSpec(composed, outline) {
 export function buildSingleFileDoc(composedSpec) {
     return composedSpec;
 }
+/**
+ * Insert the run marker as a top-level frontmatter field (IMPORT-1.0).
+ *
+ * At push time, a valid marker on a newly-created document grants its rows
+ * `imported` authorship — exempt from the requirement limit (IMPORT-2).
+ * Returns the content unchanged when it has no frontmatter block (defensive;
+ * present output always has one).
+ */
+export function stampRunMarker(content, marker) {
+    if (!content.startsWith("---\n")) {
+        return content;
+    }
+    return `---\nctsRun: ${marker}\n${content.slice(4)}`;
+}
 /**
  * Build a per-area requirements document for split mode.
  */
@@ -208,14 +224,21 @@ function validateContent(content) {
  */
 export async function runPresent(options) {
     const { outline, finalSpecPath, projectRoot, overwritePolicy, outputSubdir } = options;
-    const composedSpec = readFileSync(finalSpecPath, "utf-8");
+    // Renumber IDs one last time before writing out (CTS-COMPOSE-3.5): the
+    // cross-area review/edit pass that runs between compose and present can
+    // reintroduce ID-sequence scars (merges leave gaps, edits add suffixes), so
+    // this sweep guarantees the presented spec carries a clean sequence.
+    const composedSpec = renumberRequirements(readFileSync(finalSpecPath, "utf-8"));
     const plan = planPresentPaths(outline, projectRoot, outputSubdir);
     // Compute the content for each output up front.
+    // IMPORT-1.0/1.1: one run marker per present invocation, stamped into every
+    // document this run produces.
+    const runMarker = generateRunMarker();
     const planned = [];
     if (plan.mode === "single") {
         planned.push({
             outPath: plan.paths[0].outPath,
-            content: buildSingleFileDoc(composedSpec),
+            content: stampRunMarker(buildSingleFileDoc(composedSpec), runMarker),
         });
     }
     else {
@@ -223,7 +246,10 @@ export async function runPresent(options) {
         for (const { area, outPath } of plan.paths) {
             const body = sections.get(area) ??
                 "_(no content for this area was found in the composed spec)_";
-            planned.push({ outPath, content: buildAreaDoc(outline, area, body) });
+            planned.push({
+                outPath,
+                content: stampRunMarker(buildAreaDoc(outline, area, body), runMarker),
+            });
         }
     }
     // In fail-fast mode, scan for any conflict before writing anything.

package/dist/codebase-to-spec/prompts/planner-initial.d.ts

@@ -1,8 +1,9 @@
 /**
  * System prompt for the initial planner pass.
  *
- * Reads a compressed packed view of a codebase and produces an outline JSON.
- * Output is constrained by `OUTLINE_JSON_SCHEMA` via `claude -p --json-schema`.
+ * Reads a compressed packed view of a codebase and produces the behavioral-area
+ * outline. The worker dispatch supplies the exact output format and path; the
+ * outline's shape is the `CTS-PLAN-1` contract.
  *
  * Requirements covered:
  * - CTS-PLAN-1: Planner produces a behavioral outline from the compressed pack

package/dist/codebase-to-spec/prompts/planner-initial.js

@@ -1,8 +1,9 @@
 /**
  * System prompt for the initial planner pass.
  *
- * Reads a compressed packed view of a codebase and produces an outline JSON.
- * Output is constrained by `OUTLINE_JSON_SCHEMA` via `claude -p --json-schema`.
+ * Reads a compressed packed view of a codebase and produces the behavioral-area
+ * outline. The worker dispatch supplies the exact output format and path; the
+ * outline's shape is the `CTS-PLAN-1` contract.
  *
  * Requirements covered:
  * - CTS-PLAN-1: Planner produces a behavioral outline from the compressed pack

package/dist/codebase-to-spec/renumber.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Deterministic requirement-ID renumbering for composed CTS specs.
+ *
+ * Review and edit rounds leave ID-sequence scars behind: out-of-order,
+ * skipped, and letter-suffixed requirement numbers (`HONO-CTX-50` wedged
+ * between 16 and 17, `AUTH-PWD-12B`, `CUTIL-11a`). They are functionally
+ * harmless but read as sloppiness. This module rewrites each prefix's IDs
+ * into a clean, contiguous 1..N sequence in document order, and rewrites prose
+ * cross-references to match.
+ *
+ * It runs at two deterministic chokepoints (CTS-COMPOSE-3.0, CTS-COMPOSE-3.5):
+ *   - compose, before the cross-area review pass reads the spec (so reviewers
+ *     cite final IDs);
+ *   - present, after that pass, so scars the review/edit pass introduces are
+ *     swept before the spec is written out.
+ *
+ * It operates on raw text rather than the parsed tree on purpose: the dirty
+ * input (letter-suffixed keys) fails strict key validation in the parser — the
+ * scars are exactly what we need to clean before validation can pass. Working
+ * on text also keeps the blast radius tiny: only ID tokens change, everything
+ * else (prose, formatting, position paths) is preserved.
+ *
+ * Requirements covered:
+ * - CTS-COMPOSE-3: Compose renumbers requirement IDs into a clean sequential order
+ */
+export interface Rename {
+    /** The original ID exactly as it appears in the document. */
+    from: string;
+    /** The clean, sequential replacement ID. */
+    to: string;
+}
+/**
+ * Scan top-level requirement headers in document order and assign each prefix
+ * a contiguous 1..N sequence. Returns the rename list (including identity
+ * renames for already-clean IDs, so callers can treat the result uniformly).
+ *
+ * Only the first line of each ```dotrequirements block is treated as a header
+ * (one requirement per block, matching the parser's contract). Exact-duplicate
+ * keys are a distinct validation error and out of scope here: a repeated key
+ * does not consume a sequence slot (so it introduces no phantom gap) and keeps
+ * its first mapping, leaving the downstream validator to flag the duplicate.
+ */
+export declare function computeRenames(content: string): Rename[];
+/**
+ * Renumber every requirement ID in a composed spec into a clean, contiguous
+ * 1..N sequence per prefix, rewriting prose cross-references to match.
+ *
+ * Deterministic and idempotent: on an already-clean spec the rename map is the
+ * identity, so the output is byte-for-byte identical (CTS-COMPOSE-3.6).
+ */
+export declare function renumberRequirements(content: string): string;
+//# sourceMappingURL=renumber.d.ts.map

package/dist/codebase-to-spec/renumber.js

@@ -0,0 +1,105 @@
+/**
+ * Deterministic requirement-ID renumbering for composed CTS specs.
+ *
+ * Review and edit rounds leave ID-sequence scars behind: out-of-order,
+ * skipped, and letter-suffixed requirement numbers (`HONO-CTX-50` wedged
+ * between 16 and 17, `AUTH-PWD-12B`, `CUTIL-11a`). They are functionally
+ * harmless but read as sloppiness. This module rewrites each prefix's IDs
+ * into a clean, contiguous 1..N sequence in document order, and rewrites prose
+ * cross-references to match.
+ *
+ * It runs at two deterministic chokepoints (CTS-COMPOSE-3.0, CTS-COMPOSE-3.5):
+ *   - compose, before the cross-area review pass reads the spec (so reviewers
+ *     cite final IDs);
+ *   - present, after that pass, so scars the review/edit pass introduces are
+ *     swept before the spec is written out.
+ *
+ * It operates on raw text rather than the parsed tree on purpose: the dirty
+ * input (letter-suffixed keys) fails strict key validation in the parser — the
+ * scars are exactly what we need to clean before validation can pass. Working
+ * on text also keeps the blast radius tiny: only ID tokens change, everything
+ * else (prose, formatting, position paths) is preserved.
+ *
+ * Requirements covered:
+ * - CTS-COMPOSE-3: Compose renumbers requirement IDs into a clean sequential order
+ */
+/**
+ * A top-level requirement header line: `PREFIX-NUM[suffix]: ...`.
+ * The prefix is letters/hyphens (no digits — digits only appear in the number),
+ * so the first `-<digits>` after the prefix is unambiguously the numeric tail.
+ * A trailing letter run (`12B`, `11a`) is an editing scar we discard.
+ */
+const HEADER_RE = /^([A-Z][A-Z-]*?)-(\d+)([A-Za-z]*)\s*:/;
+/** A ```dotrequirements fenced block; group 1 is the block body. Tolerates
+ * CRLF so a `\r\n`-encoded spec still renumbers rather than silently no-op'ing. */
+const BLOCK_RE = /```dotrequirements\r?\n([\s\S]*?)```/g;
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Scan top-level requirement headers in document order and assign each prefix
+ * a contiguous 1..N sequence. Returns the rename list (including identity
+ * renames for already-clean IDs, so callers can treat the result uniformly).
+ *
+ * Only the first line of each ```dotrequirements block is treated as a header
+ * (one requirement per block, matching the parser's contract). Exact-duplicate
+ * keys are a distinct validation error and out of scope here: a repeated key
+ * does not consume a sequence slot (so it introduces no phantom gap) and keeps
+ * its first mapping, leaving the downstream validator to flag the duplicate.
+ */
+export function computeRenames(content) {
+    const counters = new Map();
+    const seen = new Set();
+    const renames = [];
+    BLOCK_RE.lastIndex = 0;
+    let block = BLOCK_RE.exec(content);
+    while (block !== null) {
+        const body = block[1];
+        const firstLine = body.split("\n").find((l) => l.trim().length > 0) ?? "";
+        const m = firstLine.match(HEADER_RE);
+        if (m) {
+            const [, prefix, num, suffix] = m;
+            const from = `${prefix}-${num}${suffix}`;
+            if (!seen.has(from)) {
+                seen.add(from);
+                const next = (counters.get(prefix) ?? 0) + 1;
+                counters.set(prefix, next);
+                renames.push({ from, to: `${prefix}-${next}` });
+            }
+        }
+        block = BLOCK_RE.exec(content);
+    }
+    return renames;
+}
+/**
+ * Renumber every requirement ID in a composed spec into a clean, contiguous
+ * 1..N sequence per prefix, rewriting prose cross-references to match.
+ *
+ * Deterministic and idempotent: on an already-clean spec the rename map is the
+ * identity, so the output is byte-for-byte identical (CTS-COMPOSE-3.6).
+ */
+export function renumberRequirements(content) {
+    const renames = computeRenames(content);
+    if (renames.length === 0)
+        return content;
+    const map = new Map(renames.map((r) => [r.from, r.to]));
+    // One combined, single-pass replacement so each ID location is rewritten
+    // exactly once — no risk of a freshly-written new ID being re-matched.
+    // Longest-first alternation so a shorter key can't shadow a longer one that
+    // shares its text. The lookbehind rejects a preceding letter/digit/hyphen so
+    // we never match the tail of a longer hyphenated token (e.g. `CTX-5` inside
+    // `HONO-CTX-5`); the lookahead mirrors it, rejecting a following
+    // letter/digit/hyphen so `AUTH-3` never matches inside `AUTH-30`, `AUTH-3B`,
+    // or a hyphen-joined token, while a following `.` (a child position path like
+    // `AUTH-3.2`) is preserved.
+    const alternation = renames
+        .map((r) => r.from)
+        .sort((a, b) => b.length - a.length)
+        .map(escapeRegExp)
+        .join("|");
+    const re = new RegExp(`(?<![A-Za-z0-9-])(${alternation})(?![A-Za-z0-9-])`, "g");
+    // Cross-references whose ID isn't an existing top-level requirement aren't in
+    // the map and so are never matched — they're left unchanged (CTS-COMPOSE-3.4).
+    return content.replace(re, (matched) => map.get(matched) ?? matched);
+}
+//# sourceMappingURL=renumber.js.map