From 0f2916e827a2ba118d9efeb2fbadfb36a56cbdb7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 08:44:16 +0800 Subject: [PATCH 01/19] feat: add persistent shadow maturity evidence store --- src/evolution/RuleMaturityStore.ts | 113 +++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 src/evolution/RuleMaturityStore.ts diff --git a/src/evolution/RuleMaturityStore.ts b/src/evolution/RuleMaturityStore.ts new file mode 100644 index 00000000..296ad100 --- /dev/null +++ b/src/evolution/RuleMaturityStore.ts @@ -0,0 +1,113 @@ +import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs' +import { join, resolve } from 'node:path' +import { + createShadowRuleMaturity, + evaluateRulePromotion, + recordShadowHit, + type RuleMaturityRecord, + type RulePromotionDecision, + type RulePromotionThresholds, +} from './RuleMaturity.js' + +export interface PersistentRuleMaturityStoreOptions { + projectDir?: string + scaleDir?: string +} + +function safeId(value: string): string { + const id = value.trim() + if (!id || id === '.' || id === '..' || !/^[a-zA-Z0-9._-]+$/.test(id)) { + throw new Error('Invalid rule maturity id') + } + return id +} + +function readRecord(path: string): RuleMaturityRecord | null { + if (!existsSync(path)) return null + try { + return JSON.parse(readFileSync(path, 'utf-8')) as RuleMaturityRecord + } catch { + throw new Error(`Invalid rule maturity record: ${path}`) + } +} + +/** + * Persistent evidence ledger for non-blocking Shadow rules. + * It records observations and eligibility only; it never writes hooks or policies. + */ +export class PersistentRuleMaturityStore { + readonly projectDir: string + readonly recordsDir: string + + constructor(options: PersistentRuleMaturityStoreOptions = {}) { + this.projectDir = resolve(options.projectDir ?? process.cwd()) + const scaleDir = resolve(options.scaleDir ?? join(this.projectDir, '.scale')) + this.recordsDir = join(scaleDir, 'evals', 'rule-maturity') + } + + private recordPath(ruleId: string): string { + return join(this.recordsDir, `${safeId(ruleId)}.json`) + } + + get(ruleId: string): RuleMaturityRecord | null { + return readRecord(this.recordPath(ruleId)) + } + + list(): RuleMaturityRecord[] { + if (!existsSync(this.recordsDir)) return [] + return readdirSync(this.recordsDir) + .filter(file => file.endsWith('.json')) + .map(file => readRecord(join(this.recordsDir, file))) + .filter((record): record is RuleMaturityRecord => Boolean(record)) + .sort((a, b) => b.updatedAt - a.updatedAt) + } + + create(input: { ruleId: string; rollback: string; defectEvidenceIds: string[] }): RuleMaturityRecord { + const ruleId = safeId(input.ruleId) + if (!input.rollback.trim()) throw new Error('A rollback method is required') + if (!input.defectEvidenceIds.length || input.defectEvidenceIds.some(id => !id.trim())) { + throw new Error('At least one defect evidence id is required') + } + mkdirSync(this.recordsDir, { recursive: true }) + const path = this.recordPath(ruleId) + if (existsSync(path)) throw new Error(`Shadow maturity record already exists: ${ruleId}`) + const record = createShadowRuleMaturity({ + ruleId, + rollback: input.rollback.trim(), + defectEvidenceIds: input.defectEvidenceIds, + }) + this.write(record) + return record + } + + recordHit(input: { ruleId: string; evidenceId: string; falsePositive?: boolean; now?: number }): RuleMaturityRecord { + const current = this.get(input.ruleId) + if (!current) throw new Error(`Shadow maturity record not found: ${input.ruleId}`) + const evidenceId = input.evidenceId.trim() + if (!evidenceId) throw new Error('A unique shadow evidence id is required') + if (current.evidenceIds.includes(evidenceId)) { + throw new Error(`Shadow evidence already recorded: ${evidenceId}`) + } + const updated = recordShadowHit(current, { + evidenceId, + falsePositive: input.falsePositive, + now: input.now, + }) + this.write(updated) + return updated + } + + evaluate(ruleId: string, thresholds: RulePromotionThresholds = {}): RulePromotionDecision { + const record = this.get(ruleId) + if (!record) throw new Error(`Shadow maturity record not found: ${ruleId}`) + return evaluateRulePromotion(record, thresholds) + } + + private write(record: RuleMaturityRecord): void { + mkdirSync(this.recordsDir, { recursive: true }) + const path = this.recordPath(record.ruleId) + const temporary = `${path}.${process.pid}.${record.updatedAt}.tmp` + writeFileSync(temporary, JSON.stringify(record, null, 2), { encoding: 'utf-8', flag: 'wx' }) + renameSync(temporary, path) + } +} From af4b7deaa0a6b6df5cca923f2d72746d80824db6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 08:44:47 +0800 Subject: [PATCH 02/19] feat: add persistent shadow evidence CLI --- src/cli/evalCommands.ts | 114 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) diff --git a/src/cli/evalCommands.ts b/src/cli/evalCommands.ts index 28dcddb0..e47fc58e 100644 --- a/src/cli/evalCommands.ts +++ b/src/cli/evalCommands.ts @@ -11,6 +11,7 @@ import { runWorkflowEvalSuite, } from '../eval/WorkflowEval.js' import { createBenchmarkFromWorkflowEval, publishBenchmark } from '../eval/BenchmarkPublisher.js' +import { PersistentRuleMaturityStore } from '../evolution/RuleMaturityStore.js' import { runGoldenSuite, type GoldenSuite } from '../eval/GoldenEval.js' import { PROJECT_DIR, isTruthyFlag, resolveScaleDirForProject } from './engineBootstrap.js' import { SCALE_ENGINE_VERSION } from '../version.js' @@ -323,6 +324,115 @@ const evalReviewImprovement = defineCommand({ }, }) +const evalShadowInit = defineCommand({ + meta: { name: 'shadow-init', description: 'Create a persistent non-blocking Shadow maturity record from an accepted improvement' }, + args: { + id: { type: 'positional', required: true, description: 'Accepted improvement candidate id' }, + rollback: { type: 'string', required: true, description: 'Documented rollback procedure' }, + dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' }, + json: { type: 'boolean', default: false }, + }, + run({ args }) { + const projectDir = resolve(String(args.dir ?? PROJECT_DIR)) + const scaleDir = resolveScaleDirForProject(projectDir) + const evalStore = new WorkflowEvalStore({ projectDir, scaleDir }) + const candidate = evalStore.getImprovement(String(args.id)) + if (!candidate) throw new Error(`Workflow improvement candidate not found: ${String(args.id)}`) + if (candidate.status !== 'accepted') { + throw new Error('Only an accepted improvement candidate can enter Shadow maturity tracking') + } + const store = new PersistentRuleMaturityStore({ projectDir, scaleDir }) + const record = store.create({ + ruleId: candidate.id, + rollback: String(args.rollback), + defectEvidenceIds: [candidate.failureId], + }) + if (args.json) { + console.log(JSON.stringify({ record, note: 'Evidence tracking only; no replay executed and no production policy or hook changed.' }, null, 2)) + return + } + console.log(`Shadow maturity record created: ${record.ruleId}`) + console.log(' Stage: shadow (non-blocking)') + console.log(' Replay: not executed; submit observed evidence with shadow-hit') + console.log(' Production policies and hooks were not modified.') + }, +}) + +const evalShadowHit = defineCommand({ + meta: { name: 'shadow-hit', description: 'Record one externally observed Shadow evaluation with unique evidence' }, + args: { + id: { type: 'positional', required: true, description: 'Shadow rule id (improvement candidate id)' }, + 'evidence-id': { type: 'string', required: true, description: 'Unique evidence artifact id' }, + 'false-positive': { type: 'boolean', default: false, description: 'Mark this observation as a false positive' }, + dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' }, + json: { type: 'boolean', default: false }, + }, + run({ args }) { + const projectDir = resolve(String(args.dir ?? PROJECT_DIR)) + const scaleDir = resolveScaleDirForProject(projectDir) + const store = new PersistentRuleMaturityStore({ projectDir, scaleDir }) + const record = store.recordHit({ + ruleId: String(args.id), + evidenceId: String(args['evidence-id']), + falsePositive: Boolean(args['false-positive']), + }) + if (args.json) { + console.log(JSON.stringify(record, null, 2)) + return + } + console.log(`Shadow evidence recorded: ${record.ruleId}`) + console.log(` Hits: ${record.shadowHits}`) + console.log(` False positives: ${record.falsePositiveCount}`) + }, +}) + +const evalShadowStatus = defineCommand({ + meta: { name: 'shadow-status', description: 'Show persistent Shadow maturity evidence' }, + args: { + id: { type: 'positional', required: true, description: 'Shadow rule id' }, + dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' }, + json: { type: 'boolean', default: false }, + }, + run({ args }) { + const projectDir = resolve(String(args.dir ?? PROJECT_DIR)) + const store = new PersistentRuleMaturityStore({ projectDir, scaleDir: resolveScaleDirForProject(projectDir) }) + const record = store.get(String(args.id)) + if (!record) throw new Error(`Shadow maturity record not found: ${String(args.id)}`) + if (args.json) { + console.log(JSON.stringify(record, null, 2)) + return + } + console.log(`Shadow maturity: ${record.ruleId}`) + console.log(` Stage: ${record.stage}`) + console.log(` Hits: ${record.shadowHits}`) + console.log(` False positives: ${record.falsePositiveCount}`) + console.log(` Evidence ids: ${record.evidenceIds.join(', ') || '(none)'}`) + console.log(` Rollback: ${record.rollback}`) + }, +}) + +const evalShadowEvaluate = defineCommand({ + meta: { name: 'shadow-evaluate', description: 'Evaluate Shadow evidence against rule maturity thresholds without promoting a rule' }, + args: { + id: { type: 'positional', required: true, description: 'Shadow rule id' }, + dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' }, + json: { type: 'boolean', default: false }, + }, + run({ args }) { + const projectDir = resolve(String(args.dir ?? PROJECT_DIR)) + const store = new PersistentRuleMaturityStore({ projectDir, scaleDir: resolveScaleDirForProject(projectDir) }) + const decision = store.evaluate(String(args.id)) + if (args.json) { + console.log(JSON.stringify({ ...decision, note: 'Eligibility only; no stage promotion, hook generation, or production policy change.' }, null, 2)) + return + } + console.log(`Shadow maturity eligible: ${decision.eligible ? 'yes' : 'no'}`) + console.log(` Next review stage: ${decision.nextStage}`) + for (const blocker of decision.blockers) console.log(` Blocker: ${blocker}`) + console.log(' No stage promotion or production policy change was performed.') + }, +}) + const evalGolden = defineCommand({ meta: { name: 'golden', description: 'P1-D: run the deterministic golden artifact-contract suite (CI merge gate)' }, args: { @@ -366,6 +476,10 @@ export const evalCommand = defineCommand({ 'promote-failure': evalPromoteFailure, improvements: evalImprovements, 'review-improvement': evalReviewImprovement, + 'shadow-init': evalShadowInit, + 'shadow-hit': evalShadowHit, + 'shadow-status': evalShadowStatus, + 'shadow-evaluate': evalShadowEvaluate, golden: evalGolden, }, }) From 60694b78c13d9b1a4ff6af7eba31b996900d923b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 08:45:11 +0800 Subject: [PATCH 03/19] test: cover persistent shadow maturity evidence --- tests/evolution/ruleMaturityStore.test.ts | 92 +++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 tests/evolution/ruleMaturityStore.test.ts diff --git a/tests/evolution/ruleMaturityStore.test.ts b/tests/evolution/ruleMaturityStore.test.ts new file mode 100644 index 00000000..5115aab6 --- /dev/null +++ b/tests/evolution/ruleMaturityStore.test.ts @@ -0,0 +1,92 @@ +import { mkdtempSync, rmSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { afterEach, describe, expect, it } from 'vitest' +import { PersistentRuleMaturityStore } from '../../src/evolution/RuleMaturityStore.js' + +describe('PersistentRuleMaturityStore', () => { + const roots: string[] = [] + + afterEach(() => { + for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }) + }) + + function createStore() { + const projectDir = mkdtempSync(join(tmpdir(), 'scale-rule-maturity-')) + roots.push(projectDir) + return new PersistentRuleMaturityStore({ projectDir }) + } + + it('persists non-blocking shadow records and evidence across store instances', () => { + const store = createStore() + const created = store.create({ + ruleId: 'IMPROVE-100', + rollback: 'Remove the shadow rule record; no hook has been installed.', + defectEvidenceIds: ['FAILURE-100'], + }) + + expect(created.stage).toBe('shadow') + expect(created.shadowHits).toBe(0) + + const updated = store.recordHit({ + ruleId: 'IMPROVE-100', + evidenceId: 'SHADOW-EVIDENCE-1', + }) + expect(updated.shadowHits).toBe(1) + expect(new PersistentRuleMaturityStore({ projectDir: store.projectDir }).get('IMPROVE-100')) + .toMatchObject({ stage: 'shadow', shadowHits: 1, evidenceIds: ['SHADOW-EVIDENCE-1'] }) + }) + + it('requires unique evidence ids and prevents duplicate observations from inflating hit counts', () => { + const store = createStore() + store.create({ + ruleId: 'IMPROVE-101', + rollback: 'Delete the shadow record.', + defectEvidenceIds: ['FAILURE-101'], + }) + store.recordHit({ ruleId: 'IMPROVE-101', evidenceId: 'SHADOW-EVIDENCE-1' }) + + expect(() => store.recordHit({ + ruleId: 'IMPROVE-101', + evidenceId: 'SHADOW-EVIDENCE-1', + })).toThrow('already recorded') + expect(store.get('IMPROVE-101')?.shadowHits).toBe(1) + }) + + it('evaluates promotion thresholds but never promotes the persisted stage', () => { + const store = createStore() + store.create({ + ruleId: 'IMPROVE-102', + rollback: 'Remove the shadow record.', + defectEvidenceIds: ['FAILURE-102'], + }) + for (let index = 0; index < 10; index++) { + store.recordHit({ + ruleId: 'IMPROVE-102', + evidenceId: `SHADOW-EVIDENCE-${index}`, + falsePositive: index < 2, + }) + } + + expect(store.evaluate('IMPROVE-102')).toMatchObject({ + eligible: true, + nextStage: 'candidate-hook', + blockers: [], + }) + expect(store.get('IMPROVE-102')?.stage).toBe('shadow') + }) + + it('rejects records without rollback and defect evidence', () => { + const store = createStore() + expect(() => store.create({ + ruleId: 'IMPROVE-103', + rollback: ' ', + defectEvidenceIds: ['FAILURE-103'], + })).toThrow('rollback') + expect(() => store.create({ + ruleId: 'IMPROVE-104', + rollback: 'Remove it.', + defectEvidenceIds: [], + })).toThrow('defect evidence') + }) +}) From a1aa58add147e3193342f1846d25eb2c8131a380 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 08:45:36 +0800 Subject: [PATCH 04/19] test: cover shadow evidence CLI lifecycle --- tests/api/workflowEvalCli.test.ts | 39 +++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/tests/api/workflowEvalCli.test.ts b/tests/api/workflowEvalCli.test.ts index 17c996ab..3170216d 100644 --- a/tests/api/workflowEvalCli.test.ts +++ b/tests/api/workflowEvalCli.test.ts @@ -307,6 +307,45 @@ describe('workflow eval CLI', () => { expect(listed.exitCode).toBe(0) expect(parseJson<{ improvements: Array<{ id: string; status: string }> }>(listed.stdout, listed.stderr).improvements) .toEqual(expect.arrayContaining([expect.objectContaining({ id: candidate.id, status: 'accepted' })])) + const shadowInit = await runScale([ + 'eval', 'shadow-init', candidate.id, + '--rollback', 'Remove the shadow maturity record; no hook is installed.', + '--json', + ], scaleDir, projectDir) + expect(shadowInit.exitCode).toBe(0) + expect(parseJson<{ record: { stage: string; ruleId: string } }>(shadowInit.stdout, shadowInit.stderr).record) + .toMatchObject({ stage: 'shadow', ruleId: candidate.id }) + + const shadowHit = await runScale([ + 'eval', 'shadow-hit', candidate.id, + '--evidence-id', 'shadow-observation-001', + '--json', + ], scaleDir, projectDir) + expect(shadowHit.exitCode).toBe(0) + expect(parseJson<{ shadowHits: number; evidenceIds: string[] }>(shadowHit.stdout, shadowHit.stderr)) + .toMatchObject({ shadowHits: 1, evidenceIds: ['shadow-observation-001'] }) + + const duplicateShadowHit = await runScale([ + 'eval', 'shadow-hit', candidate.id, + '--evidence-id', 'shadow-observation-001', + '--json', + ], scaleDir, projectDir) + expect(duplicateShadowHit.exitCode).toBe(1) + expect(`${duplicateShadowHit.stdout}\n${duplicateShadowHit.stderr}`).toContain('already recorded') + + const shadowEvaluation = await runScale([ + 'eval', 'shadow-evaluate', candidate.id, '--json', + ], scaleDir, projectDir) + expect(shadowEvaluation.exitCode).toBe(0) + expect(parseJson<{ eligible: boolean; nextStage: string }>(shadowEvaluation.stdout, shadowEvaluation.stderr)) + .toMatchObject({ eligible: false, nextStage: 'shadow' }) + + const shadowStatus = await runScale([ + 'eval', 'shadow-status', candidate.id, '--json', + ], scaleDir, projectDir) + expect(shadowStatus.exitCode).toBe(0) + expect(parseJson<{ stage: string; shadowHits: number }>(shadowStatus.stdout, shadowStatus.stderr)) + .toMatchObject({ stage: 'shadow', shadowHits: 1 }) expect(readFileSync(policyFixture, 'utf-8')).toBe(policyBefore) }, 120_000) From 11b4a621d8bec954679a8429115e0fb4471762f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 08:46:01 +0800 Subject: [PATCH 05/19] docs: document persistent shadow evidence workflow --- docs/WORKFLOW_EVAL.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/WORKFLOW_EVAL.md b/docs/WORKFLOW_EVAL.md index 55a7bee6..28d95f0c 100644 --- a/docs/WORKFLOW_EVAL.md +++ b/docs/WORKFLOW_EVAL.md @@ -66,6 +66,22 @@ scale eval review-improvement --decision reject --reviewer --rollback "Remove the shadow record; no hook is installed." +scale eval shadow-hit --evidence-id +scale eval shadow-hit --evidence-id --false-positive +scale eval shadow-status --json +scale eval shadow-evaluate --json +``` + +Records persist under `.scale/evals/rule-maturity/`. A shadow hit must reference a unique evidence artifact id; duplicate evidence is rejected rather than inflating hit counts. Evaluation reports threshold eligibility only. Even when eligible, the stored stage remains `shadow`: this workflow does not execute a replay, promote a rule, generate a hook, or modify production policy. Evidence must come from a separately run and reviewable observation; do not use the command itself as proof that replay occurred. + +候选必须先经人工接受,才能初始化非阻断成熟度记录。随后使用唯一证据 ID 记录外部观察结果。重复证据会被拒绝,不能重复累计命中数。记录保存在 `.scale/evals/rule-maturity/`。评估命令只报告是否满足晋级门槛;即使满足,持久化阶段仍保持 `shadow`。这些命令不会执行 Replay、晋级规则、生成 Hook 或修改生产策略。证据必须来自单独执行且可复核的观察,不能把记录命令本身当成 Replay 已运行的证明。 + ## Failure Replay To Memory Failure Replay is local eval evidence first. When a failure pattern is useful for future work, ingest it into Memory Brain as an `incident` candidate: From caaf62e19b452e6f44cc344d2a5583c4c23a03d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 08:46:05 +0800 Subject: [PATCH 06/19] docs: document persistent shadow evidence workflow --- docs/EVOLUTION_SHADOW_MODE.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/EVOLUTION_SHADOW_MODE.md b/docs/EVOLUTION_SHADOW_MODE.md index 7d9cf43a..8f089555 100644 --- a/docs/EVOLUTION_SHADOW_MODE.md +++ b/docs/EVOLUTION_SHADOW_MODE.md @@ -46,6 +46,14 @@ Promotion requires: - `evaluateRulePromotion` - `approveRuleMaturity` +## Persistent Shadow Evidence Ledger + +Accepted workflow improvement candidates can be initialized as persistent, non-blocking maturity records with a documented rollback procedure. Records live under `.scale/evals/rule-maturity/`. Each observed hit requires a unique evidence artifact id; duplicate ids are rejected. False positives are counted against the configured promotion threshold. + +The CLI exposes `shadow-init`, `shadow-hit`, `shadow-status`, and `shadow-evaluate`. These commands record external observations and calculate eligibility only. They do not execute the underlying rule against traffic, run a replay, change the maturity stage, generate hooks, or edit production policies. A passing evaluation reports `candidate-hook` as the next review stage while the persisted record remains `shadow`. + +持久化 Shadow 证据台账支持为已接受的改进候选创建非阻断成熟度记录,并要求提供回滚方案。每次命中必须关联唯一证据 ID;重复 ID 会被拒绝。CLI 仅记录外部观察并计算门槛,不会自动执行规则或 Replay,不会改变成熟度阶段、生成 Hook 或修改生产策略。即使评估通过,也只报告下一审核阶段为 `candidate-hook`,记录本身仍保持 `shadow`。 + ## Hook Boundary `HookGenerator` still requires `rule.approved === true`. From fc6b77fb1cc95ce781a7c368552b1e0c4157befc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 08:48:18 +0800 Subject: [PATCH 07/19] fix: serialize persistent shadow maturity updates --- src/evolution/RuleMaturityStore.ts | 70 ++++++++++++++++++++---------- 1 file changed, 47 insertions(+), 23 deletions(-) diff --git a/src/evolution/RuleMaturityStore.ts b/src/evolution/RuleMaturityStore.ts index 296ad100..fba9fcbf 100644 --- a/src/evolution/RuleMaturityStore.ts +++ b/src/evolution/RuleMaturityStore.ts @@ -1,4 +1,4 @@ -import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs' +import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } import { join, resolve } from 'node:path' import { createShadowRuleMaturity, @@ -68,33 +68,37 @@ export class PersistentRuleMaturityStore { if (!input.defectEvidenceIds.length || input.defectEvidenceIds.some(id => !id.trim())) { throw new Error('At least one defect evidence id is required') } - mkdirSync(this.recordsDir, { recursive: true }) - const path = this.recordPath(ruleId) - if (existsSync(path)) throw new Error(`Shadow maturity record already exists: ${ruleId}`) - const record = createShadowRuleMaturity({ - ruleId, - rollback: input.rollback.trim(), - defectEvidenceIds: input.defectEvidenceIds, + return this.withLock(ruleId, () => { + mkdirSync(this.recordsDir, { recursive: true }) + const path = this.recordPath(ruleId) + if (existsSync(path)) throw new Error(`Shadow maturity record already exists: ${ruleId}`) + const record = createShadowRuleMaturity({ + ruleId, + rollback: input.rollback.trim(), + defectEvidenceIds: input.defectEvidenceIds, + }) + this.write(record) + return record }) - this.write(record) - return record } recordHit(input: { ruleId: string; evidenceId: string; falsePositive?: boolean; now?: number }): RuleMaturityRecord { - const current = this.get(input.ruleId) - if (!current) throw new Error(`Shadow maturity record not found: ${input.ruleId}`) - const evidenceId = input.evidenceId.trim() - if (!evidenceId) throw new Error('A unique shadow evidence id is required') - if (current.evidenceIds.includes(evidenceId)) { - throw new Error(`Shadow evidence already recorded: ${evidenceId}`) - } - const updated = recordShadowHit(current, { - evidenceId, - falsePositive: input.falsePositive, - now: input.now, + return this.withLock(input.ruleId, () => { + const current = this.get(input.ruleId) + if (!current) throw new Error(`Shadow maturity record not found: ${input.ruleId}`) + const evidenceId = input.evidenceId.trim() + if (!evidenceId) throw new Error('A unique shadow evidence id is required') + if (current.evidenceIds.includes(evidenceId)) { + throw new Error(`Shadow evidence already recorded: ${evidenceId}`) + } + const updated = recordShadowHit(current, { + evidenceId, + falsePositive: input.falsePositive, + now: input.now, + }) + this.write(updated) + return updated }) - this.write(updated) - return updated } evaluate(ruleId: string, thresholds: RulePromotionThresholds = {}): RulePromotionDecision { @@ -103,6 +107,26 @@ export class PersistentRuleMaturityStore { return evaluateRulePromotion(record, thresholds) } + private withLock(ruleId: string, operation: () => T): T { + mkdirSync(this.recordsDir, { recursive: true }) + const lockPath = `${this.recordPath(ruleId)}.lock` + let lockFd: number + try { + lockFd = openSync(lockPath, 'wx') + } catch (error) { + if ((error as NodeJS.ErrnoException).code === 'EEXIST') { + throw new Error(`Shadow maturity record is being updated by another process: ${ruleId}`) + } + throw error + } + try { + return operation() + } finally { + closeSync(lockFd) + unlinkSync(lockPath) + } + } + private write(record: RuleMaturityRecord): void { mkdirSync(this.recordsDir, { recursive: true }) const path = this.recordPath(record.ruleId) From 5265806ba911aef9e85a0e6fd863ddea2dadaab8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 08:48:34 +0800 Subject: [PATCH 08/19] test: cover concurrent shadow maturity update lock --- tests/evolution/ruleMaturityStore.test.ts | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/tests/evolution/ruleMaturityStore.test.ts b/tests/evolution/ruleMaturityStore.test.ts index 5115aab6..d26fe996 100644 --- a/tests/evolution/ruleMaturityStore.test.ts +++ b/tests/evolution/ruleMaturityStore.test.ts @@ -1,4 +1,4 @@ -import { mkdtempSync, rmSync } from 'node:fs' +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } import { tmpdir } from 'node:os' import { join } from 'node:path' import { afterEach, describe, expect, it } from 'vitest' @@ -76,6 +76,18 @@ describe('PersistentRuleMaturityStore', () => { expect(store.get('IMPROVE-102')?.stage).toBe('shadow') }) + it('fails closed when another process holds the maturity record lock', () => { + const store = createStore() + mkdirSync(store.recordsDir, { recursive: true }) + writeFileSync(join(store.recordsDir, 'IMPROVE-105.json.lock'), 'locked', 'utf-8') + + expect(() => store.create({ + ruleId: 'IMPROVE-105', + rollback: 'Remove the shadow record.', + defectEvidenceIds: ['FAILURE-105'], + })).toThrow('being updated by another process') + }) + it('rejects records without rollback and defect evidence', () => { const store = createStore() expect(() => store.create({ From 90e8375cd6d06c48a7fa92e0030488bc79448119 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 08:50:45 +0800 Subject: [PATCH 09/19] fix: restore fs module import in shadow evidence store --- src/evolution/RuleMaturityStore.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/evolution/RuleMaturityStore.ts b/src/evolution/RuleMaturityStore.ts index fba9fcbf..d4d75380 100644 --- a/src/evolution/RuleMaturityStore.ts +++ b/src/evolution/RuleMaturityStore.ts @@ -1,4 +1,4 @@ -import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } +import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs' import { join, resolve } from 'node:path' import { createShadowRuleMaturity, From d18558396787bdd6ae93589838b329958f7f7f83 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 09:47:58 +0800 Subject: [PATCH 10/19] fix: correct rule maturity test import syntax --- tests/evolution/ruleMaturityStore.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/evolution/ruleMaturityStore.test.ts b/tests/evolution/ruleMaturityStore.test.ts index d26fe996..b10015bf 100644 --- a/tests/evolution/ruleMaturityStore.test.ts +++ b/tests/evolution/ruleMaturityStore.test.ts @@ -1,4 +1,4 @@ -import { mkdirSync, mkdtempSync, rmSync, writeFileSync } +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs' import { tmpdir } from 'node:os' import { join } from 'node:path' import { afterEach, describe, expect, it } from 'vitest' From ca75dd44f113d5ebc48acadb321c8407aff3eba9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 15:24:59 +0800 Subject: [PATCH 11/19] fix: require source failure evidence before shadow init --- src/cli/evalCommands.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/cli/evalCommands.ts b/src/cli/evalCommands.ts index e47fc58e..bc7fa671 100644 --- a/src/cli/evalCommands.ts +++ b/src/cli/evalCommands.ts @@ -341,6 +341,10 @@ const evalShadowInit = defineCommand({ if (candidate.status !== 'accepted') { throw new Error('Only an accepted improvement candidate can enter Shadow maturity tracking') } + const sourceFailure = evalStore.getFailure(candidate.failureId) + if (!sourceFailure || sourceFailure.id !== candidate.failureId) { + throw new Error(`Source failure evidence is missing or invalid for improvement candidate: ${candidate.id}`) + } const store = new PersistentRuleMaturityStore({ projectDir, scaleDir }) const record = store.create({ ruleId: candidate.id, From 687a5e899e1e5386f40834c78a87ba358ae27f34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 15:25:10 +0800 Subject: [PATCH 12/19] test: reject shadow init without source failure evidence --- tests/api/workflowEvalCli.test.ts | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/tests/api/workflowEvalCli.test.ts b/tests/api/workflowEvalCli.test.ts index 3170216d..5bf8c186 100644 --- a/tests/api/workflowEvalCli.test.ts +++ b/tests/api/workflowEvalCli.test.ts @@ -307,6 +307,18 @@ describe('workflow eval CLI', () => { expect(listed.exitCode).toBe(0) expect(parseJson<{ improvements: Array<{ id: string; status: string }> }>(listed.stdout, listed.stderr).improvements) .toEqual(expect.arrayContaining([expect.objectContaining({ id: candidate.id, status: 'accepted' })])) + const sourceFailureEvidence = readFileSync(candidate.evidencePath, 'utf-8') + rmSync(candidate.evidencePath) + const missingSourceEvidenceInit = await runScale([ + 'eval', 'shadow-init', candidate.id, + '--rollback', 'Remove the shadow maturity record; no hook is installed.', + '--json', + ], scaleDir, projectDir) + expect(missingSourceEvidenceInit.exitCode).toBe(1) + expect(`${missingSourceEvidenceInit.stdout}\\n${missingSourceEvidenceInit.stderr}`) + .toContain('Source failure evidence is missing or invalid') + writeFileSync(candidate.evidencePath, sourceFailureEvidence, 'utf-8') + const shadowInit = await runScale([ 'eval', 'shadow-init', candidate.id, '--rollback', 'Remove the shadow maturity record; no hook is installed.', From 62c5c8b4a08351231fa069683721763c50573da4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 15:25:32 +0800 Subject: [PATCH 13/19] test: normalize failure evidence assertion output --- tests/api/workflowEvalCli.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/api/workflowEvalCli.test.ts b/tests/api/workflowEvalCli.test.ts index 5bf8c186..3d4ae06c 100644 --- a/tests/api/workflowEvalCli.test.ts +++ b/tests/api/workflowEvalCli.test.ts @@ -315,7 +315,7 @@ describe('workflow eval CLI', () => { '--json', ], scaleDir, projectDir) expect(missingSourceEvidenceInit.exitCode).toBe(1) - expect(`${missingSourceEvidenceInit.stdout}\\n${missingSourceEvidenceInit.stderr}`) + expect(`${missingSourceEvidenceInit.stdout}\n${missingSourceEvidenceInit.stderr}`) .toContain('Source failure evidence is missing or invalid') writeFileSync(candidate.evidencePath, sourceFailureEvidence, 'utf-8') From d9e513eea5619c2398095381351cf9399ba5852f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 15:26:54 +0800 Subject: [PATCH 14/19] feat: require hashed in-project shadow evidence artifacts --- src/cli/evalCommands.ts | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/src/cli/evalCommands.ts b/src/cli/evalCommands.ts index bc7fa671..26c73d09 100644 --- a/src/cli/evalCommands.ts +++ b/src/cli/evalCommands.ts @@ -1,9 +1,10 @@ // SCALE Engine — Eval CLI Commands // Extracted from api/cli.ts: workflow eval baseline, failure replay, and comparison commands. +import { createHash } from 'node:crypto' import { defineCommand } from 'citty' -import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs' -import { dirname, resolve } from 'node:path' +import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs' +import { dirname, relative, resolve } from 'node:path' import { WorkflowEvalStore, compareWorkflowEvalRuns, @@ -12,6 +13,7 @@ import { } from '../eval/WorkflowEval.js' import { createBenchmarkFromWorkflowEval, publishBenchmark } from '../eval/BenchmarkPublisher.js' import { PersistentRuleMaturityStore } from '../evolution/RuleMaturityStore.js' +import { resolvePathWithinRoots } from '../core/pathSafety.js' import { runGoldenSuite, type GoldenSuite } from '../eval/GoldenEval.js' import { PROJECT_DIR, isTruthyFlag, resolveScaleDirForProject } from './engineBootstrap.js' import { SCALE_ENGINE_VERSION } from '../version.js' @@ -366,7 +368,7 @@ const evalShadowHit = defineCommand({ meta: { name: 'shadow-hit', description: 'Record one externally observed Shadow evaluation with unique evidence' }, args: { id: { type: 'positional', required: true, description: 'Shadow rule id (improvement candidate id)' }, - 'evidence-id': { type: 'string', required: true, description: 'Unique evidence artifact id' }, + 'evidence-file': { type: 'string', required: true, description: 'Reviewable evidence artifact path within the project directory' }, 'false-positive': { type: 'boolean', default: false, description: 'Mark this observation as a false positive' }, dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' }, json: { type: 'boolean', default: false }, @@ -374,17 +376,34 @@ const evalShadowHit = defineCommand({ run({ args }) { const projectDir = resolve(String(args.dir ?? PROJECT_DIR)) const scaleDir = resolveScaleDirForProject(projectDir) + const evidencePath = resolvePathWithinRoots(String(args['evidence-file']), { + baseDir: projectDir, + allowedRoots: [projectDir], + label: 'Shadow evidence', + }) + if (!existsSync(evidencePath) || !statSync(evidencePath).isFile()) { + throw new Error('Shadow evidence must be an existing regular file') + } + const evidenceStat = statSync(evidencePath) + if (evidenceStat.size > 10 * 1024 * 1024) { + throw new Error('Shadow evidence file exceeds the 10 MiB limit') + } + const digest = createHash('sha256').update(readFileSync(evidencePath)).digest('hex') + const evidenceId = `sha256:${digest}` const store = new PersistentRuleMaturityStore({ projectDir, scaleDir }) const record = store.recordHit({ ruleId: String(args.id), - evidenceId: String(args['evidence-id']), + evidenceId, falsePositive: Boolean(args['false-positive']), }) + const evidenceArtifact = { path: relative(projectDir, evidencePath), sha256: digest } if (args.json) { - console.log(JSON.stringify(record, null, 2)) + console.log(JSON.stringify({ record, evidenceArtifact }, null, 2)) return } console.log(`Shadow evidence recorded: ${record.ruleId}`) + console.log(` Artifact: ${evidenceArtifact.path}`) + console.log(` SHA-256: ${digest}`) console.log(` Hits: ${record.shadowHits}`) console.log(` False positives: ${record.falsePositiveCount}`) }, From 050681653206e0b56184dec31d4ed820be2d3e3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 15:27:03 +0800 Subject: [PATCH 15/19] test: require bounded in-project shadow evidence artifacts --- tests/api/workflowEvalCli.test.ts | 31 +++++++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/tests/api/workflowEvalCli.test.ts b/tests/api/workflowEvalCli.test.ts index 3d4ae06c..36e84f61 100644 --- a/tests/api/workflowEvalCli.test.ts +++ b/tests/api/workflowEvalCli.test.ts @@ -328,18 +328,41 @@ describe('workflow eval CLI', () => { expect(parseJson<{ record: { stage: string; ruleId: string } }>(shadowInit.stdout, shadowInit.stderr).record) .toMatchObject({ stage: 'shadow', ruleId: candidate.id }) + const shadowEvidencePath = join(projectDir, 'shadow-evidence', 'observation.json') + mkdirSync(dirname(shadowEvidencePath), { recursive: true }) + writeFileSync(shadowEvidencePath, JSON.stringify({ observation: 'independent-shadow-check', passed: true }), 'utf-8') + + const escapedShadowEvidence = await runScale([ + 'eval', 'shadow-hit', candidate.id, + '--evidence-file', '../outside-evidence.json', + '--json', + ], scaleDir, projectDir) + expect(escapedShadowEvidence.exitCode).toBe(1) + expect(`${escapedShadowEvidence.stdout}\n${escapedShadowEvidence.stderr}`) + .toContain('path escapes allowed directories') + const shadowHit = await runScale([ 'eval', 'shadow-hit', candidate.id, - '--evidence-id', 'shadow-observation-001', + '--evidence-file', shadowEvidencePath, '--json', ], scaleDir, projectDir) expect(shadowHit.exitCode).toBe(0) - expect(parseJson<{ shadowHits: number; evidenceIds: string[] }>(shadowHit.stdout, shadowHit.stderr)) - .toMatchObject({ shadowHits: 1, evidenceIds: ['shadow-observation-001'] }) + const shadowHitResult = parseJson<{ + record: { shadowHits: number; evidenceIds: string[] } + evidenceArtifact: { path: string; sha256: string } + }>(shadowHit.stdout, shadowHit.stderr) + expect(shadowHitResult.record).toMatchObject({ + shadowHits: 1, + evidenceIds: [`sha256:${shadowHitResult.evidenceArtifact.sha256}`], + }) + expect(shadowHitResult.evidenceArtifact).toMatchObject({ + path: 'shadow-evidence/observation.json', + }) + expect(shadowHitResult.evidenceArtifact.sha256).toMatch(/^[a-f0-9]{64}$/) const duplicateShadowHit = await runScale([ 'eval', 'shadow-hit', candidate.id, - '--evidence-id', 'shadow-observation-001', + '--evidence-file', shadowEvidencePath, '--json', ], scaleDir, projectDir) expect(duplicateShadowHit.exitCode).toBe(1) From 52e54090adda49a604f404dd5bc523d4f8beb64e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 15:27:14 +0800 Subject: [PATCH 16/19] docs: require hashed project-local shadow evidence artifacts --- docs/WORKFLOW_EVAL.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/WORKFLOW_EVAL.md b/docs/WORKFLOW_EVAL.md index 28d95f0c..0cd542de 100644 --- a/docs/WORKFLOW_EVAL.md +++ b/docs/WORKFLOW_EVAL.md @@ -72,15 +72,15 @@ After a candidate is explicitly accepted, initialize a non-blocking maturity rec ```bash scale eval shadow-init --rollback "Remove the shadow record; no hook is installed." -scale eval shadow-hit --evidence-id -scale eval shadow-hit --evidence-id --false-positive +scale eval shadow-hit --evidence-file shadow-evidence/ +scale eval shadow-hit --evidence-file shadow-evidence/ --false-positive scale eval shadow-status --json scale eval shadow-evaluate --json ``` -Records persist under `.scale/evals/rule-maturity/`. A shadow hit must reference a unique evidence artifact id; duplicate evidence is rejected rather than inflating hit counts. Evaluation reports threshold eligibility only. Even when eligible, the stored stage remains `shadow`: this workflow does not execute a replay, promote a rule, generate a hook, or modify production policy. Evidence must come from a separately run and reviewable observation; do not use the command itself as proof that replay occurred. +Records persist under `.scale/evals/rule-maturity/`. A shadow hit must reference an existing regular evidence file inside the project directory (maximum 10 MiB). The CLI records its SHA-256 digest as the evidence ID, so duplicate content is rejected even under another filename; paths escaping the project directory are rejected. Evaluation reports threshold eligibility only. Even when eligible, the stored stage remains `shadow`: this workflow does not execute a replay, promote a rule, generate a hook, or modify production policy. Evidence must come from a separately run and reviewable observation; do not use the command itself as proof that replay occurred. -候选必须先经人工接受,才能初始化非阻断成熟度记录。随后使用唯一证据 ID 记录外部观察结果。重复证据会被拒绝,不能重复累计命中数。记录保存在 `.scale/evals/rule-maturity/`。评估命令只报告是否满足晋级门槛;即使满足,持久化阶段仍保持 `shadow`。这些命令不会执行 Replay、晋级规则、生成 Hook 或修改生产策略。证据必须来自单独执行且可复核的观察,不能把记录命令本身当成 Replay 已运行的证明。 +候选必须先经人工接受,才能初始化非阻断成熟度记录。随后必须提交项目目录内已存在的普通证据文件(最大 10 MiB)。CLI 使用文件 SHA-256 作为证据 ID;即使更换文件名,内容相同也会被拒绝,不能重复累计命中数。越出项目目录的路径会被拒绝。记录保存在 `.scale/evals/rule-maturity/`。评估命令只报告是否满足晋级门槛;即使满足,持久化阶段仍保持 `shadow`。这些命令不会执行 Replay、晋级规则、生成 Hook 或修改生产策略。证据必须来自单独执行且可复核的观察,不能把记录命令本身当成 Replay 已运行的证明。 ## Failure Replay To Memory From d02364063c75f58e5b7da0af6e62557f79f32434 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 15:27:18 +0800 Subject: [PATCH 17/19] docs: require hashed project-local shadow evidence artifacts --- docs/EVOLUTION_SHADOW_MODE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/EVOLUTION_SHADOW_MODE.md b/docs/EVOLUTION_SHADOW_MODE.md index 8f089555..d11ae397 100644 --- a/docs/EVOLUTION_SHADOW_MODE.md +++ b/docs/EVOLUTION_SHADOW_MODE.md @@ -48,11 +48,11 @@ Promotion requires: ## Persistent Shadow Evidence Ledger -Accepted workflow improvement candidates can be initialized as persistent, non-blocking maturity records with a documented rollback procedure. Records live under `.scale/evals/rule-maturity/`. Each observed hit requires a unique evidence artifact id; duplicate ids are rejected. False positives are counted against the configured promotion threshold. +Accepted workflow improvement candidates can be initialized as persistent, non-blocking maturity records with a documented rollback procedure. Records live under `.scale/evals/rule-maturity/`. Each observed hit requires an existing regular evidence file inside the project directory (maximum 10 MiB). The CLI records its SHA-256 digest as the evidence ID; duplicate content is rejected even if submitted under another filename. Paths escaping the project directory are rejected. False positives are counted against the configured promotion threshold. The CLI exposes `shadow-init`, `shadow-hit`, `shadow-status`, and `shadow-evaluate`. These commands record external observations and calculate eligibility only. They do not execute the underlying rule against traffic, run a replay, change the maturity stage, generate hooks, or edit production policies. A passing evaluation reports `candidate-hook` as the next review stage while the persisted record remains `shadow`. -持久化 Shadow 证据台账支持为已接受的改进候选创建非阻断成熟度记录,并要求提供回滚方案。每次命中必须关联唯一证据 ID;重复 ID 会被拒绝。CLI 仅记录外部观察并计算门槛,不会自动执行规则或 Replay,不会改变成熟度阶段、生成 Hook 或修改生产策略。即使评估通过,也只报告下一审核阶段为 `candidate-hook`,记录本身仍保持 `shadow`。 +持久化 Shadow 证据台账支持为已接受的改进候选创建非阻断成熟度记录,并要求提供回滚方案。每次命中必须关联项目目录内已存在的普通证据文件(最大 10 MiB),CLI 以 SHA-256 生成证据 ID;重复内容和越界路径都会被拒绝。CLI 仅记录外部观察并计算门槛,不会自动执行规则或 Replay,不会改变成熟度阶段、生成 Hook 或修改生产策略。即使评估通过,也只报告下一审核阶段为 `candidate-hook`,记录本身仍保持 `shadow`。 ## Hook Boundary From 1b00c4af8088805d8778a4a92337ee1790910ee3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 15:28:01 +0800 Subject: [PATCH 18/19] fix: require content-addressed shadow evidence identifiers --- src/evolution/RuleMaturityStore.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/evolution/RuleMaturityStore.ts b/src/evolution/RuleMaturityStore.ts index d4d75380..0dce6f10 100644 --- a/src/evolution/RuleMaturityStore.ts +++ b/src/evolution/RuleMaturityStore.ts @@ -87,7 +87,9 @@ export class PersistentRuleMaturityStore { const current = this.get(input.ruleId) if (!current) throw new Error(`Shadow maturity record not found: ${input.ruleId}`) const evidenceId = input.evidenceId.trim() - if (!evidenceId) throw new Error('A unique shadow evidence id is required') + if (!/^sha256:[a-f0-9]{64}$/.test(evidenceId)) { + throw new Error('Shadow evidence id must be a SHA-256 digest in the form sha256:<64 lowercase hex characters>') + } if (current.evidenceIds.includes(evidenceId)) { throw new Error(`Shadow evidence already recorded: ${evidenceId}`) } From 4cf20098cb4bdca3a3293289b532c2b24aea7c0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=B8=BF=E6=9E=AB?= <163822263+hongmaple0820@users.noreply.github.com> Date: Wed, 18 Nov 2026 15:28:08 +0800 Subject: [PATCH 19/19] test: enforce content-addressed maturity evidence ids --- tests/evolution/ruleMaturityStore.test.ts | 25 ++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/tests/evolution/ruleMaturityStore.test.ts b/tests/evolution/ruleMaturityStore.test.ts index b10015bf..0b777d4e 100644 --- a/tests/evolution/ruleMaturityStore.test.ts +++ b/tests/evolution/ruleMaturityStore.test.ts @@ -30,11 +30,11 @@ describe('PersistentRuleMaturityStore', () => { const updated = store.recordHit({ ruleId: 'IMPROVE-100', - evidenceId: 'SHADOW-EVIDENCE-1', + evidenceId: `sha256:${'1'.repeat(64)}`, }) expect(updated.shadowHits).toBe(1) expect(new PersistentRuleMaturityStore({ projectDir: store.projectDir }).get('IMPROVE-100')) - .toMatchObject({ stage: 'shadow', shadowHits: 1, evidenceIds: ['SHADOW-EVIDENCE-1'] }) + .toMatchObject({ stage: 'shadow', shadowHits: 1, evidenceIds: [`sha256:${'1'.repeat(64)}`] }) }) it('requires unique evidence ids and prevents duplicate observations from inflating hit counts', () => { @@ -44,11 +44,11 @@ describe('PersistentRuleMaturityStore', () => { rollback: 'Delete the shadow record.', defectEvidenceIds: ['FAILURE-101'], }) - store.recordHit({ ruleId: 'IMPROVE-101', evidenceId: 'SHADOW-EVIDENCE-1' }) + store.recordHit({ ruleId: 'IMPROVE-101', evidenceId: `sha256:${'1'.repeat(64)}` }) expect(() => store.recordHit({ ruleId: 'IMPROVE-101', - evidenceId: 'SHADOW-EVIDENCE-1', + evidenceId: `sha256:${'1'.repeat(64)}`, })).toThrow('already recorded') expect(store.get('IMPROVE-101')?.shadowHits).toBe(1) }) @@ -63,7 +63,7 @@ describe('PersistentRuleMaturityStore', () => { for (let index = 0; index < 10; index++) { store.recordHit({ ruleId: 'IMPROVE-102', - evidenceId: `SHADOW-EVIDENCE-${index}`, + evidenceId: `sha256:${String(index).padStart(64, '0')}`, falsePositive: index < 2, }) } @@ -88,6 +88,21 @@ describe('PersistentRuleMaturityStore', () => { })).toThrow('being updated by another process') }) + it('rejects caller-supplied evidence ids that are not SHA-256 content digests', () => { + const store = createStore() + store.create({ + ruleId: 'IMPROVE-106', + rollback: 'Remove the shadow record.', + defectEvidenceIds: ['FAILURE-106'], + }) + + expect(() => store.recordHit({ + ruleId: 'IMPROVE-106', + evidenceId: 'made-up-evidence-id', + })).toThrow('must be a SHA-256 digest') + expect(store.get('IMPROVE-106')?.shadowHits).toBe(0) + }) + it('rejects records without rollback and defect evidence', () => { const store = createStore() expect(() => store.create({