@yunhozz/arc 0.2.2 → 0.2.3

package/lib/installer/superpowers.mjs

@@ -2,7 +2,7 @@ import path from 'node:path';
 import {createHash} from 'node:crypto';
 import {readCheckedFile,sameIdentity,typeOf,metadataOf} from './targets.mjs';
 export const REQUIRED=Object.freeze({
- 'brainstorming':['SKILL.md','visual-companion.md','scripts/start-server.sh','scripts/stop-server.sh','scripts/server.cjs','scripts/helper.js','scripts/frame-template.html'],
+ 'brainstorming':['SKILL.md','visual-companion.md','builder-check-prompt.md','scripts/start-server.sh','scripts/stop-server.sh','scripts/server.cjs','scripts/helper.js','scripts/frame-template.html'],
  'writing-plans':['SKILL.md'],
  'test-driven-development':['SKILL.md','writing-good-tests.md'],
 });
@@ -10,6 +10,12 @@ export const SKILLS=Object.freeze(Object.keys(REQUIRED));
 export const REPOSITORY='https://github.com/obra/superpowers';
 export const DYNAMIC_ROOTS=Object.freeze(['codex','claude'].map(platform=>`${platform}/skill/references/superpowers`));
 export const isDynamicReferencePath=name=>DYNAMIC_ROOTS.some(root=>name===root||name.startsWith(root+'/'));
+export const REFERENCE_PATH_MAP=Object.freeze([
+ ['brainstorming/SKILL.md','brainstorming.md'],['writing-plans/SKILL.md','writing-plans.md'],['test-driven-development/SKILL.md','test-driven-development.md'],
+ ['brainstorming/visual-companion.md','visual-companion.md'],['brainstorming/builder-check-prompt.md','builder-check-prompt.md'],['test-driven-development/writing-good-tests.md','writing-good-tests.md'],
+ ['brainstorming/scripts/start-server.sh','scripts/start-server.sh'],['brainstorming/scripts/stop-server.sh','scripts/stop-server.sh'],['brainstorming/scripts/server.cjs','scripts/server.cjs'],['brainstorming/scripts/helper.js','scripts/helper.js'],['brainstorming/scripts/frame-template.html','scripts/frame-template.html'],
+ ['LICENSE','superpowers-LICENSE'],['provenance.json','superpowers-provenance.json'],
+].map(([source,destination])=>Object.freeze({source,destination})));
 const hash=bytes=>createHash('sha256').update(bytes).digest('hex');
 function failure(message){throw new Error(message);}
 export function snapshotSkill(root,absolute,required){
@@ -111,3 +117,22 @@ export function composeArcSkillTree(skillFiles,references){
  entries.set('references',{type:'directory',mode:0o700n});entries.set('references/superpowers',{type:'directory',mode:0o700n});
  for(const[name,entry]of references.entries)entries.set('references/superpowers/'+name,{...entry});return entries;
 }
+export function flattenReferenceBundle(bundle){
+ validateReferenceBundle(bundle);const allowedFiles=new Set(REFERENCE_PATH_MAP.map(item=>item.source)),allowedDirectories=new Set();
+ for(const name of allowedFiles){const parts=name.split('/');for(let i=1;i<parts.length;i++)allowedDirectories.add(parts.slice(0,i).join('/'));}
+ for(const[name,entry]of bundle.entries){if(entry.type==='symlink')failure('Unsupported reference link in flat payload');if(entry.type==='file'&&!allowedFiles.has(name)||entry.type==='directory'&&!allowedDirectories.has(name))failure('Unsupported reference file in flat payload');}
+ return new Map(REFERENCE_PATH_MAP.map(({source,destination})=>{const entry=bundle.entries.get(source);if(entry?.type!=='file')failure('Required flat reference is missing or not regular');return[destination,{...entry,bytes:Buffer.from(entry.bytes)}];}));
+}
+export function validateFlatReferenceFiles(files,platform){
+ if(!(files instanceof Map)||!['codex','claude'].includes(platform))failure('Invalid flat reference input');
+ const prefix=platform+'/skill/references/',entries=new Map();
+ for(const name of files.keys())if(name.startsWith(prefix+'superpowers/'))failure('Unexpected nested reference payload');
+ for(const{source,destination}of REFERENCE_PATH_MAP){const bytes=files.get(prefix+destination);if(!Buffer.isBuffer(bytes))failure('Required flat reference file is missing: '+prefix+destination);const parts=source.split('/');for(let i=1;i<parts.length;i++)entries.set(parts.slice(0,i).join('/'),{type:'directory',mode:0o755n});entries.set(source,{type:'file',bytes,mode:0o644n});}
+ let provenance;try{provenance=JSON.parse(entries.get('provenance.json').bytes);}catch{failure('Malformed flat reference provenance');}
+ const bundle=validateReferenceBundle({entries,provenance});return{provenance,entries:flattenReferenceBundle(bundle)};
+}
+export function composeStaticArcSkillTree(skillFiles){
+ const entries=new Map();
+ for(const[name,bytes]of skillFiles){const parts=name.split('/');if(parts.some(part=>!part||part==='.'||part==='..')||name.includes('\\')||name.includes('\0')||name==='references/superpowers'||name.startsWith('references/superpowers/'))failure('Unsafe static ARC path');if(!Buffer.isBuffer(bytes))failure('Invalid static ARC bytes');for(let i=1;i<parts.length;i++)entries.set(parts.slice(0,i).join('/'),{type:'directory',mode:0o700n});entries.set(name,{type:'file',bytes:Buffer.from(bytes),mode:0o600n});}
+ return entries;
+}

package/lib/installer/transaction.mjs

@@ -1,4 +1,4 @@
-import {composeArcSkillTree} from './superpowers.mjs';
+import {composeStaticArcSkillTree} from './superpowers.mjs';
 import path from 'node:path';
 import {cleanupStage,captureCleanupEntry} from './stage-cleanup.mjs';
 import {randomUUID,createHash} from 'node:crypto';
@@ -53,13 +53,13 @@ function writeTree(directory,entries){
 }
 function snapshotEntry(parent,name){const stat=exists(parent,name);if(!stat)return null;const type=typeOf(stat);if(type===0o100000)return readCheckedFile(parent,name,stat).metadata;if(type===0o120000)return{...metadataOf(stat),type:'symlink',link:parent.readlink(name)};if(type===0o040000){const dir=parent.openDir(name);try{if(!sameObjectIdentity(stat,dir.stat()))fail('Entry directory changed');const entries=treeFromDirectory(dir);const hash=createHash('sha256');for(const[k,v]of entries){hash.update(JSON.stringify([k,v.type,...['dev','ino','mode','size','mtimeNs','ctimeNs'].map(field=>String(v.times[field])),v.bytes?.toString('hex')??v.link??null]));}return{...metadataOf(stat),type:'directory',sha256:hash.digest('hex'),children:captureCleanupEntry(parent,name).children};}finally{dir.close();}}fail('Special target entry');}
 function equalMoved(a,b){return a&&b&&['dev','ino','mode','size','mtimeNs','type','sha256','link'].every(k=>a[k]===b[k]);}
-export function applyTransaction(plan,{safeFs,acquired,signal,hooks={},specs:explicitSpecs}){
+export function applyTransaction(plan,{safeFs,signal,hooks={},specs:explicitSpecs}){
  assertPlanSnapshot(plan,{safeFs});const actions=[],areas=[],parents=[],created=[],actionLog=[],byParent=new Map();
  const cleanAreas=()=>{const paths=[],errors=[];for(const area of areas){const result=cleanupStage(area,{safeFs,hooks:{fault:event=>hooks.fault?.({...event,plan})}});paths.push(...result.residualPaths);if(result.cleanupError)errors.push(result.cleanupError);}return{paths,error:errors.length?Object.assign(new AggregateError(errors,errors.map(error=>error.message).join('; ')),{code:'ARC_INSTALL_CLEANUP',residualPaths:paths}):null};};
  const event=(phase,details={})=>{actionLog.push({phase,...details});if(signal?.aborted)throw new InstallError('Install interrupted','ARC_INSTALL_CANCELLED');hooks.fault?.({phase,...details,plan});};
  try{
   event('before-prepare');
-  const specs=explicitSpecs??plan.uninstallSpecs??[...plan.externalPaths.map(p=>({path:p,tree:acquired.skills.get(path.basename(p))?.entries,rootMetadata:acquired.skills.get(path.basename(p))?.rootMetadata})),{path:plan.target.home+'/skills/arc',tree:composeArcSkillTree(plan.generated.skill,acquired.references)},...[...plan.generated.profiles].map(([name,bytes])=>({path:plan.target.home+'/agents/'+name,bytes})),...plan.globalChanges.map(change=>({path:change.path,bytes:change.content}))];
+  const specs=explicitSpecs??plan.uninstallSpecs??[{path:plan.target.home+'/skills/arc',tree:composeStaticArcSkillTree(plan.generated.skill)},...[...plan.generated.profiles].map(([name,bytes])=>({path:plan.target.home+'/agents/'+name,bytes})),...plan.globalChanges.map(change=>({path:change.path,bytes:change.content}))];
   for(const spec of specs){if(!spec.remove&&!spec.tree&&!Buffer.isBuffer(spec.bytes))fail('Missing verified staged data');const parent=openParent(safeFs,spec.path,created);parents.push(parent);const name=path.basename(spec.path);event('before-stage',{path:spec.path});let area=byParent.get(path.dirname(spec.path));if(area&&!sameObjectIdentity(parent.stat(),area.parent.stat()))fail('Reused staging parent identity changed','ARC_INSTALL_DRIFT');if(!area){const stageName='.arc-stage-'+randomUUID();parent.mkdir(stageName,0o700);const stage=parent.openDir(stageName);area={parent,stage,name:stageName,path:path.dirname(spec.path)+'/'+stageName,identity:stage.stat(),expected:new Map()};areas.push(area);byParent.set(path.dirname(spec.path),area);}const stage=area.stage,preparedName='prepared-'+actions.length,previousName='previous-'+actions.length,rollbackName='rollback-installed-'+actions.length;
    if(spec.remove){}
    else if(spec.tree){stage.mkdir(preparedName,0o700);const dir=stage.openDir(preparedName);try{writeTree(dir,spec.tree);if(spec.rootMetadata)finishDirectory(dir,spec.rootMetadata.mode,spec.rootMetadata);else dir.sync();}finally{dir.close();}}

package/lib/installer/upgrade.mjs

@@ -1,6 +1,3 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
 import {buildInstallPlan,validatePlanSet} from './plan.mjs';
 import {assertPlanSnapshot} from './transaction.mjs';
 import {inspectPath} from './targets.mjs';
@@ -8,7 +5,6 @@ import {renderManagedBlock,removeManagedBlock,agentsBlockBody} from './global-co
 import {attachShellCompletionCleanup} from './shell-completion.mjs';
 import {verifyPayload} from './manifest.mjs';
 import {installTargets} from './install.mjs';
-import {acquireExternalSkills} from './acquisition.mjs';
 export function buildUpgradePlans({payload,state,safeFs}){
  for(const entry of state.targets)assertPlanSnapshot(entry,{safeFs});
  const plans=state.targets.map(entry=>{
@@ -22,10 +18,7 @@ export function buildUpgradePlans({payload,state,safeFs}){
  attachShellCompletionCleanup(plans,{safeFs});
  validatePlanSet(plans);return plans;
 }
-export async function upgradeInstalledTargets({packageRoot,state,safeFs,signal,acquisition}){
+export async function upgradeInstalledTargets({packageRoot,state,safeFs,signal}){
  const payload=verifyPayload({packageRoot,safeFs}),version=JSON.parse(payload.files.get('package.json').toString('utf8')).version,plans=buildUpgradePlans({payload,state,safeFs});
- const acquire=acquisition??(async()=>{const work=fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()),'arc-acquire-'));let acquired;
-  try{acquired=await acquireExternalSkills({work,safeFs,signal});}catch(error){if(!error.residualPaths?.length)try{fs.rmdirSync(work);}catch(cleanup){throw Object.assign(new AggregateError([error,cleanup],'Cannot clean private acquisition work'),{code:'ARC_ACQUISITION_CLEANUP',residualPaths:[work]});}throw error;}
-  return{...acquired,dispose:async()=>{await acquired.dispose();fs.rmdirSync(work);}};});
- return{version,...await installTargets(plans,{safeFs,signal,acquisition:acquire})};
+ return{version,...await installTargets(plans,{safeFs,signal})};
 }

package/lib/management/operations.mjs

@@ -1,6 +1,4 @@
-import fs from 'node:fs';
 import os from 'node:os';
-import path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {resolveTarget} from '../installer/targets.mjs';
 import {buildInstallPlan,validatePlanSet} from '../installer/plan.mjs';
@@ -11,8 +9,7 @@ import {installTargets} from '../installer/install.mjs';
 import {attachShellCompletionCleanup} from '../installer/shell-completion.mjs';
 import {inspectGlobalArc} from '../npm/context.mjs';
 import {uninstallGlobal,sameGlobalArc} from '../npm/uninstall.mjs';
-import {acquireExternalSkills} from '../installer/acquisition.mjs';
-/** @typedef {{packageRoot:string,userHome:string,cwd:string,env:object,safeFs:object,signal?:AbortSignal,acquisition?:Function}} ManagementContext */
+/** @typedef {{packageRoot:string,userHome:string,cwd:string,env:object,safeFs:object,signal?:AbortSignal}} ManagementContext */
 /** @typedef {{kind:string,plans:object[],options:object}} PreparedOperation */
 /** @typedef {{code:number,exitSession:boolean,results:object[],interrupted:boolean}} OperationResult */
 export async function createManagementContext(options={}){
@@ -31,11 +28,10 @@ export async function prepareOperation(context,options,{selections=[]}={}){
  return{kind:options.kind,plans,options:{...options},...(globalArc?{globalArc}:{})};
 }
 export function operationResult(result,successStatuses=['installed']){return{...result,code:result.interrupted?130:result.results.every(item=>successStatuses.includes(item.status)&&!item.error)?0:1,exitSession:false};}
-export function acquisitionFor(context){return context.acquisition??(async()=>{const work=fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()),'arc-acquire-'));let acquired;try{acquired=await acquireExternalSkills({work,safeFs:context.safeFs,signal:context.signal});}catch(error){if(!error.residualPaths?.length)try{fs.rmdirSync(work);}catch(cleanup){throw Object.assign(new AggregateError([error,cleanup],'Cannot clean private acquisition work'),{code:'ARC_ACQUISITION_CLEANUP',residualPaths:[work]});}throw error;}return{...acquired,dispose:async()=>{await acquired.dispose();fs.rmdirSync(work);}};});}
 export async function executeOperation(context,prepared){
  if(prepared.kind==='update'){const{executeUpdate}=await import('./update.mjs');return executeUpdate(context,prepared);}
  const options={safeFs:context.safeFs,signal:context.signal,hooks:context.hooks};
- if(prepared.kind==='install')return operationResult(await installTargets(prepared.plans,{...options,acquisition:acquisitionFor(context)}));
+ if(prepared.kind==='install')return operationResult(await installTargets(prepared.plans,options));
  if(prepared.kind==='preset')return operationResult(await switchPresetTargets(prepared.plans,options),['updated','unchanged']);
  if(prepared.kind==='uninstall'){
   let result;

package/lib/release/artifact.mjs

@@ -7,7 +7,7 @@ import {isDeepStrictEqual} from 'node:util';
 import {spawnSync} from 'node:child_process';
 import {fileURLToPath} from 'node:url';
 import {openRoot} from '../safe-fs/index.mjs';
-import {verifyPayload} from '../installer/manifest.mjs';
+import {verifyPayload,LOCAL_UPDATER_PATH} from '../installer/manifest.mjs';
 import {readCheckedFile,typeOf,sameIdentity} from '../installer/targets.mjs';
 import {runNpm} from '../npm/process.mjs';
 
@@ -40,6 +40,7 @@ function inventory(root,pkg){
  const files=new Map(),directory=openRoot(root);
  function visit(parent,name,relative){
   const stat=parent.lstat(name),type=typeOf(stat);
+  if(relative===LOCAL_UPDATER_PATH)throw new Error('Local updater wrapper is forbidden in release inventory');
   if(type===0o040000){
    const child=parent.openDir(name);try{if(!sameIdentity(stat,child.stat()))throw new Error('Release source directory changed');
     const before=child.stat();for(const leaf of child.readDir())visit(child,leaf,relative+'/'+leaf);if(!sameIdentity(before,child.stat()))throw new Error('Release source directory changed while reading');
@@ -97,6 +98,7 @@ function archive(bytes){
 }
 function validateTarball(bytes,{expectedName,expectedVersion}){
  const files=archive(bytes),pkgFile=files.get('package.json');if(!pkgFile)throw new Error('Artifact package metadata is missing');
+ if(files.has(LOCAL_UPDATER_PATH))throw new Error('Local updater wrapper is forbidden in release artifact');
  const pkg=JSON.parse(pkgFile.bytes);metadata(pkg,undefined,{artifact:true});
  if(pkg.name!==expectedName||pkg.version!==expectedVersion)throw new Error('Artifact package identity mismatch');
  for(const name of ['scripts/postinstall.mjs','lib/cli/postinstall.mjs','lib/tui/app.mjs','lib/tui/terminal.mjs','lib/cli/root.mjs','lib/cli/upgrade.mjs','bin/arc-upgrade.mjs'])if(!files.has(name))throw new Error('Artifact runtime asset missing: '+name);
@@ -104,7 +106,7 @@ function validateTarball(bytes,{expectedName,expectedVersion}){
  const root=fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()),'arc-release-verify-'));
  try{
   for(const[name,item]of files){const filename=path.join(root,name);fs.mkdirSync(path.dirname(filename),{recursive:true,mode:0o700});fs.writeFileSync(filename,item.bytes,{mode:item.mode});}
-  verifyPayload({packageRoot:root,safeFs:{openRoot}});
+  verifyPayload({packageRoot:root,safeFs:{openRoot},payloadMode:'package'});
  }finally{fs.rmSync(root,{recursive:true,force:true});}
  return pkg;
 }
@@ -121,7 +123,7 @@ export async function buildReleaseArtifact({sourceRoot,outDir,npmCli,signal,deps
  if(!path.isAbsolute(sourceRoot)||fs.realpathSync(sourceRoot)!==sourceRoot)throw new Error('Source root must be an absolute real path');
  abort(signal);const inputs=sourceMetadata(sourceRoot),pkg=JSON.parse(inputs['package.json']),lock=JSON.parse(inputs['package-lock.json']);metadata(pkg,lock);
  const source=inventory(sourceRoot,pkg);for(const name of ['package.json','package-lock.json'])if(!inputs[name].equals(source.files.get(name).bytes))throw new Error('Release source metadata changed during validation');
- verifyPayload({packageRoot:sourceRoot,safeFs:{openRoot}});if(inventory(sourceRoot,pkg).snapshot!==source.snapshot)throw new Error('Release source snapshot changed during validation');
+ verifyPayload({packageRoot:sourceRoot,safeFs:{openRoot},payloadMode:'source'});if(inventory(sourceRoot,pkg).snapshot!==source.snapshot)throw new Error('Release source snapshot changed during validation');
  let output,lockIdentity,workRoot,workIdentity;const id=crypto.randomUUID(),partial='.arc-release-'+id+'.partial';let partialExists=false;
  try{
   output=safeOutput(sourceRoot,outDir);const lockFile=output.openFile('.arc-release.lock',{createExclusive:true,read:false});try{lockFile.writeAll(JSON.stringify({schema:1,owner:id,pid:process.pid,state:'incomplete'}));lockIdentity=lockFile.stat();lockFile.sync();}finally{lockFile.close();}
@@ -131,7 +133,7 @@ export async function buildReleaseArtifact({sourceRoot,outDir,npmCli,signal,deps
   const stagedPkg={...pkg,scripts:{...pkg.scripts,postinstall:HOOK}},stagedLock=structuredClone(lock);stagedLock.packages[''].hasInstallScript=true;
   fs.writeFileSync(path.join(stagingRoot,'package.json'),JSON.stringify(stagedPkg,null,2)+'\n');fs.writeFileSync(path.join(stagingRoot,'package-lock.json'),JSON.stringify(stagedLock,null,2)+'\n');metadata(stagedPkg,stagedLock,{artifact:true});
   fs.writeFileSync(path.join(stagingRoot,'.arc-release-staging.json'),JSON.stringify({schema:1,owner:id,state:'incomplete',sourceSnapshot:source.snapshot}));
-  refresh(stagingRoot);verifyPayload({packageRoot:stagingRoot,safeFs:{openRoot}});await deps.onStaged?.({stagingRoot,signal});abort(signal);
+  refresh(stagingRoot);verifyPayload({packageRoot:stagingRoot,safeFs:{openRoot},payloadMode:'package'});await deps.onStaged?.({stagingRoot,signal});abort(signal);verifyPayload({packageRoot:stagingRoot,safeFs:{openRoot},payloadMode:'package'});
   const bytes=await(deps.pack??pack)({stagingRoot,workRoot,npmCli,signal});abort(signal);validateTarball(bytes,{expectedName:pkg.name,expectedVersion:pkg.version});
   if(inventory(sourceRoot,pkg).snapshot!==source.snapshot)throw new Error('Release source snapshot changed during generation');abort(signal);
   const tarballPath=path.join(outDir,'arc-release.tgz'),receiptPath=path.join(outDir,'arc-release.json');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunhozz/arc",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -27,7 +27,17 @@
   "files": [
     "bin/",
     "lib/",
-    "scripts/",
+    "scripts/build-native.mjs",
+    "scripts/check-installer-parity.mjs",
+    "scripts/pack-release.mjs",
+    "scripts/postinstall.mjs",
+    "scripts/probe-runtime-hooks.mjs",
+    "scripts/update-manifest.mjs",
+    "scripts/update-role-policy.mjs",
+    "scripts/update-runtime-assets.mjs",
+    "scripts/update-superpowers.mjs",
+    "scripts/vendor-toml.mjs",
+    "scripts/verify-release.mjs",
     "vendor/",
     "prebuilds/",
     "native/binding.c",

package/scripts/update-manifest.mjs

@@ -1,28 +1,26 @@
-import {isDynamicReferencePath} from '../lib/installer/superpowers.mjs';
+import {renderManifest,LOCAL_UPDATER_PATH} from '../lib/installer/manifest.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
-import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 const i = process.argv.indexOf('--root');
 const root = i < 0 ? fileURLToPath(new URL('../', import.meta.url)) : path.resolve(process.argv[i + 1]);
 const mutable = new Set(['codex/skill/models.toml', 'claude/skill/models.toml']);
 const excluded = new Set(['.DS_Store', '__pycache__', 'build']);
-const files = new Set();
+const files = new Map();
 function visit(relative) {
-  if(isDynamicReferencePath(relative)) return;
   const filename = path.join(root, relative);
-  if (!fs.existsSync(filename)) return;
-  const stat = fs.lstatSync(filename);
+  let stat;try { stat = fs.lstatSync(filename); } catch (error) { if(error.code==='ENOENT')return;throw error; }
   if (stat.isSymbolicLink()) throw new Error(`Protected payload contains symlink: ${relative}`);
+  if(relative===LOCAL_UPDATER_PATH){if(!stat.isFile())throw new Error('Local updater wrapper must be a regular file');return;}
   if (stat.isDirectory()) {
     for (const name of fs.readdirSync(filename).sort()) if (!excluded.has(name)) visit(`${relative}/${name}`);
-  } else if (stat.isFile() && !mutable.has(relative)) files.add(relative);
+  } else if (stat.isFile() && !mutable.has(relative)) files.set(relative,fs.readFileSync(filename));
   else if (!stat.isFile()) throw new Error(`Protected payload is not regular: ${relative}`);
 }
 for (const entry of ['README.md', 'install.command', 'package.json', 'bin', 'lib', 'native/binding.c', 'native/binding.gyp', 'scripts', 'vendor', 'prebuilds', 'codex/skill', 'codex/agents', 'claude/skill', 'claude/agents']) visit(entry);
-const content = [...files].sort().map(name => `${crypto.createHash('sha256').update(fs.readFileSync(path.join(root, name))).digest('hex')}  ${name}\n`).join('');
+const content = renderManifest(files);
 const manifest = path.join(root, 'MANIFEST.sha256');
 if (process.argv.includes('--check')) {
-  if (!fs.existsSync(manifest) || fs.readFileSync(manifest, 'utf8') !== content) { console.error('Protected payload manifest is stale'); process.exitCode = 1; }
+  if (!fs.existsSync(manifest) || !fs.readFileSync(manifest).equals(content)) { console.error('Protected payload manifest is stale'); process.exitCode = 1; }
   else console.log(`Protected payload manifest verified (${files.size} files)`);
 } else { fs.writeFileSync(manifest, content); console.log(`Updated manifest (${files.size} files)`); }

package/claude/skill/references/superpowers/brainstorming/visual-companion.md

@@ -1,299 +0,0 @@
-# Visual Companion Guide
-
-Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
-
-## When to Use
-
-Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
-
-**Use the browser** when the content itself is visual:
-
-- **UI mockups** — wireframes, layouts, navigation structures, component designs
-- **Architecture diagrams** — system components, data flow, relationship maps
-- **Side-by-side visual comparisons** — comparing two layouts, two color schemes, two design directions
-- **Design polish** — when the question is about look and feel, spacing, visual hierarchy
-- **Spatial relationships** — state machines, flowcharts, entity relationships rendered as diagrams
-
-**Use the terminal** when the content is text or tabular:
-
-- **Requirements and scope questions** — "what does X mean?", "which features are in scope?"
-- **Conceptual A/B/C choices** — picking between approaches described in words
-- **Tradeoff lists** — pros/cons, comparison tables
-- **Technical decisions** — API design, data modeling, architectural approach selection
-- **Clarifying questions** — anything where the answer is words, not a visual preference
-
-A question *about* a UI topic is not automatically a visual question. "What kind of wizard do you want?" is conceptual — use the terminal. "Which of these wizard layouts feels right?" is visual — use the browser.
-
-## How It Works
-
-The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content to `screen_dir`, the user sees it in their browser and can click to select options. Selections are recorded to `state_dir/events` that you read on your next turn.
-
-**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, connection status, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
-
-## Starting a Session
-
-```bash
-# Start AFTER the user approves the companion. --open auto-opens their browser on
-# the first screen; --project-dir persists mockups and enables same-port restart.
-bash scripts/start-server.sh --project-dir /path/to/project --open
-
-# Returns: {"type":"server-started","port":52341,
-#           "url":"http://localhost:52341/?key=ab12…",
-#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
-#           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
-```
-
-Save `screen_dir` and `state_dir` from the response. With `--open`, the browser opens itself when you push the first screen — you don't need to ask the user to open it, but still share the URL as a fallback (headless/remote setups won't auto-open).
-
-**The URL contains a session key (`?key=…`).** The server rejects any request
-without it, so always give the user the **complete** URL from the `url` field —
-never strip the query string, and never hand out a bare `http://host:port`. The
-key gates HTTP and WebSocket access so a stray browser tab or another machine on
-the network can't read the screens or inject events. After the first load the
-browser remembers the key via a cookie, so reloads and `/files/*` assets work
-without repeating it.
-
-**Finding connection info:** The server writes its startup JSON to `$STATE_DIR/server-info`. If you launched the server in the background and didn't capture stdout, read that file to get the URL and port. When using `--project-dir`, check `<project>/.superpowers/brainstorm/` for the session directory.
-
-**Note:** Pass the project root as `--project-dir` so mockups persist in `.superpowers/brainstorm/` and survive server restarts. Without it, files go to `/tmp` and get cleaned up. Remind the user to add `.superpowers/` to `.gitignore` if it's not already there.
-
-**Launching the server by platform:**
-
-**Claude Code:**
-```bash
-# Default mode works — the script backgrounds the server itself.
-bash scripts/start-server.sh --project-dir /path/to/project --open
-```
-
-On Windows, the script auto-detects and switches to foreground mode (which blocks the tool call). Use `run_in_background: true` on the Bash tool call so the server survives across conversation turns, then read `$STATE_DIR/server-info` on the next turn to get the URL and port.
-
-**Codex:**
-```bash
-# Codex reaps background processes. The script auto-detects CODEX_CI and
-# switches to foreground mode. Run it normally — no extra flags needed.
-bash scripts/start-server.sh --project-dir /path/to/project --open
-```
-
-**Gemini CLI:**
-```bash
-# Use --foreground and set is_background: true on your shell tool call
-# so the process survives across turns
-bash scripts/start-server.sh --project-dir /path/to/project --open --foreground
-```
-
-**Copilot CLI:**
-```bash
-# Start it with Copilot CLI's non-blocking/background shell mechanism so the
-# server survives across turns. Keep --foreground so the harness, not the
-# script, owns backgrounding. The launcher is a .sh, so invoke it via bash
-# (on Windows, call Git Bash's bash.exe from the PowerShell tool).
-bash scripts/start-server.sh --project-dir /path/to/project --open --foreground
-```
-
-**Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.
-
-If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
-
-```bash
-bash scripts/start-server.sh \
-  --project-dir /path/to/project \
-  --host 0.0.0.0 \
-  --url-host localhost
-```
-
-Use `--url-host` to control what hostname is printed in the returned URL JSON.
-
-## The Loop
-
-1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
-   - **Required: confirm the server is alive before referring to the URL or pushing a screen.** Check that `$STATE_DIR/server-info` exists and `$STATE_DIR/server-stopped` does not. If it has shut down, restart it with `start-server.sh` using the **same `--project-dir`** — it reuses the same port, so the user's open tab reconnects on its own (it shows a "paused" overlay while the server is down) and you don't need to send a new URL. The server auto-exits after 4 hours idle (configurable with `--idle-timeout-minutes`).
-   - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
-   - **Never reuse filenames** — each screen gets a fresh file
-   - Use your file-creation tool — **never use cat/heredoc** (dumps noise into terminal)
-   - Server automatically serves the newest file
-
-2. **Tell user what to expect and end your turn:**
-   - Remind them of the URL (every step, not just first)
-   - Give a brief text summary of what's on screen (e.g., "Showing 3 layout options for the homepage")
-   - Ask them to respond in the terminal: "Take a look and let me know what you think. Click to select an option if you'd like."
-
-3. **On your next turn** — after the user responds in the terminal:
-   - Read `$STATE_DIR/events` if it exists — this contains the user's browser interactions (clicks, selections) as JSON lines
-   - Merge with the user's terminal text to get the full picture
-   - The terminal message is the primary feedback; `state_dir/events` provides structured interaction data
-
-4. **Iterate or advance** — if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to the next question when the current step is validated.
-
-5. **Unload when returning to terminal** — when the next step doesn't need the browser (e.g., a clarifying question, a tradeoff discussion), push a waiting screen to clear the stale content:
-
-   ```html
-   <!-- filename: waiting.html (or waiting-2.html, etc.) -->
-   <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
-     <p class="subtitle">Continuing in terminal...</p>
-   </div>
-   ```
-
-   This prevents the user from staring at a resolved choice while the conversation has moved on. When the next visual question comes up, push a new content file as usual.
-
-6. Repeat until done.
-
-## Writing Content Fragments
-
-Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, connection status, and all interactive infrastructure).
-
-**Minimal example:**
-
-```html
-<h2>Which layout works better?</h2>
-<p class="subtitle">Consider readability and visual hierarchy</p>
-
-<div class="options">
-  <div class="option" data-choice="a" onclick="toggleSelect(this)">
-    <div class="letter">A</div>
-    <div class="content">
-      <h3>Single Column</h3>
-      <p>Clean, focused reading experience</p>
-    </div>
-  </div>
-  <div class="option" data-choice="b" onclick="toggleSelect(this)">
-    <div class="letter">B</div>
-    <div class="content">
-      <h3>Two Column</h3>
-      <p>Sidebar navigation with main content</p>
-    </div>
-  </div>
-</div>
-```
-
-That's it. No `<html>`, no CSS, no `<script>` tags needed. The server provides all of that.
-
-## CSS Classes Available
-
-The frame template provides these CSS classes for your content:
-
-### Options (A/B/C choices)
-
-```html
-<div class="options">
-  <div class="option" data-choice="a" onclick="toggleSelect(this)">
-    <div class="letter">A</div>
-    <div class="content">
-      <h3>Title</h3>
-      <p>Description</p>
-    </div>
-  </div>
-</div>
-```
-
-**Multi-select:** Add `data-multiselect` to the container to let users select multiple options. Each click toggles the item's selected styling.
-
-```html
-<div class="options" data-multiselect>
-  <!-- same option markup — users can select/deselect multiple -->
-</div>
-```
-
-### Cards (visual designs)
-
-```html
-<div class="cards">
-  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
-    <div class="card-image"><!-- mockup content --></div>
-    <div class="card-body">
-      <h3>Name</h3>
-      <p>Description</p>
-    </div>
-  </div>
-</div>
-```
-
-### Mockup container
-
-```html
-<div class="mockup">
-  <div class="mockup-header">Preview: Dashboard Layout</div>
-  <div class="mockup-body"><!-- your mockup HTML --></div>
-</div>
-```
-
-### Split view (side-by-side)
-
-```html
-<div class="split">
-  <div class="mockup"><!-- left --></div>
-  <div class="mockup"><!-- right --></div>
-</div>
-```
-
-### Pros/Cons
-
-```html
-<div class="pros-cons">
-  <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
-  <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
-</div>
-```
-
-### Mock elements (wireframe building blocks)
-
-```html
-<div class="mock-nav">Logo | Home | About | Contact</div>
-<div style="display: flex;">
-  <div class="mock-sidebar">Navigation</div>
-  <div class="mock-content">Main content area</div>
-</div>
-<button class="mock-button">Action Button</button>
-<input class="mock-input" placeholder="Input field">
-<div class="placeholder">Placeholder area</div>
-```
-
-### Typography and sections
-
-- `h2` — page title
-- `h3` — section heading
-- `.subtitle` — secondary text below title
-- `.section` — content block with bottom margin
-- `.label` — small uppercase label text
-
-## Browser Events Format
-
-When the user clicks options in the browser, their interactions are recorded to `$STATE_DIR/events` (one JSON object per line). The file is cleared automatically when you push a new screen.
-
-```jsonl
-{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
-{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
-{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
-```
-
-The full event stream shows the user's exploration path — they may click multiple options before settling. The last `choice` event is typically the final selection, but the pattern of clicks can reveal hesitation or preferences worth asking about.
-
-If `$STATE_DIR/events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
-
-## Design Tips
-
-- **Scale fidelity to the question** — wireframes for layout, polish for polish questions
-- **Explain the question on each page** — "Which layout feels more professional?" not just "Pick one"
-- **Iterate before advancing** — if feedback changes current screen, write a new version
-- **2-4 options max** per screen
-- **Use real content when it matters** — for a photography portfolio, use actual images (Unsplash). Placeholder content obscures design issues.
-- **Keep mockups simple** — focus on layout and structure, not pixel-perfect design
-
-## File Naming
-
-- Use semantic names: `platform.html`, `visual-style.html`, `layout.html`
-- Never reuse filenames — each screen must be a new file
-- For iterations: append version suffix like `layout-v2.html`, `layout-v3.html`
-- Server serves newest file by modification time
-
-## Cleaning Up
-
-```bash
-bash scripts/stop-server.sh $SESSION_DIR
-```
-
-If the session used `--project-dir`, mockup files persist in `.superpowers/brainstorm/` for later reference. Only `/tmp` sessions get deleted on stop.
-
-## Reference
-
-- Frame template (CSS reference): `scripts/frame-template.html`
-- Helper script (client-side): `scripts/helper.js`