feat: v0.8.0 — classifier QA fix, routing trace, cold-start UX (#39-#46) (#49)

* fix(security): remove shell injection surface and block directory traversal

Closes #43: Remove shell: true from runGit() in git-helpers.ts. Node.js
resolves the git binary via PATH directly without a shell on WSL, Linux,
macOS, and Windows. shell: true is unnecessary and allows shell metacharacters
in args to be interpreted as shell syntax.

Closes #42: Validate module paths in adf create before path.join. Paths
containing ".." or absolute paths are rejected with a clear error. A secondary
resolved-path check confirms the final path stays within the .ai/ directory,
guarding against platform-specific bypass patterns.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(adf): populate command, unknown-op error clarity, CONTEXT scaffold section

charter adf populate [--dry-run] [--force] [--ai-dir <dir>]
  Reads package.json, README.md, and stack detection signals to auto-fill
  ADF files with project-specific content after charter adf init. Populates
  CONTEXT in core/backend/frontend.adf and STATE in state.adf. Idempotent:
  skips files with non-scaffold content unless --force.

patcher: unknown ops now produce a clear error listing valid op names
  instead of the cryptic "handlers[op.op] is not a function" TypeError.

CORE_SCAFFOLD: add a CONTEXT section placeholder so ADD_BULLET
  section:CONTEXT works immediately after adf init without requiring
  ADD_SECTION first.

adf patch help: list all valid ops with concrete usage examples.

bootstrap/init next steps: point to charter adf populate as step 1
  instead of generic "edit core.adf manually" guidance.

harness: extend SDLC corpus and runner with mixed QA/backend signal
  scenarios that exposed the classifier routing issues filed in #44/#45.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(classifier): QA phrase override, routing trace, tidy --verbose (#44 #45 #46)

- QA compound phrases (smoke test, contract test, schema compat, approval
  gate, verified against, test fixtures) now fire a phrase-level override
  BEFORE keyword scoring so they cannot be outvoted by raw infra/backend
  keyword count (#44, #45)
- contentToModule() returns { module, phraseOverride?, scores } so all
  per-module candidate scores are visible to callers (#46)
- ClassificationResult gains optional routingTrace?: RoutingTrace with
  headingModule, phraseOverride, and candidateScores for debugging
- adf tidy --verbose prints per-item routing rationale (module, section,
  trigger scores or phrase override) (#46)
- 9 new tests covering phrase override routing, guard against absent
  qa.adf in triggerMap, and routingTrace shape (#44 #45 #46)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(cold-start): migrate --keep-summary, migrate --audit, doctor sparse-pointer warn (#39 #40 #41)

- adf migrate --keep-summary: injects auto-generated "## Architecture
  Summary" block listing migrated module names and section counts so
  CLAUDE.md thin pointer gives agents architectural orientation without
  duplicating rules (#39)
- adf migrate --audit: prints per-module breakdown (constraints/context/
  advisory counts) and flags potential misroutes via routingTrace — items
  routed to core.adf that scored non-zero for a specialized module (#40)
- doctor: adds 'INFO' status tier (soft, does not fail overall check);
  warns [info] when thin-pointer CLAUDE.md has <15 lines and no
  stack/framework keywords — agents have zero orientation, suggests
  charter adf populate (#41)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: bump to v0.8.0

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Kevin Overmier <kovermier@gmail.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

harness/adf-inspector.ts

@@ -120,6 +120,9 @@ export function printSnapshot(snapshot: AdfSnapshot, previous?: AdfSnapshot): vo
 export function detectAccumulationIssues(snapshots: AdfSnapshot[]): string[] {
   const issues: string[] = [];
   if (snapshots.length < 2) return issues;
+  const MIN_ABSOLUTE_GROWTH = 10;
+  const MIN_BASELINE_ITEMS = 3;
+  const MAX_SECTION_ITEMS = 20;
 
   const first = snapshots[0];
   const last = snapshots[snapshots.length - 1];
@@ -131,13 +134,13 @@ export function detectAccumulationIssues(snapshots: AdfSnapshot[]): string[] {
     const growth = mod.totalItems - start.totalItems;
     const growthRate = start.totalItems > 0 ? growth / start.totalItems : growth;
 
-    if (growthRate > 2) {
+    if (growth >= MIN_ABSOLUTE_GROWTH && start.totalItems >= MIN_BASELINE_ITEMS && growthRate > 2) {
       issues.push(`${mod.module}: grew ${growth} items (${(growthRate * 100).toFixed(0)}% increase) — possible accumulation`);
     }
 
     // Check any single section that got very large
     for (const sec of mod.sections) {
-      if (sec.itemCount > 15) {
+      if (sec.itemCount > MAX_SECTION_ITEMS) {
         issues.push(`${mod.module} > ${sec.key}: ${sec.itemCount} items — section may need pruning`);
       }
     }

harness/corpus/sdlc.ts

@@ -0,0 +1,138 @@
+/**
+ * SDLC-focused scenarios — validate that ADF modules stay updated and portable
+ * as project guidance evolves from requirements through release.
+ */
+
+import type { Scenario } from '../types';
+
+export const sdlcScenarios: Scenario[] = [
+  {
+    id: 'fullstack-sdlc-handoff-portability',
+    archetype: 'fullstack',
+    description: 'Rules evolve across SDLC phases while remaining portable through ADF modules',
+    manifest: {
+      onDemand: [
+        { path: 'frontend.adf', triggers: ['react', 'component', 'ui', 'css', 'vite', 'tsx'] },
+        { path: 'backend.adf', triggers: ['api', 'endpoint', 'route', 'handler', 'database', 'auth', 'zod', 'request', 'response'] },
+        { path: 'infra.adf', triggers: ['deploy', 'release', 'rollback', 'ci', 'pipeline', 'docker', 'env', 'artifact'] },
+        { path: 'qa.adf', triggers: ['test', 'testing', 'playwright', 'contract', 'smoke', 'verification', 'evidence', 'auditability'] },
+      ],
+    },
+    sessions: [
+      {
+        label: 'session-1: requirements',
+        inject: `
+## API Requirements
+
+- Every API endpoint must publish request and response schemas
+- Auth is required for all write endpoints
+- Route handlers must return structured error codes
+- Database migrations must be reviewed before merge
+`,
+        expected: { 'backend.adf': 4 },
+      },
+      {
+        label: 'session-2: design',
+        inject: `
+## System Design
+
+- React UI components must map one-to-one to approved design tokens
+- API handlers must validate all payloads with Zod
+- Route naming must stay stable across versions
+- Frontend component props must be typed in TSX files
+`,
+        expected: { 'frontend.adf': 2, 'backend.adf': 2 },
+      },
+      {
+        label: 'session-3: implementation',
+        inject: `
+## Implementation Rules
+
+- API route files live under \`app/api/\` and use one handler per endpoint
+- Database writes must run inside transactions
+- Auth checks execute before any handler business logic
+- Build artifacts are generated only in CI pipeline jobs
+`,
+        expected: { 'backend.adf': 3, 'infra.adf': 1 },
+      },
+      {
+        label: 'session-4: verification',
+        inject: `
+## Verification
+
+- CI pipeline must run unit, integration, and Playwright suites on every PR
+- API contract tests validate request and response schema compatibility
+- Deploy preview environments must run smoke checks before approval
+- Test artifacts are uploaded from CI for auditability
+`,
+        expected: { 'qa.adf': 4 },
+      },
+      {
+        label: 'session-5: release and portability handoff',
+        inject: `
+## Release Handoff
+
+- Deploy jobs must consume versioned artifacts from the pipeline only
+- Rollback instructions must be validated in staging before production release
+- Environment configuration uses env keys defined in the deployment checklist
+- Release evidence includes CI run ID, artifact hash, and deployment timestamp
+`,
+        expected: { 'infra.adf': 4 },
+      },
+    ],
+  },
+  {
+    id: 'fullstack-sdlc-generic-checklist-routing',
+    archetype: 'fullstack',
+    description: 'Generic SDLC handoff headings still separate verification evidence from release operations',
+    manifest: {
+      onDemand: [
+        { path: 'frontend.adf', triggers: ['react', 'component', 'ui', 'css', 'vite', 'tsx'] },
+        { path: 'backend.adf', triggers: ['api', 'endpoint', 'route', 'handler', 'database', 'auth', 'zod', 'request', 'response'] },
+        { path: 'infra.adf', triggers: ['deploy', 'release', 'rollback', 'ci', 'pipeline', 'docker', 'env', 'artifact'] },
+        { path: 'qa.adf', triggers: ['test', 'testing', 'playwright', 'contract', 'smoke', 'verification', 'evidence', 'auditability'] },
+      ],
+    },
+    sessions: [
+      {
+        label: 'session-1: generic checklist handoff',
+        inject: `
+## Checklist
+
+- Playwright smoke tests must pass before release approval
+- Contract test evidence is attached to the deployment record for auditability
+- Release artifact hashes are recorded before deploy starts
+- Rollback drills must use the staged deploy artifact from the pipeline
+`,
+        expected: { 'qa.adf': 2, 'infra.adf': 2 },
+      },
+    ],
+  },
+  {
+    id: 'fullstack-sdlc-mixed-qa-backend-signals',
+    archetype: 'fullstack',
+    description: 'Mixed backend and QA wording in a generic checklist should still route by dominant verification vs API intent',
+    manifest: {
+      onDemand: [
+        { path: 'frontend.adf', triggers: ['react', 'component', 'ui', 'css', 'vite', 'tsx'] },
+        { path: 'backend.adf', triggers: ['api', 'endpoint', 'route', 'handler', 'database', 'auth', 'zod', 'request', 'response'] },
+        { path: 'infra.adf', triggers: ['deploy', 'release', 'rollback', 'ci', 'pipeline', 'docker', 'env', 'artifact'] },
+        { path: 'qa.adf', triggers: ['test', 'testing', 'playwright', 'contract', 'smoke', 'verification', 'evidence', 'auditability'] },
+      ],
+    },
+    sessions: [
+      {
+        label: 'session-1: mixed checklist bullets',
+        inject: `
+## Checklist
+
+- API contract test evidence must be attached to the release review for auditability
+- Request and response schema contract tests must pass before merging backend changes
+- Endpoint smoke tests run in CI before deploy approval
+- API handler error responses are verified against contract fixtures
+`,
+        expected: { 'qa.adf': 3, 'backend.adf': 1 },
+      },
+    ],
+  },
+];

harness/runner.ts

@@ -21,7 +21,8 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { execFileSync } from 'node:child_process';
 
-import type { Scenario, TidyOutput, ScenarioResult, HarnessReport } from './types';
+import { buildMigrationPlan, parseMarkdownSections, type TriggerMap } from '../packages/adf/src';
+import type { Scenario, TidyOutput, ScenarioResult, HarnessReport, StaticSessionAudit, StaticItemRoute } from './types';
 import { evaluateSession, printSessionResult } from './evaluator';
 import { generateScenarios, getArchetypeManifest } from './ollama';
 import { REAL_REPOS } from './corpus/real-repos';
@@ -31,6 +32,7 @@ import { workerScenarios } from './corpus/worker';
 import { backendScenarios } from './corpus/backend';
 import { fullstackScenarios } from './corpus/fullstack';
 import { edgeCaseScenarios } from './corpus/edge-cases';
+import { sdlcScenarios } from './corpus/sdlc';
 
 // ============================================================================
 // Config
@@ -44,6 +46,7 @@ const ALL_STATIC: Scenario[] = [
   ...backendScenarios,
   ...fullstackScenarios,
   ...edgeCaseScenarios,
+  ...sdlcScenarios,
 ];
 
 const OLLAMA_ARCHETYPES = ['worker', 'backend', 'fullstack'];
@@ -158,7 +161,12 @@ function runTidy(repoDir: string, dryRun = true): TidyOutput {
 function runStaticScenario(scenario: Scenario): ScenarioResult {
   const tmp = makeTempRepo(scenario);
   const sessionResults = [];
+  const sessionAudits: StaticSessionAudit[] = [];
+  const snapshots: AdfSnapshot[] = [];
+  let prevSnapshot: AdfSnapshot | undefined;
   let scenarioPass = true;
+  const baseClaude = THIN_POINTER.trim();
+  const aiDir = path.join(tmp, '.ai');
 
   for (const session of scenario.sessions) {
     // Each session: inject onto thin pointer, dry-run to evaluate, then apply
@@ -173,18 +181,123 @@ function runStaticScenario(scenario: Scenario): ScenarioResult {
 
     // Apply tidy (non-dry-run) to route content into ADF modules, restoring
     // CLAUDE.md to thin pointer so the next session sees a clean baseline.
-    runTidy(tmp, false);
+    const applyOutput = runTidy(tmp, false);
+
+    const postClaude = fs.readFileSync(path.join(tmp, 'CLAUDE.md'), 'utf-8').trim();
+    const claudeRestored = postClaude === baseClaude;
+    if (!claudeRestored) {
+      scenarioPass = false;
+      console.log('      portability warning: CLAUDE.md was not restored to thin pointer state');
+    }
+
+    const snapshot = inspectAdfModules(aiDir, session.label, prevSnapshot);
+    snapshots.push(snapshot);
+    prevSnapshot = snapshot;
+    const itemRoutes = previewItemRoutes(session.inject, scenario);
+
+    sessionAudits.push({
+      sessionLabel: session.label,
+      dryRunExtracted: tidyOutput.totalExtracted,
+      appliedModulesModified: applyOutput.modulesModified,
+      claudeRestored,
+      adfTotalItems: snapshot.totalItemsAcrossAllModules,
+      modulesGrew: snapshot.grew,
+      itemRoutes,
+    });
+
+    if (!sessionResult.pass) {
+      console.log('      item routing preview:');
+      for (const item of itemRoutes) {
+        const matches = item.matchedTriggers.length > 0 ? ` | matches=${item.matchedTriggers.join(', ')} score=${item.matchScore}` : '';
+        console.log(`        [${item.heading || 'preamble'} -> ${item.headingModule}] ${item.targetModule} (${item.targetSection}) :: ${item.content}${matches}`);
+      }
+    }
+  }
+
+  const accumulationIssues = detectAccumulationIssues(snapshots);
+  if (accumulationIssues.length > 0) {
+    console.log('      accumulation warnings:');
+    for (const issue of accumulationIssues) console.log(`        - ${issue}`);
   }
 
   return {
     scenarioId: scenario.id,
     archetype: scenario.archetype,
     description: scenario.description,
     sessions: sessionResults,
+    staticAudit: {
+      sessions: sessionAudits,
+      accumulationIssues,
+    },
     pass: scenarioPass,
   };
 }
 
+function previewItemRoutes(inject: string, scenario: Scenario): StaticItemRoute[] {
+  const triggerMap: TriggerMap = {};
+  for (const entry of scenario.manifest.onDemand) {
+    if (entry.triggers.length > 0) {
+      triggerMap[entry.path] = entry.triggers.map(trigger => trigger.toLowerCase());
+    }
+  }
+
+  const sections = parseMarkdownSections(inject);
+  const plan = buildMigrationPlan(sections, undefined, triggerMap);
+
+  return plan.items.map(item => ({
+    heading: item.sourceHeading,
+    content: item.element.content,
+    headingModule: previewHeadingModule(item.sourceHeading),
+    targetModule: item.classification.targetModule,
+    targetSection: item.classification.targetSection,
+    decision: item.classification.decision,
+    reason: item.classification.reason,
+    ...scoreItemAgainstTriggers(item.element.content, triggerMap),
+  }));
+}
+
+function previewHeadingModule(heading: string): string {
+  const lower = heading.toLowerCase();
+  if (/\b(design.system|ui|frontend|css|component|react|vue|svelte|next|nextjs|tailwind|shadcn|radix|storybook|vite|vitest|playwright|remix|nuxt|astro)\b/.test(lower)) {
+    return 'frontend.adf';
+  }
+  if (/\b(qa|quality|test|testing|verification|validate|validation|contract|smoke|evidence|audit)\b/.test(lower)) {
+    return 'qa.adf';
+  }
+  if (/\b(auth|authentication|authorization|security|secret|token|permission|cors|rate.limit|jwt|oauth|clerk|nextauth|lucia|session|cookie|csrf|xss|password|bcrypt)\b/.test(lower)) {
+    return 'security.adf';
+  }
+  if (/\b(deploy|deployment|infrastructure|infra|ci|cd|pipeline|config|configuration|environment|env|docker|wrangler|cloudflare|vercel|netlify|railway|fly|render|github.actions|kv|d1|r2|queue|durable.object)\b/.test(lower)) {
+    return 'infra.adf';
+  }
+  if (/\b(api|backend|server|database|db|endpoint|query|migration|handler|prisma|drizzle|mongoose|postgres|postgresql|mysql|sqlite|express|fastify|hono|trpc|zod|graphql)\b/.test(lower)) {
+    return 'backend.adf';
+  }
+  return 'core.adf';
+}
+
+function scoreItemAgainstTriggers(text: string, triggerMap: TriggerMap): Pick<StaticItemRoute, 'matchedTriggers' | 'matchScore'> {
+  const lower = text.toLowerCase();
+  let matchedTriggers: string[] = [];
+  let matchScore = 0;
+
+  for (const triggers of Object.values(triggerMap)) {
+    const currentMatches = triggers.filter(trigger =>
+      new RegExp(`\\b${escapeRegex(trigger)}(?:s|ed|ing|ment|tion|ity|ication)?\\b`, 'i').test(lower),
+    );
+    if (currentMatches.length > matchScore) {
+      matchedTriggers = currentMatches;
+      matchScore = currentMatches.length;
+    }
+  }
+
+  return { matchedTriggers, matchScore };
+}
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 // ============================================================================
 // Ollama Scenario Runner (exploratory — no expected routing)
 // ============================================================================

harness/types.ts

@@ -87,9 +87,37 @@ export interface ScenarioResult {
   archetype: string;
   description: string;
   sessions: SessionResult[];
+  staticAudit?: StaticScenarioAudit;
   pass: boolean;
 }
 
+export interface StaticSessionAudit {
+  sessionLabel: string;
+  dryRunExtracted: number;
+  appliedModulesModified: string[];
+  claudeRestored: boolean;
+  adfTotalItems: number;
+  modulesGrew: string[];
+  itemRoutes: StaticItemRoute[];
+}
+
+export interface StaticScenarioAudit {
+  sessions: StaticSessionAudit[];
+  accumulationIssues: string[];
+}
+
+export interface StaticItemRoute {
+  heading: string;
+  content: string;
+  headingModule: string;
+  targetModule: string;
+  targetSection: string;
+  decision: 'STAY' | 'MIGRATE';
+  reason: string;
+  matchedTriggers: string[];
+  matchScore: number;
+}
+
 // ============================================================================
 // Run Report
 // ============================================================================

package.json

@@ -42,5 +42,6 @@
     "typescript": "~5.8.2",
     "vitest": "^4.0.18",
     "zod": "^3.24.1"
-  }
+  },
+  "version": "0.8.0"
 }

packages/adf/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stackbilt/adf",
   "sideEffects": false,
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "ADF (Attention-Directed Format) — AST-backed context format for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",