@oevery/rsp 3.1.0-beta.4 → 3.1.1

package/dist/cli.mjs

@@ -4,14 +4,18 @@ import {
   installPackagedSkills,
   printPackagedSkillInventory,
   printSkillInstallResult
-} from "./chunk-D7XDXBFO.mjs";
+} from "./chunk-3Z4IO2TD.mjs";
 import {
   ArchiveHistoryError,
   GROUP_BRIEF_FILENAME,
+  GROUP_REOPEN_COMPLETION_PREFIX,
   HISTORY_DEFAULT_LIMIT,
   HISTORY_MAX_LIMIT,
+  IssueRelationshipError,
   WorkRefError,
+  createIssueRelationship,
   generateGroupBriefContent,
+  getGroupReopenEvidence,
   hasArchivedGroupBrief,
   historyInspectionComplete,
   inspectArchiveHistory,
@@ -23,6 +27,7 @@ import {
   inspectWorkTree,
   normalizeExecutableWorkRef,
   normalizeWorkRefSegment,
+  parseIssueRelationships,
   projectDependencyForest,
   queryArchiveHistory,
   readArchiveHistoryDetail,
@@ -30,8 +35,9 @@ import {
   resolveExecutableChange,
   resolveFocusMarkerPath,
   resolveWorkRef,
-  selectArchiveHistoryRecord
-} from "./chunk-FI3SYHVH.mjs";
+  selectArchiveHistoryRecord,
+  selectArchivedGroupBrief
+} from "./chunk-MUNLLVVH.mjs";
 import {
   ARCHIVES_DIR,
   CHANGES_DIR,
@@ -40,7 +46,9 @@ import {
   DEFAULT_DECISION_RECORDS_PATH,
   DocumentSectionCardinalityError,
   FOCUS_DIR,
+  GROUP_BRIEF_DOCUMENT_SCHEMA,
   LOCK_PATH,
+  ManagedPathError,
   OBSOLETE_RSP_RULES_PATH,
   PKG_ROOT,
   RSP_DIR,
@@ -61,8 +69,10 @@ import {
   generateChangeContent,
   generateDesignContent,
   generateSpecContent,
+  getDocumentSectionBody,
   getDocumentSectionDefinitionByHeading,
   getDocumentSections,
+  getDocumentTitles,
   getDurableReviewCandidateTargets,
   getVersion,
   guardRspInitialized,
@@ -91,7 +101,7 @@ import {
   validateDecisionRecordsFilesystemPath,
   walkMarkdownFiles,
   writeManagedFile
-} from "./chunk-FJVH7ZYU.mjs";
+} from "./chunk-WJXKLLIF.mjs";
 
 // src/cli.ts
 import { resolve } from "path";
@@ -734,6 +744,17 @@ async function runCheck(options = {}) {
       }
     }
     if (fm) {
+      try {
+        parseIssueRelationships(fm);
+      } catch (error) {
+        addDiagnostic({
+          severity: "error",
+          code: error instanceof IssueRelationshipError ? error.code : "invalid_issue_metadata",
+          change: name,
+          path: fp,
+          message: error instanceof Error ? error.message : String(error)
+        });
+      }
       if (!("kind" in fm)) {
         addDiagnostic({
           severity: "error",
@@ -922,15 +943,21 @@ async function createChange(name, summary = "", kind, options = {}) {
     console.error(`  ${pc.red("Usage:")} rsp create <name> [summary]`);
     process.exit(1);
   }
+  const hasIssueOption = options.issue !== void 0;
+  if (options.issueRelation && !hasIssueOption)
+    throw new Error("--issue-relation requires --issue");
+  const issues = options.issue !== void 0 ? [createIssueRelationship(options.issue, options.issueRelation)] : [];
   guardRspInitialized();
   try {
     return await withRspLock("create-change", async () => {
       const workRef = await resolveExecutableChange(name);
       const changePath = workRef.path;
       const existed = existsSync2(changePath);
+      if (existed && hasIssueOption)
+        throw new Error(`Change already exists; --issue cannot update ${workRef.name}`);
       if (!existed) {
         const focusEntry = resolveFocusMarkerPath(workRef);
-        const content = generateChangeContent(workRef.name, summary, kind, { lite: Boolean(options.lite) });
+        const content = generateChangeContent(workRef.name, summary, kind, { lite: Boolean(options.lite), issues });
         await mkdir4(dirname2(changePath), { recursive: true });
         let changeCreated = false;
         try {
@@ -1631,7 +1658,9 @@ function exitWorkRefError(error) {
 }
 
 // src/commands/group.ts
-import { mkdir as mkdir7, rename as rename2, writeFile as writeFile4 } from "fs/promises";
+import { randomUUID } from "crypto";
+import { existsSync as existsSync6 } from "fs";
+import { link, mkdir as mkdir7, readdir as readdir2, readFile as readFile8, rename as rename2, unlink as unlink8, writeFile as writeFile4 } from "fs/promises";
 import { join as join7 } from "path";
 var ChangeGroupError = class extends Error {
   name = "ChangeGroupError";
@@ -1719,6 +1748,136 @@ async function closeChangeGroup(name) {
     throw error;
   }
 }
+async function reopenChangeGroup(name, options) {
+  if (!name) {
+    console.error(`  ${pc.red("Usage:")} rsp group reopen <name> --reason <text> [--from <archive-path>]`);
+    process.exit(1);
+  }
+  const reason = options.reason?.trim();
+  if (!reason || /[\r\n]/.test(reason)) {
+    console.error(`  ${pc.red("Error:")} --reason must be one non-empty line`);
+    process.exit(1);
+  }
+  guardRspInitialized();
+  try {
+    await withRspLock("reopen-change-group", async () => {
+      const groupName = normalizeWorkRefSegment(name);
+      await requireEmptyGroupRecoverySubtree(join7(CHANGES_DIR, groupName), `Change Group work subtree for ${groupName}`);
+      await requireEmptyGroupRecoverySubtree(join7(FOCUS_DIR, groupName), `Change Group focus subtree for ${groupName}`);
+      const ref = resolveWorkRef(`${groupName}/brief`);
+      if (ref.kind !== "group-brief")
+        throw new ChangeGroupError(`invalid Change Group name: ${name}`);
+      const inspection = await inspectArchiveHistory();
+      if (!historyInspectionComplete(inspection)) {
+        throw new ArchiveHistoryError(
+          "archive_inspection_incomplete",
+          "archive history inspection is incomplete; resolve the reported diagnostics before reopening a Change Group"
+        );
+      }
+      const record = selectArchivedGroupBrief(
+        inspection.groupBriefs,
+        options.from ? { path: options.from } : { group: groupName }
+      );
+      if (record.group !== groupName) {
+        throw new ArchiveHistoryError(
+          "archive_identity_mismatch",
+          `selected archived Change Group belongs to ${record.group}, not ${groupName}`
+        );
+      }
+      if (existsSync6(ref.path))
+        throw new ArchiveHistoryError("open_group_exists", `open Change Group already exists: ${groupName}`);
+      const archivedContent = await readFile8(record.sourcePath, "utf-8");
+      const document = parseRspDocument(archivedContent, GROUP_BRIEF_DOCUMENT_SCHEMA);
+      validateArchivedGroupBrief(document, groupName);
+      const evidenceKey = `${GROUP_REOPEN_COMPLETION_PREFIX} \`${record.path}\`: ${reason}`;
+      const retainedEvidence = /* @__PURE__ */ new Set();
+      for (const retained of inspection.groupBriefs.filter((candidate) => candidate.group === groupName)) {
+        const content = retained.sourcePath === record.sourcePath ? archivedContent : await readFile8(retained.sourcePath, "utf-8");
+        for (const item of getGroupReopenEvidence(content))
+          retainedEvidence.add(item.key);
+      }
+      if (retainedEvidence.has(evidenceKey)) {
+        throw new ArchiveHistoryError(
+          "archive_reopen_evidence_replayed",
+          `reopen evidence already exists in retained Change Group history; choose a fresh reason or a different exact archive: ${record.path}`
+        );
+      }
+      const reopenedContent = appendDocumentSectionItem(
+        document,
+        "completionConditions",
+        `- [ ] ${evidenceKey}`
+      );
+      const groupDirectory = resolveManagedDirectoryChain(CHANGES_DIR, [groupName], "Change Group path");
+      await mkdir7(groupDirectory, { recursive: true });
+      const temporaryPath = join7(RSP_DIR, `.group-reopen-${process.pid}-${randomUUID()}.tmp`);
+      let mutationError;
+      try {
+        await writeFile4(temporaryPath, reopenedContent, { flag: "wx" });
+        await link(temporaryPath, ref.path);
+      } catch (error) {
+        mutationError = error;
+      }
+      try {
+        await unlink8(temporaryPath);
+      } catch (error) {
+        if (!mutationError)
+          console.log(`  ${pc.yellow("\u26A0")} temporary reopen file cleanup failed: ${toErrorMessage(error)}`);
+      }
+      if (mutationError) {
+        try {
+          await cleanupEmptyParentDirs(ref.path, CHANGES_DIR);
+        } catch {
+        }
+        if (mutationError.code === "EEXIST")
+          throw new ArchiveHistoryError("open_group_exists", `open Change Group already exists: ${groupName}`);
+        throw mutationError;
+      }
+      console.log(`  ${pc.green("Reopened Change Group:")} ${groupName}`);
+      console.log(`  ${pc.dim("retained archive")} \u2192 ${record.path}`);
+      console.log(`  ${pc.dim("unfocused Group Brief")} \u2192 ${ref.path}`);
+      console.log(`  ${pc.cyan("Next:")} run rsp reopen ${groupName}/<change> --reason <text> only for an incomplete archived child
+`);
+    });
+  } catch (error) {
+    if (error instanceof ArchiveHistoryError || error instanceof WorkRefError || error instanceof ChangeGroupError || error instanceof ManagedPathError) {
+      console.error(`  ${pc.red("Error:")} ${error.message}`);
+      if (error instanceof ArchiveHistoryError) {
+        for (const candidate of error.candidates)
+          console.error(`    ${candidate}`);
+        if (error.candidatesTruncated)
+          console.error(`    ... ${error.candidateTotal - error.candidates.length} more`);
+      }
+      process.exit(1);
+    }
+    throw error;
+  }
+}
+async function requireEmptyGroupRecoverySubtree(path, label) {
+  if (!requireManagedDirectory(path, label, { allowMissing: true }))
+    return;
+  let entries;
+  try {
+    entries = await readdir2(path);
+  } catch (error) {
+    throw new ChangeGroupError(`unable to inspect ${label}: ${toErrorMessage(error)}`);
+  }
+  if (entries.length > 0)
+    throw new ChangeGroupError(`${label} must be absent or empty before reopen; found: ${entries.sort().join(", ")}`);
+}
+function validateArchivedGroupBrief(document, group) {
+  const titles = getDocumentTitles(document, "identity");
+  if (titles.length !== 1 || titles[0] !== group)
+    throw new ArchiveHistoryError("archive_heading_invalid", `archived Change Group must contain exactly one canonical identity heading for ${group}`);
+  for (const section of GROUP_BRIEF_DOCUMENT_SCHEMA.sections) {
+    const matches = getDocumentSections(document, section.id);
+    if (matches.length !== 1 || !matches[0].canonical || !getDocumentSectionBody(document, section.id)) {
+      throw new ArchiveHistoryError(
+        "archive_section_invalid",
+        `archived Change Group must contain exactly one canonical required section: ${section.heading}`
+      );
+    }
+  }
+}
 function collectCloseReasons(group, errors) {
   const reasons = [...errors, ...group.warnings];
   const open = group.slices.filter((slice) => slice.state === "open").map((slice) => slice.name);
@@ -1926,6 +2085,11 @@ function printHistoryDetail(result) {
   console.log(`  ${pc.dim("Kind:")} ${record.kind}`);
   console.log(`  ${pc.dim("Path:")} ${record.path}`);
   console.log(`  ${pc.dim("Summary:")} ${record.summary}${record.summaryTruncated ? "\u2026" : ""}`);
+  if ((record.issues?.length ?? 0) > 0) {
+    console.log(`  ${pc.dim("Issues:")}`);
+    for (const issue of record.issues ?? [])
+      console.log(`    ${issue.relation} ${issue.url}`);
+  }
   console.log(`  ${pc.dim("Scenarios:")} ${record.scenarioCount}`);
   console.log(`  ${pc.dim("Tasks:")} ${record.checkboxes.tasks.done}/${record.checkboxes.tasks.total}`);
   console.log(`  ${pc.dim("Verify:")} ${record.checkboxes.verify.done}/${record.checkboxes.verify.total}`);
@@ -1943,8 +2107,8 @@ function printHistoryDetail(result) {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync6 } from "fs";
-import { mkdir as mkdir8, readFile as readFile8 } from "fs/promises";
+import { existsSync as existsSync7 } from "fs";
+import { mkdir as mkdir8, readFile as readFile9 } from "fs/promises";
 import { join as join8 } from "path";
 function generateConfigTemplate() {
   const fmtList = (items, indent) => items.map((i) => `${" ".repeat(indent)}# - ${i}`).join("\n");
@@ -1986,7 +2150,7 @@ function toTitle(projectName) {
   return projectName.startsWith("@") ? projectName.split("/")[1] || projectName : projectName;
 }
 async function initProject(args = {}) {
-  const isNew = !existsSync6(RSP_DIR);
+  const isNew = !existsSync7(RSP_DIR);
   const projectName = await detectProjectName();
   const mode = args.agentsMode ?? "managed";
   if (mode !== "managed" && mode !== "print") {
@@ -2001,7 +2165,7 @@ async function initProject(args = {}) {
     const agentsInspection = inspectManagedFile(agentsPath, "AGENTS.md", { allowMissing: true });
     if (agentsInspection.issue)
       throw agentsInspection.issue;
-    if (existsSync6(CONFIG_PATH)) {
+    if (existsSync7(CONFIG_PATH)) {
       clearConfigCache();
       const existingConfig = await inspectRspConfig();
       if (existingConfig.issues.length > 0)
@@ -2022,7 +2186,7 @@ async function initProject(args = {}) {
     for (const directory of dirs)
       await mkdir8(directory.path, { recursive: true });
     let created = false;
-    const bundledRules = await readFile8(join8(PKG_ROOT, "rules", "rsp-rules.md"), "utf-8");
+    const bundledRules = await readFile9(join8(PKG_ROOT, "rules", "rsp-rules.md"), "utf-8");
     created = await ensureFile(RSP_RULES_PATH, bundledRules) || created;
     created = await ensureFile(join8(RSP_DIR, "config.yaml"), generateConfigTemplate()) || created;
     clearConfigCache();
@@ -2055,7 +2219,7 @@ ${upsertRspAgentsBlock("").content}
       created = true;
       agentsUpdated = true;
     } else {
-      const existing = await readFile8(agentsPath, "utf-8");
+      const existing = await readFile9(agentsPath, "utf-8");
       const next = upsertRspAgentsBlock(existing);
       if (next.changed) {
         await writeManagedFile(agentsPath, next.content, "AGENTS.md");
@@ -2064,7 +2228,7 @@ ${upsertRspAgentsBlock("").content}
       }
     }
     if (mode === "print") {
-      const managed = await readFile8(agentsPath, "utf-8");
+      const managed = await readFile9(agentsPath, "utf-8");
       console.log(`
 ${managed}
 `);
@@ -2103,7 +2267,7 @@ ${managed}
 }
 
 // src/commands/ready.ts
-import { readFile as readFile9 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 function exitReadyError(name, error, options) {
   if (options.json) {
     emitJson({
@@ -2138,7 +2302,7 @@ async function showReady(name, options = {}) {
   const runtime = [];
   let content;
   try {
-    content = await readFile9(srcPath, "utf-8");
+    content = await readFile10(srcPath, "utf-8");
   } catch {
     console.error(`  ${pc.red("Error:")} unable to read .rsp/changes/${name}.md`);
     process.exit(1);
@@ -2221,8 +2385,8 @@ function formatArchiveReady(value) {
 }
 
 // src/commands/reopen.ts
-import { existsSync as existsSync7 } from "fs";
-import { mkdir as mkdir9, readFile as readFile10, unlink as unlink8, writeFile as writeFile5 } from "fs/promises";
+import { existsSync as existsSync8 } from "fs";
+import { mkdir as mkdir9, readFile as readFile11, unlink as unlink9, writeFile as writeFile5 } from "fs/promises";
 import { dirname as dirname4 } from "path";
 async function reopenChange(name, options) {
   if (!name) {
@@ -2267,12 +2431,12 @@ async function reopenChange(name, options) {
         }
         throw error;
       }
-      if (existsSync7(workRef.path))
+      if (existsSync8(workRef.path))
         throw new ArchiveHistoryError("open_change_exists", `open Change already exists: ${name}`);
       const focusEntry = resolveFocusMarkerPath(workRef);
-      if (existsSync7(focusEntry))
+      if (existsSync8(focusEntry))
         throw new ArchiveHistoryError("focus_marker_exists", `focus marker already exists for non-open Change: ${name}; run rsp doctor`);
-      const archivedContent = await readFile10(record.sourcePath, "utf-8");
+      const archivedContent = await readFile11(record.sourcePath, "utf-8");
       const reopenedContent = appendChecklistItem(
         appendChecklistItem(archivedContent, "tasks", `- [ ] Resolve reopened concern: ${reason}`),
         "verify",
@@ -2289,7 +2453,7 @@ async function reopenChange(name, options) {
       } catch (error) {
         if (changeCreated) {
           try {
-            await unlink8(workRef.path);
+            await unlink9(workRef.path);
             await cleanupEmptyParentDirs(workRef.path, CHANGES_DIR);
           } catch {
           }
@@ -2301,7 +2465,7 @@ async function reopenChange(name, options) {
       console.log(`  ${pc.dim("focused via focus.d")} \u2192 ${workRef.name}`);
       console.log(`  ${pc.cyan("Next:")} refine the reopened Task and Verify evidence, then resolve the concern
 `);
-      if (existsSync7(".git")) {
+      if (existsSync8(".git")) {
         console.log(`  ${pc.cyan("Git delivery:")}`);
         console.log(`    git status --short`);
         console.log(`    Inspect the complete reopen transition; stage and commit only with separate Git authority.`);
@@ -2337,7 +2501,7 @@ function appendChecklistItem(content, sectionId, item) {
 }
 
 // src/commands/show.ts
-import { readFile as readFile11 } from "fs/promises";
+import { readFile as readFile12 } from "fs/promises";
 function exitShowError(error, options) {
   const nextActions = error.code === "no_focused_change" ? ["Run: rsp status", "Run: rsp focus <name>", "Or run: rsp create <name>"] : [];
   if (options.json) {
@@ -2395,15 +2559,19 @@ async function showChange(nameOrFocused, options = {}) {
   const srcPath = workRef.path;
   let content;
   try {
-    content = await readFile11(srcPath, "utf-8");
+    content = await readFile12(srcPath, "utf-8");
   } catch {
     exitShowError({ code: "change_read_failed", message: `unable to read .rsp/changes/${name}.md` }, options);
   }
   let kind = "\u2014";
+  let issues = [];
   try {
     const fm = parseFrontmatter(content);
     kind = fm?.kind ? String(fm.kind) : "\u2014";
+    issues = parseIssueRelationships(fm);
   } catch (error) {
+    if (error instanceof IssueRelationshipError)
+      exitShowError({ code: error.code, message: error.message }, options);
     kind = "(invalid)";
     reportRuntime({
       code: "frontmatter_parse_failed",
@@ -2450,6 +2618,7 @@ async function showChange(nameOrFocused, options = {}) {
       name,
       path: normalizeLogicalPath(srcPath),
       kind,
+      issues,
       isFocused,
       progress: { done: cb.done, total: cb.total },
       blockers,
@@ -2468,6 +2637,11 @@ async function showChange(nameOrFocused, options = {}) {
   console.log(`  ${pc.bold("Change:")} ${pc.cyan(name)}`);
   console.log(`  ${pc.dim("Path:")} ${normalizeLogicalPath(srcPath)}`);
   console.log(`  ${pc.dim("Kind:")} ${kind}`);
+  if (issues.length > 0) {
+    console.log(`  ${pc.dim("Issues:")}`);
+    for (const issue of issues)
+      console.log(`    ${issue.relation} ${issue.url}`);
+  }
   console.log(`  ${pc.dim("Focused:")} ${isFocused ? pc.green("yes") : pc.dim("no")}`);
   console.log(`  ${pc.dim("Progress:")} ${cb.done}/${cb.total}`);
   console.log(`  ${pc.dim("Blockers:")} ${blockers ? pc.yellow("yes") : pc.green("no")}`);
@@ -2872,24 +3046,36 @@ var createCommand = defineCommand({
     description: "Create .rsp/changes/<name>.md [summary]"
   },
   args: {
-    name: {
+    "name": {
       type: "positional",
       description: "Change name",
       required: true
     },
-    kind: {
+    "kind": {
       type: "string",
       description: "Optional kind for a kind-aware template (feature, fix, refactor, docs, ops, research)"
     },
-    lite: {
+    "lite": {
       type: "boolean",
       description: "Use a shorter change template while keeping the required RSP sections",
       default: false
+    },
+    "issue": {
+      type: "string",
+      description: "Attach one external issue URL without fetching it"
+    },
+    "issue-relation": {
+      type: "string",
+      description: "Issue relationship: relates (default) or closes; requires --issue"
     }
   },
   async run({ args }) {
     const summary = Array.isArray(args._) && args._.length > 1 ? args._.slice(1).join(" ") : "";
-    await createChange(args.name, summary, args.kind, { lite: Boolean(args.lite) });
+    await createChange(args.name, summary, args.kind, {
+      lite: Boolean(args.lite),
+      issue: args.issue,
+      issueRelation: args.issueRelation
+    });
   }
 });
 var groupCreateCommand = defineCommand({
@@ -2912,7 +3098,7 @@ var groupCreateCommand = defineCommand({
 var groupCommand = defineCommand({
   meta: {
     name: "group",
-    description: "Create and close shallow Change Groups"
+    description: "Create, close, and explicitly reopen shallow Change Groups"
   },
   subCommands: {
     create: groupCreateCommand,
@@ -2931,6 +3117,31 @@ var groupCommand = defineCommand({
       async run({ args }) {
         await closeChangeGroup(args.name);
       }
+    }),
+    reopen: defineCommand({
+      meta: {
+        name: "reopen",
+        description: "Restore one archived Group Brief while retaining history"
+      },
+      args: {
+        name: {
+          type: "positional",
+          description: "Archived Change Group name",
+          required: true
+        },
+        from: {
+          type: "string",
+          description: "Exact .rsp/archives/... path when the Group has multiple archives"
+        },
+        reason: {
+          type: "string",
+          description: "One-line concern that makes Group completion unfinished",
+          required: true
+        }
+      },
+      async run({ args }) {
+        await reopenChangeGroup(args.name, { from: args.from, reason: args.reason });
+      }
     })
   }
 });
@@ -3396,7 +3607,7 @@ async function runCli(rawArgs = process.argv.slice(2)) {
   if (shouldLaunchSkillsUi(rawArgs, terminalEnvironment)) {
     const { resolveUiLocale } = await import("./locale-HT44UIUP.mjs");
     const locale = resolveUiLocale("auto", process.env.RSP_UI_LANG, process.env.LC_ALL ?? process.env.LC_MESSAGES ?? process.env.LANG ?? new Intl.DateTimeFormat().resolvedOptions().locale);
-    const { runSkillsTui } = await import("./entry-5OPKUZHF.mjs");
+    const { runSkillsTui } = await import("./entry-KAWA2AS4.mjs");
     const selection = await runSkillsTui(locale);
     if (selection.kind === "confirmed") {
       const result = await installPackagedSkills({ names: selection.names, force: selection.force });
@@ -3414,7 +3625,7 @@ async function runCli(rawArgs = process.argv.slice(2)) {
     } else {
       const { resolveUiLocale } = await import("./locale-HT44UIUP.mjs");
       const locale = resolveUiLocale(lang, process.env.RSP_UI_LANG, process.env.LC_ALL ?? process.env.LC_MESSAGES ?? process.env.LANG ?? new Intl.DateTimeFormat().resolvedOptions().locale);
-      const { runTui } = await import("./entry-FVUG6YW2.mjs");
+      const { runTui } = await import("./entry-IPHJBI53.mjs");
       const exitCode = await runTui(locale);
       if (exitCode !== 0)
         process.exitCode = exitCode;

package/dist/{entry-FVUG6YW2.mjs → entry-IPHJBI53.mjs}

@@ -7,14 +7,14 @@ import {
   projectDependencyForest,
   queryArchiveHistory,
   readArchiveHistoryDetail
-} from "./chunk-FI3SYHVH.mjs";
+} from "./chunk-MUNLLVVH.mjs";
 import {
   displayWidth,
   openTerminalSession,
   truncateDisplay,
   wrapDisplay
 } from "./chunk-JOMFFQRG.mjs";
-import "./chunk-FJVH7ZYU.mjs";
+import "./chunk-WJXKLLIF.mjs";
 
 // src/tui/entry.tsx
 import process from "process";

package/dist/{entry-5OPKUZHF.mjs → entry-KAWA2AS4.mjs}

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import {
   inspectPackagedSkillInventory
-} from "./chunk-D7XDXBFO.mjs";
+} from "./chunk-3Z4IO2TD.mjs";
 import {
   openTerminalSession,
   truncateDisplay
 } from "./chunk-JOMFFQRG.mjs";
-import "./chunk-FJVH7ZYU.mjs";
+import "./chunk-WJXKLLIF.mjs";
 
 // src/skills-tui/entry.tsx
 import process from "process";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oevery/rsp",
   "type": "module",
-  "version": "3.1.0-beta.4",
+  "version": "3.1.1",
   "description": "RSP (Reliable Software Practice), a repository-native engineering workflow for humans and AI agents",
   "author": "oevery",
   "license": "MIT",
@@ -37,13 +37,18 @@
   },
   "scripts": {
     "prepare": "pnpm run build",
-    "release:check": "pnpm run release:metadata-check && pnpm run build && pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run release:package-check",
+    "release:check": "pnpm run release:metadata-check && pnpm run docs:check && pnpm run docs:build && pnpm run build && pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run release:package-check",
     "release:candidate-check": "node scripts/release-candidate-check.mjs && pnpm run release:check",
     "release:metadata-check": "node scripts/release-metadata-check.mjs",
     "release:package-check": "node scripts/clean-install-check.mjs",
     "prepublishOnly": "pnpm run release:candidate-check",
     "build": "tsup",
     "dev": "tsup --watch",
+    "docs:build": "vitepress build docs",
+    "docs:check": "node scripts/docs-check.mjs",
+    "docs:deploy": "wrangler deploy",
+    "docs:dev": "vitepress dev docs",
+    "docs:preview": "vitepress preview docs",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
     "typecheck": "tsc --noEmit",
@@ -65,6 +70,8 @@
     "ink-testing-library": "4.0.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.10"
+    "vitepress": "^1.6.4",
+    "vitest": "^4.1.10",
+    "wrangler": "^4.114.0"
   }
 }

package/rules/rsp-rules.md

@@ -34,7 +34,7 @@ This file is the minimal fallback protocol for agents that cannot load the `rsp`
 - Parallel Changes in one Group follow the Brief `Slices` declaration order in plan output; unrelated work uses stable lexical ordering.
 - A Group Brief blocker is inherited by its direct child Changes as an external blocker; it does not create inferred dependency edges.
 - Persist only `open` and `archived`; readiness, blockers, verification, and next actions are derived.
-- When fresh evidence shows that an archived executable Change did not meet its original acceptance, explicitly use `rsp reopen <work-ref> --reason <text>` to restore the same WorkRef. Reopen retains the selected archive, focuses the open Change, and adds unfinished Task and Verify evidence. Multiple archives require exact `--from .rsp/archives/...` selection; open work wins over same-WorkRef history in current dependency state. Use a new corrective Change for genuinely new scope or an independently delivered correction. Do not reopen a closed Change Group implicitly.
+- When fresh evidence shows that archived acceptance was incomplete, restore the same owner explicitly. `rsp reopen <work-ref> --reason <text>` retains the selected archive, focuses the executable Change, and adds unfinished Task and Verify evidence. If the enclosing Group is closed, first run `rsp group reopen <group> --reason <text>` to restore only its retained Brief as unfocused work with unfinished completion evidence, then separately reopen only the incomplete child. Multiple matching Change or Group archives require exact `--from .rsp/archives/...` selection. Neither command cascades into children or dependents, and `rsp group create` never reuses archived identity. Open work wins over same-identity history in current state; genuinely new or independently delivered scope uses a new owner.
 - Ordinary implementation is the default after unexplained failures are ruled out. Use test-first only when authority requires it or a concrete risk makes pre-mutation failure materially safer. Retain a new test only when it protects observable behavior or a real boundary with distinct proportionate value; otherwise remove the temporary probe and use decisive final verification.
 - Before later-turn mutation under a direct report, design, tiny, or small route, rederive from the newly authorized objective and prospective work. Cross-module implementation, multiple acceptance surfaces, repeated production-path correction, real-host validation, bounded review convergence, lifecycle delivery, or a clear ready successor requires the smallest sufficient WorkRef and fresh qualification before mutation; unchanged tiny/small follow-ups stay direct. Elapsed time and message count alone never escalate work.
 - Before focusing or mutating a different WorkRef, compare dirty product or durable-truth paths with the prior owner's declared or observed paths. Overlap requires continuation of the same open WorkRef, an authorized reopen, an explicitly authorized integration owner, or a stop for boundary resolution. Disjoint authorized work may proceed without staging or forcing a commit; insufficient ownership evidence stops the transition.
@@ -59,6 +59,8 @@ This file is the minimal fallback protocol for agents that cannot load the `rsp`
 
 ## Continuation and conflicts
 
+- During managed execution, treat a progress or status inquiry as an evidence update, not a stop signal, and continue authorized work while authority and blockers permit it. An explicit pause stops and confirms active workers before acknowledgement, preserves the focused owner, and permits no further mutation until resume. Only an explicit release or unfocus request clears owner selection; environment and verification blockers preserve the focused owner.
+- Resume treats continuation prose only as pointers: reread authority, status, focus, owned diff, blockers, and decisive evidence, invalidate stale claims, and requalify Manage before mutation or dispatch. Never persist paused, worker, controller, or execution-chronology state.
 - When execution stops with accepted work remaining, return one compact continuation with the semantic fields `WorkRef`, `Authority`, `Current state`, `Changed artifacts`, `Fresh verification`, `Blockers`, and `Next action`. Keep this field order, but localize the human-facing title and labels to the response language without changing referenced artifact prose or canonical technical values. Reopen its authority pointers, inspect drift, and refresh verification before resuming; it is not durable truth or a second state store.
 - Write a continuation file only when explicitly authorized. Never persist hidden handoff or controller state.
 - If an active merge, rebase, or cherry-pick conflict intersects authorized implementation, inspect the exact operation and conflicted paths, then compare base/ours/theirs semantics in that operation. Resolve only evidenced in-scope content while preserving unrelated work.
@@ -69,6 +71,6 @@ This file is the minimal fallback protocol for agents that cannot load the `rsp`
 
 - Do not create RSP-managed files directly when a command owns the operation.
 - Do not create archive entries directly; use `npx -y @oevery/rsp archive <name>`.
-- Do not restore archived Change content directly; use `npx -y @oevery/rsp reopen <name> --reason <text>` and exact `--from` selection when required.
+- Do not restore archived Change or Group Brief content directly; use `npx -y @oevery/rsp reopen <name> --reason <text>` or `npx -y @oevery/rsp group reopen <group> --reason <text>` and exact `--from` selection when required.
 - Do not modify content outside the managed RSP block in `AGENTS.md` unless explicitly requested.
 - Archive reports warnings but does not grant commit, push, publication, deletion, or external approval authority.