create-yss-spec 3.4.6 → 3.4.8

package/template/docs/process/schemas/slice-implementation-contract-v3.schema.json

@@ -902,6 +902,47 @@
                   ]
                 }
               }
+            },
+            "first_slice": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "artifacts"
+              ],
+              "properties": {
+                "artifacts": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "role",
+                      "path",
+                      "type"
+                    ],
+                    "properties": {
+                      "role": {
+                        "enum": [
+                          "domain",
+                          "application",
+                          "infrastructure",
+                          "web",
+                          "test"
+                        ]
+                      },
+                      "path": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "type": {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    }
+                  }
+                }
+              }
             }
           },
           "required": [

package/template/scripts/lib/backend-platform-provenance.mjs

@@ -21,7 +21,7 @@ export function platformSourceFingerprint(family, root = ROOT) {
   const skill = family === 'domain-driven' ? 'yss-ddd-scaffold-generator' : family === 'layered-mvc' ? 'yss-layered-mvc-scaffold-generator' : null;
   if (!skill) fail('unknown architecture');
   const base = `.agents/skills/${skill}`;
-  const generator = fileMap(root, [`${base}/scripts/generate_scaffold.mjs`, ...(family === 'domain-driven' ? [`${base}/assets`] : ['.agents/skills/yss-ddd-scaffold-generator/assets/wrapper']), 'scripts/lib/backend-platform.mjs', 'scripts/lib/scaffold-local-database.mjs']);
+  const generator = fileMap(root, [`${base}/scripts/generate_scaffold.mjs`, ...(family === 'domain-driven' ? [`${base}/assets`] : [`${base}/assets`, '.agents/skills/yss-ddd-scaffold-generator/assets/wrapper']), 'scripts/lib/backend-platform.mjs', 'scripts/lib/scaffold-local-database.mjs']);
   const verifier = fileMap(root, ['scripts/lib/backend-platform-provenance.mjs', 'scripts/lib/backend-platform-verification.mjs', 'scripts/lib/command-runner.mjs', 'scripts/vendor/xml.mjs', '.agents/skills/yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs']);
   return { schema_version: 1, generator_digest: digest(JSON.stringify(generator)), verifier_digest: digest(JSON.stringify(verifier)) };
 }

package/template/scripts/lib/backend-platform-verification.mjs

@@ -21,9 +21,9 @@ export async function platformEvidenceArtifacts(evidenceDir) {
 export function checkPlatformTests(source, capabilities = []) {
   const suite = parseXmlDocument(source).testsuite;
   const cases = array(suite?.testcase);
-  const required = ['httpJsonRoundTrip', 'httpValidationRejectsBlank', 'validationAndJsonAutoConfiguration', 'mybatisCanMapVerificationQuery', ...(capabilities.includes('feign-client') ? ['feignCanDecodeJson'] : [])];
+  const required = ['httpJsonRoundTrip', 'httpValidationRejectsBlank', 'validationAndJsonAutoConfiguration', 'mybatisCanMapVerificationQuery', 'mappingPersistenceAndPaginationRoundTrip', 'transactionRollsBackOnUseCaseFailure', ...(capabilities.includes('feign-client') ? ['feignCanDecodeJson'] : [])];
   if (!suite || required.some(name => !cases.some(item => item['@_name'] === name && !['failure', 'error', 'skipped'].some(key => Object.hasOwn(item, key))))) fail('integration tests missing, failed or skipped');
-  return { status: 'passed', test_count: cases.length };
+  return { status: 'passed', test_count: cases.length, scope: 'test-scope mapping, MyBatis RowBounds, TransactionTemplate, HTTP status and JSON; not component error envelope, pagination interceptor, use-case proxy or production dialect certification' };
 }
 export async function verifyPlatformTests(projectRoot, evidenceDir, manifest, startedAt) {
   try {

package/template/scripts/lib/backend-platform.mjs

@@ -367,6 +367,13 @@ class PlatformIntegrationTest {
         try {
             try (java.io.OutputStream stream = connection.getOutputStream()) { stream.write(mapper.writeValueAsBytes(request)); }
             assertEquals(expectedStatus, connection.getResponseCode());
+            if (expectedStatus == 400) {
+                try (java.io.InputStream stream = connection.getErrorStream()) {
+                    assertNotNull(stream);
+                    java.util.Map<?, ?> error = mapper.readValue(stream, java.util.Map.class);
+                    assertFalse(error.isEmpty()); // Exact YSS error envelope requires the component capability contract.
+                }
+            }
             if (expectedStatus == 200) {
                 assertTrue(connection.getContentType().startsWith("application/json"));
                 try (java.io.InputStream stream = connection.getInputStream()) { assertEquals(value, mapper.readValue(stream, ProbePayload.class).getValue()); }
@@ -375,6 +382,54 @@ class PlatformIntegrationTest {
     }
     @Autowired ${mapper.split(".").at(-1)} mapper;
     @Autowired SqlSessionFactory sqlSessionFactory;
+    @Autowired org.springframework.jdbc.core.JdbcTemplate jdbc;
+    @Autowired org.springframework.transaction.PlatformTransactionManager transactions;
+    @Autowired org.mybatis.spring.SqlSessionTemplate sessions;
+    @Autowired PlatformProbeMapping probeMapping;
+
+    @lombok.Getter
+    @lombok.Setter
+    public static class ProbeRow {
+        private Long id;
+        private String value;
+    }
+    interface RoundTripMapper {
+        @org.apache.ibatis.annotations.Insert("INSERT INTO scaffold_roundtrip(id, probe_value) VALUES(#{id}, #{value})")
+        int insert(ProbeRow row);
+        @org.apache.ibatis.annotations.Results(@org.apache.ibatis.annotations.Result(column = "probe_value", property = "value"))
+        @Select("SELECT id, probe_value FROM scaffold_roundtrip ORDER BY id")
+        java.util.List<ProbeRow> page(org.apache.ibatis.session.RowBounds bounds);
+        @Select("SELECT COUNT(*) FROM scaffold_roundtrip") int count();
+    }
+    private RoundTripMapper roundTripMapper() {
+        jdbc.execute("CREATE TABLE IF NOT EXISTS scaffold_roundtrip(id BIGINT PRIMARY KEY, probe_value VARCHAR(100) NOT NULL)");
+        jdbc.update("DELETE FROM scaffold_roundtrip");
+        if (!sqlSessionFactory.getConfiguration().hasMapper(RoundTripMapper.class)) sqlSessionFactory.getConfiguration().addMapper(RoundTripMapper.class);
+        return sessions.getMapper(RoundTripMapper.class);
+    }
+    @Test void mappingPersistenceAndPaginationRoundTrip() {
+        RoundTripMapper persistence = roundTripMapper();
+        for (long id = 1; id <= 3; id++) {
+            ProbeRow original = new ProbeRow(); original.setId(id); original.setValue("probe-" + id);
+            ProbeRow copy = probeMapping.copy(original);
+            assertNotSame(original, copy); assertEquals(original.getId(), copy.getId());
+            persistence.insert(copy);
+        }
+        assertEquals(3, persistence.count());
+        java.util.List<ProbeRow> page = persistence.page(new org.apache.ibatis.session.RowBounds(1, 1));
+        assertEquals(1, page.size()); assertEquals(Long.valueOf(2), page.get(0).getId());
+        assertEquals("probe-2", page.get(0).getValue());
+        assertNull(probeMapping.copy(null));
+    }
+    @Test void transactionRollsBackOnUseCaseFailure() {
+        final RoundTripMapper persistence = roundTripMapper();
+        org.springframework.transaction.support.TransactionTemplate transaction = new org.springframework.transaction.support.TransactionTemplate(transactions);
+        assertThrows(IllegalStateException.class, () -> transaction.execute(status -> {
+            ProbeRow row = new ProbeRow(); row.setId(9L); row.setValue("must-rollback"); persistence.insert(row);
+            throw new IllegalStateException("synthetic use-case failure");
+        }));
+        assertEquals(0, persistence.count());
+    }
     static final class ValidationProbe { @NotBlank String value = ""; }
     @Test void validationAndJsonAutoConfiguration() throws Exception {
         assertFalse(validator.validate(new ValidationProbe()).isEmpty());
@@ -398,5 +453,12 @@ ${capabilities.includes("feign-client") ? `    @Autowired org.springframework.cl
         assertTrue(decoder.decode(response, java.util.Map.class) instanceof java.util.Map);
     }
 ` : ""}}
+
+@org.mapstruct.Mapper(componentModel = "spring", unmappedTargetPolicy = org.mapstruct.ReportingPolicy.ERROR)
+interface PlatformProbeMapping {
+    @org.mapstruct.Mapping(target = "id", source = "id")
+    @org.mapstruct.Mapping(target = "value", source = "value")
+    PlatformIntegrationTest.ProbeRow copy(PlatformIntegrationTest.ProbeRow row);
+}
 `;
 }

package/template/scripts/lib/backend-review.mjs

@@ -0,0 +1,102 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { parseSliceYaml, selectSliceWorkUnit } from './slice-contract.mjs';
+import { inspectSliceContract } from './slice-execution-preflight.mjs';
+import { inspectMaintenanceCandidate } from './maintenance-candidate.mjs';
+
+const ensure = (condition, message) => { if (!condition) throw new Error(`backend-review: ${message}`); };
+const text = value => typeof value === 'string' && value.trim();
+const digest = value => createHash('sha256').update(value).digest('hex');
+function git(root, args) {
+  const result = spawnSync('git', args, { cwd: root, maxBuffer: 64 * 1024 * 1024 });
+  ensure(result.status === 0, `git ${args[0]} failed`); return result.stdout;
+}
+function file(root, ref) {
+  ensure(text(ref) && !path.isAbsolute(ref), 'relative evidence reference required');
+  const resolved = fs.realpathSync(path.resolve(root, ref));
+  ensure(resolved.startsWith(`${fs.realpathSync(root)}${path.sep}`), 'evidence path escape');
+  return resolved;
+}
+
+export function backendReviewSkills(contract, actualSkills = []) {
+  return [...new Set([...(contract.resolution?.required_skills || []), ...(contract.common?.required_skills || []),
+    ...(contract.backend?.required_skills || []), ...actualSkills, 'alibaba-java-code-style', 'yss-repository', 'yss-mybatis'])].sort();
+}
+
+/** Validate existing code-review result and constraint_results; this is not an approval authority. */
+export function validateBackendReview(state, { root = process.cwd() } = {}) {
+  const input = state?.review_input;
+  ensure(input?.slice_contract_ref, 'review input must bind Slice contract');
+  const loaded = inspectSliceContract(input.slice_contract_ref, { root, approval_ref: input.approval_ref, work_unit_id: input.work_unit_id });
+  ensure(loaded.report.execution_allowed, `approved current contract required: ${loaded.report.blockers.join('; ')}`);
+  const contract = selectSliceWorkUnit(loaded.contract, input.work_unit_id);
+  if (contract.backend?.status !== 'required') return { status: 'not-applicable', reason: 'contract has no backend impact' };
+  ensure(Array.isArray(input.actual_skill_impacts), 'actual_skill_impacts must be explicit (may be empty)');
+  const result = parseSliceYaml(fs.readFileSync(file(root, state.review_result_ref), 'utf8'));
+  ensure(result.skill === 'code-review' && result.result === 'completed', 'only completed code-review can proceed');
+  ensure(result.contract_digest === loaded.binding.digest, 'review contract digest stale');
+  for (const identity of ['reviewer','implementer']) {
+    const actor = result[identity];
+    for (const field of ['actor_id','runtime_id','instance_id']) ensure(text(actor?.[field]), `${identity}.${field} required`);
+  }
+  ensure(result.reviewer.actor_id !== result.implementer.actor_id && result.reviewer.instance_id !== result.implementer.instance_id, 'independent Reviewer required');
+  ensure(result.implementer.actor_id === input.implementation_actor_id && result.implementer.instance_id === input.implementation_instance_id, 'implementation identity mismatch');
+  ensure(result.candidate_digest === input.candidate_digest, 'candidate digest mismatch');
+  const projectRoot = fs.realpathSync(path.resolve(root, input.project_root || '.'));
+  ensure(contract.common.project_roots.some(ref => fs.realpathSync(path.resolve(root, ref)) === projectRoot), 'candidate project is outside approved contract');
+  // Reuse the packed worktree candidate protocol. Its exclusions are restricted to review evidence.
+  if (input.review_mode === 'worktree') {
+    const { manifest, trackedDiff, entries } = inspectMaintenanceCandidate({ manifestPath: file(projectRoot, input.candidate_snapshot_ref) });
+    ensure(manifest.candidate_digest === input.candidate_digest, 'snapshot digest mismatch');
+    ensure(trackedDiff.equals(git(projectRoot, ['diff','--no-ext-diff','--binary','--full-index',manifest.merge_base])), 'tracked candidate stale');
+    const excluded = manifest.excluded_paths || [];
+    ensure(excluded.every(p => p.startsWith('.template-source/evidence/maintenance/') && !p.split('/').includes('..')), 'candidate exclusions must be evidence only');
+    const actual = git(projectRoot, ['ls-files','-z','--others','--exclude-standard']).toString().split('\0').filter(Boolean)
+      .filter(p => !excluded.some(ex => p === ex || p.startsWith(`${ex}/`))).sort();
+    ensure(JSON.stringify(actual) === JSON.stringify(entries.map(e => e.path).sort()), 'untracked candidate inventory stale');
+    for (const entry of entries) {
+      const info = fs.lstatSync(path.resolve(projectRoot, entry.path));
+      ensure(info.mode === entry.mode && (entry.kind === 'symlink' ? info.isSymbolicLink() : info.isFile()), `untracked candidate mode/kind stale: ${entry.path}`);
+      const current = entry.kind === 'symlink' ? Buffer.from(fs.readlinkSync(path.resolve(projectRoot, entry.path))) : fs.readFileSync(file(projectRoot, entry.path));
+      ensure(current.equals(entry.content), `untracked candidate stale: ${entry.path}`);
+    }
+  } else {
+    ensure(input.review_mode === 'committed', 'unsupported candidate mode');
+    const tree = git(projectRoot, ['rev-parse',`${input.implementation_candidate_ref}^{tree}`]).toString().trim();
+    ensure(tree === input.candidate_digest, 'committed candidate mismatch');
+    ensure(git(projectRoot, ['rev-parse','HEAD^{tree}']).toString().trim() === tree && !git(projectRoot, ['status','--porcelain']).length, 'committed candidate is not current clean checkout');
+  }
+  const layerSkills = { domain: 'yss-domain', application: 'yss-application', infrastructure: 'yss-repository', web: 'yss-web-controller' };
+  const actualSkills = [...input.actual_skill_impacts, ...(contract.backend.affected_layers || []).map(layer => layerSkills[layer]).filter(Boolean)];
+  const required = backendReviewSkills(contract, actualSkills);
+  const applicable = new Set([...(contract.resolution?.required_skills || []), ...(contract.common?.required_skills || []), ...(contract.backend?.required_skills || []), ...actualSkills, "alibaba-java-code-style"]);
+  ensure(Array.isArray(result.constraint_results), 'constraint_results required');
+  for (const skill of required) {
+    const rows = result.constraint_results.filter(row => row.skill === skill && row.axis === 'Standards');
+    ensure(rows.length, `skill not reviewed: ${skill}`);
+    for (const row of rows) {
+      ensure(text(row.constraint) && text(row.rule_ref) && text(row.code_ref) && text(row.evidence_ref), `${skill}: rule/code/evidence required`);
+      ensure(['passed','not-applicable'].includes(row.status), `${skill}: unresolved violation`);
+      ensure(row.status !== 'not-applicable' || (text(row.reason) && !applicable.has(skill)), `${skill}: applicable skill cannot be waived`);
+      ensure(row.rule_ref.startsWith(`.agents/skills/${skill}/`), `${skill}: rule must cite its canonical skill`);
+      const rule = fs.readFileSync(file(root, row.rule_ref.split('#')[0]));
+      ensure(digest(rule) === row.rule_digest, `${skill}: rule evidence stale`);
+      ensure(fs.existsSync(file(projectRoot, row.code_ref.split(':')[0])), `${skill}: missing code location`);
+      ensure(digest(fs.readFileSync(file(root, row.evidence_ref))) === row.evidence_digest, `${skill}: verification evidence stale`);
+    }
+  }
+  ensure(Array.isArray(result.verification_results) && result.verification_results.length > 0, 'machine verification required');
+  for (const check of result.verification_results) {
+    ensure(text(check.command) && Number.isFinite(Date.parse(check.executed_at)) && check.exit_code === 0 && check.candidate_digest === result.candidate_digest, 'machine check failed, absent or stale');
+    ensure(digest(fs.readFileSync(file(root, check.evidence_ref))) === check.evidence_digest, 'machine evidence stale');
+  }
+  ensure(result.axes?.Standards === 'passed' && result.axes?.Spec === 'passed', 'Standards and Spec must pass separately');
+  ensure(Array.isArray(result.findings), 'findings required');
+  for (const finding of result.findings) {
+    ensure(!['violation','drift','new_impacts','missing_evidence'].includes(finding.disposition) || finding.status === 'resolved', 'blocking finding remains open');
+    if (finding.disposition === 'suggestion' && finding.status !== 'resolved') ensure(text(finding.follow_up_ref), 'suggestion needs backlog reference');
+  }
+  return { status: 'passed', candidate_digest: input.candidate_digest, reviewed_skills: required };
+}

package/template/scripts/lib/first-slice-artifacts.mjs

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Declarations bind responsibilities to compiled types, not naming conventions. */
+export function inspectFirstSliceArtifacts(contract, projectRoot) {
+  const declaration = contract.backend?.first_slice;
+  const failures = [], properties = { 'yss.firstSlice': 'true' };
+  if (!declaration || !Array.isArray(declaration.artifacts) || !declaration.artifacts.length) {
+    return { failures: ['backend.first_slice.artifacts-required'], properties };
+  }
+  const roles = new Map(), types = [], seen = new Set();
+  const root = fs.realpathSync(projectRoot);
+  for (const item of declaration.artifacts) {
+    const label = item?.type || item?.path || 'unknown';
+    try {
+      if (!['domain','application','infrastructure','web','test'].includes(item.role)) throw Error('invalid-role');
+      if (!/^[a-zA-Z_$][\w$]*(\.[a-zA-Z_$][\w$]*)+$/.test(item.type || '')) throw Error('qualified-type-required');
+      if (seen.has(item.type)) throw Error('duplicate-type');
+      seen.add(item.type);
+      if (!item.path || path.isAbsolute(item.path) || item.path.split(/[\\/]/).includes('..')) throw Error('relative-path-required');
+      const file = fs.realpathSync(path.resolve(root, item.path));
+      if (!file.startsWith(`${root}${path.sep}`)) throw Error('path-escape');
+      const source = fs.readFileSync(file, 'utf8');
+      const pkg = source.match(/^\s*package\s+([\w.]+)\s*;/m)?.[1];
+      const name = item.type.slice(item.type.lastIndexOf('.') + 1);
+      if (`${pkg}.${name}` !== item.type || !new RegExp(`\\b(class|interface|enum|record)\\s+${name}\\b`).test(source)) throw Error('declared-type-mismatch');
+      if (item.role === 'test') {
+        if (!item.path.includes('/src/test/java/')) throw Error('test-source-required');
+      } else {
+        if (!item.path.includes('/src/main/java/')) throw Error('main-source-required');
+        types.push(item.type);
+        const packages = roles.get(item.role) || new Set(); packages.add(pkg); roles.set(item.role, packages);
+      }
+    } catch (error) { failures.push(`${label}:${error.message}`); }
+  }
+  const aliases = { service: 'application', core: 'domain', repository: 'infrastructure', server: 'web' };
+  for (const layer of contract.backend.affected_layers || []) {
+    const role = aliases[layer] || layer;
+    if (['domain','application','infrastructure','web'].includes(role) && !roles.has(role)) failures.push(`affected-role-empty:${role}`);
+  }
+  if (!declaration.artifacts.some(item => item.role === 'test')) failures.push('behavior-test-binding-required');
+  if ((contract.backend.affected_layers || []).some(layer => ['web','server'].includes(layer))) properties['yss.arch.requireController'] = 'true';
+  if (!types.length) failures.push('business-type-required');
+  properties['yss.arch.requiredTypes'] = types.join(',');
+  for (const [role, packages] of roles) properties[`yss.arch.${role}`] = [...packages].join(',');
+  return { failures, properties };
+}

package/template/scripts/lib/first-slice-tests.mjs

@@ -0,0 +1,24 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseXmlDocument } from '../vendor/xml.mjs';
+const array = value => value === undefined ? [] : Array.isArray(value) ? value : [value];
+
+export function verifyFirstSliceTests(contract, projectRoot, startedAt, architectureType) {
+  const declarations = contract.backend.first_slice.artifacts.filter(item => item.role === 'test');
+  const required = [...declarations.map(item => ({ type: item.type, module: item.path.split('/src/test/java/')[0] })), architectureType];
+  const evidence = [], failures = [];
+  for (const item of required) {
+    try {
+      const candidates = ['surefire-reports','failsafe-reports'].map(folder => path.join(projectRoot,item.module,'target',folder,`TEST-${item.type}.xml`));
+      const ref = candidates.find(file => fs.existsSync(file) && fs.statSync(file).mtimeMs >= startedAt);
+      if (!ref) throw Error('fresh execution report missing');
+      const bytes = fs.readFileSync(ref), suite = parseXmlDocument(bytes.toString()).testsuite;
+      const cases = array(suite?.testcase);
+      if (!cases.length || cases.some(c => ['failure','error','skipped'].some(key => Object.hasOwn(c,key)))) throw Error('test not executed successfully');
+      if (cases.some(c => c['@_classname'] !== item.type)) throw Error('test class does not match contract');
+      evidence.push({type:item.type,ref,sha256:createHash('sha256').update(bytes).digest('hex'),test_count:cases.length});
+    } catch(error) { failures.push(`${item.type}:${error.message}`); }
+  }
+  return { status: failures.length ? 'failed' : 'passed', evidence, failures };
+}

package/template/scripts/lib/lifecycle-transition.mjs

@@ -9,6 +9,7 @@ import { validatePlanSpecEntry } from "./plan-spec-entry.mjs";
 import path from "node:path";
 import { validateApiContractDecision } from "./api-contract-decision.mjs";
 import { loadApprovalRecord, validateApprovalRecord } from "./approval-record.mjs";
+import { validateBackendReview } from "./backend-review.mjs";
 import { ROOT } from "./lifecycle-registry.mjs";
 
 const IMPLEMENTATION_WORK_UNIT = "work-unit.slice-implementation";
@@ -248,6 +249,11 @@ function validateTicketReference(ref, trackerKind) {
  * by `validateWorkflowExecutionResult` before this function is called.
  */
 export function validateNextRoute(currentWorkUnit, nextRoute, decisionState, options = {}) {
+  if (currentWorkUnit === "work-unit.code-review" && nextRoute === "work-unit.release-and-retrospective") {
+    try { validateBackendReview(decisionState, { root: options.root || ROOT }); }
+    catch (error) { return blockedResult(["backend-review-incomplete"], [error.message]); }
+  }
+
 
   if (["work-unit.technical-analysis", TICKET_DECOMPOSITION_WORK_UNIT, IMPLEMENTATION_WORK_UNIT, "work-unit.frontend-implementation-verification"].includes(nextRoute)) {
     try { enforceFrontendDelivery(decisionState, { root: options.root, phase: nextRoute === IMPLEMENTATION_WORK_UNIT ? "implementation" : "inputs" }); }

package/template/scripts/lib/maintenance-candidate.mjs

@@ -0,0 +1,160 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parseDocument, stringify } from "../vendor/yaml.mjs";
+
+const MAGIC = Buffer.from("YSS-WORKTREE-CANDIDATE-V1\0", "ascii");
+const MAX_BUFFER = 512 * 1024 * 1024;
+const MAINTENANCE_EVIDENCE_ROOT = ".template-source/evidence/maintenance";
+const CANDIDATE_FILES = ["candidate-manifest.yaml", "candidate.bin", "tracked.diff"];
+
+function fail(message) { throw new TypeError(message); }
+function ensure(condition, message) { if (!condition) fail(message); }
+function git(args, root, encoding = "utf8") {
+  const result = spawnSync("git", args, { cwd: root, encoding, maxBuffer: MAX_BUFFER });
+  if (result.status !== 0) fail((typeof result.stderr === "string" ? result.stderr : result.stderr?.toString()).trim() || `git ${args.join(" ")} 执行失败`);
+  return result.stdout;
+}
+function uint64(value) { const buffer = Buffer.alloc(8); buffer.writeBigUInt64BE(BigInt(value)); return buffer; }
+function uint32(value) { const buffer = Buffer.alloc(4); buffer.writeUInt32BE(value >>> 0); return buffer; }
+function splitNull(buffer) {
+  const result = [];
+  let start = 0;
+  for (let index = 0; index < buffer.length; index += 1) if (buffer[index] === 0) { if (index > start) result.push(buffer.subarray(start, index)); start = index + 1; }
+  if (start < buffer.length) result.push(buffer.subarray(start));
+  return result;
+}
+function normalizeRelative(value, label) {
+  ensure(typeof value === "string" && value.trim(), `${label} 不能为空`);
+  const normalized = value.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
+  ensure(normalized && !path.posix.isAbsolute(normalized) && path.posix.normalize(normalized) === normalized && normalized !== ".." && !normalized.startsWith("../"), `${label} 必须是规范的仓库内相对路径`);
+  return normalized;
+}
+function isMaintenanceEvidencePath(value) {
+  return value === MAINTENANCE_EVIDENCE_ROOT || value.startsWith(`${MAINTENANCE_EVIDENCE_ROOT}/`);
+}
+function readLength(buffer, offset, bytes, label) {
+  ensure(offset + bytes <= buffer.length, `packed candidate 缺少 ${label}`);
+  const value = bytes === 8 ? buffer.readBigUInt64BE(offset) : BigInt(buffer.readUInt32BE(offset));
+  ensure(value <= BigInt(Number.MAX_SAFE_INTEGER), `packed candidate ${label} 过大`);
+  return { value: Number(value), offset: offset + bytes };
+}
+
+export function captureMaintenanceCandidate({ root, outputDir, baseRef = "HEAD", excludePaths = [] }) {
+  const repositoryRoot = path.resolve(root);
+  const outputPath = path.resolve(repositoryRoot, outputDir);
+  const outputRelative = normalizeRelative(path.relative(repositoryRoot, outputPath).replaceAll(path.sep, "/"), "outputDir");
+  ensure(isMaintenanceEvidencePath(outputRelative), `outputDir 必须位于 ${MAINTENANCE_EVIDENCE_ROOT}`);
+  ensure(!existsSync(outputPath), "outputDir 必须不存在，禁止复用可能含残留文件的候选目录");
+  ensure(Array.isArray(excludePaths), "excludePaths 必须是数组");
+  const explicitExclusions = excludePaths.map((value) => normalizeRelative(value, "excludePaths"));
+  for (const exclusion of explicitExclusions) ensure(isMaintenanceEvidencePath(exclusion), `excludePaths 只允许 ${MAINTENANCE_EVIDENCE_ROOT} 下的维护证据`);
+  const exclusions = [...new Set([outputRelative, ...explicitExclusions])];
+  const mergeBase = git(["merge-base", baseRef, "HEAD"], repositoryRoot).trim();
+  const trackedDiff = git(["diff", "--no-ext-diff", "--binary", "--full-index", mergeBase], repositoryRoot, null);
+  const rawPaths = splitNull(git(["ls-files", "-z", "--others", "--exclude-standard"], repositoryRoot, null))
+    .filter((rawPath) => {
+      const value = rawPath.toString();
+      return !exclusions.some((exclusion) => value === exclusion || value.startsWith(`${exclusion}/`));
+    })
+    .sort(Buffer.compare);
+  ensure(trackedDiff.length > 0 || rawPaths.length > 0, "维护候选不能为空");
+
+  const parts = [MAGIC, Buffer.from([0x54]), uint64(trackedDiff.length), trackedDiff];
+  const untrackedFiles = [];
+  const untrackedPathBytes = [];
+  for (const rawPath of rawPaths) {
+    ensure(!rawPath.includes(0) && rawPath.length > 0, "untracked path 无效");
+    const relative = rawPath.toString();
+    const absolute = path.resolve(repositoryRoot, relative);
+    ensure(!path.relative(repositoryRoot, absolute).startsWith(".."), `untracked path 越界: ${relative}`);
+    const stat = lstatSync(absolute);
+    let kind;
+    let content;
+    if (stat.isFile()) { kind = 0x52; content = readFileSync(absolute); }
+    else if (stat.isSymbolicLink()) { kind = 0x4c; content = readlinkSync(absolute, { encoding: "buffer" }); }
+    else fail(`候选包含不支持的 untracked 类型: ${relative}`);
+    parts.push(Buffer.from([0x55]), uint64(rawPath.length), rawPath, uint32(stat.mode), Buffer.from([kind]), uint64(content.length), content);
+    untrackedFiles.push(relative);
+    untrackedPathBytes.push(rawPath.toString("base64"));
+  }
+  const stream = Buffer.concat(parts);
+  const digest = createHash("sha256").update(stream).digest("hex");
+  const streamRef = `${outputRelative}/candidate.bin`;
+  const diffRef = `${outputRelative}/tracked.diff`;
+  const manifestRef = `${outputRelative}/candidate-manifest.yaml`;
+  const manifest = {
+    schema_version: 1,
+    candidate_kind: "yss-worktree-candidate-v1",
+    storage: "packed-stream",
+    review_mode: "worktree",
+    review_base_ref: baseRef,
+    merge_base: mergeBase,
+    implementation_candidate_ref: "working-tree",
+    candidate_snapshot_ref: manifestRef,
+    candidate_digest: digest,
+    tracked_diff_command: `git diff --no-ext-diff --binary --full-index ${mergeBase}`,
+    untracked_inventory_command: "git ls-files -z --others --exclude-standard",
+    untracked_diff_command: "packed in candidate.bin",
+    untracked_files: untrackedFiles,
+    untracked_path_bytes: untrackedPathBytes,
+    excluded_paths: exclusions,
+    snapshot_stream_ref: streamRef,
+    tracked_diff_ref: diffRef,
+    commit_list_command: `git log ${baseRef}..HEAD --oneline`
+  };
+  const outputParent = path.dirname(outputPath);
+  mkdirSync(outputParent, { recursive: true });
+  const stagingPath = mkdtempSync(path.join(outputParent, ".candidate-staging-"));
+  try {
+    writeFileSync(path.join(stagingPath, "candidate.bin"), stream);
+    writeFileSync(path.join(stagingPath, "tracked.diff"), trackedDiff);
+    writeFileSync(path.join(stagingPath, "candidate-manifest.yaml"), stringify(manifest, { lineWidth: 0 }));
+    renameSync(stagingPath, outputPath);
+  } finally {
+    if (existsSync(stagingPath)) rmSync(stagingPath, { recursive: true, force: true });
+  }
+  return { candidate_digest: digest, manifest, manifest_ref: manifestRef, files: [manifestRef, streamRef, diffRef] };
+}
+
+export function inspectMaintenanceCandidate({ manifestPath }) {
+  const absoluteManifest = path.resolve(manifestPath);
+  const document = parseDocument(readFileSync(absoluteManifest, "utf8"), { uniqueKeys: true });
+  ensure(document.errors.length === 0, document.errors[0]?.message || "candidate manifest 无法解析");
+  const manifest = document.toJS({ maxAliasCount: 0 });
+  ensure(manifest.storage === "packed-stream", "只支持 packed-stream candidate");
+  const candidateDir = path.dirname(absoluteManifest);
+  ensure(JSON.stringify(readdirSync(candidateDir).sort()) === JSON.stringify([...CANDIDATE_FILES].sort()), `packed candidate 目录必须恰好包含 ${CANDIDATE_FILES.join("、")}`);
+  const root = path.resolve(path.dirname(absoluteManifest), ...Array(manifest.candidate_snapshot_ref.split("/").length - 1).fill(".."));
+  ensure(path.resolve(root, manifest.candidate_snapshot_ref) === absoluteManifest, "candidate_snapshot_ref 未绑定当前 manifest");
+  const streamPath = path.resolve(root, manifest.snapshot_stream_ref);
+  const diffPath = path.resolve(root, manifest.tracked_diff_ref);
+  ensure(streamPath === path.join(candidateDir, "candidate.bin") && diffPath === path.join(candidateDir, "tracked.diff"), "packed candidate 引用必须绑定同目录规范文件");
+  const stream = readFileSync(streamPath);
+  ensure(createHash("sha256").update(stream).digest("hex") === manifest.candidate_digest.replace(/^sha256:/, ""), "candidate_digest 与 packed stream 不一致");
+  ensure(stream.subarray(0, MAGIC.length).equals(MAGIC), "packed stream magic 无效");
+  let offset = MAGIC.length;
+  ensure(stream[offset] === 0x54, "packed stream 缺少 tracked record");
+  offset += 1;
+  let length = readLength(stream, offset, 8, "tracked length");
+  offset = length.offset;
+  const trackedDiff = stream.subarray(offset, offset + length.value);
+  offset += length.value;
+  ensure(readFileSync(diffPath).equals(trackedDiff), "tracked.diff 与 packed stream 不一致");
+  const entries = [];
+  while (offset < stream.length) {
+    ensure(stream[offset] === 0x55, "packed stream record kind 无效");
+    offset += 1;
+    length = readLength(stream, offset, 8, "path length"); offset = length.offset;
+    const rawPath = stream.subarray(offset, offset + length.value); offset += length.value;
+    length = readLength(stream, offset, 4, "mode"); offset = length.offset;
+    const mode = length.value;
+    const kind = stream[offset]; offset += 1;
+    length = readLength(stream, offset, 8, "content length"); offset = length.offset;
+    const content = stream.subarray(offset, offset + length.value); offset += length.value;
+    entries.push({ path: rawPath.toString(), path_bytes: rawPath.toString("base64"), mode, kind: kind === 0x52 ? "regular" : "symlink", content });
+  }
+  ensure(JSON.stringify(entries.map((entry) => entry.path_bytes)) === JSON.stringify(manifest.untracked_path_bytes), "manifest inventory 与 packed stream 不一致");
+  return { manifest, trackedDiff, entries };
+}

package/template/scripts/lib/skill-registry.mjs

@@ -6,7 +6,11 @@ import { nestedSkillPaths, OBSOLETE, PROJECTION_ROOTS, ROOT, unregisteredNestedS
 export const DEFAULT_REGISTRY = path.join(ROOT, "docs/agents/yss-skill-registry.yaml");
 const LOCK_PATH = path.join(ROOT, "skills-lock.json");
 const COMPILER_CONTRACT = path.join(ROOT, ".agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml");
-const LIFECYCLE_CONTRACT = path.join(ROOT, ".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml");
+const LIFECYCLE_CONTRACT = [
+  path.join(ROOT, ".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml"),
+  path.join(ROOT, ".agents/skills/harness-orchestrator/references/orchestration-contract.yaml"),
+].find((candidate) => existsSync(candidate))
+  ?? path.join(ROOT, ".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml");
 const BACKEND_PLATFORMS = path.join(ROOT, "docs/engineering/backend-platforms.json");
 const LAYERS = new Set(["core", "specialist", "compatibility", "maintainer-only"]);
 const MATURITIES = new Set(["draft", "verified", "supported", "deprecated"]);

package/template/scripts/lib/skill-supply-chain.mjs

@@ -11,7 +11,7 @@ const YSS_UI_MANIFEST_PATH = path.join(SOURCE_ROOT, ".yss-skills-manifest.json")
 const STRATEGIC_DESIGN_MANIFEST_PATH = path.join(SOURCE_ROOT, ".strategic-design-skills-manifest.json");
 export const PROJECTION_ROOTS = [".codex/skills", ".cursor/skills", ".pi/skills"];
 export const OBSOLETE = new Set(["yss-antd-design", "yss-antdv-next-design", "to-" + "prd", "to-" + "issues", "design-an-interface", "qa", "request-refactor-plan", "ubiquitous-language", "edit-article", "obsidian-vault", "writing-great-skills", "code-review-process", "yss-domain-modeling", "yss-dir", "yss-duckdb", "yss-file", "yss-filerunner", "yss-db2mybatis", "yss-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-valuation", "yss-variable", "yss-openapi", "web-design-engineer", "web-video-presentation", "wireframe-prototype", "wizard", "git-guardrails-claude-code", "claude-handoff", "batch-grill-me", "product-design-prototype", "research", "ask-matt", "dispatching-parallel-agents", "loop-me", "migrate-to-shoehorn", "prototype-page-acceptance", "scaffold-exercises", "setup-pre-commit", "setup-ts-deep-modules", "teach", "writing-beats", "writing-fragments", "writing-shape", "yss-microapp-commit", "yss-page-module-development", "yss-dictionary", "yss-jdbc", "yss-log", "yss-taskflow", "yss-backend-scaffold-application", "yss-backend-scaffold-domain", "yss-backend-scaffold-infrastructure", "yss-backend-scaffold-web", "yss-router", "yss-source-index"]);
-for (const id of ["yss-components", "yss-mvc-scaffold-generator", "yss-backend-scaffold-adapter", "yss-application-layer-reference", "yss-domain-layer-reference", "yss-infrastructure-layer-reference", "yss-web-layer-reference"]) OBSOLETE.add(id);
+for (const id of ["component-selection-imports", "page-form-module", "page-list-module", "page-skeleton", "vue3-best-practices", "yss-use-table-height", "yss-use-tree-height", "yss-components", "yss-mvc-scaffold-generator", "yss-mvc-design", "yss-mvc-data-analysis-project-initializer", "yss-backend-scaffold-parent", "yss-backend-scaffold-adapter", "yss-application-layer-reference", "yss-domain-layer-reference", "yss-infrastructure-layer-reference", "yss-web-layer-reference"]) OBSOLETE.add(id);
 export function obsoleteCanonicalResidues(names, obsolete = OBSOLETE) {
   return names.filter((name) => obsolete.has(name)).sort();
 }

package/template/scripts/lib/slice-execution-preflight.mjs

@@ -0,0 +1,43 @@
+import { readSliceContract } from './slice-contract.mjs';
+import { createApprovedExecutionContext } from './approved-execution-context.mjs';
+import { evaluateContractFreshness, loadCompilerContract } from './implementation-contract-compiler.mjs';
+import { loadSkillRegistry } from './skill-registry.mjs';
+
+/** Readability, structure and execution approval are different levels of evidence. */
+export function inspectSliceContract(ref, { root = process.cwd(), approval_ref, work_unit_id } = {}) {
+  const loaded = readSliceContract(ref, { root });
+  const { contract, binding } = loaded;
+  const checks = { readable: 'passed', structure: 'passed', approval: 'not-checked', freshness: 'not-checked' };
+  const blockers = [];
+  if (loaded.raw.schema_version === 2) {
+    for (const [section, fields] of Object.entries(loadCompilerContract().slice_contract_required)) {
+      const target = section === 'root' ? contract : contract[section];
+      for (const field of fields) if (!target || !Object.hasOwn(target, field)) blockers.push(`missing:${section}.${field}`);
+    }
+    for (const section of ['common', 'resolution', 'backend']) {
+      if (!Array.isArray(contract[section]?.required_skills)) blockers.push(`invalid:${section}.required_skills`);
+    }
+    if (!Array.isArray(contract.work_units) || !contract.work_units.length) blockers.push('slice-contract-work-units-missing');
+    for (const unit of contract.work_units || []) {
+      if (unit.contract_id !== contract.contract_id) blockers.push(`work-unit-contract-id-mismatch:${unit.id}`);
+      if (unit.contract_version !== contract.contract_version) blockers.push(`work-unit-contract-version-mismatch:${unit.id}`);
+      if (!unit.work_unit?.primary_skill) blockers.push(`work-unit-primary-skill-missing:${unit.id}`);
+    }
+    if (blockers.length) checks.structure = 'failed';
+  }
+  if (approval_ref && !blockers.length) {
+    try {
+      const approved_slice = { ...binding, approval_ref };
+      const context = createApprovedExecutionContext(approved_slice, { root, contract, work_unit_id });
+      checks.approval = 'passed';
+      const current = evaluateContractFreshness(contract, { root, registry: loadSkillRegistry(), compilerContract: loadCompilerContract(), approved_slice, work_unit_id }, context);
+      checks.freshness = current.freshness === 'current' ? 'passed' : 'failed';
+      blockers.push(...current.reasons);
+    } catch (error) {
+      checks.approval = 'failed';
+      blockers.push(error.code || error.message);
+    }
+  }
+  return { ...loaded, report: { read_only: true, ...binding, checks, approval_validity: checks.approval,
+    execution_allowed: !!approval_ref && !blockers.length && checks.freshness === 'passed', blockers } };
+}

package/template/scripts/slice-contract

@@ -4,13 +4,14 @@ import path from 'node:path';
 import { prepareSliceImplementationContract, migrateSliceContractV2, persistSliceDraft } from './lib/slice-contract-preparation.mjs';
 import { renderSliceContractView, diffSliceContracts } from './lib/slice-contract-views.mjs';
 import { parseSliceYaml, readSliceContract } from './lib/slice-contract.mjs';
+import { inspectSliceContract } from './lib/slice-execution-preflight.mjs';
 
 try {
   const args=process.argv.slice(2),mode=args.shift(),options={},positional=[];
   for(let i=0;i<args.length;i++) {
     if(args[i]==='--json'){options.json=true;continue;}
     if(args[i].startsWith('--')) {
-      const key=args[i].slice(2);if(!['root','input','output','unit','before-root'].includes(key)||!args[i+1])throw new Error(`未知或缺值参数 ${args[i]}`);
+      const key=args[i].slice(2);if(!['root','input','output','unit','before-root','approval-ref'].includes(key)||!args[i+1])throw new Error(`未知或缺值参数 ${args[i]}`);
       options[key]=args[++i];
     }else positional.push(args[i]);
   }
@@ -24,7 +25,10 @@ try {
     if(result.report.blockers.length)process.exitCode=1;
   }else if(mode==='view')result=renderSliceContractView(positional[0],{root,unit_id:options.unit});
   else if(mode==='diff')result=diffSliceContracts(positional[0],positional[1],{root,beforeRoot:options['before-root']?path.resolve(options['before-root']):root});
-  else if(mode==='verify')result={read_only:true,approval_validity:'not-checked',...readSliceContract(positional[0],{root}).binding};
-  else throw new Error('用法: scripts/slice-contract prepare <ticket> --input <补充.yaml> --output <新合同.yaml> | migrate <v2.yaml> --input <补充.yaml> --output <新合同.yaml> | view <合同.yaml> [--unit <id>] | diff <旧合同> <新合同> | verify <合同> [--root <项目根>]');
+  else if(mode==='verify') {
+    result=inspectSliceContract(positional[0],{root,approval_ref:options['approval-ref'],work_unit_id:options.unit}).report;
+    if(result.blockers.length)process.exitCode=1;
+  }
+  else throw new Error('用法: scripts/slice-contract prepare <ticket> --input <补充.yaml> --output <新合同.yaml> | migrate <v2.yaml> --input <补充.yaml> --output <新合同.yaml> | view <合同.yaml> [--unit <id>] | diff <旧合同> <新合同> | verify <合同> [--root <项目根>] [--approval-ref <批准记录>] [--unit <工作单元>]');
   process.stdout.write(options.json||!result.markdown?`${JSON.stringify(result,null,2)}\n`:`${result.markdown}\n`);
 }catch(error){process.stderr.write(`${error.message}\n`);process.exitCode=1;}