@xenonbyte/xsk 0.1.0 → 0.1.2

package/lib/status.js

@@ -5,7 +5,8 @@ const path = require('node:path');
 const os = require('node:os');
 
 const { read, validate, defaultXskRoot, isSafePath, isInsideDir, validateOperationalSemantics } = require('./manifest');
-const { ALL_PLATFORMS, MARKER, rootFor } = require('./install');
+const { ALL_PLATFORMS, MARKER, rootFor, commandsRootFor } = require('./install');
+const { contentSha256 } = require('./content-hash');
 
 const STATES = ['not-installed', 'ok', 'drift', 'invalid'];
 
@@ -14,12 +15,30 @@ function expectedInstalledPathType(p) {
   if (base === 'SKILL.md' || base === MARKER) {
     return 'file';
   }
+  // A flat command file (commandsRoot/<name>.md) is an expected regular file, so
+  // a missing or no-longer-a-file command path reports drift.
+  if (base.endsWith('.md')) {
+    return 'file';
+  }
   return 'directory';
 }
 
 function recordedPathEntries(manifest) {
+  const installedHashes = new Map(
+    Array.isArray(manifest.installed_hashes)
+      ? manifest.installed_hashes.map((h) => [h.target, h.sha256])
+      : [],
+  );
   const installed = Array.isArray(manifest.installed_paths)
-    ? manifest.installed_paths.map((p) => ({ path: p, expectedType: expectedInstalledPathType(p) }))
+    ? manifest.installed_paths.map((p) => {
+      const expectedType = expectedInstalledPathType(p);
+      const entry = { path: p, expectedType };
+      const expectedSha256 = installedHashes.get(p);
+      if (expectedType === 'file' && expectedSha256) {
+        entry.expectedSha256 = expectedSha256;
+      }
+      return entry;
+    })
     : [];
   const backups = Array.isArray(manifest.backups)
     ? manifest.backups.map((b) => ({ path: b.backup, target: b.target, expectedType: 'file', kind: 'backup' }))
@@ -43,6 +62,14 @@ function pathType(p) {
   }
 }
 
+function matchesExpectedSha256(entry) {
+  try {
+    return contentSha256(fs.readFileSync(entry.path)) === entry.expectedSha256;
+  } catch (e) {
+    return false;
+  }
+}
+
 function recordedPathHasDrift(entry, options) {
   const opts = options || {};
   const exists = opts.exists || ((p) => fs.existsSync(p));
@@ -51,6 +78,7 @@ function recordedPathHasDrift(entry, options) {
   if (!safe(entry.path, entry)) return true;
   if (!exists(entry.path, entry)) return true;
   if (typeOf && typeOf(entry.path, entry) !== entry.expectedType) return true;
+  if (entry.expectedSha256 && !matchesExpectedSha256(entry)) return true;
   return false;
 }
 
@@ -104,7 +132,8 @@ function computeStatus(options) {
     let skillsRoot = null;
     if (validate(manifest, { expectedPlatform: platform })) {
       skillsRoot = rootFor(platform, opts.platformRoots);
-      const semantics = validateOperationalSemantics({ platform, skillsRoot, manifest });
+      const commandsRoot = commandsRootFor(platform, opts.platformCommandsRoots);
+      const semantics = validateOperationalSemantics({ platform, skillsRoot, commandsRoot, manifest });
       if (!semantics.valid) {
         result.platforms[platform] = { state: 'invalid', reason: semantics.reason };
         continue;
@@ -158,7 +187,7 @@ function render(result, options) {
       line += ` v${entry.version}`;
     }
     if (entry.missing && entry.missing.length) {
-      line += `; ${entry.missing.length} recorded path(s) missing`;
+      line += `; ${entry.missing.length} recorded path(s) drifted`;
     }
     if (entry.reason) {
       line += ` - ${entry.reason}`;

package/lib/uninstall.js

@@ -13,7 +13,9 @@ const {
   removeManifest,
   manifestPath,
   atomicWriteFile,
+  assertSafePath,
   isInsideDir,
+  isSafePath,
 } = require('./manifest');
 const { get } = require('./skills');
 const { buildSkill } = require('./generator');
@@ -124,10 +126,25 @@ function capturePathState(targetPath) {
   }
 }
 
+// Rollback restore re-runs the same path-safety walk install/uninstall use
+// everywhere else. The capture-to-restore window is fully synchronous, but a
+// guarded delete/create here keeps the documented "no symlink traversal or
+// removal" invariant true even if an ancestor were swapped under us: it fails
+// closed (rollback reports an error) rather than following a symlink out of the
+// owned roots. allowNonDirectoryTarget lets the target itself be a regular file
+// (the common case); a symlinked target or any symlinked ancestor still throws.
 function removePathForRestore(targetPath) {
+  assertSafePath(targetPath, 'rollback restore target', { allowNonDirectoryTarget: true });
   fs.rmSync(targetPath, { recursive: true, force: true });
 }
 
+function ensureRestoreParent(targetPath) {
+  const dir = path.dirname(targetPath);
+  assertSafePath(dir, 'rollback restore dir');
+  fs.mkdirSync(dir, { recursive: true });
+  assertSafePath(dir, 'rollback restore dir');
+}
+
 function restorePathState(targetPath, state) {
   if (!state.exists) {
     removePathForRestore(targetPath);
@@ -137,6 +154,7 @@ function restorePathState(targetPath, state) {
     if (fs.existsSync(targetPath) && !fs.lstatSync(targetPath).isDirectory()) {
       removePathForRestore(targetPath);
     }
+    assertSafePath(targetPath, 'rollback restore dir');
     fs.mkdirSync(targetPath, { recursive: true, mode: state.mode });
     try {
       fs.chmodSync(targetPath, state.mode);
@@ -146,12 +164,17 @@ function restorePathState(targetPath, state) {
     return;
   }
   removePathForRestore(targetPath);
-  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  ensureRestoreParent(targetPath);
   if (state.type === 'symlink') {
+    assertSafePath(targetPath, 'rollback restore symlink', { allowNonDirectoryTarget: true });
     fs.symlinkSync(state.link, targetPath);
     return;
   }
   if (state.type === 'file') {
+    // writeFileSync follows a symlink at targetPath; re-assert it is not one
+    // (removePathForRestore cleared it, so this is normally an ENOENT no-op)
+    // before writing, then preserve the captured mode via writeFileSync+chmod.
+    assertSafePath(targetPath, 'rollback restore file', { allowNonDirectoryTarget: true });
     fs.writeFileSync(targetPath, state.content, { mode: state.mode });
     try {
       fs.chmodSync(targetPath, state.mode);
@@ -178,7 +201,9 @@ function createRollbackJournal() {
   };
 }
 
-function uninstallPlatform({ platform, xskRoot, skillsRoot }) {
+function uninstallPlatform({ platform, xskRoot, skillsRoot, commandsRoot }) {
+  // Lazy require avoids a load-time cycle (install.js requires uninstall.js).
+  const { isCommandFilePath } = require('./install');
   let manifest;
   try {
     manifest = read(platform, { xskRoot });
@@ -226,7 +251,7 @@ function uninstallPlatform({ platform, xskRoot, skillsRoot }) {
     };
   }
 
-  const sem = validateOperationalSemantics({ platform, skillsRoot, manifest });
+  const sem = validateOperationalSemantics({ platform, skillsRoot, commandsRoot, manifest });
   if (!sem.valid) {
     return {
       platform,
@@ -243,7 +268,12 @@ function uninstallPlatform({ platform, xskRoot, skillsRoot }) {
   }
 
   const backups = manifest.backups || [];
-  const skillDirs = classifyPaths(manifest.installed_paths);
+  // Command files are flat, markerless `.md` files outside skillsRoot. Filter
+  // them out before classifyPaths / ownedDirs / validateBackupTargets so a flat
+  // command path is never synthesized into a <cmd>.md/SKILL.md skill triple.
+  const commandPaths = manifest.installed_paths.filter((p) => isCommandFilePath(p));
+  const skillInstalledPaths = manifest.installed_paths.filter((p) => !isCommandFilePath(p));
+  const skillDirs = classifyPaths(skillInstalledPaths);
   const backupTargets = validateBackupTargets(backups, skillDirs, skillsRoot);
   if (!backupTargets.valid) {
     return {
@@ -274,8 +304,9 @@ function uninstallPlatform({ platform, xskRoot, skillsRoot }) {
   let error = null;
   const manifestPaths = new Set(manifest.installed_paths);
 
+  const retainedCommands = [];
   const ownedDirs = new Set(
-    manifest.installed_paths.filter((p) => {
+    skillInstalledPaths.filter((p) => {
       const base = path.basename(p);
       return base !== 'SKILL.md' && base !== MARKER;
     }),
@@ -493,13 +524,57 @@ function uninstallPlatform({ platform, xskRoot, skillsRoot }) {
     }
   }
 
-  const retainedPaths = [...retainedDirs, ...retainedFiles, ...retainedMarkers];
+  // Dedicated command-file pass: remove a hash-matched (owned) command file,
+  // retain a hash-mismatched (user-edited) one, and prune command files for
+  // skills no longer installed. Command files carry no marker and no backup, so
+  // ownership rests solely on the recorded installed_hashes content match.
+  for (const commandPath of commandPaths) {
+    if (!isSafePath(commandPath, 'command file', { allowNonDirectoryTarget: true })) {
+      refused.push(commandPath);
+      retainedCommands.push(commandPath);
+      partial = true;
+      continue;
+    }
+    let stat = null;
+    try {
+      stat = fs.lstatSync(commandPath);
+    } catch (e) {
+      if (e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')) {
+        stat = null;
+      } else {
+        throw e;
+      }
+    }
+    if (stat === null) {
+      // Already gone: drop it from the manifest (nothing to remove or retain).
+      continue;
+    }
+    if (!stat.isFile()) {
+      refused.push(commandPath);
+      retainedCommands.push(commandPath);
+      partial = true;
+      continue;
+    }
+    const recordedHash = installedHashes.get(commandPath);
+    const onDisk = fs.readFileSync(commandPath);
+    const owned = Boolean(recordedHash) && contentSha256(onDisk) === recordedHash;
+    if (!owned) {
+      retainedCommands.push(commandPath);
+      partial = true;
+      continue;
+    }
+    rollbackJournal.capture(commandPath);
+    fs.rmSync(commandPath, { force: true });
+    removed.push(commandPath);
+  }
+
+  const retainedPaths = [...retainedDirs, ...retainedFiles, ...retainedMarkers, ...retainedCommands];
   let narrowed = null;
   if (retainedPaths.length > 0 || retainedBackups.length > 0) {
     narrowed = create(platform, manifest.version);
     narrowed.installed_paths = retainedPaths;
     narrowed.backups = retainedBackups;
-    narrowed.installed_hashes = retainedInstalledHashes(manifest, retainedFiles);
+    narrowed.installed_hashes = retainedInstalledHashes(manifest, [...retainedFiles, ...retainedCommands]);
     try {
       rollbackJournal.capture(manifestPath(platform, { xskRoot }));
       write(platform, narrowed, { xskRoot });
@@ -532,7 +607,7 @@ function uninstallPlatform({ platform, xskRoot, skillsRoot }) {
     platform,
     removed,
     restored,
-    retained: retainedFiles,
+    retained: [...retainedFiles, ...retainedCommands],
     skipped,
     refused,
     partial,
@@ -549,13 +624,14 @@ function uninstall(options) {
   const opts = options || {};
   const platforms = opts.platforms || ['claude', 'codex', 'opencode', 'gemini'];
   const xskRoot = opts.xskRoot || defaultXskRoot();
-  const { rootFor } = require('./install');
+  const { rootFor, commandsRootFor } = require('./install');
 
   const summary = { platforms: {} };
   let exitCode = 0;
   for (const platform of platforms) {
     const skillsRoot = rootFor(platform, opts.platformRoots);
-    const res = uninstallPlatform({ platform, xskRoot, skillsRoot });
+    const commandsRoot = commandsRootFor(platform, opts.platformCommandsRoots);
+    const res = uninstallPlatform({ platform, xskRoot, skillsRoot, commandsRoot });
     summary.platforms[platform] = res;
     if (res.exitCode > exitCode) {
       exitCode = res.exitCode;
@@ -570,6 +646,8 @@ module.exports = {
   uninstallPlatform,
   classifyPaths,
   generatedContentFor,
+  removePathForRestore,
+  restorePathState,
   isSymlink,
   safeBackupForSkill,
   PARTIAL_EXIT,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenonbyte/xsk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Agent skill aggregator. Install a curated set of agent skills across Claude Code, Codex, opencode, and Gemini with manifest-backed safety.",
   "license": "MIT",
   "bin": {

package/skills/archive-req/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: xsk-archive-req
-description: Archive the active requirement document into requirements/archive/ and leave zero active docs.
+description: Archive the active requirement document into .xsk/requirements/archive/ and leave zero active docs.
 ---
 
 # xsk-archive-req
 
-Archive the active requirement document into `requirements/archive/`. After it runs, zero active requirement docs remain.
+Archive the active requirement document into `.xsk/requirements/archive/`. After it runs, zero active requirement docs remain.
 
 ## When to use
 
@@ -17,17 +17,22 @@ Match the intent, not the exact words. Common cues:
 
 ## How it works
 
-1. Scan `requirements/*.md` (excluding `requirements/archive/`) for the single document whose frontmatter has `status: active`. If more than one exists, stop, list the offending paths, and report the broken invariant for the user to resolve.
+1. Scan `.xsk/requirements/*.md` (excluding `.xsk/requirements/archive/`) for the single document whose frontmatter has `status: active`. If more than one exists, stop, list the offending paths, and report the broken invariant for the user to resolve.
 2. If there is no active document, refuse with a one-line reason and stop. Do not archive anything.
 3. Read the active doc slug and validate it against `^[a-z0-9]+(-[a-z0-9]+)*$`. If the slug is missing/invalid, stop with the reason before any write.
-4. Check the archive target `requirements/archive/<slug>.md`. If it already exists, stop, ask the user how to proceed, and leave it unchanged, writing nothing.
-5. Write the fully-updated archived content to `requirements/archive/<slug>.md`: set `status: archived`, add `archived_at: <ISO date>`, and preserve every other frontmatter field and the entire body unchanged.
+4. Check the archive target `.xsk/requirements/archive/<slug>.md`. If it already exists, stop, ask the user how to proceed, and leave it unchanged, writing nothing.
+5. Write the fully-updated archived content to `.xsk/requirements/archive/<slug>.md`: set `status: archived`, add `archived_at: <ISO date>`, and preserve every other frontmatter field and the entire body unchanged.
 6. Confirm it landed as written, then remove the source active doc.
 7. After archiving, confirm zero active documents remain.
+8. Offer to commit the archival, git-aware. The archive copy lives under the git-ignored `requirements/archive/`, so from git's view the only change is the deletion of the source active doc. If the project is a git repository and that active doc was tracked (`git ls-files --error-unmatch <path>` succeeds), ask the user once whether to commit this archival, and act on the answer:
+   - On yes, commit only that deleted path. Stage the deletion first, then commit only that path: `git add -- <the removed active doc path> && git commit -m "docs(xsk): archive requirement <slug>" -- <the removed active doc path>`. Never `git add -A` or `git add .`.
+   - On no, leave the working tree as is and report that the deletion was left for the user to commit.
+
+   If the doc was untracked, or the project is not a git repository, skip the prompt and say nothing about committing.
 
 ## Output
 
-Either a one-line refusal that names the missing/invalid slug, a stop-and-ask response when `requirements/archive/<slug>.md` already exists and it was left unchanged, writing nothing, or the archived path (`requirements/archive/<slug>.md`) plus confirmation that it landed before the source active doc was removed and that no active requirement docs remain.
+Either a one-line refusal that names the missing/invalid slug, a stop-and-ask response when `.xsk/requirements/archive/<slug>.md` already exists and it was left unchanged, writing nothing, or the archived path (`.xsk/requirements/archive/<slug>.md`) plus confirmation that it landed before the source active doc was removed and that no active requirement docs remain, and, when the removed doc was tracked by git, whether the user committed the archival or left it uncommitted.
 
 ## Conventions shared across xsk skills
 

package/skills/check/SKILL.md

@@ -45,7 +45,7 @@ Match the intent, not the exact words. Common cues:
 
 **6. Gate every finding on evidence.** A HIGH or CRITICAL finding needs three things: the exact file and line, the concrete trigger that produces the bad outcome, and why existing guards do not already prevent it. Missing any one, downgrade it or drop it. Do not pad the report with low-confidence noise that trains the reader to ignore the real findings.
 
-**7. Route the fixes.** Apply safe, risk-free fixes (typos, missing imports, obvious style) right away. Batch behavior-changing fixes (added null checks, new error handling) into one confirmation block instead of asking one at a time. Leave architecture and security tradeoffs for the user to decide, and mark informational notes as advisory.
+**7. Route the fixes. Review-only by default.** Do not modify files during a review. List the safe, risk-free mechanical fixes (typos, missing imports, obvious style) separately from the findings, and apply them only when the user explicitly asks for fixes. Batch behavior-changing fixes (added null checks, new error handling) into one confirmation block instead of asking one at a time. Leave architecture and security tradeoffs for the user to decide, and mark informational notes as advisory.
 
 **8. Verify before claiming done.** Run the project's own verification (its tests, lint, type check, build, or syntax check) and read the output. For a bug fix, a regression test that fails on the old code must exist before the fix counts as done. If no verification command is available, say so plainly and call it a gap. Never present unverified work as passing.
 

package/skills/consume-point/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: xsk-consume-point
+description: Fold selected .xsk/points into one .xsk/requirements doc via xsk-write-req, archiving consumed points write-before-remove and leaving unconsumed points active.
+---
+
+# xsk-consume-point
+
+Fold one or more researched point documents from `.xsk/points/` into a single requirement document via `xsk-write-req`. Points that land in the requirement are archived as `consumed`; the rest stay active or are dropped only on user confirmation.
+
+## When to use
+
+Match the intent, not the exact words. Common cues:
+
+- "把这些 point 变成需求", "消费 point", "把调研结果写成需求"
+- "consume points", "turn points into a requirement", "fold points into a req"
+- any request to convert accumulated point documents into a structured requirement document
+
+## How it works
+
+**1. Scan and list available points.** Read all `.md` files under `.xsk/points/` excluding `.xsk/points/archive/`. For each, extract `slug`, `status`, and the `## Aspect` line. Display the list with status, highlighting `ready` entries as eligible. If no files exist, or all are already archived, stop with a one-line reason and do not proceed. If no unarchived point has `status: ready`, stop with a one-line reason, leave every point unchanged, and do not proceed.
+
+**2. Have the user select.** Ask the user which `ready` points to fold into the requirement. Only points with `status: ready` may be selected. If the user selects or names any `researching` or otherwise non-ready point, stop without writing or archiving anything and say it must be completed by `xsk-point` first. If the user selects none, stop without writing anything.
+
+**3. Guard the single-active requirement.** Scan `.xsk/requirements/*.md` (excluding `.xsk/requirements/archive/`) for frontmatter `status: active`. If one exists, prompt the user: append the selected points to the existing active requirement, or abort. If the user aborts, leave `.xsk/requirements/` and `.xsk/points/` entirely unchanged and stop. If more than one active requirement exists, stop, list the offending paths, and report the broken invariant for the user to resolve.
+
+**4. Hand off to xsk-write-req.** Pass the selected `ready` points to `xsk-write-req` as the input need. Before the handoff, re-read each selected point and confirm `status: ready`; if any selected point is no longer ready, stop, archive nothing, and leave all points unchanged. For each selected point, supply the `## Aspect` and `## Landed plan` as the core input, with `## Research` as supporting context. Do not duplicate or modify the `xsk-write-req` behavior; invoke it by reference. If `xsk-write-req` stops for any reason (blocking decision, user abort, audit failure), archive nothing and leave all points unchanged.
+
+**5. Archive folded points as consumed (write-before-remove).** After the requirement lands successfully, for each selected point that was folded in: set `status: consumed`, add `consumed_at: <ISO date>` and `consumed_by: .xsk/requirements/<slug>.md` to the frontmatter. Before writing, check the archive target `.xsk/points/archive/<slug>.md`: if it already exists, stop, ask the user how to proceed, and leave that point's source and archive unchanged rather than overwriting. Otherwise write the updated content to `.xsk/points/archive/<slug>.md`, confirm it landed, then remove `.xsk/points/<slug>.md`. Complete write-before-remove for every folded point before reporting done.
+
+**6. Leave excluded and deferred points active.** Points not selected, or points the user deferred, stay in `.xsk/points/` unchanged with their current status.
+
+**7. Drop consume-rejected points only on user confirmation.** If the user decides a point should be discarded rather than deferred, confirm before writing. On confirmation, set `status: dropped`, add `dropped_at: <ISO date>` and a one-line `dropped_reason`. Before writing, check the archive target `.xsk/points/archive/<slug>.md`: if it already exists, stop, ask the user how to proceed, and leave it unchanged, writing nothing. Otherwise write to `.xsk/points/archive/<slug>.md` (write-before-remove), then remove the source file.
+
+## Output
+
+The path of the produced requirement document (or the existing active doc if appended), plus a summary of which points were archived as `consumed` and which remain active or were dropped.
+
+## Conventions shared across xsk skills
+
+- Triggers are matched by intent, not by exact wording. The phrases listed under "When to use" are cues, not a required incantation.
+- Write in natural, direct prose. No formulaic openers, no filler conclusions, no restating the request before you answer it.
+- When a decision would change the implementation, surface it as a short question and let the user decide. Do not pick silently.
+- These are instruction skills. They shape how work is approached, not what the agent is technically capable of.

package/skills/point/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: xsk-point
+description: Research one aspect into .xsk/points/ to a decision-complete landed plan using xsk-think discipline, then persist and manage it as a named point document.
+---
+
+# xsk-point
+
+Research one aspect of the current project to a decision-complete landed plan and persist it as a point document in `.xsk/points/`. The result is a concrete, slug-named file an implementer can consume without re-doing the research.
+
+It is research-and-persist only. It writes no code, no scaffolding, and no requirement document.
+
+## When to use
+
+Match the intent, not the exact words. Common cues:
+
+- "研究一下", "调研一下", "先搞清楚", "这块需要研究"
+- "spike this", "research this", "figure out the approach for", "investigate"
+- any request to explore and nail down one aspect before writing a requirement or starting implementation
+- a slug argument that names an existing point (triggers a refinement of that point, not a new one)
+
+## How it works
+
+**1. Ground in the current project.** Read the relevant code, config, and docs before forming any opinion. Never rely on memory for project-specific facts. Identify the one aspect under investigation and state it as a single sentence.
+
+**2. Research with xsk-think's discipline.** Apply the same depth-matching, option-weighing, and premise-collapse discipline that `xsk-think` uses: match depth to the problem (lightweight, evaluation, or triage), declare premise collapse explicitly if one assumption invalidates everything, and reach a decision-complete landed plan. Do not stop at "it depends" - resolve the options and commit to one. If a blocking decision can only be resolved by the user, surface it as a single question before writing anything.
+
+**3. Re-invoke-by-slug to refine.** If the user supplies a slug and `.xsk/points/<slug>.md` already exists, load it, treat the existing `## Research` and `## Landed plan` as prior context, and refine in place rather than starting over. Update the file with the refined content; do not create a duplicate.
+
+**4. Persist the point document.** Write `.xsk/points/<slug>.md` where `<slug>` is generated from the aspect title using the pattern `^[a-z0-9]+(-[a-z0-9]+)*$`. Set `status: researching` while work is in progress; promote to `status: ready` only when the `## Landed plan` is decision-complete and the user confirms.
+
+Point document schema:
+
+```markdown
+---
+status: researching | ready
+slug: <slug>
+created_at: <ISO date>
+---
+
+# <title>
+
+## Aspect
+
+One-sentence statement of the aspect under investigation.
+
+## Research
+
+Evidence gathered, options considered, and tradeoffs weighed. Grounded in project reality.
+
+## Landed plan
+
+The concrete, decision-complete outcome. No "TBD". No open forks.
+```
+
+**5. Ensure the gitignore line.** Ensure `.xsk/.gitignore` contains the line `points/archive/` (relative to `.xsk/`). Create `.xsk/` and `.xsk/.gitignore` if absent; append the line only if it is missing; never overwrite an existing `.xsk/.gitignore`.
+
+**6. Drop only on user confirmation.** If the user asks to drop a point, confirm before writing. On confirmation, set `status: dropped`, add `dropped_at: <ISO date>` and a one-line `dropped_reason` to the frontmatter. Before writing, check the archive target `.xsk/points/archive/<slug>.md`: if it already exists, stop, ask the user how to proceed, and leave everything unchanged, writing nothing. Otherwise move the file to `.xsk/points/archive/<slug>.md` using write-before-remove (write the archive copy first, confirm it landed, then remove the source).
+
+## Output
+
+The path of the point document and its current `status`: active points (`researching`, `ready`) are at `.xsk/points/<slug>.md`; dropped points are at `.xsk/points/archive/<slug>.md`.
+
+## Conventions shared across xsk skills
+
+- Triggers are matched by intent, not by exact wording. The phrases listed under "When to use" are cues, not a required incantation.
+- Write in natural, direct prose. No formulaic openers, no filler conclusions, no restating the request before you answer it.
+- When a decision would change the implementation, surface it as a short question and let the user decide. Do not pick silently.
+- These are instruction skills. They shape how work is approached, not what the agent is technically capable of.

package/skills/skill-scaffold/SKILL.md

@@ -32,11 +32,14 @@ Match the intent, not the exact words. Common cues:
 - Unknown options fail loud.
 - `status` validates manifest **shape**, not just parse success.
 - Removed or renamed commands leave no stale references (grep-clean across CLI, help, README, generated text, `AGENTS.md`, `CLAUDE.md`).
-- Four platforms, all full: Claude Code, Codex, opencode, Gemini.
-- Manifest-backed install safety: owned-only removal, ownership markers, atomic writes, symlink refusal.
+- Four platforms covered: Claude Code, Codex, opencode, Gemini.
+- User-invocable on every platform, not merely present. Installing a skill must make it invocable on each target platform. Platforms that do not auto-expose skill files as slash commands need a verified platform-specific invocation artifact carrying the skill body and the platform's argument placeholder so invocation arguments are not dropped. This project currently implements that artifact for opencode as a command file; do not claim it for another platform until adapter, install, uninstall, status, docs, and tests all cover that platform. Claude exposes skill files directly. Verify per platform rather than assuming.
+- Manifest-backed install safety: owned-only removal, ownership markers, atomic writes, symlink refusal, and content-hash modification detection. The manifest records a hash per owned file; a previously generated install is recognized by that hash even without the marker (markerless detection), so a user-edited owned file is detected and refused or rolled back rather than silently overwritten.
 - `install` is uninstall-first: a reinstall resets the previously-owned files (pruning skills no longer installed) before regenerating, so no manual `uninstall` is needed. It still refuses to overwrite a user-edited owned file and rolls back instead of destroying it.
+- Built from source: skills are generated from a single per-skill source, not hand-maintained per platform or per file. The reference composes each skill from per-section fragments (`purpose`, `triggers`, `behavior`, `output`) plus a shared common body and a template, with one registry listing the skills. The build is deterministic, and the committed packed skill output stays byte-for-byte in sync with the generator, enforced by a test. The golden snapshot below is the masked form of that output.
 - A golden snapshot of the generated skill shell, masking embedded `shared/` body.
 - A bilingual README (`README.md` plus `README.zh-CN.md`) with identical headings, English literals preserved, and content-pinning tests.
+- Test coverage spans the install surface, not only generation and docs: install, uninstall, uninstall-first reset, transactional rollback, and the safety refusals (a user-edited owned file, symlinked paths) are exercised by executable tests, alongside the golden snapshot, README parity, and self-conformance tests.
 
 ### Self-conformance
 

package/skills/write-req/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: xsk-write-req
-description: Turn plain-language needs into a grounded requirement document in requirements/, with a self-audit gate before it is finalized.
+description: Turn plain-language needs into a grounded requirement document in .xsk/requirements/, with a self-audit gate before it is finalized.
 ---
 
 # xsk-write-req
 
-Convert plain-language ("白话") needs into a compliant requirement document in `requirements/`, grounded in the current project's actual code. The output is a doc an implementer can act on without guessing, not a transcript of the request.
+Convert plain-language ("白话") needs into a compliant requirement document in `.xsk/requirements/`, grounded in the current project's actual code. The output is a doc an implementer can act on without guessing, not a transcript of the request.
 
 ## When to use
 
@@ -19,16 +19,17 @@ Match the intent, not the exact words. Common cues:
 
 **1. Read the project first.** `grep` and `read` the current project structure, config files (`package.json` and the like), and relevant code to ground the requirement in reality. Never quote defaults from memory.
 
-**2. Locate or create the active requirement doc.** Scan `requirements/*.md` for frontmatter `status: active`. There is **at most one** active doc at a time. If more than one exists, stop, list the offending paths, and report the broken invariant for the user to resolve. If one exists, lock onto it and append or refine. If none exists, create `requirements/<slug>.md` with `status: active` and a slug generated from the need.
+**2. Locate or create the active requirement doc.** Scan `.xsk/requirements/*.md` for frontmatter `status: active`. There is **at most one** active doc at a time. If more than one exists, stop, list the offending paths, and report the broken invariant for the user to resolve. If one exists, lock onto it and append or refine. If none exists, create `.xsk/requirements/<slug>.md` with `status: active` and a slug generated from the need.
 
-**3. Ensure the directory convention.** Auto-create `requirements/.gitignore` containing `archive/` if it is absent (creating `requirements/` and `requirements/archive/` as needed). Never overwrite an existing `.gitignore`; append `archive/` only if the line is missing.
+**3. Ensure the directory convention.** Ensure `.xsk/.gitignore` contains the line `requirements/archive/` (create `.xsk/` and `.xsk/.gitignore` if absent; append only if the line is missing; never overwrite an existing `.xsk/.gitignore`).
 
 **4. Convert fuzzy into concrete.** Match the document structure to the input richness:
 
 - A minimal one-liner becomes a concise requirement: Goal, Scope, Acceptance. Do not force a Background section that would be filler.
 - Richer input becomes Background, Goal, Scope (in and out), Requirements, Open Questions, Checkpoints.
+- Open Questions holds only non-blocking items, and each one names its disposition: escalate it to the user to decide (step 5), or defer it to a named owner at a named checkpoint. A choice that would fork the implementation is never parked here. Resolve it inline, or raise it as a decision point.
 
-**5. Decision points go to the user.** When a genuine technical or scoping choice would change the implementation, stop and ask the user to decide. Surface the options and the tradeoffs; let them pick. Do not pick silently.
+**5. Decision points go to the user, resolved one at a time.** When a genuine technical or scoping choice would change the implementation, stop and ask the user to decide: surface the options and the tradeoffs, let them pick, do not pick silently. When several genuine decisions exist, take them in dependency order rather than all at once. Surface the most upstream open one first, fold the answer in, then re-derive what remains before surfacing the next. A resolved decision often removes or reshapes the forks beneath it, so never surface a fork whose options still depend on an open decision.
 
 **6. Brainstorm the genuinely open-ended.** Where the need is open-ended, run a short exploration with the user before writing.
 
@@ -38,8 +39,9 @@ Match the intent, not the exact words. Common cues:
 
 - **Conflict check:** verify no internal contradictions (Goal versus Scope, in-scope versus out-of-scope, Requirements versus Open Questions, any two statements that cannot both hold). Resolve every conflict, or surface it to the user. A finalized doc contains zero conflicts.
 - **Ambiguity check:** verify no undefined terms, unstated assumptions, or vague qualifiers ("fast", "supported", "as needed") that would force the implementer to guess. Tighten each to a concrete, testable statement. A finalized doc leaves no ambiguity that blocks implementation.
+- **Open-questions check:** verify every Open Question is non-blocking and names a disposition (escalated to the user, or deferred to a named owner at a named checkpoint). Resolve or raise anything that would block or fork implementation before finalizing. A finalized doc parks no blocking or unowned question.
 - **Checkpoint gates:** ensure the requirement defines the verification points where downstream implementation must pause and confirm against the requirement (acceptance criteria, integration gates, review gates). If it lacks them, add them before finalizing.
-- If the audit surfaces issues only the user can resolve, stop, list them, and ask. Do not write a contradictory or under-specified doc.
+The audit is a loop, not a single pass. If it surfaces issues only the user can resolve, take them one at a time in dependency order (as in step 5), then re-run the checks before finalizing. Repeat until one full pass finds zero conflicts, zero blocking ambiguity, and nothing left for the user to resolve. Do not write a contradictory or under-specified doc.
 
 The document frontmatter:
 
@@ -51,9 +53,14 @@ created_at: <ISO date>
 ---
 ```
 
+**9. Offer to commit, git-aware.** Only after the doc passes the self-audit and is finalized, decide whether to offer a commit. If the project is not a git repository (`git rev-parse --is-inside-work-tree` fails), or the requirement doc is byte-identical to what git already tracks, skip silently and say nothing about committing. Otherwise ask the user once whether to commit this requirement, and act on the answer:
+
+- On yes, commit only the paths this run wrote: the requirement doc, plus `.xsk/.gitignore` if this run created it. Stage those exact paths first, then commit only them: `git add -- <those paths> && git commit -m "docs(xsk): write requirement <slug>" -- <those paths>`. Stage first because a bare `git commit -- <path>` rejects an untracked new doc. Never `git add -A` or `git add .`, so unrelated working-tree changes are never swept in.
+- On no, leave the doc uncommitted and report that it was left for the user to commit.
+
 ## Output
 
-The path of the requirement file, with confirmation that it is now the single active doc.
+The path of the requirement file, with confirmation that it is now the single active doc, and, when a commit was offered, whether the user committed it or left it uncommitted.
 
 ## Conventions shared across xsk skills
 

package/templates/fragments/archive-req.behavior.md

@@ -1,7 +1,12 @@
-1. Scan `requirements/*.md` (excluding `requirements/archive/`) for the single document whose frontmatter has `status: active`. If more than one exists, stop, list the offending paths, and report the broken invariant for the user to resolve.
+1. Scan `.xsk/requirements/*.md` (excluding `.xsk/requirements/archive/`) for the single document whose frontmatter has `status: active`. If more than one exists, stop, list the offending paths, and report the broken invariant for the user to resolve.
 2. If there is no active document, refuse with a one-line reason and stop. Do not archive anything.
 3. Read the active doc slug and validate it against `^[a-z0-9]+(-[a-z0-9]+)*$`. If the slug is missing/invalid, stop with the reason before any write.
-4. Check the archive target `requirements/archive/<slug>.md`. If it already exists, stop, ask the user how to proceed, and leave it unchanged, writing nothing.
-5. Write the fully-updated archived content to `requirements/archive/<slug>.md`: set `status: archived`, add `archived_at: <ISO date>`, and preserve every other frontmatter field and the entire body unchanged.
+4. Check the archive target `.xsk/requirements/archive/<slug>.md`. If it already exists, stop, ask the user how to proceed, and leave it unchanged, writing nothing.
+5. Write the fully-updated archived content to `.xsk/requirements/archive/<slug>.md`: set `status: archived`, add `archived_at: <ISO date>`, and preserve every other frontmatter field and the entire body unchanged.
 6. Confirm it landed as written, then remove the source active doc.
 7. After archiving, confirm zero active documents remain.
+8. Offer to commit the archival, git-aware. The archive copy lives under the git-ignored `requirements/archive/`, so from git's view the only change is the deletion of the source active doc. If the project is a git repository and that active doc was tracked (`git ls-files --error-unmatch <path>` succeeds), ask the user once whether to commit this archival, and act on the answer:
+   - On yes, commit only that deleted path. Stage the deletion first, then commit only that path: `git add -- <the removed active doc path> && git commit -m "docs(xsk): archive requirement <slug>" -- <the removed active doc path>`. Never `git add -A` or `git add .`.
+   - On no, leave the working tree as is and report that the deletion was left for the user to commit.
+
+   If the doc was untracked, or the project is not a git repository, skip the prompt and say nothing about committing.

package/templates/fragments/archive-req.output.md

@@ -1 +1 @@
-Either a one-line refusal that names the missing/invalid slug, a stop-and-ask response when `requirements/archive/<slug>.md` already exists and it was left unchanged, writing nothing, or the archived path (`requirements/archive/<slug>.md`) plus confirmation that it landed before the source active doc was removed and that no active requirement docs remain.
+Either a one-line refusal that names the missing/invalid slug, a stop-and-ask response when `.xsk/requirements/archive/<slug>.md` already exists and it was left unchanged, writing nothing, or the archived path (`.xsk/requirements/archive/<slug>.md`) plus confirmation that it landed before the source active doc was removed and that no active requirement docs remain, and, when the removed doc was tracked by git, whether the user committed the archival or left it uncommitted.

package/templates/fragments/archive-req.purpose.md

@@ -1 +1 @@
-Archive the active requirement document into `requirements/archive/`. After it runs, zero active requirement docs remain.
+Archive the active requirement document into `.xsk/requirements/archive/`. After it runs, zero active requirement docs remain.

package/templates/fragments/check.behavior.md

@@ -24,6 +24,6 @@
 
 **6. Gate every finding on evidence.** A HIGH or CRITICAL finding needs three things: the exact file and line, the concrete trigger that produces the bad outcome, and why existing guards do not already prevent it. Missing any one, downgrade it or drop it. Do not pad the report with low-confidence noise that trains the reader to ignore the real findings.
 
-**7. Route the fixes.** Apply safe, risk-free fixes (typos, missing imports, obvious style) right away. Batch behavior-changing fixes (added null checks, new error handling) into one confirmation block instead of asking one at a time. Leave architecture and security tradeoffs for the user to decide, and mark informational notes as advisory.
+**7. Route the fixes. Review-only by default.** Do not modify files during a review. List the safe, risk-free mechanical fixes (typos, missing imports, obvious style) separately from the findings, and apply them only when the user explicitly asks for fixes. Batch behavior-changing fixes (added null checks, new error handling) into one confirmation block instead of asking one at a time. Leave architecture and security tradeoffs for the user to decide, and mark informational notes as advisory.
 
 **8. Verify before claiming done.** Run the project's own verification (its tests, lint, type check, build, or syntax check) and read the output. For a bug fix, a regression test that fails on the old code must exist before the fix counts as done. If no verification command is available, say so plainly and call it a gap. Never present unverified work as passing.

package/templates/fragments/consume-point.behavior.md

@@ -0,0 +1,13 @@
+**1. Scan and list available points.** Read all `.md` files under `.xsk/points/` excluding `.xsk/points/archive/`. For each, extract `slug`, `status`, and the `## Aspect` line. Display the list with status, highlighting `ready` entries as eligible. If no files exist, or all are already archived, stop with a one-line reason and do not proceed. If no unarchived point has `status: ready`, stop with a one-line reason, leave every point unchanged, and do not proceed.
+
+**2. Have the user select.** Ask the user which `ready` points to fold into the requirement. Only points with `status: ready` may be selected. If the user selects or names any `researching` or otherwise non-ready point, stop without writing or archiving anything and say it must be completed by `xsk-point` first. If the user selects none, stop without writing anything.
+
+**3. Guard the single-active requirement.** Scan `.xsk/requirements/*.md` (excluding `.xsk/requirements/archive/`) for frontmatter `status: active`. If one exists, prompt the user: append the selected points to the existing active requirement, or abort. If the user aborts, leave `.xsk/requirements/` and `.xsk/points/` entirely unchanged and stop. If more than one active requirement exists, stop, list the offending paths, and report the broken invariant for the user to resolve.
+
+**4. Hand off to xsk-write-req.** Pass the selected `ready` points to `xsk-write-req` as the input need. Before the handoff, re-read each selected point and confirm `status: ready`; if any selected point is no longer ready, stop, archive nothing, and leave all points unchanged. For each selected point, supply the `## Aspect` and `## Landed plan` as the core input, with `## Research` as supporting context. Do not duplicate or modify the `xsk-write-req` behavior; invoke it by reference. If `xsk-write-req` stops for any reason (blocking decision, user abort, audit failure), archive nothing and leave all points unchanged.
+
+**5. Archive folded points as consumed (write-before-remove).** After the requirement lands successfully, for each selected point that was folded in: set `status: consumed`, add `consumed_at: <ISO date>` and `consumed_by: .xsk/requirements/<slug>.md` to the frontmatter. Before writing, check the archive target `.xsk/points/archive/<slug>.md`: if it already exists, stop, ask the user how to proceed, and leave that point's source and archive unchanged rather than overwriting. Otherwise write the updated content to `.xsk/points/archive/<slug>.md`, confirm it landed, then remove `.xsk/points/<slug>.md`. Complete write-before-remove for every folded point before reporting done.
+
+**6. Leave excluded and deferred points active.** Points not selected, or points the user deferred, stay in `.xsk/points/` unchanged with their current status.
+
+**7. Drop consume-rejected points only on user confirmation.** If the user decides a point should be discarded rather than deferred, confirm before writing. On confirmation, set `status: dropped`, add `dropped_at: <ISO date>` and a one-line `dropped_reason`. Before writing, check the archive target `.xsk/points/archive/<slug>.md`: if it already exists, stop, ask the user how to proceed, and leave it unchanged, writing nothing. Otherwise write to `.xsk/points/archive/<slug>.md` (write-before-remove), then remove the source file.

package/templates/fragments/consume-point.output.md

@@ -0,0 +1 @@
+The path of the produced requirement document (or the existing active doc if appended), plus a summary of which points were archived as `consumed` and which remain active or were dropped.

package/templates/fragments/consume-point.purpose.md

@@ -0,0 +1 @@
+Fold one or more researched point documents from `.xsk/points/` into a single requirement document via `xsk-write-req`. Points that land in the requirement are archived as `consumed`; the rest stay active or are dropped only on user confirmation.

package/templates/fragments/consume-point.triggers.md

@@ -0,0 +1,5 @@
+Match the intent, not the exact words. Common cues:
+
+- "把这些 point 变成需求", "消费 point", "把调研结果写成需求"
+- "consume points", "turn points into a requirement", "fold points into a req"
+- any request to convert accumulated point documents into a structured requirement document