scene-capability-engine 3.6.65 → 3.6.67
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +16 -0
- package/README.md +17 -6
- package/README.zh.md +18 -6
- package/bin/scene-capability-engine.js +4 -0
- package/docs/README.md +2 -2
- package/docs/command-reference.md +382 -6
- package/docs/document-governance.md +3 -2
- package/docs/integration-modes.md +62 -478
- package/docs/integration-philosophy.md +56 -263
- package/docs/magicball-project-portfolio-contract.md +114 -2
- package/docs/project-management/README.md +14 -0
- package/docs/project-management/assurance/backup.md +3 -0
- package/docs/project-management/assurance/config.md +3 -0
- package/docs/project-management/assurance/evidence/README.md +3 -0
- package/docs/project-management/assurance/incidents/README.md +3 -0
- package/docs/project-management/assurance/logs.md +3 -0
- package/docs/project-management/assurance/overview.md +3 -0
- package/docs/project-management/assurance/recovery/README.md +3 -0
- package/docs/project-management/assurance/resource.md +3 -0
- package/docs/project-management/assurance/runbooks/README.md +3 -0
- package/docs/project-management/delivery/acceptance/README.md +3 -0
- package/docs/project-management/delivery/acceptance/evidence/README.md +3 -0
- package/docs/project-management/delivery/acceptance/exceptions/README.md +3 -0
- package/docs/project-management/delivery/acceptance/reports/README.md +3 -0
- package/docs/project-management/delivery/documents/changes.md +3 -0
- package/docs/project-management/delivery/documents/issues.md +3 -0
- package/docs/project-management/delivery/documents/overview.md +3 -0
- package/docs/project-management/delivery/documents/planning.md +3 -0
- package/docs/project-management/delivery/documents/requirements.md +3 -0
- package/docs/project-management/delivery/documents/tracking.md +3 -0
- package/docs/project-management/delivery/handoffs/README.md +3 -0
- package/docs/project-management/delivery/handoffs/evidence/README.md +3 -0
- package/docs/project-management/delivery/handoffs/records/README.md +3 -0
- package/docs/project-management/delivery/overview.md +10 -0
- package/docs/project-management/delivery/releases/README.md +3 -0
- package/docs/project-management/delivery/releases/baselines/README.md +3 -0
- package/docs/project-management/delivery/releases/evidence/README.md +3 -0
- package/docs/project-management/delivery/tables/changes.md +3 -0
- package/docs/project-management/delivery/tables/issues.md +3 -0
- package/docs/project-management/delivery/tables/planning.md +3 -0
- package/docs/project-management/delivery/tables/requirements.md +3 -0
- package/docs/project-management/delivery/tables/tracking.md +3 -0
- package/docs/project-management/environment/agent-discovery.md +3 -0
- package/docs/project-management/environment/development.md +3 -0
- package/docs/project-management/environment/overview.md +10 -0
- package/docs/project-management/environment/testing.md +3 -0
- package/docs/project-management/environment/version-alignment.md +3 -0
- package/docs/quick-start-with-ai-tools.md +68 -308
- package/docs/releases/README.md +2 -0
- package/docs/releases/v3.6.66.md +23 -0
- package/docs/releases/v3.6.67.md +23 -0
- package/docs/steering-governance.md +64 -2
- package/docs/zh/README.md +2 -2
- package/docs/zh/releases/README.md +2 -0
- package/docs/zh/releases/v3.6.66.md +23 -0
- package/docs/zh/releases/v3.6.67.md +23 -0
- package/lib/commands/adopt.js +24 -0
- package/lib/commands/native.js +158 -0
- package/lib/commands/project.js +95 -0
- package/lib/commands/semantic.js +1459 -0
- package/lib/commands/session.js +74 -3
- package/lib/commands/spec-bootstrap.js +10 -1
- package/lib/commands/spec-gate.js +10 -1
- package/lib/commands/spec-pipeline.js +10 -1
- package/lib/commands/studio.js +405 -30
- package/lib/commands/task.js +141 -7
- package/lib/governance/supreme-principles.js +530 -0
- package/lib/problem/problem-evaluator.js +4 -0
- package/lib/project/candidate-inspection-service.js +24 -1
- package/lib/project/portfolio-projection-service.js +315 -5
- package/lib/project/project-channel-output.js +94 -0
- package/lib/project/project-channel-projection.js +181 -0
- package/lib/project/root-onboarding-service.js +60 -8
- package/lib/project/semantic-shared-source-projection.js +150 -0
- package/lib/project/supervision-action-model.js +277 -0
- package/lib/project/supervision-projection-service.js +305 -5
- package/lib/project/target-resolution-service.js +70 -5
- package/lib/project/visibility-policy.js +93 -0
- package/lib/runtime/multi-spec-scene-session.js +8 -1
- package/lib/runtime/project-channel-context-store.js +387 -0
- package/lib/runtime/project-channel-context.js +406 -0
- package/lib/runtime/scene-session-binding.js +46 -0
- package/lib/runtime/session-store.js +186 -0
- package/lib/runtime/steering-contract.js +7 -1
- package/lib/semantic/archive-report.js +283 -0
- package/lib/semantic/archive-routing.js +67 -0
- package/lib/semantic/backflow-report.js +245 -0
- package/lib/semantic/capability-contract.js +30 -0
- package/lib/semantic/delta-export.js +145 -0
- package/lib/semantic/interaction-observer.js +254 -0
- package/lib/semantic/kernel-loader.js +881 -0
- package/lib/semantic/native-runtime.js +359 -0
- package/lib/semantic/progress-ledger.js +433 -0
- package/lib/semantic/replay-evaluator.js +382 -0
- package/lib/semantic/shared-publication.js +592 -0
- package/lib/semantic/shared-source-config.js +183 -0
- package/lib/semantic/shared-source-connect.js +139 -0
- package/lib/semantic/shared-source-discovery.js +98 -0
- package/lib/semantic/shared-sync-export.js +413 -0
- package/lib/semantic/shared-sync-intake.js +592 -0
- package/lib/semantic/shared-sync-merge.js +547 -0
- package/lib/semantic/shared-sync-release.js +463 -0
- package/lib/semantic/supreme-intent-report.js +300 -0
- package/lib/state/sce-state-store.js +1360 -0
- package/lib/steering/context-sync-manager.js +276 -25
- package/lib/studio/spec-intake-governor.js +39 -3
- package/lib/studio/task-envelope.js +35 -2
- package/lib/workspace/takeover-baseline.js +342 -83
- package/package.json +7 -2
- package/scripts/agent-governance-baseline-audit.js +395 -0
- package/scripts/clarification-first-audit.js +9 -9
- package/scripts/deprecated-entry-audit.js +240 -0
- package/scripts/release-posture-report.js +262 -0
- package/template/.sce/README.md +62 -228
- package/template/.sce/config/semantic-shared-sources.json +5 -0
- package/template/.sce/config/supreme-principles-policy.json +105 -0
- package/template/.sce/config/takeover-baseline.json +7 -0
- package/template/.sce/steering/CORE_PRINCIPLES.md +23 -63
- package/template/.sce/steering/CURRENT_CONTEXT.md +4 -0
- package/template/.sce/steering/RULES_GUIDE.md +17 -9
- package/template/README.md +32 -96
|
@@ -0,0 +1,262 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
'use strict';
|
|
3
|
+
|
|
4
|
+
const fs = require('fs');
|
|
5
|
+
const path = require('path');
|
|
6
|
+
|
|
7
|
+
const { auditDeprecatedEntry } = require('./deprecated-entry-audit');
|
|
8
|
+
const { auditReleaseDocs } = require('./release-doc-version-audit');
|
|
9
|
+
|
|
10
|
+
const STABLE_CORE_MARKERS = [
|
|
11
|
+
'npm run test:release',
|
|
12
|
+
'npm run audit:clarification-first',
|
|
13
|
+
'npm run audit:agent-governance',
|
|
14
|
+
'npm run audit:release-docs',
|
|
15
|
+
'npm run gate:git-managed',
|
|
16
|
+
'npm run gate:errorbook-release',
|
|
17
|
+
'npm run gate:errorbook-registry-health',
|
|
18
|
+
'Publish to npm'
|
|
19
|
+
];
|
|
20
|
+
|
|
21
|
+
const EXTENDED_EVIDENCE_MARKERS = [
|
|
22
|
+
'moqui',
|
|
23
|
+
'matrix-regression',
|
|
24
|
+
'interactive-matrix-signals',
|
|
25
|
+
'weekly ops',
|
|
26
|
+
'release-evidence',
|
|
27
|
+
'release-risk-remediation',
|
|
28
|
+
'state-migration-reconciliation'
|
|
29
|
+
];
|
|
30
|
+
|
|
31
|
+
function parseArgs(argv = process.argv.slice(2)) {
|
|
32
|
+
const options = {
|
|
33
|
+
projectPath: process.cwd(),
|
|
34
|
+
json: false,
|
|
35
|
+
failOnBlocking: false,
|
|
36
|
+
requireStable: false,
|
|
37
|
+
out: null
|
|
38
|
+
};
|
|
39
|
+
|
|
40
|
+
for (let index = 0; index < argv.length; index += 1) {
|
|
41
|
+
const token = argv[index];
|
|
42
|
+
const next = argv[index + 1];
|
|
43
|
+
if (token === '--project-path' && next) {
|
|
44
|
+
options.projectPath = path.resolve(next);
|
|
45
|
+
index += 1;
|
|
46
|
+
continue;
|
|
47
|
+
}
|
|
48
|
+
if (token === '--json') {
|
|
49
|
+
options.json = true;
|
|
50
|
+
continue;
|
|
51
|
+
}
|
|
52
|
+
if (token === '--fail-on-blocking') {
|
|
53
|
+
options.failOnBlocking = true;
|
|
54
|
+
continue;
|
|
55
|
+
}
|
|
56
|
+
if (token === '--require-stable') {
|
|
57
|
+
options.requireStable = true;
|
|
58
|
+
continue;
|
|
59
|
+
}
|
|
60
|
+
if (token === '--out' && next) {
|
|
61
|
+
options.out = path.resolve(next);
|
|
62
|
+
index += 1;
|
|
63
|
+
continue;
|
|
64
|
+
}
|
|
65
|
+
if (token === '--help' || token === '-h') {
|
|
66
|
+
printHelpAndExit(0);
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
return options;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function printHelpAndExit(code) {
|
|
74
|
+
const lines = [
|
|
75
|
+
'Usage: node scripts/release-posture-report.js [options]',
|
|
76
|
+
'',
|
|
77
|
+
'Options:',
|
|
78
|
+
' --project-path <path> Project root to inspect (default: current directory)',
|
|
79
|
+
' --json Print JSON payload',
|
|
80
|
+
' --fail-on-blocking Exit code 2 when blocking issues are found',
|
|
81
|
+
' --require-stable Exit code 2 unless posture resolves to stable',
|
|
82
|
+
' --out <path> Write JSON payload to file',
|
|
83
|
+
' -h, --help Show this help'
|
|
84
|
+
];
|
|
85
|
+
console.log(lines.join('\n'));
|
|
86
|
+
process.exit(code);
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
function countMarkers(content, markers) {
|
|
90
|
+
return markers.reduce((count, marker) => {
|
|
91
|
+
const regex = new RegExp(marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi');
|
|
92
|
+
const matches = content.match(regex);
|
|
93
|
+
return count + (matches ? matches.length : 0);
|
|
94
|
+
}, 0);
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
function auditReleasePosture(options = {}) {
|
|
98
|
+
const projectPath = path.resolve(options.projectPath || process.cwd());
|
|
99
|
+
const releaseWorkflowPath = path.join(projectPath, '.github', 'workflows', 'release.yml');
|
|
100
|
+
const blockers = [];
|
|
101
|
+
const warnings = [];
|
|
102
|
+
const signals = {
|
|
103
|
+
stable_core_markers_found: 0,
|
|
104
|
+
stable_core_markers_expected: STABLE_CORE_MARKERS.length,
|
|
105
|
+
extended_evidence_marker_count: 0,
|
|
106
|
+
release_workflow_exists: fs.existsSync(releaseWorkflowPath)
|
|
107
|
+
};
|
|
108
|
+
|
|
109
|
+
let workflowContent = '';
|
|
110
|
+
if (!signals.release_workflow_exists) {
|
|
111
|
+
blockers.push({
|
|
112
|
+
code: 'missing_release_workflow',
|
|
113
|
+
message: 'Release workflow is missing.'
|
|
114
|
+
});
|
|
115
|
+
} else {
|
|
116
|
+
workflowContent = fs.readFileSync(releaseWorkflowPath, 'utf8');
|
|
117
|
+
signals.stable_core_markers_found = STABLE_CORE_MARKERS.filter((marker) => workflowContent.includes(marker)).length;
|
|
118
|
+
signals.extended_evidence_marker_count = countMarkers(workflowContent, EXTENDED_EVIDENCE_MARKERS);
|
|
119
|
+
|
|
120
|
+
if (signals.stable_core_markers_found < STABLE_CORE_MARKERS.length) {
|
|
121
|
+
blockers.push({
|
|
122
|
+
code: 'stable_core_markers_missing',
|
|
123
|
+
message: `Release workflow only exposes ${signals.stable_core_markers_found}/${STABLE_CORE_MARKERS.length} stable-core markers.`
|
|
124
|
+
});
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
if (signals.extended_evidence_marker_count > 0) {
|
|
128
|
+
blockers.push({
|
|
129
|
+
code: 'release_workflow_mixes_extended_evidence',
|
|
130
|
+
message: 'Release workflow still mixes stable-core gates with extended evidence generation.'
|
|
131
|
+
});
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
const deprecatedEntry = auditDeprecatedEntry({ projectPath });
|
|
136
|
+
const releaseDocs = auditReleaseDocs({ projectPath });
|
|
137
|
+
|
|
138
|
+
if (!deprecatedEntry.passed) {
|
|
139
|
+
blockers.push({
|
|
140
|
+
code: 'deprecated_entry_drift',
|
|
141
|
+
message: `Deprecated entry audit found ${deprecatedEntry.violation_count} violation(s).`
|
|
142
|
+
});
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
if (!releaseDocs.passed) {
|
|
146
|
+
blockers.push({
|
|
147
|
+
code: 'release_doc_drift',
|
|
148
|
+
message: `Release doc audit found ${releaseDocs.error_count} error(s).`
|
|
149
|
+
});
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
if (signals.release_workflow_exists && !workflowContent.includes('audit:deprecated-entry')) {
|
|
153
|
+
warnings.push({
|
|
154
|
+
code: 'deprecated_entry_audit_not_wired',
|
|
155
|
+
message: 'Release workflow does not yet run deprecated-entry audit.'
|
|
156
|
+
});
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
if (signals.release_workflow_exists && !workflowContent.includes('gate:git-managed')) {
|
|
160
|
+
warnings.push({
|
|
161
|
+
code: 'git_managed_gate_not_wired',
|
|
162
|
+
message: 'Release workflow does not yet run git-managed gate.'
|
|
163
|
+
});
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
if (signals.release_workflow_exists && !workflowContent.includes('gate:errorbook-release')) {
|
|
167
|
+
warnings.push({
|
|
168
|
+
code: 'errorbook_release_gate_not_wired',
|
|
169
|
+
message: 'Release workflow does not yet run errorbook release gate.'
|
|
170
|
+
});
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
let posture = 'stable';
|
|
174
|
+
if (blockers.some((item) => item.code === 'missing_release_workflow' || item.code === 'stable_core_markers_missing')) {
|
|
175
|
+
posture = 'preview';
|
|
176
|
+
} else if (blockers.length > 0) {
|
|
177
|
+
posture = 'rc-candidate';
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
return {
|
|
181
|
+
mode: 'release-posture-report',
|
|
182
|
+
project_path: projectPath,
|
|
183
|
+
posture,
|
|
184
|
+
passed: blockers.length === 0,
|
|
185
|
+
blocking_count: blockers.length,
|
|
186
|
+
warning_count: warnings.length,
|
|
187
|
+
stable_required_checks: [
|
|
188
|
+
'test:release',
|
|
189
|
+
'clarification-first-audit',
|
|
190
|
+
'agent-governance-baseline-audit',
|
|
191
|
+
'release-doc-version-audit',
|
|
192
|
+
'git-managed-gate',
|
|
193
|
+
'errorbook-release-gate',
|
|
194
|
+
'errorbook-registry-health-gate',
|
|
195
|
+
'publish-to-npm'
|
|
196
|
+
],
|
|
197
|
+
advisory_checks: [
|
|
198
|
+
'deprecated-entry-audit',
|
|
199
|
+
'interactive-governance-report',
|
|
200
|
+
'release-asset-integrity',
|
|
201
|
+
'state-migration-reconciliation'
|
|
202
|
+
],
|
|
203
|
+
extended_evidence_examples: [
|
|
204
|
+
'moqui-*',
|
|
205
|
+
'matrix-regression',
|
|
206
|
+
'weekly ops',
|
|
207
|
+
'release-evidence bundles'
|
|
208
|
+
],
|
|
209
|
+
signals,
|
|
210
|
+
blockers,
|
|
211
|
+
warnings,
|
|
212
|
+
deprecated_entry_audit: {
|
|
213
|
+
passed: deprecatedEntry.passed,
|
|
214
|
+
violation_count: deprecatedEntry.violation_count
|
|
215
|
+
},
|
|
216
|
+
release_doc_audit: {
|
|
217
|
+
passed: releaseDocs.passed,
|
|
218
|
+
error_count: releaseDocs.error_count
|
|
219
|
+
}
|
|
220
|
+
};
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
function writeReportIfNeeded(report, outPath) {
|
|
224
|
+
if (!outPath) {
|
|
225
|
+
return;
|
|
226
|
+
}
|
|
227
|
+
const resolved = path.resolve(outPath);
|
|
228
|
+
fs.mkdirSync(path.dirname(resolved), { recursive: true });
|
|
229
|
+
fs.writeFileSync(resolved, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
function main() {
|
|
233
|
+
const options = parseArgs(process.argv.slice(2));
|
|
234
|
+
const report = auditReleasePosture(options);
|
|
235
|
+
writeReportIfNeeded(report, options.out);
|
|
236
|
+
|
|
237
|
+
if (options.json) {
|
|
238
|
+
process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
|
|
239
|
+
} else {
|
|
240
|
+
console.log(`[release-posture-report] posture=${report.posture} blockers=${report.blocking_count} warnings=${report.warning_count}`);
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
if ((options.failOnBlocking && report.blocking_count > 0) || (options.requireStable && report.posture !== 'stable')) {
|
|
244
|
+
process.exitCode = 2;
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
if (require.main === module) {
|
|
249
|
+
try {
|
|
250
|
+
main();
|
|
251
|
+
} catch (error) {
|
|
252
|
+
console.error(`[release-posture-report] ${error.message}`);
|
|
253
|
+
process.exit(1);
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
module.exports = {
|
|
258
|
+
STABLE_CORE_MARKERS,
|
|
259
|
+
EXTENDED_EVIDENCE_MARKERS,
|
|
260
|
+
parseArgs,
|
|
261
|
+
auditReleasePosture
|
|
262
|
+
};
|
package/template/.sce/README.md
CHANGED
|
@@ -1,248 +1,82 @@
|
|
|
1
|
-
# Project
|
|
2
|
-
|
|
3
|
-
> **AI Tools: Read this first!** This project follows Spec-driven development methodology powered by sce (Scene Capability Engine).
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## 🎯 How This Project Works
|
|
8
|
-
|
|
9
|
-
This project uses **Spec-driven development** - a structured approach where:
|
|
10
|
-
- Every feature starts with a **Spec** (requirements + design + tasks)
|
|
11
|
-
- All work is tracked and documented
|
|
12
|
-
- AI tools help implement features according to Specs
|
|
13
|
-
|
|
14
|
-
**Your role as AI:**
|
|
15
|
-
- When user requests a feature → Check if Spec exists, if not, help create one
|
|
16
|
-
- When implementing → Follow the Spec's requirements and design
|
|
17
|
-
- When stuck → Read the Spec documents for context
|
|
18
|
-
- When business scene/module/page/entity is unclear → Clarify scope first; do not replace missing understanding with blanket disable
|
|
19
|
-
- Track progress by updating task status
|
|
20
|
-
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
## 🚀 sce Capabilities
|
|
24
|
-
|
|
25
|
-
**IMPORTANT**: After installing or updating sce, read this section to understand all available capabilities. Using the right tool for the job ensures efficient, high-quality development.
|
|
26
|
-
|
|
27
|
-
### Core: Spec-Driven Development
|
|
28
|
-
- `sce adopt` — Initialize sce in a project (creates `.sce/` structure)
|
|
29
|
-
- `sce create-spec <name>` — Create a new Spec (requirements + design + tasks)
|
|
30
|
-
- `sce status` — Show project status and Spec progress
|
|
31
|
-
- `sce workflows` — List available Specs and workflows
|
|
32
|
-
- `sce context export <spec-name>` — Export Spec context for AI consumption
|
|
33
|
-
- `sce prompt generate <spec> <task>` — Generate task-specific prompt
|
|
34
|
-
|
|
35
|
-
### Task Management
|
|
36
|
-
- `sce task claim <spec> <task-id>` — Claim a task for execution
|
|
37
|
-
- `sce task list <spec>` — List claimed tasks
|
|
38
|
-
- Task status tracking in `tasks.md`: `[ ]` not started, `[-]` in progress, `[x]` completed
|
|
39
|
-
|
|
40
|
-
### Spec Locking (Multi-User)
|
|
41
|
-
- `sce lock acquire <spec>` — Lock a Spec to prevent conflicts
|
|
42
|
-
- `sce lock release <spec>` / `sce unlock <spec>` — Release lock
|
|
43
|
-
- `sce lock status` — Check lock status
|
|
44
|
-
- `sce lock cleanup` — Remove stale locks (24h timeout)
|
|
45
|
-
- `sce lock whoami` — Show machine identifier
|
|
46
|
-
|
|
47
|
-
### Workspace Management
|
|
48
|
-
- `sce workspace create/list/switch/info/remove` — Manage multiple sce projects
|
|
49
|
-
- Global state: `~/.sce/workspace-state.json`
|
|
50
|
-
|
|
51
|
-
### Environment Configuration
|
|
52
|
-
- `sce env list/switch/info/register/unregister/rollback/verify/run` — Multi-environment management
|
|
53
|
-
- Automatic backup before each switch, instant rollback support
|
|
54
|
-
|
|
55
|
-
### Multi-Repository Management
|
|
56
|
-
- `sce repo init [--nested]` — Auto-discover Git repositories
|
|
57
|
-
- `sce repo status [--verbose]` — Status of all repositories
|
|
58
|
-
- `sce repo exec "<command>"` — Execute command across all repos
|
|
59
|
-
- `sce repo health` — Check repository health
|
|
60
|
-
|
|
61
|
-
### Spec-Level Collaboration
|
|
62
|
-
- `sce collab init/status/assign/verify/integrate/migrate` — Coordinate parallel Spec development
|
|
63
|
-
- Master Spec + Sub-Specs with dependency management
|
|
64
|
-
- Interface contracts for cross-Spec compatibility
|
|
65
|
-
|
|
66
|
-
### Multi-Agent Parallel Coordination
|
|
67
|
-
When multiple AI agents work on the same project simultaneously:
|
|
68
|
-
- **AgentRegistry** (`lib/collab`) — Agent lifecycle with heartbeat monitoring
|
|
69
|
-
- **TaskLockManager** (`lib/lock`) — File-based task mutual exclusion
|
|
70
|
-
- **TaskStatusStore** (`lib/task`) — Concurrent-safe tasks.md updates with retry
|
|
71
|
-
- **SteeringFileLock** (`lib/lock`) — Steering file write serialization
|
|
72
|
-
- **MergeCoordinator** (`lib/collab`) — Git branch isolation per agent
|
|
73
|
-
- **Coordinator** (`lib/collab`) — Central task assignment (optional)
|
|
74
|
-
- Config: `.sce/config/multi-agent.json` (default `enabled: true`; set `enabled: false` to opt out)
|
|
75
|
-
- If a project opts out with `enabled: false`, all components fall back to single-agent no-op behavior
|
|
76
|
-
- See `docs/multi-agent-coordination-guide.md` for full API reference
|
|
77
|
-
|
|
78
|
-
### Spec-Level Steering & Context Sync
|
|
79
|
-
Fourth steering layer (L4) and Spec lifecycle coordination for multi-agent scenarios:
|
|
80
|
-
- **SpecSteering** (`lib/steering`) — Per-Spec `steering.md` CRUD with template generation, Markdown ↔ structured object roundtrip
|
|
81
|
-
- **SteeringLoader** (`lib/steering`) — Unified L1-L4 four-layer steering loader with merged output
|
|
82
|
-
- **ContextSyncManager** (`lib/steering`) — Multi-agent CURRENT_CONTEXT.md maintenance with Spec progress table, SteeringFileLock-protected writes
|
|
83
|
-
- **SpecLifecycleManager** (`lib/collab`) — Spec state machine (planned → assigned → in-progress → completed → released) with auto-completion detection
|
|
84
|
-
- **SyncBarrier** (`lib/collab`) — Agent Spec-switch synchronization barrier (uncommitted changes check, steering reload)
|
|
85
|
-
- **Coordinator Integration** — `completeTask` auto-checks Spec completion; `assignTask` runs SyncBarrier
|
|
86
|
-
- If needed, a project can still opt out by setting `enabled: false`, which restores single-agent no-op behavior
|
|
87
|
-
- See `docs/multi-agent-coordination-guide.md` for full API reference
|
|
88
|
-
|
|
89
|
-
### Autonomous Control
|
|
90
|
-
- `sce auto create <description>` — Create and execute Spec autonomously
|
|
91
|
-
- `sce auto run <spec>` — Execute existing Spec tasks autonomously
|
|
92
|
-
- `sce auto status/resume/stop/config` — Manage autonomous execution
|
|
93
|
-
- Intelligent error recovery, checkpoint system, learning from history
|
|
94
|
-
|
|
95
|
-
### Agent Orchestrator — Multi-Agent Spec Execution
|
|
96
|
-
Automate parallel Spec execution via Codex CLI sub-agents (replaces manual multi-terminal workflow):
|
|
97
|
-
- `sce orchestrate run --specs "spec-a,spec-b,spec-c" --max-parallel 3` — Start multi-agent orchestration
|
|
98
|
-
- `sce orchestrate status` — View orchestration progress (per-Spec status, overall state)
|
|
99
|
-
- `sce orchestrate stop` — Gracefully stop all sub-agents
|
|
100
|
-
- **OrchestratorConfig** (`lib/orchestrator`) — Configuration management (agent backend, parallelism, timeout, retries) via `.sce/config/orchestrator.json`
|
|
101
|
-
- **BootstrapPromptBuilder** (`lib/orchestrator`) — Builds bootstrap prompts with Spec path, steering context, execution instructions
|
|
102
|
-
- **AgentSpawner** (`lib/orchestrator`) — Process manager for Codex CLI sub-agents with timeout detection, graceful termination (SIGTERM → SIGKILL)
|
|
103
|
-
- **StatusMonitor** (`lib/orchestrator`) — Codex JSON Lines event parsing, per-Spec status tracking, orchestration-level aggregation
|
|
104
|
-
- **OrchestrationEngine** (`lib/orchestrator`) — DAG-based dependency analysis, batch scheduling, parallel execution (≤ maxParallel), failure propagation, retry mechanism
|
|
105
|
-
- Prerequisites: Codex CLI installed, `CODEX_API_KEY` environment variable set
|
|
106
|
-
- 11 correctness properties verified via property-based testing
|
|
107
|
-
|
|
108
|
-
### Scene Runtime (Template Engine + Quality + ERP)
|
|
109
|
-
- **Template Engine**: `sce scene template-validate/resolve/render` — Variable schema, multi-file rendering, 3-layer inheritance
|
|
110
|
-
- **Package Registry**: `sce scene publish/unpublish/install/list/search/info/diff/version` — Local package management
|
|
111
|
-
- **Quality Pipeline**: `sce scene lint/score/contribute` — 10-category lint, quality scoring, one-stop publish
|
|
112
|
-
- **Ontology**: `sce scene ontology show/deps/validate/actions/lineage/agent-info` — Semantic relationship graph
|
|
113
|
-
- **Moqui ERP**: `sce scene connect/discover/extract` — ERP integration and template extraction
|
|
114
|
-
- **Registry Ops**: `sce scene deprecate/audit/owner/tag/lock/stats` — Advanced registry management
|
|
115
|
-
|
|
116
|
-
### Document Governance
|
|
117
|
-
- `sce docs diagnose/cleanup/validate/archive/hooks` — Document lifecycle management
|
|
118
|
-
- Automatic compliance checking and cleanup
|
|
119
|
-
|
|
120
|
-
### DevOps Integration
|
|
121
|
-
- `sce ops init/validate/audit/takeover/feedback` — Operations Spec management
|
|
122
|
-
- Progressive AI autonomy levels (L1-L5)
|
|
123
|
-
|
|
124
|
-
### Knowledge Management
|
|
125
|
-
- `sce knowledge init/add/list/search/show/delete/stats` — Personal knowledge base
|
|
126
|
-
|
|
127
|
-
---
|
|
128
|
-
|
|
129
|
-
## 📋 Development Workflow
|
|
130
|
-
|
|
131
|
-
### When User Asks You to Implement a Feature
|
|
132
|
-
|
|
133
|
-
**Step 1: Check if Spec exists**
|
|
134
|
-
```
|
|
135
|
-
Look in .sce/specs/ directory
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
**Step 2: If Spec exists**
|
|
139
|
-
- Read `requirements.md` - understand what to build
|
|
140
|
-
- Read `design.md` - understand how to build it
|
|
141
|
-
- Read `tasks.md` - see implementation steps
|
|
142
|
-
- Implement according to the Spec
|
|
143
|
-
- Update task status as you complete work
|
|
1
|
+
# Project Delivery Guide
|
|
144
2
|
|
|
145
|
-
|
|
146
|
-
- Suggest creating a Spec first
|
|
147
|
-
- Help user define requirements
|
|
148
|
-
- Help design the solution
|
|
149
|
-
- Break down into tasks
|
|
150
|
-
- Then implement
|
|
3
|
+
> Read this file first after SCE takes over a project.
|
|
151
4
|
|
|
152
|
-
|
|
5
|
+
This project is governed by SCE. Work is not managed as a loose chat transcript. It is managed through governed project, channel, scene, spec, task, and evidence objects.
|
|
153
6
|
|
|
154
|
-
|
|
155
|
-
1. Register with AgentRegistry before starting work
|
|
156
|
-
2. Acquire task locks before modifying any task
|
|
157
|
-
3. Use TaskStatusStore for concurrent-safe tasks.md updates
|
|
158
|
-
4. Use SteeringFileLock when updating steering files
|
|
159
|
-
5. Deregister when done (auto-releases all locks)
|
|
7
|
+
## Operating Baseline
|
|
160
8
|
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
.sce/
|
|
167
|
-
├── README.md # This file - project development guide
|
|
168
|
-
├── specs/ # All Specs live here
|
|
169
|
-
│ └── {spec-name}/ # Individual Spec
|
|
170
|
-
│ ├── requirements.md # What we're building
|
|
171
|
-
│ ├── design.md # How we'll build it
|
|
172
|
-
│ ├── tasks.md # Implementation steps
|
|
173
|
-
│ ├── steering.md # Spec-level steering (L4, multi-agent)
|
|
174
|
-
│ ├── lifecycle.json # Spec lifecycle state (multi-agent)
|
|
175
|
-
│ └── locks/ # Task lock files (multi-agent)
|
|
176
|
-
├── steering/ # Development rules (auto-loaded by AI)
|
|
177
|
-
│ ├── CORE_PRINCIPLES.md # Core development principles
|
|
178
|
-
│ ├── ENVIRONMENT.md # Project environment
|
|
179
|
-
│ ├── CURRENT_CONTEXT.md # Current work context
|
|
180
|
-
│ └── RULES_GUIDE.md # Rules index
|
|
181
|
-
├── config/ # Configuration files
|
|
182
|
-
│ ├── multi-agent.json # Multi-agent coordination config
|
|
183
|
-
│ ├── agent-registry.json # Active agent registry
|
|
184
|
-
│ └── coordination-log.json # Coordinator assignment log
|
|
185
|
-
└── tools/ # Tool configurations
|
|
186
|
-
```
|
|
9
|
+
- Read `.sce/steering/CORE_PRINCIPLES.md` first
|
|
10
|
+
- Read `.sce/steering/RULES_GUIDE.md` for execution baselines
|
|
11
|
+
- Treat `.sce/steering/CURRENT_CONTEXT.md` as a summary, not the truth source
|
|
12
|
+
- Use the active Spec files as the primary work contract
|
|
13
|
+
- Keep all generated artifacts under governed Spec directories
|
|
187
14
|
|
|
188
|
-
|
|
189
|
-
- `.sce/steering/CORE_PRINCIPLES.md` - Development principles for this project
|
|
190
|
-
- `.sce/steering/CURRENT_CONTEXT.md` - What we're currently working on
|
|
191
|
-
- `.sce/specs/{spec-name}/` - Feature specifications
|
|
15
|
+
## Core Model
|
|
192
16
|
|
|
193
|
-
|
|
17
|
+
- `project -> scene -> spec`
|
|
18
|
+
- `project -> channel/session -> (scene + spec focus) -> task -> event`
|
|
19
|
+
- `scene` is the semantic continuity boundary
|
|
20
|
+
- `channel/session` is the collaboration unit
|
|
21
|
+
- `spec` is the governed work package
|
|
22
|
+
- `task` is the smallest user-facing execution unit
|
|
194
23
|
|
|
195
|
-
|
|
24
|
+
One project may host multiple collaboration channels in parallel by default.
|
|
196
25
|
|
|
197
|
-
|
|
26
|
+
- Do not assume there is only one current session
|
|
27
|
+
- `focusedChannelId` only marks the current UI focus
|
|
28
|
+
- Every `project + channel/session` must preserve its own `scene/spec/doc/session/tabs/tree/draft/runState`
|
|
29
|
+
- Never collapse other channels back into one global current-context slot
|
|
198
30
|
|
|
199
|
-
|
|
200
|
-
- User stories, functional requirements, acceptance criteria
|
|
31
|
+
## How To Execute Work
|
|
201
32
|
|
|
202
|
-
|
|
203
|
-
|
|
33
|
+
1. Understand the real user goal first, then verify facts in code/spec/state before deciding.
|
|
34
|
+
2. Bind the work to the correct scene/spec path before implementation.
|
|
35
|
+
3. Keep changes, evidence, and follow-up under the active Spec.
|
|
36
|
+
4. Use `spec pipeline` and `spec gate` to keep delivery governed.
|
|
37
|
+
5. Use project/semantic supervision views to inspect cross-spec or cross-channel drift.
|
|
204
38
|
|
|
205
|
-
|
|
206
|
-
- Ordered task list with dependencies and implementation notes
|
|
207
|
-
- Status: `- [ ]` Not started | `- [-]` In progress | `- [x]` Completed
|
|
39
|
+
If the request is not yet tied to a concrete Spec, create or route it through governed planning first.
|
|
208
40
|
|
|
209
|
-
|
|
41
|
+
```bash
|
|
42
|
+
sce studio plan --goal "clarify and stage work" --json
|
|
43
|
+
sce spec bootstrap --name 01-00-example --scene scene.example --non-interactive
|
|
44
|
+
sce spec pipeline run --spec 01-00-example --scene scene.example
|
|
45
|
+
sce spec gate run --spec 01-00-example --scene scene.example --json
|
|
46
|
+
```
|
|
210
47
|
|
|
211
|
-
##
|
|
48
|
+
## Mandatory Execution Behaviors
|
|
212
49
|
|
|
213
|
-
|
|
214
|
-
-
|
|
215
|
-
-
|
|
216
|
-
-
|
|
217
|
-
-
|
|
218
|
-
-
|
|
219
|
-
-
|
|
50
|
+
- Supreme-principle layer is `Four Teachings + Little Nine`
|
|
51
|
+
- All agent-generated logs, reports, debug artifacts, and test scripts default into the active Spec subtree
|
|
52
|
+
- If there is no explicit active Spec yet, use a governed general Spec
|
|
53
|
+
- Temporary analysis documents should be removed after the work is complete
|
|
54
|
+
- Do not let documents spread outside governed Spec locations
|
|
55
|
+
- After more than two failed localization rounds, record/update the `errorbook` incident and use bisection-style debug logs to halve the search scope
|
|
56
|
+
- Do not throw unresolved blocking analysis back to the user until you have actively decomposed and localized it
|
|
220
57
|
|
|
221
|
-
|
|
222
|
-
- ❌ Start implementing without understanding requirements
|
|
223
|
-
- ❌ Ignore the design document
|
|
224
|
-
- ❌ Create files in wrong locations (use Spec directories)
|
|
225
|
-
- ❌ Skip updating task status
|
|
226
|
-
- ❌ Modify tasks.md without locks in multi-agent mode
|
|
58
|
+
## Useful Commands
|
|
227
59
|
|
|
228
|
-
|
|
60
|
+
```bash
|
|
61
|
+
sce status
|
|
62
|
+
sce studio plan --goal "continue current work" --json
|
|
63
|
+
sce task ref --json
|
|
64
|
+
sce project supervision show --json
|
|
65
|
+
sce semantic progress --json
|
|
66
|
+
```
|
|
229
67
|
|
|
230
|
-
##
|
|
68
|
+
## Project Layout
|
|
231
69
|
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
| Multi-agent setup | `.sce/config/multi-agent.json` |
|
|
241
|
-
| Full documentation | `docs/` directory |
|
|
70
|
+
```text
|
|
71
|
+
.sce/
|
|
72
|
+
├── README.md
|
|
73
|
+
├── steering/
|
|
74
|
+
├── config/
|
|
75
|
+
├── specs/
|
|
76
|
+
└── state/sce-state.sqlite
|
|
77
|
+
```
|
|
242
78
|
|
|
243
|
-
|
|
79
|
+
The active truth is in the current project state plus the active Spec subtree, not in historical chat output.
|
|
244
80
|
|
|
245
|
-
**
|
|
246
|
-
**
|
|
247
|
-
**Last Updated**: 2026-03-22
|
|
248
|
-
**Purpose**: Guide AI tools to work effectively with this project
|
|
81
|
+
**sce Version**: 3.6.67
|
|
82
|
+
**Last Updated**: 2026-03-29
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schema_version": "1.0",
|
|
3
|
+
"enabled": true,
|
|
4
|
+
"allow_planning_actions": [
|
|
5
|
+
"allow",
|
|
6
|
+
"clarify",
|
|
7
|
+
"rewrite",
|
|
8
|
+
"narrow"
|
|
9
|
+
],
|
|
10
|
+
"allow_execution_actions": [
|
|
11
|
+
"allow",
|
|
12
|
+
"rewrite",
|
|
13
|
+
"narrow"
|
|
14
|
+
],
|
|
15
|
+
"clarify_question": "请先明确你真正要达成的业务目标、作用对象和约束边界。",
|
|
16
|
+
"refuse_message": "该请求不符合 SCE 的最高道德规范,不能直接执行。",
|
|
17
|
+
"rewrite_message": "原始请求存在失范或越界风险,已收敛为可正当执行的目标。",
|
|
18
|
+
"narrow_message": "原始请求风险过高,已收缩为审查、备份、验证优先的安全目标。",
|
|
19
|
+
"refuse_rules": [
|
|
20
|
+
{
|
|
21
|
+
"id": "credential-theft",
|
|
22
|
+
"keywords": [
|
|
23
|
+
"steal password",
|
|
24
|
+
"dump token",
|
|
25
|
+
"exfiltrate",
|
|
26
|
+
"keylogger",
|
|
27
|
+
"phish",
|
|
28
|
+
"窃取密码",
|
|
29
|
+
"盗取令牌",
|
|
30
|
+
"导出凭证"
|
|
31
|
+
],
|
|
32
|
+
"reason": "请求明显指向凭证盗取、数据外流或钓鱼等恶意行为。"
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
"id": "malware-abuse",
|
|
36
|
+
"keywords": [
|
|
37
|
+
"malware",
|
|
38
|
+
"ransomware",
|
|
39
|
+
"backdoor",
|
|
40
|
+
"payload",
|
|
41
|
+
"木马",
|
|
42
|
+
"勒索软件",
|
|
43
|
+
"后门"
|
|
44
|
+
],
|
|
45
|
+
"reason": "请求明显指向恶意控制、破坏或持久化投毒。"
|
|
46
|
+
},
|
|
47
|
+
{
|
|
48
|
+
"id": "audit-evasion",
|
|
49
|
+
"keywords": [
|
|
50
|
+
"delete logs to hide",
|
|
51
|
+
"evade audit",
|
|
52
|
+
"disable audit trail",
|
|
53
|
+
"清除日志掩盖",
|
|
54
|
+
"绕过审计",
|
|
55
|
+
"删除审计日志"
|
|
56
|
+
],
|
|
57
|
+
"reason": "请求明显指向规避责任、破坏审计或掩盖痕迹。"
|
|
58
|
+
}
|
|
59
|
+
],
|
|
60
|
+
"rewrite_rules": [
|
|
61
|
+
{
|
|
62
|
+
"id": "auth-bypass-to-safe-test-fixture",
|
|
63
|
+
"keywords": [
|
|
64
|
+
"disable auth",
|
|
65
|
+
"bypass auth",
|
|
66
|
+
"skip login",
|
|
67
|
+
"skip approval",
|
|
68
|
+
"关闭认证",
|
|
69
|
+
"绕过认证",
|
|
70
|
+
"跳过登录",
|
|
71
|
+
"跳过审批"
|
|
72
|
+
],
|
|
73
|
+
"replacement": "Design a dev/test-only mechanism with explicit scope guard, audit trail, rollback plan, and no production bypass of authentication or approval controls.",
|
|
74
|
+
"reason": "将越界的“绕过保护”目标改写为受边界约束的测试/诊断机制。"
|
|
75
|
+
},
|
|
76
|
+
{
|
|
77
|
+
"id": "remove-audit-to-safe-observability",
|
|
78
|
+
"keywords": [
|
|
79
|
+
"remove audit",
|
|
80
|
+
"turn off audit",
|
|
81
|
+
"delete logs",
|
|
82
|
+
"关闭审计",
|
|
83
|
+
"删除日志",
|
|
84
|
+
"去掉审计"
|
|
85
|
+
],
|
|
86
|
+
"replacement": "Design a safe observability adjustment that preserves required auditability, keeps retention boundaries, and reduces noise without deleting accountability evidence.",
|
|
87
|
+
"reason": "将“去掉审计/日志”改写为保留责任边界的可观测性优化目标。"
|
|
88
|
+
}
|
|
89
|
+
],
|
|
90
|
+
"narrow_rules": [
|
|
91
|
+
{
|
|
92
|
+
"id": "destructive-production-change",
|
|
93
|
+
"keywords": [
|
|
94
|
+
"drop database",
|
|
95
|
+
"delete production data",
|
|
96
|
+
"truncate table",
|
|
97
|
+
"删除生产数据",
|
|
98
|
+
"清空数据表",
|
|
99
|
+
"删库"
|
|
100
|
+
],
|
|
101
|
+
"replacement": "Review the destructive change request, produce backup and rollback steps, verify scope, and require explicit confirmation before any irreversible data operation.",
|
|
102
|
+
"reason": "高风险破坏性操作必须先收缩为审查、备份和回滚准备。"
|
|
103
|
+
}
|
|
104
|
+
]
|
|
105
|
+
}
|