role-os 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.0.2
+
+### Fixed
+- Fix double-nested `.claude/.claude/` directory created by `roleos init` — `starter-pack/.claude/workflows/full-treatment.md` moved to `starter-pack/workflows/`
+- Read VERSION from `package.json` at runtime instead of hardcoded constant — prevents version drift between CLI and package metadata
+
+### Added
+- `roleos init --force` — update canonical scaffolded files while always protecting user-filled `context/` files
+- 4 regression tests: no double-nesting, correct workflow placement, version sync, --force context protection
+
 ## 1.0.0
 
 ### Added

package/bin/roleos.mjs

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { initCommand } from "../src/init.mjs";
 import { packetCommand } from "../src/packet.mjs";
 import { routeCommand } from "../src/route.mjs";
 import { reviewCommand } from "../src/review.mjs";
 import { statusCommand } from "../src/status.mjs";
 
-const VERSION = "1.0.0";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VERSION = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
 
 function printHelp() {
   console.log(`
@@ -14,6 +18,7 @@ roleos v${VERSION} — Role OS bootstrap CLI
 
 Usage:
   roleos init                        Scaffold Role OS into .claude/
+  roleos init --force                Update canonical files (protects context/)
   roleos packet new <type>           Create a new packet (feature|integration|identity)
   roleos route <packet-file>         Recommend the smallest valid chain
   roleos review <packet-file> <verdict>  Record a review verdict

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "role-os",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Role OS — a repo-native operating layer where specialized roles execute work through contracts, handoffs, review, and escalation",
   "type": "module",
   "bin": {

package/src/fs-utils.mjs

@@ -3,11 +3,14 @@ import { join, dirname, relative } from "node:path";
 
 /**
  * Recursively copy a directory, skipping files that already exist at the target.
- * Returns { created: string[], skipped: string[] } with relative paths.
+ * With force=true, overwrites existing files (except those matching protectedPaths).
+ * Returns { created: string[], skipped: string[], updated: string[] } with relative paths.
  */
-export function copyDirSafe(srcDir, destDir, baseDir = destDir) {
+export function copyDirSafe(srcDir, destDir, { baseDir, force = false, protectedPaths = [] } = {}) {
+  const root = baseDir || destDir;
   const created = [];
   const skipped = [];
+  const updated = [];
 
   if (!existsSync(srcDir)) {
     throw new Error(`Source directory does not exist: ${srcDir}`);
@@ -18,15 +21,23 @@ export function copyDirSafe(srcDir, destDir, baseDir = destDir) {
   for (const entry of entries) {
     const srcPath = join(srcDir, entry.name);
     const destPath = join(destDir, entry.name);
-    const relPath = relative(baseDir, destPath);
+    const relPath = relative(root, destPath);
 
     if (entry.isDirectory()) {
-      const sub = copyDirSafe(srcPath, destPath, baseDir);
+      const sub = copyDirSafe(srcPath, destPath, { baseDir: root, force, protectedPaths });
       created.push(...sub.created);
       skipped.push(...sub.skipped);
+      updated.push(...sub.updated);
     } else {
       if (existsSync(destPath)) {
-        skipped.push(relPath);
+        const normalizedRel = relPath.replace(/\\/g, "/");
+        if (force && !protectedPaths.some(p => normalizedRel.startsWith(p))) {
+          mkdirSync(dirname(destPath), { recursive: true });
+          copyFileSync(srcPath, destPath);
+          updated.push(relPath);
+        } else {
+          skipped.push(relPath);
+        }
       } else {
         mkdirSync(dirname(destPath), { recursive: true });
         copyFileSync(srcPath, destPath);
@@ -35,7 +46,7 @@ export function copyDirSafe(srcDir, destDir, baseDir = destDir) {
     }
   }
 
-  return { created, skipped };
+  return { created, skipped, updated };
 }
 
 /**

package/src/init.mjs

@@ -5,13 +5,23 @@ import { copyDirSafe } from "./fs-utils.mjs";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const STARTER_PACK_DIR = join(__dirname, "..", "starter-pack");
 
+// Paths that --force must never overwrite (user-filled content)
+const PROTECTED_PATHS = [
+  "context/",
+];
+
 export async function initCommand(args) {
-  const targetDir = args[0] || ".";
+  const force = args.includes("--force");
+  const positional = args.filter(a => !a.startsWith("--"));
+  const targetDir = positional[0] || ".";
   const claudeDir = join(targetDir, ".claude");
 
-  console.log("roleos init — scaffolding Role OS into .claude/\n");
+  console.log(`roleos init${force ? " --force" : ""} — scaffolding Role OS into .claude/\n`);
 
-  const { created, skipped } = copyDirSafe(STARTER_PACK_DIR, claudeDir);
+  const { created, skipped, updated } = copyDirSafe(STARTER_PACK_DIR, claudeDir, {
+    force,
+    protectedPaths: PROTECTED_PATHS,
+  });
 
   if (created.length > 0) {
     console.log(`Created (${created.length}):`);
@@ -20,6 +30,13 @@ export async function initCommand(args) {
     }
   }
 
+  if (updated.length > 0) {
+    console.log(`\nUpdated (${updated.length}):`);
+    for (const f of updated) {
+      console.log(`  ~ ${f}`);
+    }
+  }
+
   if (skipped.length > 0) {
     console.log(`\nSkipped (${skipped.length} — already exist):`);
     for (const f of skipped) {
@@ -27,8 +44,11 @@ export async function initCommand(args) {
     }
   }
 
-  if (created.length === 0 && skipped.length > 0) {
+  if (created.length === 0 && updated.length === 0 && skipped.length > 0) {
     console.log("\nRole OS is already scaffolded. No files were overwritten.");
+    if (!force) {
+      console.log("Use --force to update canonical files (context/ files are always protected).");
+    }
   } else {
     console.log(`\nDone. Fill the context/ files for your project, then run:`);
     console.log(`  roleos packet new feature`);

package/starter-pack/workflows/full-treatment.md

@@ -0,0 +1,176 @@
+# Full Treatment
+
+Every tool repo gets the full treatment before it's "whole." This is the complete 7-phase protocol — not a pointer to an external file.
+
+## Gate: Shipcheck runs first
+
+Full treatment does not start until shipcheck passes. Shipcheck is the 31-item quality gate (hard gates A-D block release).
+
+Order: `npx @mcptoolshop/shipcheck audit` → exits 0 → then full treatment.
+
+No v1.0.0 bump without passing hard gates A-D.
+
+## Phase 1 — Pre-flight + finalize README + hand off translations
+
+a) Clone repo, verify Pages source is "GitHub Actions", enable if not. Check for existing site/ and pages.yml.
+b) Note whether root package.json has "private": true (controls npm badge/link decisions).
+c) Push logo to brand repo: `mcp-tool-shop-org/brand/logos/<slug>/readme.png`, run `brand manifest`, commit+push. Min 530x530px.
+d) Update README: brand logo URL (`https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/<slug>/readme.png`), width="400", centered.
+e) Badges (after logo, centered): CI status, Codecov coverage, MIT license, Landing Page. Only if published: npm/PyPI version badges.
+f) If logo contains product name, remove redundant `<h1>`.
+g) Update footer: `Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>`
+h) README is now final — hand the user the translation command(s).
+
+Translation command (user runs in PowerShell, NOT Claude):
+```
+node F:/AI/polyglot-mcp/scripts/translate-all.mjs F:/AI/<repo>/README.md
+```
+Monorepos: chain with semicolons. Large monorepos: batch into groups of 5-7.
+
+WARNING: NEVER run translations from Claude — wastes Claude points. User runs locally (TranslateGemma 12B, Ollama, zero API cost, ~2-4 min/README).
+
+### Role owners
+- **Repo Researcher** — verify repo state, Pages config, package.json
+- **Brand Guardian** — verify logo, README identity, footer
+- **Repo Translator** — hand off and verify translations
+
+## Phase 2 — Scaffold landing page (while translations run)
+
+a) `npx @mcptoolshop/site-theme init` from repo root
+b) Add to .gitignore: site/.astro/, site/dist/, site/node_modules/, .polyglot-cache.json
+c) `cd site && npm install`
+d) Verify site/astro.config.mjs base matches `/<repo-name>/` (case-sensitive)
+e) Write site/src/site-config.ts (typed as SiteConfig). Description from root package.json.
+f) pages.yml does NOT count toward "max 2 workflow files" rule
+
+### Role owners
+- **Docs Architect** — site-theme init, site-config.ts
+- **Frontend Developer** — landing page content and build
+- **Brand Guardian** — verify brand alignment
+
+## Phase 3 — Handbook (Starlight docs)
+
+a) `cd <repo>/site && npm install @astrojs/starlight`
+b) Replace astro.config.mjs (social must be array, disable404Route: true)
+c) Create content.config.ts in site/src/:
+```ts
+import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+export const collections = { docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }) };
+```
+d) Create starlight-custom.css (derive accent from global.css):
+
+| Accent | --sl-color-accent-low | --sl-color-accent | --sl-color-accent-high |
+|--------|----------------------|-------------------|------------------------|
+| emerald (default) | #022c22 | #34d399 | #6ee7b7 |
+| amber | #451a03 | #d97706 | #fbbf24 |
+| blue | #1e1b4b | #3b82f6 | #93c5fd |
+| rose | #4c0519 | #f43f5e | #fb7185 |
+| violet | #2e1065 | #8b5cf6 | #a78bfa |
+| cyan | #083344 | #06b6d4 | #67e8f9 |
+| pink | #500724 | #ec4899 | #f9a8d4 |
+
+Dark background vars: `--sl-color-bg: #09090b`, `--sl-color-hairline: #27272a`, etc.
+
+e) Create handbook pages in site/src/content/docs/handbook/ (min 3: index, getting-started, reference)
+
+| Source | File | Order |
+|--------|------|-------|
+| Welcome | index.md | 0 |
+| Install/Quick Start | getting-started.md | 1 |
+| Usage | usage.md | 2 |
+| Config/Options | configuration.md | 3 |
+| API/Commands | reference.md | 4 |
+| Architecture | architecture.md | 5 |
+| Security | security.md | 6 |
+
+Minimum 3 pages. Rich repos get 5-7. Expand README content — don't just copy-paste.
+
+f) Update landing page CTA in site-config.ts: `secondaryCta: { href: 'handbook/', label: 'Read the Handbook' }`
+g) Build and verify: `cd site && npm run build` — check dist/index.html + dist/handbook/
+
+### Role owners
+- **Docs Architect** — Starlight setup, page structure, content
+- **Repo Translator** — docs translation if applicable
+
+## Phase 4 — Repo metadata + coverage
+
+a) Set GitHub metadata:
+```
+gh repo edit mcp-tool-shop-org/<repo> --description "<from package.json>" --homepage "https://mcp-tool-shop-org.github.io/<repo-name>/"
+gh repo edit mcp-tool-shop-org/<repo> --add-topic <tags>
+```
+b) Code coverage: add coverage dep, coverage CI step (one matrix entry), codecov upload, badge in README
+c) Verify site builds, .gitignore complete, logo renders at brand URL
+d) Review README for typos, broken links, stale content
+
+### Role owners
+- **Metadata Curator** — GitHub metadata, badges, manifest
+- **Coverage Auditor** — test coverage assessment, CI integration
+
+## Phase 5 — Repo Knowledge DB entry
+
+Every treated repo gets a proper entry in the repo-knowledge database. This is NOT optional.
+
+a) Sync the repo if not already in the DB:
+```
+rk sync --owners mcp-tool-shop-org
+```
+
+b) Add required notes using MCP tools or CLI:
+- **thesis** — what the repo is and why it exists (1-2 sentences)
+- **architecture** — how it's built, key components, data flow
+- At least one **relationship** mapped (depends_on, related_to, shares_domain_with, etc.)
+
+c) Add recommended notes where applicable:
+- **convention** — important patterns/rules specific to this repo
+- **next_step** — what should happen next
+- **warning** or **drift_risk** — known issues or things that could break
+- **command** — key commands to build/test/deploy
+
+d) Verify the entry:
+```
+rk show <slug>
+```
+Confirm: thesis present, architecture present, relationships mapped, tech detected, docs indexed.
+
+### Role owners
+- **Repo Researcher** — thesis, architecture, relationships
+- **Metadata Curator** — verify entry completeness
+
+## Phase 6 — Commit and deploy
+
+Stage explicitly: `git add site/ .github/workflows/pages.yml .gitignore README.md README.*.md`
+WARNING: Use `README.*.md` glob — NEVER hand-type individual filenames.
+Never `git add .` — translated READMEs may have CRLF drift on Windows.
+Push to main. Verify landing page + handbook render.
+
+### Role owners
+- **Release Engineer** — staging, version, tag, push
+
+## Phase 7 — Post-deploy verification
+
+- Landing page renders at `https://mcp-tool-shop-org.github.io/<repo-name>/`
+- Handbook renders at `.../handbook/`
+- Pagefind search works in handbook
+- Translations are complete (check ja for degenerate output)
+- Coverage badge shows real data
+- `rk show <slug>` returns complete knowledge entry
+- Repo-knowledge DB has thesis, architecture, and relationships
+
+### Role owners
+- **Deployment Verifier** — landing page, handbook, package, badges, translations
+
+### Final gate
+- **Critic Reviewer** — accept or reject treatment completeness
+
+## Do NOT
+
+- Copy or modify theme components locally
+- Add extra Astro pages beyond index.astro unless requested
+- Skip the init CLI and scaffold manually
+- Add npm badges for private/unpublished repos
+- Skip the repo-knowledge DB entry — it's part of the treatment now
+- Run translations from Claude
+- Reference "memory/" paths without absolute paths — protocols must be self-contained

package/starter-pack/.claude/workflows/full-treatment.md

@@ -1,74 +0,0 @@
-# Full Treatment
-
-Role OS does not own or redefine the full treatment protocol. The canonical protocol lives in Claude project memory (`memory/full-treatment.md`) and is a 7-phase polish + publish playbook.
-
-## Canonical source
-
-The full treatment is defined in Claude project memory as a 7-phase protocol:
-
-1. Pre-flight + finalize README + hand off translations
-2. Scaffold landing page (Astro site-theme)
-3. Handbook (Starlight docs)
-4. Repo metadata + coverage
-5. Repo Knowledge DB entry
-6. Commit and deploy
-7. Post-deploy verification
-
-Read `memory/full-treatment.md` and `memory/handbook-playbook.md` before starting.
-
-## Gate: Shipcheck runs first
-
-Full treatment does not start until shipcheck passes. Shipcheck is the 31-item quality gate (hard gates A-D block release). The canonical shipcheck reference lives in Claude project memory (`memory/shipcheck.md`).
-
-Order: `npx @mcptoolshop/shipcheck audit` → exits 0 → then full treatment.
-
-No v1.0.0 bump without passing hard gates A-D.
-
-## Role chain per phase
-
-Each treatment phase maps to specific roles:
-
-### Phase 1 — Pre-flight + README + translations
-- **Repo Researcher** — verify repo state, Pages config, package.json
-- **Brand Guardian** — verify logo, README identity, footer
-- **Repo Translator** — hand off and verify translations
-
-### Phase 2 — Scaffold landing page
-- **Docs Architect** — site-theme init, site-config.ts
-- **Frontend Developer** — landing page content and build
-- **Brand Guardian** — verify brand alignment
-
-### Phase 3 — Handbook (Starlight docs)
-- **Docs Architect** — Starlight setup, page structure, content
-- **Repo Translator** — docs translation if applicable
-
-### Phase 4 — Repo metadata + coverage
-- **Metadata Curator** — GitHub metadata, badges, manifest
-- **Coverage Auditor** — test coverage assessment, CI integration
-
-### Phase 5 — Repo Knowledge DB entry
-- **Repo Researcher** — thesis, architecture, relationships
-- **Metadata Curator** — verify entry completeness
-
-### Phase 6 — Commit and deploy
-- **Release Engineer** — staging, version, tag, push
-
-### Phase 7 — Post-deploy verification
-- **Deployment Verifier** — landing page, handbook, package, badges, translations
-
-### Final gate
-- **Critic Reviewer** — accept or reject treatment completeness
-
-## What Role OS adds
-
-- Explicit role ownership for each treatment phase
-- Structured handoffs between phases
-- Review gate on treatment completeness
-- Routing and escalation law
-
-## What Role OS does not own
-
-- The treatment protocol itself
-- The shipcheck gate
-- Claude project memory
-- Treatment history and repo facts (those live in Claude project memory)