chore: misc updates — PROSE platform overview, provenant compliance, scaffold cmd, wiki compiler

Author: StackMemory Bot (CLI)

docs/specs/PROSE-platform-overview.md

@@ -102,6 +102,106 @@ The local SQLite database is self-contained within `.stackmemory/` and portable
 
 **SOP basis:** `SOP-202 Data Portability` — the database must be relocatable and restorable without external services.
 
+### E.6 Error Handling contract
+Errors are surfaced through structured responses with sufficient context for callers to recover or retry.
+
+**SOP basis:** `SOP-1601 Circuit Breaking` and generated error-handling SOPs — failures must be isolated and observable.
+
+### E.7 Observability contract
+The platform emits metrics, logs, or traces that make internal state visible to operators.
+
+**SOP basis:** Generated observability SOPs — state changes must be observable without relying on ad-hoc inspection.
+
+### E.8 Backup and Recovery contract
+User data can be exported and restored within the same major CLI version without external services.
+
+**SOP basis:** Generated backup-and-recovery SOPs — data loss scenarios must have a documented recovery path.
+
+### E.9 Authentication contract
+Actions that modify project state are attributable to an authenticated actor.
+
+**SOP basis:** Generated authentication SOPs — identity must be established before privileged operations.
+
+### E.10 Authorization contract
+Access to project context is enforced according to the actor's permissions.
+
+**SOP basis:** Generated authorization SOPs — unauthorized access to project memory is non-compliant.
+
+### E.11 Data Encryption contract
+Sensitive data at rest is encrypted using platform-standard algorithms.
+
+**SOP basis:** Generated data-encryption SOPs — plaintext storage of secrets or credentials is non-compliant.
+
+### E.12 Input Validation contract
+External input is validated before processing to prevent injection or corruption.
+
+**SOP basis:** Generated input-validation SOPs — invalid input must be rejected at the boundary.
+
+### E.13 Rate Limiting contract
+API and CLI operations respect configured rate limits to prevent abuse or overload.
+
+**SOP basis:** Generated rate-limiting SOPs — exceeding configured limits must be throttled.
+
+### E.14 Audit Logging contract
+Security-relevant actions are recorded in an append-only audit log.
+
+**SOP basis:** Generated audit-logging SOPs — privileged actions must leave a traceable record.
+
+### E.15 Dependency Management contract
+External dependencies are tracked and scanned for known vulnerabilities.
+
+**SOP basis:** Generated dependency-management SOPs — unmanaged dependencies are non-compliant.
+
+### E.16 Secret Rotation contract
+Credentials and secrets are rotated on a defined schedule.
+
+**SOP basis:** Generated secret-rotation SOPs — expired or stale secrets must be replaced.
+
+### E.17 Multi-Agent Coordination contract
+Concurrent agents operating on the same project do not corrupt shared state.
+
+**SOP basis:** Generated multi-agent-coordination SOPs — conflicting writes must be resolved safely.
+
+### E.18 API Versioning contract
+Public API changes preserve backward compatibility within a major version.
+
+**SOP basis:** Generated API-versioning SOPs — breaking changes must be versioned explicitly.
+
+### E.19 Configuration Management contract
+Configuration is validated at load time and changes are traceable.
+
+**SOP basis:** Generated configuration-management SOPs — invalid or untracked config is non-compliant.
+
+### E.20 Schema Migration contract
+Database schema changes are forward-compatible and reversible within a major version.
+
+**SOP basis:** Generated schema-migration SOPs — migrations must not destroy user data.
+
+### E.21 Performance Budget contract
+Operations complete within defined latency and resource limits.
+
+**SOP basis:** Generated performance-budget SOPs — consistent budget violations are non-compliant.
+
+### E.22 Caching Strategy contract
+Cached data is invalidated or refreshed when underlying state changes.
+
+**SOP basis:** Generated caching-strategy SOPs — stale cache reads are non-compliant.
+
+### E.23 Retry Policy contract
+Transient failures are retried with backoff and jitter before surfacing as errors.
+
+**SOP basis:** Generated retry-policy SOPs — unbounded or immediate retries are non-compliant.
+
+### E.24 Circuit Breaking contract
+Repeated failures trigger circuit breaking to prevent cascading overload.
+
+**SOP basis:** `SOP-1601 Circuit Breaking` and generated circuit-breaking SOPs — the circuit must open after configured thresholds.
+
+### E.25 Feature Flagging contract
+Feature flags are evaluated consistently and changes are auditable.
+
+**SOP basis:** Generated feature-flagging SOPs — flag state must be deterministic and traceable.
+
 ---
 
 ## SOP → PROSE → Tests workflow
@@ -145,3 +245,23 @@ For example, `SOP-101 Frame Lifecycle` becomes PROSE `E.1`, which becomes the te
 | E.3 | `SOP-103 Project Boundary Enforcement` | `projects in different directories are isolated` |
 | E.4 | `SOP-201 CLI Exit-Code Compliance` | `CLI commands return correct exit codes` |
 | E.5 | `SOP-202 Data Portability` | `SQLite database is self-contained in .stackmemory` |
+| E.6 | `SOP-1xxx Error Handling` | `errors are surfaced as structured responses` |
+| E.7 | `SOP-1xxx Observability` | `platform emits observable metrics/logs/traces` |
+| E.8 | `SOP-1xxx Backup and Recovery` | `data can be exported and restored` |
+| E.9 | `SOP-1xxx Authentication` | `modifications are attributable to an actor` |
+| E.10 | `SOP-1xxx Authorization` | `access is enforced by permission` |
+| E.11 | `SOP-1xxx Data Encryption` | `sensitive data at rest is encrypted` |
+| E.12 | `SOP-1xxx Input Validation` | `invalid input is rejected at the boundary` |
+| E.13 | `SOP-1xxx Rate Limiting` | `operations respect configured rate limits` |
+| E.14 | `SOP-1xxx Audit Logging` | `security actions are append-only logged` |
+| E.15 | `SOP-1xxx Dependency Management` | `dependencies are tracked and scanned` |
+| E.16 | `SOP-1xxx Secret Rotation` | `secrets are rotated on schedule` |
+| E.17 | `SOP-1xxx Multi-Agent Coordination` | `concurrent agents do not corrupt state` |
+| E.18 | `SOP-1xxx API Versioning` | `public API changes preserve compatibility` |
+| E.19 | `SOP-1xxx Configuration Management` | `config is validated and traceable` |
+| E.20 | `SOP-1xxx Schema Migration` | `schema changes are forward-compatible` |
+| E.21 | `SOP-1xxx Performance Budget` | `operations stay within latency/resource limits` |
+| E.22 | `SOP-1xxx Caching Strategy` | `cache is invalidated on state change` |
+| E.23 | `SOP-1xxx Retry Policy` | `transient failures retry with backoff` |
+| E.24 | `SOP-1601 Circuit Breaking` | `circuit opens after failure thresholds` |
+| E.25 | `SOP-1xxx Feature Flagging` | `flag evaluation is deterministic and auditable` |

packages/provenant/src/cli/commands/compliance.ts

@@ -17,7 +17,9 @@ interface ComplianceEntry {
 
 export function compliance(opts: ComplianceOpts): void {
   if (!existsSync(opts.db)) {
-    console.error('No database found. Run `provenant log-decision` or ingest first.');
+    console.error(
+      'No database found. Run `provenant log-decision` or ingest first.'
+    );
     process.exit(1);
   }
 
@@ -42,13 +44,19 @@ export function compliance(opts: ComplianceOpts): void {
         // ignore malformed payload
       }
 
-      const proseId = (metadata['proseId'] as string) ?? extractProseId(node.content);
+      const proseId =
+        (metadata['proseId'] as string) ?? extractProseId(node.content);
       const sop = (metadata['sop'] as string) ?? extractSop(node.content);
       if (!proseId || seen.has(proseId)) continue;
       seen.add(proseId);
 
-      const passed = node.content.includes('compliance verified');
-      const failed = node.content.includes('compliance NOT verified');
+      const metadataStatus = metadata['status'] as string | undefined;
+      const passed =
+        metadataStatus === 'passed' ||
+        node.content.includes('compliance verified');
+      const failed =
+        metadataStatus === 'failed' ||
+        node.content.includes('compliance NOT verified');
 
       entries.push({
         proseId,
@@ -76,14 +84,17 @@ export function compliance(opts: ComplianceOpts): void {
     const failed = entries.filter((e) => e.status === 'fail').length;
 
     for (const entry of entries) {
-      const icon = entry.status === 'pass' ? '✓' : entry.status === 'fail' ? '✗' : '?';
+      const icon =
+        entry.status === 'pass' ? '✓' : entry.status === 'fail' ? '✗' : '?';
       console.log(
         `${icon} ${entry.proseId}  ${entry.sop.slice(0, 40).padEnd(40)}  confidence ${entry.confidence.toFixed(2)}`
       );
     }
 
     console.log('─'.repeat(60));
-    console.log(`Total: ${entries.length}  Passed: ${passed}  Failed: ${failed}`);
+    console.log(
+      `Total: ${entries.length}  Passed: ${passed}  Failed: ${failed}`
+    );
   } finally {
     db.close();
   }

scripts/verify-dist.cjs

@@ -43,14 +43,21 @@ function main() {
     join(dist, 'cli/codex-sm-danger.js'),
     join(dist, 'cli/claude-sm.js'),
     join(dist, 'cli/claude-sm-danger.js'),
+    join(dist, 'cli/hermes-sm.js'),
+    join(dist, 'cli/opencode-sm.js'),
+    join(dist, 'cli/gemini-sm.js'),
   ];
   requiredFiles.forEach(checkFile);
 
   // 2) Bin launchers reference dist/src/* (ESM dynamic import)
-  fileContains('bin/codex-sm', "import('../dist/src/cli/codex-sm.js')");
-  fileContains('bin/codex-smd', "import('../dist/src/cli/codex-sm-danger.js')");
-  fileContains('bin/claude-sm', "import('../dist/src/cli/claude-sm.js')");
-  fileContains('bin/claude-smd', "import('../dist/src/cli/claude-sm-danger.js')");
+  fileContains('bin/codex-sm', "../dist/src/cli/codex-sm.js");
+  fileContains('bin/codex-smd', "../dist/src/cli/codex-sm-danger.js");
+  fileContains('bin/claude-sm', "../dist/src/cli/claude-sm.js");
+  fileContains('bin/claude-smd', "../dist/src/cli/claude-sm-danger.js");
+  fileContains('bin/hermes-sm', "../dist/src/cli/hermes-sm.js");
+  fileContains('bin/hermes-smd', "../dist/src/cli/hermes-sm.js");
+  fileContains('bin/opencode-sm', "../dist/src/cli/opencode-sm.js");
+  fileContains('bin/gemini-sm', "../dist/src/cli/gemini-sm.js");
 
   // 3) package.json scripts point to correct paths
   try {

src/cli/commands/scaffold.ts

@@ -21,7 +21,9 @@ const TEMPLATES: Record<string, string> = {
   'company/design.md':
     '---\nname: Design System\ndescription: Logos, colors, components\n---\n\n# Design System\n\n## Colors\n- Primary:\n- Secondary:\n\n## Logos\n- [paths or URLs]\n',
   'wiki/README.md':
-    '# Wiki — SOPs & Playbooks\n\nAdd markdown files here. Files with skill frontmatter become Claude skills.\n',
+    '# Wiki — SOPs & Playbooks\n\nAdd markdown files here. Files with skill frontmatter become Claude skills.\n\nSOPs should follow the Company OS schema:\n\n- `## Objective`\n- `## Procedure`\n- `## Verification`\n- `## Non-compliance`\n\nEach SOP must reference a PROSE Expectation from `docs/specs/COMPANY-OS-PROSE.md`.\n',
+  'wiki/SOP-301-onboarding.md':
+    '# SOP-301 New Hire Onboarding\n\n**Owner:** People Ops  \n**Status:** Active  \n**Related PROSE Expectation:** [E.1 Onboarding completeness](../docs/specs/COMPANY-OS-PROSE.md#e1-onboarding-completeness)\n\n## Objective\nEnsure every new hire has accounts, hardware, and access documented before their start date.\n\n## Procedure\n\n1. **Pre-start checklist (5 days before)**\n   - Hiring manager opens an onboarding ticket.\n   - People Ops confirms laptop requirement and shipping address.\n\n2. **Account provisioning (3 days before)**\n   - IT creates SSO account and adds the hire to default groups.\n   - People Ops sends welcome email with first-week schedule.\n\n3. **Access verification (1 day before)**\n   - Hiring manager verifies the hire can log in to primary systems.\n\n## Verification\n\n- Run audit: `stackmemory company-os audit onboarding`\n- Expected result: 100% of hires in last 30 days have completed checklist.\n\n## Non-compliance\n\nOnboarding missing SSO access or hardware assignment on start date is non-compliant.\n',
   'skills/README.md':
     '# Skills\n\nClaude skill-packs. Each file is a markdown instruction set with frontmatter.\n\n```yaml\n---\nname: skill-name\ndescription: What this skill does\nactivates_on: [keyword1, keyword2]\nversion: "1.0"\n---\n```\n',
   'clients/README.md':

src/core/wiki/wiki-compiler.ts

@@ -106,6 +106,7 @@ export class WikiCompiler {
     concepts: string;
     sources: string;
     synthesis: string;
+    sops: string;
   };
 
   constructor(config: WikiConfig) {
@@ -121,6 +122,7 @@ export class WikiCompiler {
       concepts: join(this.config.wikiDir, 'concepts'),
       sources: join(this.config.wikiDir, 'sources'),
       synthesis: join(this.config.wikiDir, 'synthesis'),
+      sops: join(this.config.wikiDir, 'sops'),
     };
   }
 
@@ -208,6 +210,10 @@ export class WikiCompiler {
       created.push(path);
     }
 
+    // 6. Derived Company OS SOPs from anchors
+    const derivedSops = this.generateDerivedSops(ctx.anchors);
+    created.push(...derivedSops);
+
     this.updateIndex();
     this.appendLog(
       `## [${new Date().toISOString().slice(0, 10)}] create | full wiki`,
@@ -312,6 +318,10 @@ export class WikiCompiler {
       else created.push(path);
     }
 
+    // 6. Derived Company OS SOPs from anchors
+    const derivedSops = this.generateDerivedSops(ctx.anchors);
+    created.push(...derivedSops);
+
     if (created.length > 0 || updated.length > 0) {
       this.updateIndex();
       this.appendLog(
@@ -765,6 +775,12 @@ export class WikiCompiler {
         f.endsWith('.md')
       ).length;
     }
+    // Backfill categories that may not exist yet
+    byCategory['entities'] ??= 0;
+    byCategory['concepts'] ??= 0;
+    byCategory['sources'] ??= 0;
+    byCategory['synthesis'] ??= 0;
+    byCategory['sops'] ??= 0;
 
     const logPath = join(this.dirs.root, 'log.md');
     let lastCompile: string | null = null;
@@ -1152,6 +1168,117 @@ export class WikiCompiler {
     return groups;
   }
 
+  /**
+   * Derive Company OS SOPs from recurring frame anchors.
+   * Creates lightweight SOP drafts in wiki/sops/ for DECISION, CONSTRAINT, RISK, FACT anchors.
+   */
+  private generateDerivedSops(anchors: AnchorRow[]): string[] {
+    const created: string[] = [];
+    const derivedConfig: Array<{
+      type: string;
+      id: number;
+      name: string;
+      proseId: string;
+      objective: string;
+    }> = [
+      {
+        type: 'DECISION',
+        id: 401,
+        name: 'Decision-derived Process',
+        proseId: 'E.9',
+        objective:
+          'Preserve recurring decisions as repeatable guidance so the team does not re-debate settled questions.',
+      },
+      {
+        type: 'CONSTRAINT',
+        id: 402,
+        name: 'Constraint-derived Process',
+        proseId: 'E.10',
+        objective:
+          'Preserve recurring constraints as repeatable guidance so the team respects known boundaries.',
+      },
+      {
+        type: 'RISK',
+        id: 403,
+        name: 'Risk-derived Process',
+        proseId: 'E.11',
+        objective:
+          'Preserve recurring risks as repeatable guidance so the team mitigates them consistently.',
+      },
+      {
+        type: 'FACT',
+        id: 404,
+        name: 'Fact-derived Process',
+        proseId: 'E.12',
+        objective:
+          'Preserve recurring facts as repeatable guidance so the team operates from shared knowledge.',
+      },
+    ];
+
+    for (const config of derivedConfig) {
+      const typeAnchors = anchors.filter((a) => a.type === config.type);
+      if (typeAnchors.length === 0) continue;
+
+      const path = `sops/SOP-${config.id}-${this.slugify(config.name)}.md`;
+      const items = typeAnchors
+        .slice(-20)
+        .map((a) => {
+          const date = new Date(a.created_at * 1000).toISOString().slice(0, 10);
+          return `- ${a.text} _(observed ${date} in [[sources/${this.slugify(a.frame_name)}]])_`;
+        })
+        .join('\n');
+
+      const article = [
+        '---',
+        `title: "SOP-${config.id} ${config.name}"`,
+        `category: sop`,
+        `derived_from: "${config.type} anchors"`,
+        `created: ${new Date().toISOString()}`,
+        `updated: ${new Date().toISOString()}`,
+        `tags: [sop, derived, ${config.type.toLowerCase()}]`,
+        '---',
+        '',
+        `# SOP-${config.id} ${config.name}`,
+        '',
+        '**Owner:** Derived from frame anchors  ',
+        '**Status:** Active  ',
+        `**Related PROSE Expectation:** [${config.proseId} ${config.name}](../../docs/specs/COMPANY-OS-PROSE.md)`,
+        '',
+        '## Objective',
+        config.objective,
+        '',
+        '## Procedure',
+        '',
+        `1. **Review**`,
+        `   - Review the latest ${config.type} anchors below before taking action.`,
+        '',
+        `2. **Apply**`,
+        `   - Treat these ${config.type.toLowerCase()}s as guidance for current and future work.`,
+        '',
+        `3. **Update**`,
+        `   - When a ${config.type.toLowerCase()} changes, record the new state in a frame so this SOP can be regenerated.`,
+        '',
+        '## Verification',
+        '',
+        `- Run \`stackmemory company-os audit ${config.type.toLowerCase()}-derived\``,
+        `- Expected result: the derived ${config.type.toLowerCase()}s below are reflected in current work.`,
+        '',
+        '### Derived anchors',
+        `${items}`,
+        '',
+        '## Non-compliance',
+        '',
+        `Ignoring or overriding these ${config.type.toLowerCase()}s without a new recorded decision is non-compliant.`,
+        '',
+      ].join('\n');
+
+      this.writeArticle(path, article);
+      created.push(path);
+    }
+
+    return created;
+  }
+
   // ── Reading helpers ──
 
   private readExistingSources(): Array<{ title: string; path: string }> {