@oevery/rsp 3.1.0-beta.4 → 3.1.0-beta.5

package/README.md

@@ -34,17 +34,17 @@ RSP derives the next action from the selected Change, repository evidence, verif
 ## Quick start
 
 ```bash
-npx -y @oevery/rsp@3.1.0-beta.4 init
-npx -y @oevery/rsp@3.1.0-beta.4 doctor
+npx -y @oevery/rsp@3.1.0-beta.5 init
+npx -y @oevery/rsp@3.1.0-beta.5 doctor
 ```
 
 Recommended bootstrap flow:
 
 ```bash
-npx -y @oevery/rsp@3.1.0-beta.4 init --with-project-setup
+npx -y @oevery/rsp@3.1.0-beta.5 init --with-project-setup
 # fill .rsp/changes/project-setup.md
 # fill .rsp/specs/design.md
-npx -y @oevery/rsp@3.1.0-beta.4 doctor
+npx -y @oevery/rsp@3.1.0-beta.5 doctor
 ```
 
 ## Artifact foundation
@@ -89,15 +89,16 @@ npx -y @oevery/rsp@3.1.0-beta.4 doctor
 - An exact blocker line, `- requires \`<change-work-ref>\`: <reason>`, declares a dependency on another executable Change. Free-form blockers stay external; RSP never guesses edges from prose. Archived prerequisites resolve automatically.
 - Change names are either flat (`<change>`) or one direct grouped child (`<group>/<change>`). Recursive work directories are rejected.
 - A Change Group is optional and is the only composite work shape. Its non-executable, non-focusable logical identity `<group>/brief`, physically stored as `<group>/00-brief.md`, owns the shared goal, constraints, declared slices, completion conditions, durable outcomes, and blockers for at least two direct child Changes.
-- Create a group before its children. Every grouped Change must be declared by the brief, is focused and archived independently, and includes the brief in its context. With no focus, `status` uses Brief declaration order and current blockers to recommend the first executable slice. `status`, `check`, and `doctor` derive group health and completion without persisting another state; `rsp group close` archives only a completed brief. Archived Group identities cannot be reopened.
+- Create a group before its children. Every grouped Change must be declared by the brief, is focused and archived independently, and includes the brief in its context. With no focus, `status` uses Brief declaration order and current blockers to recommend the first executable slice. `status`, `check`, and `doctor` derive group health and completion without persisting another state; `rsp group close` archives only a completed brief. `rsp group create` never reuses an archived identity; `rsp group reopen <group> --reason <text>` explicitly restores one retained Brief snapshot as unfinished, unfocused continuation of that same Group.
 - A Group Brief blocker is inherited by its direct children as an external blocker in the derived execution plan; it does not create guessed dependency edges.
 - A Markdown file and directory cannot claim the same work identity.
 - `rsp status`, `rsp check`, and `rsp doctor` inspect the same complete work tree and dependency facts. `status` derives exact edges with their reasons, ready work, blockers, and stable waves without a graph file; `check` and `doctor` reject incomplete archive inspection, malformed or missing targets, self-dependencies, and cycles. The `changes/` root must exist as a real directory, and existing focus/archive roots and group prefixes must also be real directories. Unsupported directories, non-Markdown entries, symlinks, missing or unreadable current work, incomplete reads, and identity collisions are visible errors. `status` exits non-zero instead of hiding invalid work.
 - `rsp init`, `rsp update`, `rsp add spec`, and the generated Specs index builder apply the same no-follow managed-path checks. Archive discovery accepts only flat archive files or one real group directory; recursively organized Specs accept only real directories and regular files.
 - Final managed files—such as the project `AGENTS.md`, focus markers, fallback/config files, the generated Specs index, and placeholders—must also be regular files; RSP rejects static symlink targets before reading or writing them.
 - Completed changes move to `archives/`. Stable current facts belong in Specs; lasting rationale belongs in Decision Records; stable scoped operating instructions belong in nearest project-owned `AGENTS.md`.
-- When later evidence shows that the original acceptance was not actually met, `rsp reopen <work-ref> --reason <text>` restores the same executable WorkRef as focused open work and retains the selected archive as history. Multiple archives require an exact `--from .rsp/archives/...` path. Use a new corrective Change for genuinely new scope or an independently delivered correction; reopening never rewrites Git or published history.
+- When later evidence shows that the original acceptance was not actually met, `rsp reopen <work-ref> --reason <text>` restores the same executable WorkRef as focused open work and retains the selected archive as history. If its Group is closed, first use `rsp group reopen <group> --reason <text>`, then reopen only the incomplete child. Multiple matching Change or Group archives require an exact `--from .rsp/archives/...` path. Group reopen creates no focus and never reopens children or dependents. Use a new corrective Change for genuinely new scope or an independently delivered correction; reopening never rewrites Git or published history.
 - Do not promote task history, debugging notes, or one-off implementation context into Specs, Decision Records, or project instructions.
+- Managed progress questions report current evidence and do not implicitly pause an authorized run. Explicit pause confirms active work has stopped but preserves the focused WorkRef; only explicit release or `rsp unfocus` clears selection. Blocked or paused runs return a response-only continuation, and resume rereads authority, status, diff, blockers, and verification before requalifying Manage. RSP persists no paused or controller state.
 - Change `Spec` delta markers (`### ADDED`, `### MODIFIED`, `### REMOVED`) are planning aids only. `rsp archive` does not automatically promote them into Specs or Decision Records. Durable writeback remains an explicit semantic decision.
 - `rsp check` performs deterministic hygiene checks. It warns about unfinished template placeholders and unresolved clarification markers, but those warnings do not replace the semantic durable-update decision.
 
@@ -204,7 +205,7 @@ New `rsp init` config templates use the shown `auto` plus `lifecycle` policy. If
 
 Humans should start with this README. Agents should follow the nearest `AGENTS.md`, prefer `skills/rsp/SKILL.md`, and use `.rsp/rsp-rules.md` only when the Skill is unavailable.
 
-When this README shows `rsp <command>`, it assumes the command is already available in your environment. For opt-in beta evaluation, pin the exact prerelease identity, such as `npx -y @oevery/rsp@3.1.0-beta.4 <command>`; stable users can keep using the unversioned package entrypoint for npm `latest`.
+When this README shows `rsp <command>`, it assumes the command is already available in your environment. For opt-in beta evaluation, pin the exact prerelease identity, such as `npx -y @oevery/rsp@3.1.0-beta.5 <command>`; stable users can keep using the unversioned package entrypoint for npm `latest`.
 
 Install the exact package's default lifecycle suite into the current project:
 
@@ -232,8 +233,8 @@ rsp skills install rsp-structural-audit
 Both forms install from the package that invoked `rsp`, so prerelease dogfooding can pin one exact npm identity:
 
 ```bash
-npx -y @oevery/rsp@3.1.0-beta.4 skills install --dry-run
-npx -y @oevery/rsp@3.1.0-beta.4 skills install
+npx -y @oevery/rsp@3.1.0-beta.5 skills install --dry-run
+npx -y @oevery/rsp@3.1.0-beta.5 skills install
 ```
 
 Exact prerelease identities avoid depending on a moving dist-tag. `rsp update` refreshes RSP-managed project files only; run `rsp skills install` separately to refresh the package-owned Skill suite.
@@ -287,8 +288,8 @@ Durable review makes two independent semantic choices: whether current facts or
 
 New project:
 
-1. `npx -y @oevery/rsp@3.1.0-beta.4 init`
-2. Prefer `npx -y @oevery/rsp@3.1.0-beta.4 init --with-project-setup`, or run `rsp create project-setup` manually
+1. `npx -y @oevery/rsp@3.1.0-beta.5 init`
+2. Prefer `npx -y @oevery/rsp@3.1.0-beta.5 init --with-project-setup`, or run `rsp create project-setup` manually
 3. Fill `.rsp/specs/design.md`
 4. Use `rsp add spec <name>` only when a new durable project doc is needed
 5. Keep lasting rationale in the configured Decision Record directory and stable scoped operating instructions in the nearest project-owned `AGENTS.md`
@@ -302,14 +303,14 @@ New project:
 
 Existing project with a rich `AGENTS.md`:
 
-1. `npx -y @oevery/rsp@3.1.0-beta.4 init`
+1. `npx -y @oevery/rsp@3.1.0-beta.5 init`
 2. Keep the managed block thin
 3. Keep project-wide boundaries and navigation in `.rsp/specs/design.md`, and route cohesive durable facts to the smallest domain Spec
 4. Use `rsp add spec <name>` only when another durable current-fact document is needed
 
 AI-assisted setup:
 
-1. `npx -y @oevery/rsp@3.1.0-beta.4 init --agents-mode print --with-project-setup`
+1. `npx -y @oevery/rsp@3.1.0-beta.5 init --agents-mode print --with-project-setup`
 2. Keep the managed block as generated and adapt only the surrounding human-owned content if needed
 3. Have the AI review and fill `.rsp/changes/project-setup.md`
 4. Have the AI fill `.rsp/specs/design.md`
@@ -327,9 +328,11 @@ rsp skills list [--json]        List bundled Skills and exact project installati
 rsp skills install [name] [--dry-run] [--force]
                                   Install the default eleven Skills or one exact optional Skill into .agents/skills
 rsp add spec <name>             Create .rsp/specs/<name>.md and rebuild specs index
-rsp create <name> [summary]     Create .rsp/changes/<name>.md; add --lite for a shorter template
+rsp create <name> [summary]     Create .rsp/changes/<name>.md; add --lite or --issue <url> [--issue-relation relates|closes]
 rsp group create <name> [goal] Create an unfocused .rsp/changes/<name>/00-brief.md
 rsp group close <name>         Archive a completed Group Brief after every child is archived
+rsp group reopen <name> --reason <text> [--from <archive-path>]
+                                  Restore the same Group Brief as unfinished, unfocused open work and retain history
 rsp focus <name>                Mark an open change as currently focused
 rsp unfocus <name>              Remove an open change from the current focus set
 rsp archive <name>              Archive to .rsp/archives/
@@ -378,6 +381,8 @@ The JSON-producing inspection commands `status`, `show`, `ready`, `check`, `doct
 
 `rsp create --lite` is a shorter template for explicitly tracked small changes; simple current-session tasks should not create RSP changes unless tracking is intentionally needed.
 
+`rsp create <name> --issue <url>` attaches one validated external issue without network access and defaults to `relation: relates`; `--issue-relation closes` must be explicit and requires `--issue`. Issue options never update an existing Change: that invocation fails without changing the Change or focus. RSP stores only the canonical URL and relationship, never credentials, fetched title/body, or retrieval state. `status --json`, `show`, and `history` preserve valid relationships; immutable archives with older issue metadata remain readable but omit that opaque legacy projection. Shape may use available host access to retrieve real issue content, but failed access degrades to login retry, pasted source data, or a link-only draft rather than fabrication. Commit may add a closing keyword only for a terminal commit with completed acceptance and an owned `closes` relationship; otherwise it keeps a non-closing canonical URL reference.
+
 `rsp doctor --fix` runs only safe deterministic repairs. Its `fixed` JSON entries report actual filesystem changes; a healthy project returns `fixed: []` and the human output says no safe fixes are needed.
 
 ## Platform-agnostic

package/README.zh-CN.md

@@ -34,17 +34,17 @@ RSP 根据 selected Change、仓库证据、验证结果和 blockers 推导下
 ## 快速开始
 
 ```bash
-npx -y @oevery/rsp@3.1.0-beta.4 init
-npx -y @oevery/rsp@3.1.0-beta.4 doctor
+npx -y @oevery/rsp@3.1.0-beta.5 init
+npx -y @oevery/rsp@3.1.0-beta.5 doctor
 ```
 
 推荐启动流程：
 
 ```bash
-npx -y @oevery/rsp@3.1.0-beta.4 init --with-project-setup
+npx -y @oevery/rsp@3.1.0-beta.5 init --with-project-setup
 # 填写 .rsp/changes/project-setup.md
 # 填写 .rsp/specs/design.md
-npx -y @oevery/rsp@3.1.0-beta.4 doctor
+npx -y @oevery/rsp@3.1.0-beta.5 doctor
 ```
 
 ## Artifact foundation
@@ -203,7 +203,7 @@ Change 粒度由一个可观察结果及其共享的 acceptance、verification
 
 人类应从本 README 开始；agent 应遵循 nearest `AGENTS.md`，优先加载 `skills/rsp/SKILL.md`，仅在 Skill 不可用时读取 `.rsp/rsp-rules.md`。
 
-如果文档中写的是 `rsp <command>`，默认前提是你的环境里已经能直接运行 `rsp`。进行 opt-in beta 评估时，应固定精确 prerelease 身份，例如 `npx -y @oevery/rsp@3.1.0-beta.4 <command>`；stable 用户仍可使用不带版本的入口获取 npm `latest`。
+如果文档中写的是 `rsp <command>`，默认前提是你的环境里已经能直接运行 `rsp`。进行 opt-in beta 评估时，应固定精确 prerelease 身份，例如 `npx -y @oevery/rsp@3.1.0-beta.5 <command>`；stable 用户仍可使用不带版本的入口获取 npm `latest`。
 
 将当前精确包内置的默认生命周期 Skill 套件安装到当前项目：
 
@@ -231,8 +231,8 @@ rsp skills install rsp-structural-audit
 两种形式都从调用 `rsp` 的同一个包安装，因此 beta 评估可以固定精确 npm 身份：
 
 ```bash
-npx -y @oevery/rsp@3.1.0-beta.4 skills install --dry-run
-npx -y @oevery/rsp@3.1.0-beta.4 skills install
+npx -y @oevery/rsp@3.1.0-beta.5 skills install --dry-run
+npx -y @oevery/rsp@3.1.0-beta.5 skills install
 ```
 
 精确 prerelease 身份可以避免依赖持续移动的 dist-tag。`rsp update` 只刷新由 RSP 管理的项目文件；刷新 package-owned Skill 套件需要单独运行 `rsp skills install`。
@@ -286,8 +286,8 @@ durable review 包含两个独立语义判断：是否更新当前事实或作
 
 新项目：
 
-1. `npx -y @oevery/rsp@3.1.0-beta.4 init`
-2. 优先使用 `npx -y @oevery/rsp@3.1.0-beta.4 init --with-project-setup`，或手动执行 `rsp create project-setup`
+1. `npx -y @oevery/rsp@3.1.0-beta.5 init`
+2. 优先使用 `npx -y @oevery/rsp@3.1.0-beta.5 init --with-project-setup`，或手动执行 `rsp create project-setup`
 3. 填写 `.rsp/specs/design.md`
 4. 仅在需要新的长期项目文档时使用 `rsp add spec <name>`
 5. 将长期理由写入配置的 Decision Record 目录，将稳定的作用域操作指令写入 nearest project-owned `AGENTS.md`
@@ -300,14 +300,14 @@ durable review 包含两个独立语义判断：是否更新当前事实或作
 
 已有复杂 `AGENTS.md` 的项目：
 
-1. `npx -y @oevery/rsp@3.1.0-beta.4 init`
+1. `npx -y @oevery/rsp@3.1.0-beta.5 init`
 2. 保持受管块尽量薄
 3. 将项目级边界与导航放在 `.rsp/specs/design.md`，把成组的长期事实放入最小领域 Spec
 4. 只有需要额外的 durable current-fact 文档时才使用 `rsp add spec <name>`
 
 AI 协助接入：
 
-1. `npx -y @oevery/rsp@3.1.0-beta.4 init --agents-mode print --with-project-setup`
+1. `npx -y @oevery/rsp@3.1.0-beta.5 init --agents-mode print --with-project-setup`
 2. 保持受管块原样，只在需要时调整周围由人维护的内容
 3. 让 AI 审阅并填写 `.rsp/changes/project-setup.md`
 4. 让 AI 填写 `.rsp/specs/design.md`

package/dist/{chunk-D7XDXBFO.mjs → chunk-3X2V6IEW.mjs}

@@ -5,7 +5,7 @@ import {
   inspectManagedDirectory,
   inspectManagedFileTree,
   resolveManagedDirectoryChain
-} from "./chunk-FJVH7ZYU.mjs";
+} from "./chunk-UVYEXKYS.mjs";
 
 // src/commands/skills.ts
 import { randomUUID } from "crypto";

package/dist/{chunk-FJVH7ZYU.mjs → chunk-UVYEXKYS.mjs}

@@ -472,10 +472,11 @@ function normalizeLogicalPath(pathValue) {
 function generateChangeContent(name, summary = "", kind, options = {}) {
   const placeholder = "<\u2026>";
   const proposalSummary = summary || placeholder;
+  const issueFrontmatter = renderIssueFrontmatter(options.issues ?? []);
   if (name === "project-setup") {
     return `---
 kind: ops
----
+${issueFrontmatter}---
 
 ${renderDocumentTitle(CHANGE_DOCUMENT_SCHEMA, "project-setup")}
 
@@ -533,11 +534,11 @@ ${changeSectionHeading("blockers")}
   }
   const frontmatterKind = kind ?? "<choose: feature | fix | refactor | docs | ops | research>";
   if (options.lite)
-    return generateLiteChangeContent(name, proposalSummary, frontmatterKind);
+    return generateLiteChangeContent(name, proposalSummary, frontmatterKind, issueFrontmatter);
   const template = getChangeTemplateByKind(kind);
   return `---
 kind: "${frontmatterKind}"
----
+${issueFrontmatter}---
 
 ${renderDocumentTitle(CHANGE_DOCUMENT_SCHEMA, name)}
 
@@ -582,11 +583,11 @@ ${changeSectionHeading("blockers")}
 - none
 `;
 }
-function generateLiteChangeContent(name, proposalSummary, frontmatterKind) {
+function generateLiteChangeContent(name, proposalSummary, frontmatterKind, issueFrontmatter) {
   const placeholder = "<\u2026>";
   return `---
 kind: "${frontmatterKind}"
----
+${issueFrontmatter}---
 
 ${renderDocumentTitle(CHANGE_DOCUMENT_SCHEMA, name)}
 
@@ -635,6 +636,14 @@ ${changeSectionHeading("blockers")}
 - none
 `;
 }
+function renderIssueFrontmatter(issues) {
+  if (issues.length === 0)
+    return "";
+  return `issues:
+${issues.map((issue) => `  - url: ${JSON.stringify(issue.url)}
+    relation: ${issue.relation}`).join("\n")}
+`;
+}
 function getChangeTemplateByKind(kind) {
   const placeholder = "<\u2026>";
   const delta = kind === "feature" || kind === "research" || kind === void 0 ? "ADDED" : "MODIFIED";

package/dist/{chunk-FI3SYHVH.mjs → chunk-ZKZVWJQ7.mjs}

@@ -29,7 +29,7 @@ import {
   resolveLanguagePolicy,
   resolveManagePolicy,
   toErrorMessage
-} from "./chunk-FJVH7ZYU.mjs";
+} from "./chunk-UVYEXKYS.mjs";
 
 // src/status/inspect.ts
 import { readFile as readFile5, stat } from "fs/promises";
@@ -666,6 +666,7 @@ function normalizeLogicalPath2(path) {
 
 // src/core/change-group.ts
 var GROUP_BRIEF_SECTIONS = getCanonicalSectionHeadings(GROUP_BRIEF_DOCUMENT_SCHEMA);
+var GROUP_REOPEN_COMPLETION_PREFIX = "Resolve reopened concern from";
 async function resolveExecutableChange(name, options = {}) {
   const ref = resolveWorkRef(name, { ...options, executable: true });
   if (ref.kind === "group-change")
@@ -711,6 +712,8 @@ async function inspectChangeGroups(options = {}) {
   const groups = [];
   const archivedSlicesByGroup = /* @__PURE__ */ new Map();
   const archivedGroups = /* @__PURE__ */ new Set();
+  const archivedGroupReopenEvidence = /* @__PURE__ */ new Map();
+  const archivedGroupBriefPaths = /* @__PURE__ */ new Map();
   const openGroupNames = new Set(workTree.briefs.map((brief) => brief.group));
   for (const path of archiveTree.files) {
     const archivePath = normalizeLogicalPath(relative2(ARCHIVES_DIR, path));
@@ -736,8 +739,16 @@ async function inspectChangeGroups(options = {}) {
           archivedSlicesByGroup.set(archiveGroup, groupSlices);
         }
       }
-      if (getDocumentTitle(parseRspDocument(content, GROUP_BRIEF_DOCUMENT_SCHEMA), "identity") === archiveGroup)
+      if (getDocumentTitle(parseRspDocument(content, GROUP_BRIEF_DOCUMENT_SCHEMA), "identity") === archiveGroup) {
         archivedGroups.add(archiveGroup);
+        const evidence = archivedGroupReopenEvidence.get(archiveGroup) ?? /* @__PURE__ */ new Set();
+        for (const item of getGroupReopenEvidence(content))
+          evidence.add(item.key);
+        archivedGroupReopenEvidence.set(archiveGroup, evidence);
+        const retainedPaths = archivedGroupBriefPaths.get(archiveGroup) ?? /* @__PURE__ */ new Set();
+        retainedPaths.add(`.rsp/archives/${archivePath}`);
+        archivedGroupBriefPaths.set(archiveGroup, retainedPaths);
+      }
     } catch (error) {
       diagnostics.push({
         severity: "error",
@@ -764,7 +775,11 @@ async function inspectChangeGroups(options = {}) {
     }
     const parsed = parseGroupBrief(brief.group, content);
     diagnostics.push(...parsed.diagnostics.map((diagnostic) => ({ ...diagnostic, path: brief.path })));
-    if (archivedGroups.has(brief.group)) {
+    if (archivedGroups.has(brief.group) && !hasExplicitGroupReopenEvidence(
+      content,
+      archivedGroupReopenEvidence.get(brief.group) ?? /* @__PURE__ */ new Set(),
+      archivedGroupBriefPaths.get(brief.group) ?? /* @__PURE__ */ new Set()
+    )) {
       diagnostics.push({
         severity: "error",
         code: "group_identity_reopened",
@@ -855,6 +870,16 @@ async function inspectChangeGroups(options = {}) {
   groups.sort((left, right) => left.name.localeCompare(right.name));
   return { groups, diagnostics };
 }
+function getGroupReopenEvidence(content) {
+  const completion = getDocumentSectionBody(parseRspDocument(content, GROUP_BRIEF_DOCUMENT_SCHEMA), "completionConditions");
+  return completion.split("\n").flatMap((line) => {
+    const match = line.trim().match(/^-\s+\[([ /xX-])\]\s+(Resolve reopened concern from `(\.rsp\/archives\/[^`]+)`: \S.*)$/);
+    return match ? [{ active: match[1] !== "-", key: match[2], sourcePath: match[3] }] : [];
+  });
+}
+function hasExplicitGroupReopenEvidence(content, retainedEvidence, retainedGroupBriefPaths) {
+  return getGroupReopenEvidence(content).some((item) => item.active && retainedGroupBriefPaths.has(item.sourcePath) && !retainedEvidence.has(item.key));
+}
 async function requireDeclaredGroupSlice(ref) {
   const briefPath = join2(dirname(ref.path), GROUP_BRIEF_FILENAME);
   let content;
@@ -975,6 +1000,69 @@ import { readFile as readFile3 } from "fs/promises";
 import { readFile as readFile2 } from "fs/promises";
 import { basename, dirname as dirname2, relative as relative3 } from "path";
 
+// src/core/issue-relationship.ts
+var ISSUE_RELATIONS = /* @__PURE__ */ new Set(["relates", "closes"]);
+var ISSUE_FIELDS = /* @__PURE__ */ new Set(["url", "relation"]);
+var IssueRelationshipError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "IssueRelationshipError";
+  }
+  code;
+};
+function parseIssueRelationships(frontmatter) {
+  if (!frontmatter || !("issues" in frontmatter))
+    return [];
+  if (!Array.isArray(frontmatter.issues))
+    throw new IssueRelationshipError("invalid_issue_shape", 'frontmatter field "issues" must be a list');
+  const seen = /* @__PURE__ */ new Set();
+  return frontmatter.issues.map((value, index) => {
+    if (!isPlainObject(value))
+      throw new IssueRelationshipError("invalid_issue_shape", `issues[${index}] must be a mapping with url and relation`);
+    const fields = Object.keys(value);
+    const unsupported = fields.filter((field) => !ISSUE_FIELDS.has(field));
+    if (unsupported.length > 0)
+      throw new IssueRelationshipError("unsupported_issue_field", `issues[${index}] contains unsupported field(s): ${unsupported.sort().join(", ")}`);
+    if (fields.length !== 2 || !("url" in value) || !("relation" in value))
+      throw new IssueRelationshipError("invalid_issue_shape", `issues[${index}] must contain exactly url and relation`);
+    if (typeof value.url !== "string")
+      throw new IssueRelationshipError("invalid_issue_url", `issues[${index}].url must be an absolute http or https URL`);
+    if (typeof value.relation !== "string" || !ISSUE_RELATIONS.has(value.relation))
+      throw new IssueRelationshipError("unsupported_issue_relation", `issues[${index}].relation must be relates or closes`);
+    const url = normalizeIssueUrl(value.url, `issues[${index}].url`);
+    if (seen.has(url))
+      throw new IssueRelationshipError("duplicate_issue_url", `issues contains duplicate normalized URL: ${url}`);
+    seen.add(url);
+    return { url, relation: value.relation };
+  });
+}
+function createIssueRelationship(url, relation = "relates") {
+  return parseIssueRelationships({ issues: [{ url, relation }] })[0];
+}
+function normalizeIssueUrl(raw, label) {
+  if (raw.trim() !== raw || raw === "")
+    throw new IssueRelationshipError("invalid_issue_url", `${label} must be an absolute http or https URL without surrounding whitespace`);
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new IssueRelationshipError("invalid_issue_url", `${label} must be an absolute http or https URL`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+    throw new IssueRelationshipError("invalid_issue_url", `${label} must use http or https`);
+  if (!parsed.hostname)
+    throw new IssueRelationshipError("invalid_issue_url", `${label} must include a host`);
+  if (parsed.username || parsed.password)
+    throw new IssueRelationshipError("unsafe_issue_url", `${label} must not contain credentials`);
+  if (parsed.hash)
+    throw new IssueRelationshipError("unsafe_issue_url", `${label} must not contain a fragment`);
+  return parsed.toString();
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // src/history/model.ts
 var HISTORY_DEFAULT_LIMIT = 20;
 var HISTORY_MAX_LIMIT = 100;
@@ -1011,6 +1099,7 @@ async function inspectArchiveHistory(options = {}) {
   }));
   const runtime = [];
   const records = [];
+  const groupBriefs = [];
   if (!tree.rootExists && tree.diagnostics.length === 0) {
     diagnostics.push({
       severity: "error",
@@ -1034,14 +1123,18 @@ async function inspectArchiveHistory(options = {}) {
       diagnostics.push(parsed.diagnostic);
     if (parsed.record)
       records.push(parsed.record);
+    if (parsed.groupBrief)
+      groupBriefs.push(parsed.groupBrief);
   }
   records.sort(compareHistoryRecords);
+  groupBriefs.sort(compareArchivedGroupBriefs);
   diagnostics.sort(compareDiagnostics);
   const diagnosticTotal = diagnostics.length;
   const boundedDiagnostics = diagnostics.slice(0, HISTORY_MAX_DIAGNOSTICS);
   return {
     rootExists: tree.rootExists,
     records,
+    groupBriefs,
     diagnostics: boundedDiagnostics,
     diagnosticSummary: {
       total: diagnosticTotal,
@@ -1082,7 +1175,15 @@ function parseArchiveEntry(sourcePath, path, archivesDir, content) {
     if (!archiveGroup || group !== archiveGroup || frontmatter.kind !== "group" || !matchesArchiveStem(archiveStem, "brief")) {
       return { diagnostic: errorDiagnostic("archive_identity_mismatch", path, `archived Change Group identity ${group} does not match its archive path`) };
     }
-    return {};
+    return { groupBrief: { date, group, path, sourcePath } };
+  }
+  let issues;
+  if ("issues" in frontmatter) {
+    try {
+      issues = parseIssueRelationships(frontmatter);
+    } catch {
+      issues = void 0;
+    }
   }
   const workRef = changeHeadings[0];
   const segments = workRef.split("/");
@@ -1107,6 +1208,7 @@ function parseArchiveEntry(sourcePath, path, archivesDir, content) {
       summary: summary.value,
       summaryTruncated: summary.truncated,
       path,
+      ...issues === void 0 ? {} : { issues },
       sourcePath,
       searchSummary: rawSummary
     }
@@ -1151,6 +1253,9 @@ function escapeRegExp(value) {
 function compareHistoryRecords(left, right) {
   return right.date.localeCompare(left.date) || left.workRef.localeCompare(right.workRef) || left.path.localeCompare(right.path);
 }
+function compareArchivedGroupBriefs(left, right) {
+  return right.date.localeCompare(left.date) || left.group.localeCompare(right.group) || left.path.localeCompare(right.path);
+}
 function compareDiagnostics(left, right) {
   return (left.path ?? "").localeCompare(right.path ?? "") || left.code.localeCompare(right.code) || left.message.localeCompare(right.message);
 }
@@ -1205,6 +1310,17 @@ function selectArchiveHistoryRecord(records, selector) {
   }
   return matches[0];
 }
+function selectArchivedGroupBrief(records, selector) {
+  const matches = "path" in selector ? records.filter((record) => record.path === selector.path) : records.filter((record) => record.group === selector.group);
+  const identity = "path" in selector ? selector.path : selector.group;
+  if (matches.length === 0)
+    throw new ArchiveHistoryError("archive_not_found", `archived Change Group not found: ${identity}`);
+  if (matches.length > 1) {
+    const candidates = matches.map((record) => record.path).sort();
+    throw new ArchiveHistoryError("archive_ambiguous", `multiple archives match Change Group ${identity}`, candidates);
+  }
+  return matches[0];
+}
 async function readArchiveHistoryDetail(record) {
   let content;
   try {
@@ -1600,6 +1716,7 @@ async function inspectProjectStatus(options = {}) {
     let done = 0;
     let total = 0;
     let progressKnown = false;
+    let issues = [];
     if (path) {
       try {
         const content = await readFile5(path, "utf-8");
@@ -1608,10 +1725,21 @@ async function inspectProjectStatus(options = {}) {
         try {
           const frontmatter = parseFrontmatter(content);
           kind = frontmatter?.kind ? String(frontmatter.kind) : "\u2014";
+          issues = parseIssueRelationships(frontmatter);
         } catch (error) {
           kind = "(invalid)";
+          const issueError = error instanceof IssueRelationshipError;
+          if (issueError) {
+            diagnostics.push({
+              severity: "error",
+              code: error.code,
+              change: name,
+              path,
+              message: error.message
+            });
+          }
           runtime.push({
-            code: "frontmatter_parse_failed",
+            code: issueError ? error.code : "frontmatter_parse_failed",
             operation: "parseFrontmatter",
             path,
             message: toErrorMessage(error)
@@ -1692,7 +1820,8 @@ async function inspectProjectStatus(options = {}) {
         ageDays,
         isFocused,
         isBlocked,
-        path: path ? normalizeLogicalPath(path) : null
+        path: path ? normalizeLogicalPath(path) : null,
+        issues
       },
       progressKnown,
       title,
@@ -1785,16 +1914,22 @@ export {
   inspectFocusTree,
   inspectArchiveTree,
   inspectWorkTree,
+  GROUP_REOPEN_COMPLETION_PREFIX,
   resolveExecutableChange,
   generateGroupBriefContent,
   inspectChangeGroups,
+  getGroupReopenEvidence,
   hasArchivedGroupBrief,
+  IssueRelationshipError,
+  parseIssueRelationships,
+  createIssueRelationship,
   HISTORY_DEFAULT_LIMIT,
   HISTORY_MAX_LIMIT,
   ArchiveHistoryError,
   inspectArchiveHistory,
   queryArchiveHistory,
   selectArchiveHistoryRecord,
+  selectArchivedGroupBrief,
   readArchiveHistoryDetail,
   historyInspectionComplete,
   inspectChangeDependencies,