prizmkit 1.1.193 → 1.1.195
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/bin/create-prizmkit.js +43 -12
- package/bundled/VERSION.json +3 -3
- package/bundled/dev-pipeline/.env.example +5 -0
- package/bundled/dev-pipeline/README.md +2 -1
- package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py +111 -30
- package/bundled/dev-pipeline/prizmkit_runtime/cli.py +44 -3
- package/bundled/dev-pipeline/prizmkit_runtime/commands.py +29 -9
- package/bundled/dev-pipeline/prizmkit_runtime/config.py +121 -44
- package/bundled/dev-pipeline/prizmkit_runtime/daemon.py +190 -37
- package/bundled/dev-pipeline/prizmkit_runtime/interoperability.py +1 -0
- package/bundled/dev-pipeline/prizmkit_runtime/iterate.py +2480 -0
- package/bundled/dev-pipeline/prizmkit_runtime/paths.py +3 -0
- package/bundled/dev-pipeline/prizmkit_runtime/runner_bookkeeping.py +32 -8
- package/bundled/dev-pipeline/prizmkit_runtime/runners.py +29 -12
- package/bundled/dev-pipeline/prizmkit_runtime/runtime_commit.py +13 -5
- package/bundled/dev-pipeline/prizmkit_runtime/status.py +166 -0
- package/bundled/dev-pipeline/scripts/feature_list_contract.py +964 -0
- package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py +18 -40
- package/bundled/dev-pipeline/scripts/generate-bugfix-prompt.py +24 -19
- package/bundled/dev-pipeline/scripts/prompt_framework.py +24 -8
- package/bundled/dev-pipeline/templates/bootstrap-tier3.md +1 -63
- package/bundled/dev-pipeline/templates/bug-fix-list-schema.json +8 -6
- package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md +0 -10
- package/bundled/dev-pipeline/templates/feature-list-schema.json +8 -6
- package/bundled/dev-pipeline/templates/iterate/evaluate-prompt.md +97 -0
- package/bundled/dev-pipeline/templates/iterate/evaluation-schema.json +538 -0
- package/bundled/dev-pipeline/templates/iterate/headless-plan-prompt.md +66 -0
- package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md +2 -2
- package/bundled/dev-pipeline/templates/sections/runtime-commit-handoff.md +13 -4
- package/bundled/rules/USAGE.md +15 -48
- package/bundled/rules/_rules-metadata.json +7 -14
- package/bundled/rules/general/coding-baseline.md +23 -0
- package/bundled/rules/prizm/prizm-progressive-loading.md +2 -2
- package/bundled/skills/_metadata.json +12 -42
- package/bundled/skills/app-planner/SKILL.md +2 -2
- package/bundled/skills/app-planner/references/generated-plan-review.md +2 -2
- package/bundled/skills/app-planner/references/project-state-detection.md +1 -1
- package/bundled/skills/app-planner/references/rules-configuration.md +158 -88
- package/bundled/skills/app-planner/scripts/validate-rules-configuration.py +543 -12
- package/bundled/skills/bug-planner/references/verification.md +4 -5
- package/bundled/skills/bugfix-pipeline-launcher/SKILL.md +20 -14
- package/bundled/skills/bugfix-pipeline-launcher/references/configuration.md +49 -9
- package/bundled/skills/feature-pipeline-launcher/SKILL.md +20 -14
- package/bundled/skills/feature-pipeline-launcher/references/configuration.md +49 -9
- package/bundled/skills/feature-planner/SKILL.md +3 -3
- package/bundled/skills/feature-planner/references/browser-interaction.md +9 -29
- package/bundled/skills/iterate-pipeline-launcher/SKILL.md +273 -0
- package/bundled/skills/iterate-pipeline-launcher/references/configuration.md +105 -0
- package/bundled/skills/prizmkit-code-review/SKILL.md +10 -8
- package/bundled/skills/prizmkit-code-review/references/independent-code-review.md +4 -1
- package/bundled/skills/prizmkit-code-review/references/review-report-template.md +2 -1
- package/bundled/skills/prizmkit-code-review/scripts/render_review_report.py +12 -8
- package/bundled/skills/prizmkit-implement/SKILL.md +2 -2
- package/bundled/skills/prizmkit-init/SKILL.md +10 -10
- package/bundled/skills/prizmkit-init/references/brownfield-deep-init.md +81 -0
- package/bundled/skills/prizmkit-plan/SKILL.md +2 -1
- package/bundled/skills/prizmkit-plan/assets/plan-template.md +2 -0
- package/bundled/skills/prizmkit-prizm-docs/SKILL.md +8 -4
- package/bundled/skills/prizmkit-prizm-docs/assets/prizm-docs-format.md +8 -7
- package/bundled/skills/prizmkit-prizm-docs/references/op-init.md +33 -16
- package/bundled/skills/prizmkit-prizm-docs/references/op-validate.md +1 -1
- package/bundled/skills/prizmkit-retrospective/SKILL.md +29 -12
- package/bundled/skills/prizmkit-retrospective/references/retrospective-result-schema.json +126 -2
- package/bundled/skills/prizmkit-retrospective/references/rule-evolution-steps.md +86 -0
- package/bundled/skills/prizmkit-test/SKILL.md +2 -1
- package/bundled/skills/prizmkit-workflow/SKILL.md +8 -0
- package/bundled/skills/prizmkit-workflow/references/cold-start-rules.md +84 -0
- package/bundled/templates/project-memory-template.md +3 -3
- package/package.json +1 -1
- package/src/clean.js +2 -3
- package/src/config.js +52 -39
- package/src/index.js +29 -111
- package/src/prompts.js +20 -87
- package/src/runtime-passthrough.js +324 -0
- package/src/scaffold.js +41 -294
- package/src/upgrade.js +7 -39
- package/bundled/dev-pipeline/templates/sections/phase-browser-verification-auto.md +0 -127
- package/bundled/dev-pipeline/templates/sections/phase-browser-verification-opencli.md +0 -124
- package/src/external-skills.js +0 -103
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Brownfield Deep Initialization — Core L2 Construction Protocol
|
|
2
|
+
|
|
3
|
+
Use this reference during Phase 5 of `/prizmkit-init` when the repository is in **Brownfield mode** (existing source code detected).
|
|
4
|
+
|
|
5
|
+
## Mode Boundary: Greenfield vs Brownfield
|
|
6
|
+
|
|
7
|
+
- **Greenfield / nearly empty projects** (no source code): do **not** run this protocol. Generate only a minimal `.prizmkit/prizm-docs/root.prizm` (L0) skeleton (`PRIZM_VERSION: 4`, `PROJECT`, `LANG`, `MODULE_INDEX: []`, core `RULES:`, and optional user-supplied `TECH_STACK:`) with **zero L1** and **zero L2** files.
|
|
8
|
+
- **Brownfield projects** (existing source code): run default core-module deep construction producing:
|
|
9
|
+
- L0: exact `.prizmkit/prizm-docs/root.prizm` (`PRIZM_VERSION: 4`, concise project map, `MODULE_INDEX` or capacity-safe `MODULE_GROUPS` when >15 modules or capacity requires, preserving any existing `LAYER_RULES:` block analogously to `PROJECT_BRIEF:` without converting it into MUST/NEVER `RULES:` entries or globbing `.prizmkit/rules/`);
|
|
10
|
+
- L1: one direct-child `.prizmkit/prizm-docs/<M>.prizm` structural index per top-level source module;
|
|
11
|
+
- L2: source-evidenced, Value-Gate-qualified nested `.prizmkit/prizm-docs/<M>/<S>.prizm` (mirrored first) or deterministic `.prizmkit/prizm-docs/<M>/<concern-slug>.prizm` (semantic only on flat-module overflow) documents for qualifying core modules.
|
|
12
|
+
|
|
13
|
+
## Hard Boundary: Legitimate Brownfield L2 vs Prohibited Placeholder L2
|
|
14
|
+
|
|
15
|
+
**Prohibited placeholder L2 files remain strictly forbidden**:
|
|
16
|
+
- Never generate an L2 guessed from directory names, file paths, or shallow directory listings without reading source files.
|
|
17
|
+
- Never repeat source-derivable signatures, boilerplate exports, or low-value file inventories.
|
|
18
|
+
- Never pad sections with `TBD`, `TODO`, generic advice, or fabricated traps/decisions.
|
|
19
|
+
|
|
20
|
+
**Legitimate Brownfield L2 qualification criteria**:
|
|
21
|
+
1. **Actual source and contract-test inspection**: Read the module's entry file(s), core implementation files, and 1–2 representative contract or behavior test files (when tests exist).
|
|
22
|
+
2. **Value Gate minimum**: Extract only facts that pass the future-incorrect-modification Value Gate (`Could a future AI that lacks this fact make an incorrect modification?`). Every generated Brownfield L2 must contain **at least two non-obvious durable facts** (for example, wire/public contracts, cross-module invariants, state transitions, side effects, concurrency/transaction boundaries, security/auth checks, or architectural constraints). If deep-reading a candidate yields fewer than two Value-Gate-qualified non-obvious facts, do **not** force-create an L2; keep the directory as a structural-only entry in parent L1 without `->`.
|
|
23
|
+
3. **Mirrored L2 shape and inline `TRAPS: none` rule**:
|
|
24
|
+
- Required fields: `MODULE`, `FILES`, `RESPONSIBILITY`, `INTERFACES`, `KEY_FILES`, `DEPENDENCIES`, `TRAPS` (never `CONCERN`).
|
|
25
|
+
- Omit optional sections (`DATA_FLOW`, `RULES`, `DECISIONS`, domain-specific sections) when no fact passes the Value Gate.
|
|
26
|
+
- When no source-evidenced trap exists, render `TRAPS: none` **inline** on the header line (never as a list item `- none`, which fails trap-severity validation). Likewise render `INTERFACES: none` inline when no non-obvious public/wire contract exists.
|
|
27
|
+
- Every concrete trap entry must use `- [CRITICAL|HIGH|LOW] <description> | FIX: <approach>`.
|
|
28
|
+
4. **Semantic L2 (flat-module overflow only)**:
|
|
29
|
+
- Always prefer mirrored `.prizmkit/prizm-docs/<M>/<S>.prizm` for real source submodules.
|
|
30
|
+
- Use deterministic semantic `.prizmkit/prizm-docs/<M>/<concern-slug>.prizm` **only** when a flat source module contains multiple stable domain behavior concerns and required protected knowledge cannot fit one 5120B L2 after Value/Cleanup filtering.
|
|
31
|
+
- Semantic L2 requires the complete terminal shape (`MODULE`, `CONCERN: <stable concern identity> | SLUG: <concern-slug>`, `FILES`, `RESPONSIBILITY`, `INTERFACES`, `DATA_FLOW`, `KEY_FILES`, `DEPENDENCIES`, `RULES`, `TRAPS`, `DECISIONS`), Unicode NFKC -> lowercase -> kebab-case slug normalization, explicit non-empty non-overlapping repository-relative `FILES`, mirrored-submodule precedence, one matching direct-child L1 `DETAILS:` pointer (`- <concern-slug>: <one-line stable behavior summary> -> .prizmkit/prizm-docs/<M>/<concern-slug>.prizm`), and inline `<SECTION>: none` for any empty required behavioral section.
|
|
32
|
+
- Block on ambiguous boundaries, empty slugs, mirrored-path/slug collisions, or overlapping ownership; never resolve with task IDs or numeric suffixes (`-2`, `-003`).
|
|
33
|
+
|
|
34
|
+
## Six Deterministic Core-Module Selection Signals
|
|
35
|
+
|
|
36
|
+
Evaluate discovered submodules (and flat top-level modules) using these six high-signal criteria:
|
|
37
|
+
|
|
38
|
+
1. **System entry points and routing / command dispatch**: HTTP/RPC routers, CLI command dispatchers, application bootstraps, request/event entry handlers.
|
|
39
|
+
2. **Core business domain and state machines**: domain services, workflow/orchestration engines, rule/policy evaluators, explicit state-transition logic.
|
|
40
|
+
3. **Data models and persistence / migration boundaries**: schemas, ORM entities, repositories, storage engines, transactional/migration boundaries.
|
|
41
|
+
4. **Authentication, authorization, and security boundaries**: authn/authz flows, token/session verification, permission guards, cryptographic or secret/trust boundaries.
|
|
42
|
+
5. **High-fan-in cross-module contracts and external adapters**: shared core interfaces imported across multiple modules, host/platform/protocol adapters, external API/SDK/webhook integrations.
|
|
43
|
+
6. **Complex side-effect, concurrency, process, or Git modules**: workers/queues, locks/heartbeats, subprocess/daemon lifecycle, atomic I/O, or VCS/checkout management.
|
|
44
|
+
|
|
45
|
+
### Explicit Exclusions (Structural-Only in Parent L1 Without `->`)
|
|
46
|
+
|
|
47
|
+
Exclude these directories from Brownfield core L2 creation and keep them as structural-only entries in parent L1 without `->` pointers:
|
|
48
|
+
- Static assets (`public/`, `static/`, `assets/`, stylesheets, fonts, media);
|
|
49
|
+
- Locales and translation bundles (`locales/`, `i18n/`);
|
|
50
|
+
- Thin `utils/` / `helpers/` / pure formatting helpers without non-obvious invariants;
|
|
51
|
+
- Simple DTO, type-only, or constants-only folders (`types/`, `dto/`, `constants/`);
|
|
52
|
+
- Test, mock, and fixture directories (`tests/`, `__tests__/`, `mocks/`, `fixtures/`, `e2e/`);
|
|
53
|
+
- Generated artifacts, build output, vendored code, platform directories, and `.prizmkit/` (`dist/`, `build/`, `generated/`, `node_modules/`, `vendor/`, `.git/`, `.prizmkit/`, `.claude/`, `.codebuddy/`, `.codex/`, `.agent/`, `.agents/`, `.pi/`, `.cursor/` — while never excluding a repository's canonical top-level `dev-pipeline/` source module by basename);
|
|
54
|
+
- Trivial 1–2 file edge directories lacking cross-module contracts or non-obvious invariants.
|
|
55
|
+
|
|
56
|
+
In parent L1 `SUBDIRS:`, emit `-> .prizmkit/prizm-docs/<M>/<S>.prizm` **only** when that nested L2 actually exists. Excluded and unexpanded submodules appear as structural-only entries (for example, `- utils/: shared formatting helpers`) with **no `->` pointer**.
|
|
57
|
+
|
|
58
|
+
## Bounded Single-Init Batch Budget (Context-Overflow Protection)
|
|
59
|
+
|
|
60
|
+
- **Up to 5 qualifying core candidates (`<= 5`)**: Deep-read and generate all qualifying core L2 documents in one pass.
|
|
61
|
+
- **More than 5 qualifying core candidates (`> 5`)**: Prioritize candidates deterministically by signal coverage (count of matched criteria among the six selection signals, breaking ties by security/persistence/entry criticality, cross-module fan-in, and source file count) and limit single-pass deep reading to the **top 5–8 highest-value core modules**.
|
|
62
|
+
- Before any disk write, preserve exact pre-write bytes of every existing `.prizm` file under `.prizmkit/prizm-docs/` (on reinitialize/overwrite) and track newly created targets so exact-byte rollback remains possible across the entire Init batch.
|
|
63
|
+
- Process selected core candidates **sequentially**, one module at a time:
|
|
64
|
+
1. **Bounded source read**: Read the module's entry file(s), core implementation files, and 1–2 representative contract/behavior tests (when present). Do not bulk-load unrelated modules or generated files.
|
|
65
|
+
2. **Value Gate extraction**: Extract durable non-obvious facts passing the Value Gate (`>= 2` required; skip L2 creation if fewer qualify).
|
|
66
|
+
3. **Identity and formatting**: Build mirrored L2 first (or deterministic semantic L2 only on flat-module >5120B overflow after cleanup). Use strict ALL CAPS `KEY: value` / `- item` format with zero prohibited hygiene metadata (no `CHANGELOG`, `UPDATED`/date fields, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` paths). Render `TRAPS: none` inline when no trap is source-evidenced.
|
|
67
|
+
4. **Per-L2 raw UTF-8 capacity preflight and validation**: Measure exact raw UTF-8 bytes against L2 limit 5120B. Keep natural content <80% unpadded; report 80%–<90% warnings without failing; remediate generated/rewritten L2 targets at >=90% toward **4096–4607B** without deleting protected critical knowledge. Validate per-document shape, hygiene, semantic ownership (when semantic), and `TRAPS` format before writing; any unresolved byte above hard limit blocks completion and rolls back prior writes.
|
|
68
|
+
5. **Write validated L2 and record pointer**: Write the validated nested L2 file first (skipping byte-identical writes) and record its resolving `SUBDIRS:` or `DETAILS:` pointer for its parent direct-child L1.
|
|
69
|
+
6. **Discard raw source context**: Release the completed module's raw source/test content from working focus before starting the next core module.
|
|
70
|
+
- **Complete bottom-up L1/L0 writes and whole-snapshot validation with exact-byte rollback**:
|
|
71
|
+
1. After the core-module L2 pass completes, run raw UTF-8 capacity preflight on all direct-child L1s and L0 `root.prizm` (4096B hard limit; remediate >=90% toward **3277–3686B** without deleting protected knowledge; use `MODULE_GROUPS` on L0 when >15 modules or capacity requires).
|
|
72
|
+
2. Write bottom-up: all direct-child L1 structural indexes (emitting `SUBDIRS:`/`DETAILS:` `->` pointers only to written L2s and keeping excluded/unexpanded submodules structural-only without `->`), then L0 `root.prizm`, skipping byte-identical writes.
|
|
73
|
+
3. Re-read actual written bytes across the complete `.prizmkit/prizm-docs/` snapshot and validate all affected documents (including running `.prizmkit/scripts/validate-prizm-docs.py --all` when installed in the project).
|
|
74
|
+
4. If **any** post-write check fails, restore every replaced target to its exact pre-write bytes and remove every newly created target before reporting the blocker.
|
|
75
|
+
|
|
76
|
+
## Completion Report Follow-Up and Invariants
|
|
77
|
+
|
|
78
|
+
- **Remaining unexpanded core candidates**: When a repository has more qualifying core candidates than the 5–8 Init batch budget, list the unexpanded high-value candidates **only in the Init completion report** with recommended follow-up via existing `/prizmkit-prizm-docs rebuild <module>`, `/prizmkit-prizm-docs update`, or `/prizmkit-retrospective`.
|
|
79
|
+
- **No documentation state machine**: Never store pending queues, completion flags, priority scores, or a documentation state machine inside any `.prizm` file, and never create L3 or relax the 4096B/4096B/5120B limits.
|
|
80
|
+
- **Git neutrality**: Never stage, commit, force-add, change or interpret `.gitignore`, require Git history, or treat `.prizmkit/**` tracking state as initialization health.
|
|
81
|
+
- **Post-Init fallback for unexpanded/non-core modules**: When a future session edits or reads a module with no existing L2, inspect only bounded relevant source and narrowly implicated contracts without creating a placeholder.
|
|
@@ -46,7 +46,7 @@ Before proposing or finalizing a plan:
|
|
|
46
46
|
1. Reuse any project context already loaded in the current session (including `{artifact_dir}/context-snapshot.md` when supplied by the caller), and check whether `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json`, or a project brief exists.
|
|
47
47
|
2. If initialization context is missing, do not block planning; load the README, manifests, project instruction files, source structure, and relevant source files as fallback.
|
|
48
48
|
3. If Prizm docs exist, read `root.prizm`, follow only its relevant module/detail pointers, and use source fallback when detailed documentation is absent.
|
|
49
|
-
4. If the current requirement lands on frontend, backend, database, or mobile, Read `.prizmkit/rules/<layer>-rules.md` when that exact convention path exists
|
|
49
|
+
4. If the current requirement lands on frontend, backend, database, or mobile, Read `.prizmkit/rules/<layer>-rules.md` when that exact convention path exists and enforce it consciously as planning criteria. Never load all four files by default. If a requirement spans two layers, read both existing files. Map browser UI work to frontend, service or API work to backend, schema migration or ORM work to database, and iOS, Android, React Native, or Flutter work to mobile. Discover by exact path Read; do not depend on git tracking or glob. When the file does not exist, do not block and do not silently skip—explicitly activate the built-in `coding-baseline` plus detected language/stack conventions (e.g., strict typing and no unhandled promises in TypeScript, no bare `except:` or mutable default arguments in Python, explicit `err` handling in Go, parameterized SQL). Enforce three-tier override precedence without a clarification pause: Tier 1 (highest) repository explicit contracts, current source and nested `.prizm` detail facts, committed OpenAPI/schemas, project linters/compilers, and host project instruction conventions; Tier 2 `.prizmkit/rules/<layer>-rules.md`; Tier 3 (fallback) framework `coding-baseline` and language conventions—when rules conflict, those current sources win without a clarification pause. L0 `RULES:` MUST/NEVER remain authoritative for that key.
|
|
50
50
|
5. Read `${SKILL_DIR}/references/artifact-identity.md`, validate or generate `artifact_dir` exactly once, and keep it stable throughout this planning invocation.
|
|
51
51
|
|
|
52
52
|
## Phase 1: Specify (`spec.md`)
|
|
@@ -78,6 +78,7 @@ Precondition: `spec.md` exists with no unresolved blocker.
|
|
|
78
78
|
- concise for small, well-scoped formal requirements;
|
|
79
79
|
- comprehensive for multi-module, public API, data model, security, permission, payment, deployment-impacting, or ambiguous requirements.
|
|
80
80
|
4. Generate `plan.md` from `${SKILL_DIR}/assets/plan-template.md` with:
|
|
81
|
+
- active rule source (`project-layer-rules` naming loaded `.prizmkit/rules/<layer>-rules.md` path(s), `framework-coding-baseline` naming detected language/stack conventions, or `not-applicable` for non-layer tasks);
|
|
81
82
|
- change approach and goal/constraint traceability;
|
|
82
83
|
- decision rationale and alternatives only when materially different viable paths exist;
|
|
83
84
|
- component and file changes;
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# Plan: [TITLE]
|
|
2
2
|
|
|
3
3
|
## Change Approach
|
|
4
|
+
- Active Rule Source: [project-layer-rules (<paths>) | framework-coding-baseline (<detected language/stack conventions>) | not-applicable]
|
|
5
|
+
|
|
4
6
|
[Description of the minimum-sufficient technical approach — how these changes integrate with the existing system]
|
|
5
7
|
|
|
6
8
|
## Decision Traceability
|
|
@@ -90,7 +90,9 @@ Use the canonical capacity classifier: exact raw UTF-8 bytes; L0 `root.prizm` li
|
|
|
90
90
|
|
|
91
91
|
## Operation: Init
|
|
92
92
|
|
|
93
|
-
Bootstrap `.prizmkit/prizm-docs/` for the current project
|
|
93
|
+
Bootstrap `.prizmkit/prizm-docs/` for the current project:
|
|
94
|
+
- **Greenfield / nearly empty projects**: create only a minimal `root.prizm` (L0) skeleton with zero L1 and zero L2 files.
|
|
95
|
+
- **Brownfield projects**: run default core-module deep construction producing L0 `root.prizm`, direct-child L1 structural indexes, and source-evidenced, Value-Gate-qualified core L2 documents within a bounded single-Init batch (top 5–8 ranked core modules on larger repositories), while keeping excluded/edge/unexpanded modules structural-only in L1 without `->` pointers and strictly forbidding placeholder L2s.
|
|
94
96
|
|
|
95
97
|
Precondition: no `.prizmkit/prizm-docs/` directory exists, or user confirms overwrite.
|
|
96
98
|
|
|
@@ -187,13 +189,15 @@ For detailed protocol specifications, read `${SKILL_DIR}/assets/prizm-docs-forma
|
|
|
187
189
|
|
|
188
190
|
## Examples
|
|
189
191
|
|
|
190
|
-
**Init output:**
|
|
192
|
+
**Init output (brownfield):**
|
|
191
193
|
|
|
192
194
|
```text
|
|
193
195
|
Generated .prizmkit/prizm-docs/:
|
|
194
196
|
root.prizm (L0) — top-level module map
|
|
195
|
-
src.prizm (L1) — direct-child source-module structure and
|
|
196
|
-
(
|
|
197
|
+
src.prizm (L1) — direct-child source-module structure and resolving SUBDIRS pointers
|
|
198
|
+
src/routes.prizm (L2) — source-evidenced routing contracts and entry behavior
|
|
199
|
+
src/models.prizm (L2) — source-evidenced persistence boundaries and invariants
|
|
200
|
+
(edge/utility/test directories kept structural-only in L1 without ->; zero placeholder L2s; greenfield emits root.prizm only)
|
|
197
201
|
```
|
|
198
202
|
|
|
199
203
|
L1 docs are structural indexes. Interface signatures, data flow, TRAPS, and DECISIONS belong in L2 docs.
|
|
@@ -44,7 +44,7 @@ CORE_PRINCIPLES:
|
|
|
44
44
|
- Memory hygiene over traceability noise (no CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths)
|
|
45
45
|
- Size-enforced (hard limits per level prevent bloat; no project-size override)
|
|
46
46
|
- Capacity-aware (raw UTF-8 byte bands drive warnings and safe remediation; critical knowledge is never deleted merely to meet a check)
|
|
47
|
-
-
|
|
47
|
+
- Value-gated L2 generation (brownfield Init generates source-evidenced core L2 docs within a bounded batch; greenfield Init stays L0-only; remaining modules gain L2 incrementally via retrospective or explicit repair; placeholder L2s are always prohibited)
|
|
48
48
|
- Rules hierarchy (root.prizm RULES are authoritative, module RULES supplement only)
|
|
49
49
|
- Three levels only (semantic concern documents are L2, never a fourth level or memory state machine)
|
|
50
50
|
|
|
@@ -326,6 +326,7 @@ REQUIRED_FIELDS:
|
|
|
326
326
|
- Mirrored source-submodule L2: MODULE, FILES, RESPONSIBILITY, INTERFACES, KEY_FILES, DEPENDENCIES, TRAPS. DATA_FLOW, RULES, DECISIONS, and domain-specific sections are present only when facts pass the Value Gate, preserving existing mirrored-document compatibility.
|
|
327
327
|
- Semantic concern L2 complete terminal shape: MODULE, CONCERN, FILES, RESPONSIBILITY, INTERFACES, DATA_FLOW, KEY_FILES, DEPENDENCIES, RULES, TRAPS, DECISIONS
|
|
328
328
|
- In a semantic concern L2, if a required behavioral section has no fact that passes the Value Gate, render the section as `<SECTION>: none`; never invent filler to populate it
|
|
329
|
+
- In a mirrored source-submodule L2, optional sections (DATA_FLOW, RULES, DECISIONS, and domain-specific sections) are omitted when no fact passes the Value Gate; if a required behavioral field such as INTERFACES or TRAPS has no source-evidenced fact passing the Value Gate, render it inline as `INTERFACES: none` or `TRAPS: none` (never as a bullet item `- none`) rather than fabricating entries
|
|
329
330
|
- DOMAIN-SPECIFIC sections are optional and contain only Value-Gate-qualified facts
|
|
330
331
|
|
|
331
332
|
SEMANTIC_CONCERN_TERMINAL_SHAPE:
|
|
@@ -410,7 +411,7 @@ FOR any source file at path P:
|
|
|
410
411
|
3. Mirrored source-submodule identity has precedence; for a flat module, semantic FILES ownership selects the detail
|
|
411
412
|
4. Before modifying P, read the complete selected L2 and complete resolving parent/child pointer documents
|
|
412
413
|
5. If ownership is absent, overlaps, or disagrees with its pointer, report ambiguity instead of guessing
|
|
413
|
-
6. If no relevant L2 exists, inspect only the bounded source files needed for P and proceed without creating a placeholder; documentation creation remains an owning retrospective
|
|
414
|
+
6. If no relevant L2 exists, inspect only the bounded source files needed for P and proceed without creating a placeholder; documentation creation remains an owning brownfield-core-init, retrospective, or repair operation
|
|
414
415
|
|
|
415
416
|
## 5.4 Deterministic Semantic Concern Identity
|
|
416
417
|
|
|
@@ -580,9 +581,9 @@ OPERATION: Init (invoked via prizmkit-prizm-docs skill)
|
|
|
580
581
|
PRECONDITION: No .prizmkit/prizm-docs/ directory exists (or user confirms overwrite)
|
|
581
582
|
|
|
582
583
|
INPUT: Project root directory
|
|
583
|
-
OUTPUT: .prizmkit/prizm-docs/ with root.prizm
|
|
584
|
+
OUTPUT: .prizmkit/prizm-docs/ with minimal root.prizm (L0 only, zero L1/L2) for greenfield projects, or root.prizm (L0), direct-child L1 structural indexes, and source-evidenced core L2 documents for brownfield projects
|
|
584
585
|
|
|
585
|
-
SUMMARY: Detect project type → discover modules (MODULE_DISCOVERY_CRITERIA) →
|
|
586
|
+
SUMMARY: Detect project type and greenfield/brownfield mode → (greenfield: write minimal L0 root.prizm only) / (brownfield: discover modules (MODULE_DISCOVERY_CRITERIA) → select qualifying core modules using the six high-signal criteria and keep excluded edge/utility/static/test directories structural-only in L1 without `->` → deep-read up to 5–8 ranked core modules sequentially under the Value Gate (>=2 non-obvious facts, inline `TRAPS: none` when none is source-evidenced, strictly no placeholders) → remediate >=90% targets toward 3277–3686B (L0/L1) or 4096–4607B (L2) → write bottom-up L2->L1->L0 with exact-byte rollback) → configure hook → validate format/capacity/pointers → report (listing any remaining unexpanded core candidates in output only, never in `.prizm` files).
|
|
586
587
|
|
|
587
588
|
DETAILED_STEPS: → ${SKILL_DIR}/references/op-init.md
|
|
588
589
|
|
|
@@ -601,14 +602,14 @@ A directory does NOT qualify if ALL of the following are true:
|
|
|
601
602
|
|
|
602
603
|
HIERARCHY RULE: if directory X lives inside top-level module M, X is a sub-module of M — NOT a separate top-level module. Its durable behavioral detail uses the mirrored L2 path. Semantic concern identity is considered only for a flat module under Section 5.4.
|
|
603
604
|
|
|
604
|
-
CAPACITY RULE: use MODULE_GROUPS whenever MODULE_INDEX cannot fit L0 within 4096B. Do not change hard limits for project size. Init
|
|
605
|
+
CAPACITY RULE: use MODULE_GROUPS whenever MODULE_INDEX cannot fit L0 within 4096B. Do not change hard limits for project size. Init strictly prohibits placeholder L2s; brownfield Init generates only source-evidenced core L2s within the 5–8 module sequential batch budget (mirrored first; deterministic semantic L2 only when a flat module exceeds 5120B after cleanup), while greenfield Init stays L0-only. Later Update/Rebuild/Migrate/Retrospective may create complete L2 documents for remaining modules when durable knowledge and unambiguous identity exist.
|
|
605
606
|
|
|
606
607
|
EXCLUDE: .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .codex/, .agent/, .agents/, .pi/, .cursor/, .prizmkit/
|
|
607
608
|
SOURCE_BOUNDARY: Excluding `.prizmkit/` excludes the installed Runtime at `.prizmkit/dev-pipeline/`; never exclude a repository's canonical top-level `dev-pipeline/` source module by basename.
|
|
608
609
|
|
|
609
610
|
## 9.2 Post-Init Behavior
|
|
610
611
|
|
|
611
|
-
After initialization,
|
|
612
|
+
After initialization, non-core modules and any remaining unexpanded core candidates beyond the Init batch gain L2 docs incrementally through retrospective or explicit rebuild/repair when durable knowledge exists:
|
|
612
613
|
|
|
613
614
|
ON_MODIFY trigger:
|
|
614
615
|
- Before editing a file in sub-module S within module M:
|
|
@@ -618,7 +619,7 @@ ON_MODIFY trigger:
|
|
|
618
619
|
AI reads bounded relevant source files as fallback, creates no placeholder, and proceeds with the modification.
|
|
619
620
|
- After the change, `/prizmkit-retrospective` creates L2 only when candidate interfaces, data flow, traps, or decisions pass the Value Gate.
|
|
620
621
|
- Real source submodules retain mirrored paths. A flat-module semantic detail follows Sections 3.3 and 5.4 and blocks on ambiguous concern identity, slug collision, or overlapping ownership.
|
|
621
|
-
- This
|
|
622
|
+
- This pairs immediate brownfield core L2 depth with bounded context cost while expanding remaining modules incrementally when real durable context exists.
|
|
622
623
|
|
|
623
624
|
ON_DEEP_READ trigger:
|
|
624
625
|
- When AI needs to deeply understand a module but not modify it (e.g., code review, architecture analysis, dependency tracing, explaining complex logic):
|
|
@@ -4,34 +4,51 @@ Bootstrap .prizmkit/prizm-docs/ for the current project.
|
|
|
4
4
|
|
|
5
5
|
PRECONDITION: No .prizmkit/prizm-docs/ directory exists, or user confirms overwrite.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
MODE BOUNDARY:
|
|
8
|
+
- **Greenfield / nearly empty repository** (no source code): create `.prizmkit/prizm-docs/` and generate ONLY a minimal `root.prizm` (L0) skeleton (`PRIZM_VERSION: 4`, concise `PROJECT`, `LANG`, `MODULE_INDEX: []`, core `RULES`, and optional `TECH_STACK` if known) with **zero L1** and **zero L2** files. Validate format, raw UTF-8 capacity (4096B), and hygiene, then report and stop.
|
|
9
|
+
- **Brownfield repository** (existing source code): run default core-module deep construction through Steps 1–12 below, generating exact `root.prizm` (L0), direct-child L1 structural indexes, and source-evidenced, Value-Gate-qualified nested L2 documents for qualifying core modules within a bounded single-Init batch.
|
|
10
|
+
|
|
11
|
+
STEPS (BROWNFIELD):
|
|
8
12
|
1. Detect project type by scanning for build system files (go.mod, package.json, requirements.txt, Cargo.toml, pom.xml, *.csproj). Identify primary language, framework, build command, test command, and entry points.
|
|
9
13
|
2. Discover modules using MODULE_DISCOVERY_CRITERIA:
|
|
10
14
|
- A directory qualifies as a module if it contains source files forming a logical unit, contains entry/config/interface files, contains qualifying sub-modules, or is referenced by multiple modules as a dependency.
|
|
11
15
|
- TOP-LEVEL modules: directories directly under project root (or under src/ for src-based layouts) that qualify.
|
|
12
|
-
- SUB-MODULES: directories INSIDE a top-level module that qualify. Record them as source structure in the direct-child parent L1;
|
|
16
|
+
- SUB-MODULES: directories INSIDE a top-level module that qualify. Record them as source structure in the direct-child parent L1; qualifying core sub-modules get mirrored nested L2 documents during brownfield Init, while excluded or unexpanded sub-modules remain structural-only entries in L1 without `->` pointers.
|
|
13
17
|
- HIERARCHY RULE: exact `root.prizm` is L0; top-level module M maps to direct-child `.prizmkit/prizm-docs/<M>.prizm` (L1); directory X inside M maps to nested `.prizmkit/prizm-docs/<M>/<X>.prizm` (L2). Deeper source ownership remains L2 and never creates L3.
|
|
14
18
|
- Exclude .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .codex/, .agent/, .agents/, .pi/, .cursor/, and the complete `.prizmkit/` framework directory. This excludes installed `.prizmkit/dev-pipeline/` artifacts but never excludes a repository's canonical top-level `dev-pipeline/` source module by basename. If total module count > 30, ask user for include/exclude patterns.
|
|
15
|
-
3. Apply the Value Gate from SKILL.md and the format specification to every metadata, rule, pattern, dependency, file, and summary candidate. Keep navigational structure only when needed to locate ownership. Reject source-derivable signatures, history, test inventories, temporary conclusions, stale/duplicate meanings, procedures, and low-value file lists.
|
|
16
|
-
4. Create `.prizmkit/prizm-docs/` and only the mirrored directories needed by documents that will exist.
|
|
17
|
-
5.
|
|
19
|
+
3. Apply the Value Gate from SKILL.md and the format specification to every metadata, rule, pattern, dependency, file, behavioral fact, and summary candidate. Keep navigational structure only when needed to locate ownership. Reject source-derivable signatures, history, test inventories, temporary conclusions, stale/duplicate meanings, procedures, and low-value file lists.
|
|
20
|
+
4. Before any disk write, capture exact pre-write bytes of every existing `.prizm` file under `.prizmkit/prizm-docs/` (on confirmed overwrite) and track newly created targets so exact-byte rollback remains possible. Create `.prizmkit/prizm-docs/` and only the mirrored directories needed by complete documents that will actually exist. Never create placeholder detail files.
|
|
21
|
+
5. Prepare `root.prizm` (L0) candidate in memory with concise PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY, navigation pointers, and only Value-Gate-qualified global RULES/PATTERNS/CROSS_CUTTING facts. Set `PRIZM_VERSION: 4`. Keep L0 a summary/pointer map; never copy child interfaces, data flow, traps, decisions, or full rules. No CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths.
|
|
18
22
|
- If `.prizmkit/plans/project-brief.md` exists, add `PROJECT_BRIEF: .prizmkit/plans/project-brief.md`; otherwise skip it.
|
|
19
23
|
- If the previous `root.prizm` already contains a `LAYER_RULES:` block, preserve that block analogously to `PROJECT_BRIEF:`. Do not convert it into MUST/NEVER `RULES:` entries. Do not invent `LAYER_RULES:` by globbing `.prizmkit/rules/`.
|
|
20
24
|
- Use MODULE_GROUPS whenever MODULE_INDEX cannot fit the required map within 4096B. More than 15 modules is a mandatory grouping trigger. Use 3-8 stable functional domains; never raise the L0 limit for project size.
|
|
21
25
|
- Generate only high-value intent-matching keyword tags; do not copy exported names or imports mechanically when they add no navigation value.
|
|
22
|
-
6.
|
|
23
|
-
7.
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
26
|
+
6. Prepare one direct-child L1 structural index candidate in memory for each discovered top-level source module at `.prizmkit/prizm-docs/<module>.prizm`. Include concise MODULE, FILES navigation summary, RESPONSIBILITY, SUBDIRS (and DETAILS only for flat-module semantic L2s), KEY_FILES, DEPENDENCIES, and at most three critical RULES. Emit a `SUBDIRS:` or `DETAILS:` `->` arrow ONLY for nested L2 documents actually written in Step 7, so every arrow resolves. Keep excluded and unexpanded submodules as structural-only entries without `->`. Do not include INTERFACES, DATA_FLOW, TRAPS, DECISIONS, full rules, or a low-value file inventory.
|
|
27
|
+
7. Run **Brownfield Core-Module Deep L2 Construction** (writing validated L2s first):
|
|
28
|
+
- **Six deterministic core-module selection signals** — select qualifying submodules (or flat modules) matching one or more of:
|
|
29
|
+
1. system entry points and routing / command dispatch;
|
|
30
|
+
2. core business domain and state machines;
|
|
31
|
+
3. data models and persistence / migration boundaries;
|
|
32
|
+
4. authentication, authorization, and security boundaries;
|
|
33
|
+
5. high-fan-in cross-module contracts and external adapters;
|
|
34
|
+
6. complex side-effect, concurrency, process, or Git modules.
|
|
35
|
+
- **Explicit exclusions** — exclude static assets, locales/i18n, thin utils/helpers, simple DTO/type-only/constants folders, test/mock/fixture directories, generated artifacts/vendored code, and trivial 1–2 file edge directories lacking cross-module contracts or non-obvious invariants; keep them structural-only in parent L1 without `->`.
|
|
36
|
+
- **Hard anti-placeholder boundary** — placeholder L2 files (guessed from directory names, repeating source-derivable signatures, or padded with TBD/generic prose) remain strictly prohibited. Every Brownfield L2 must be backed by reading core entry/implementation source files plus 1–2 representative contract tests (when present) and contain **at least two non-obvious facts** passing the future-incorrect-modification Value Gate; if fewer qualify, skip L2 creation and leave the module structural-only in L1.
|
|
37
|
+
- **Mirrored vs semantic L2 & inline `TRAPS: none`** — use mirrored `.prizmkit/prizm-docs/<M>/<S>.prizm` first for real source submodules (`MODULE`, `FILES`, `RESPONSIBILITY`, `INTERFACES`, `KEY_FILES`, `DEPENDENCIES`, `TRAPS`, omitting optional `DATA_FLOW`, `RULES`, `DECISIONS`, or domain sections when empty; render `TRAPS: none` or `INTERFACES: none` **inline** when no source-evidenced entry exists rather than fabricating filler or emitting `- none`). Use deterministic flat-module semantic L2 (`.prizmkit/prizm-docs/<M>/<concern-slug>.prizm`) ONLY when a flat module has multiple stable concerns and required protected knowledge exceeds 5120B after cleanup; semantic L2 requires the complete CONCERN/FILES/DETAILS contract and blocks on unstable or ambiguous boundaries, overlapping ownership, empty slugs, or mirrored/sibling collisions—task-named and numbered shards are prohibited.
|
|
38
|
+
- **Bounded single-Init batch budget** — if qualifying core candidates `<= 5`, deep-read and generate all in one pass. If `> 5`, rank candidates deterministically by the six signals (breaking ties by security/persistence/entry criticality, cross-module fan-in, and source file count) and process only the **top 5–8 highest-value core modules sequentially**:
|
|
39
|
+
`bounded read (entry + core files + 1–2 contract tests) -> Value Gate extraction (>=2 non-obvious facts) -> mirrored L2 first (or semantic L2 only on flat-module >5120B overflow) -> per-L2 raw UTF-8 capacity preflight (5120B limit; >=90% remediated toward 4096–4607B) and format/hygiene validation -> write validated L2 (skipping byte-identical) and record its resolving L1 pointer -> discard raw source context before next module`.
|
|
40
|
+
- Never store unexpanded queues, scores, or a documentation state machine inside any `.prizm` file.
|
|
41
|
+
8. Complete raw UTF-8 capacity preflight for every remaining L1 and L0 candidate using the canonical classifier (L0/L1 4096B, L2 5120B). Keep natural content below 80% unpadded; report warning-range (80% to <90%) files without failing. If any generated L1/L0 reaches 90% or above, clean, deduplicate, move child detail, or switch L0 to `MODULE_GROUPS` toward **3277–3686B** (and any L2 at >=90% toward **4096–4607B**) without deleting protected knowledge. Any unresolved hard-limit error blocks Init and triggers rollback.
|
|
42
|
+
9. Finish bottom-up writes for all direct-child L1 structural indexes (containing `SUBDIRS:`/`DETAILS:` `->` pointers only to L2s written in Step 7) and then L0 `root.prizm`, comparing candidate bytes against existing disk bytes to skip byte-identical replacements.
|
|
43
|
+
10. Re-read actual written bytes across the complete `.prizmkit/prizm-docs/` snapshot and validate all generated docs (running installed `.prizmkit/scripts/validate-prizm-docs.py --all` when available): Value Gate, raw UTF-8 size/band reporting, bidirectional pointer resolution (`MODULE_INDEX`/`MODULE_GROUPS` -> L1, L1 `SUBDIRS:`/`DETAILS:` -> nested L2), semantic ownership/identity, no circular dependencies, KEY: value format, valid `TRAPS` format (inline `TRAPS: none` or severity + `| FIX:`), parent-summary boundary, no anti-patterns, and no prohibited metadata. Warning-only capacity results pass; hard-limit or format errors fail. If any post-write check fails, restore every replaced target to its exact pre-write bytes captured in Step 4 and remove every newly created target before returning a blocker.
|
|
44
|
+
11. Configure UserPromptSubmit hook in platform settings per `${SKILL_DIR}/assets/prizm-docs-format.md` Section 11.
|
|
45
|
+
12. Report modules discovered, L1 and source-evidenced core L2 docs generated, any remaining unexpanded high-value core candidates beyond the 5–8 Init batch (listed **only** in the completion report with recommended follow-up via `/prizmkit-prizm-docs rebuild <module>`, `/prizmkit-prizm-docs update`, or `/prizmkit-retrospective`), excluded/Value-Gate-omitted categories, capacity diagnostics in descending utilization, and any required manual decisions. Do not stage, commit, force-add, change ignore policy, require history, or report tracking state as documentation health.
|
|
46
|
+
|
|
47
|
+
OUTPUT: List of generated files (L0, L1, core L2), module count, remaining unexpanded core candidates (report-only), Value-Gate omissions/exclusions by category, capacity results, and validation results.
|
|
31
48
|
|
|
32
49
|
## Post-Init Behavior
|
|
33
50
|
|
|
34
|
-
After initialization,
|
|
51
|
+
After initialization, non-core modules and any remaining unexpanded core candidates gain L2 incrementally only when durable context exists (via `/prizmkit-retrospective`, `/prizmkit-prizm-docs rebuild <module>`, or `/prizmkit-prizm-docs update`):
|
|
35
52
|
|
|
36
53
|
ON_MODIFY behavior:
|
|
37
54
|
- Before modification, read the complete relevant L2 plus complete resolving parent/child pointer documents. When `.prizmkit/prizm-docs/<M>/<S>.prizm` does not exist, inspect only the bounded relevant source files in S and narrowly implicated contracts as fallback context, create no placeholder, and proceed.
|
|
@@ -41,5 +58,5 @@ ON_MODIFY behavior:
|
|
|
41
58
|
|
|
42
59
|
ON_DEEP_READ behavior:
|
|
43
60
|
- When an AI needs deep understanding but L2 is absent, read the relevant source files directly as fallback context.
|
|
44
|
-
- Create L2 through `/prizmkit-retrospective` after normal development work, or through explicit `/prizmkit-prizm-docs` repair
|
|
61
|
+
- Create L2 through `/prizmkit-retrospective` after normal development work, or through explicit `/prizmkit-prizm-docs` rebuild/repair when expanding remaining core modules or fixing out-of-band doc drift.
|
|
45
62
|
- Do not create L2 merely because a module was read; L2 should capture durable knowledge, not transient investigation notes.
|
|
@@ -13,7 +13,7 @@ STEPS:
|
|
|
13
13
|
6. CAPACITY RESULT: Warning and strong-warning entries are advisory and do not fail Validate when no other violation exists. Any byte above a hard limit is an error and fails; format, pointer, hierarchy, ownership, or completeness errors also fail and are never downgraded because capacity is only a warning.
|
|
14
14
|
7. POINTER/PARENT CHECK: Verify every arrow resolves. L0/L1 contain concise summaries and pointers rather than copied L2 INTERFACES/DATA_FLOW/TRAPS/DECISIONS/full RULES. SUBDIRS targets mirrored source-submodule L2. DETAILS uses exactly `- <concern-slug>: <one-line stable behavior summary> -> .prizmkit/prizm-docs/<module>/<concern-slug>.prizm` and targets one matching semantic L2.
|
|
15
15
|
8. SEMANTIC IDENTITY/OWNERSHIP CHECK: For each semantic L2, verify required fields MODULE, CONCERN, FILES, RESPONSIBILITY, INTERFACES, DATA_FLOW, KEY_FILES, DEPENDENCIES, RULES, TRAPS, and DECISIONS; verify `CONCERN: <stable concern identity> | SLUG: <concern-slug>`; rerun Unicode NFKC/lowercase/kebab normalization; require non-empty explicit repository-relative FILES ownership with no sibling overlap; and require exact parent/path/slug agreement. A mirrored source-submodule path has precedence. Ambiguous identity, collision, or overlap is a validation error requiring a manual decision, not a numbered or task-named repair.
|
|
16
|
-
9. COMPLETENESS CHECK: Verify exact root has `PRIZM_VERSION: 4`, PROJECT, LANG, RULES, and exactly one of MODULE_INDEX/MODULE_GROUPS. Verify every direct-child L1 has MODULE, FILES, RESPONSIBILITY, DEPENDENCIES, no CONCERN, and none of INTERFACES/DATA_FLOW/TRAPS/DECISIONS. Verify every root module pointer targets L1 and every L1 SUBDIRS/DETAILS pointer targets nested L2. Verify mirrored L2 has MODULE, FILES, RESPONSIBILITY, INTERFACES, KEY_FILES, DEPENDENCIES, and TRAPS with no CONCERN field; DATA_FLOW, RULES, DECISIONS, and domain sections remain optional when no fact passes the Value Gate
|
|
16
|
+
9. COMPLETENESS CHECK: Verify exact root has `PRIZM_VERSION: 4`, PROJECT, LANG, RULES, and exactly one of MODULE_INDEX/MODULE_GROUPS. Verify every direct-child L1 has MODULE, FILES, RESPONSIBILITY, DEPENDENCIES, no CONCERN, and none of INTERFACES/DATA_FLOW/TRAPS/DECISIONS. Verify every root module pointer targets L1 and every L1 SUBDIRS/DETAILS pointer targets nested L2. Verify mirrored L2 has MODULE, FILES, RESPONSIBILITY, INTERFACES, KEY_FILES, DEPENDENCIES, and TRAPS with no CONCERN field; DATA_FLOW, RULES, DECISIONS, and domain sections remain optional when no fact passes the Value Gate, and inline `<SECTION>: none` (such as `INTERFACES: none` or `TRAPS: none`, never a list item `- none`) satisfies a required behavioral field when no source-evidenced fact passes the Value Gate. In semantic L2, explicit inline `<SECTION>: none` likewise satisfies any required behavioral section with no Value-Gate-qualified fact.
|
|
17
17
|
10. STALENESS CHECK: When requested as a separate advisory health check, compare document/source filesystem times from current mapped ownership. Validation itself never requires Git history, interprets ignore rules, or treats ignored/untracked/tracked state as an error.
|
|
18
18
|
11. RULES HIERARCHY CHECK: Verify L1/L2 RULES do not contradict authoritative root RULES.
|
|
19
19
|
12. TRAPS STALENESS CHECK: When an L2 TRAPS section has more than 8 entries, flag entries lacking `STALE_IF:` or `REF:` as `NEEDS_METADATA`; do not auto-remove them.
|
|
@@ -21,9 +21,9 @@ Do not discover a different artifact directory, expand the path set, or infer pr
|
|
|
21
21
|
|
|
22
22
|
## Atomic Boundary
|
|
23
23
|
|
|
24
|
-
`prizmkit-retrospective` owns only targeted structural documentation synchronization, durable knowledge injection, and `{artifact_dir}/retrospective-result.json` for the supplied paths. It does not invoke another Skill, does not read or mutate caller or checkpoint state, and does not choose stage order or routing.
|
|
24
|
+
`prizmkit-retrospective` owns only targeted structural documentation synchronization, durable knowledge injection, optional Phase B governed evolution of existing `.prizmkit/rules/<layer>-rules.md` files, and `{artifact_dir}/retrospective-result.json` for the supplied paths. It does not invoke another Skill, does not read or mutate caller or checkpoint state, and does not choose stage order or routing.
|
|
25
25
|
|
|
26
|
-
It does not stage, commit, force-add, reset, checkout, or stash; it does not add, remove, or interpret `.gitignore` entries; and it does not directly edit generated platform outputs. `.prizmkit/**` is the PrizmKit framework directory, and this Skill owns only its exact documentation
|
|
26
|
+
It does not stage, commit, force-add, reset, checkout, or stash; it does not add, remove, or interpret `.gitignore` entries; and it does not directly edit generated platform outputs. `.prizmkit/**` is the PrizmKit framework directory, and this Skill owns only its exact documentation, governed project-rule, and result writes. The project controls whether those paths are ignored, untracked, or tracked; retrospective behavior is otherwise identical and never requires Git history. Capacity maintenance does not add a capacity state machine, fact scoring system, routing field, caller-state field, or fourth documentation level. The stage returns `RETRO_COMPLETE` or `RETRO_BLOCKED` and stops.
|
|
27
27
|
|
|
28
28
|
## When to Use
|
|
29
29
|
|
|
@@ -44,11 +44,11 @@ Treat only the exact caller-supplied non-`.prizmkit/` `change_paths` as authorit
|
|
|
44
44
|
1. Normalize `artifact_dir` and every path exactly as supplied without broadening the set.
|
|
45
45
|
2. Reject paths outside the checkout, paths under `.prizmkit/`, and paths that do not belong to the supplied project change.
|
|
46
46
|
3. Inspect the current change only through exact pathspecs for the validated paths. Use narrowly required source context only when one eligible change raises a concrete ambiguity about its interface, caller, dependent, data flow, or behavior.
|
|
47
|
-
4. Generated artifacts, lifecycle records, caller metadata, `change_summary`, repository-wide discovery, and existing Prizm text must not independently establish a candidate fact or expand the input scope. Existing Prizm documents are target/current-state evidence only.
|
|
47
|
+
4. Generated artifacts, lifecycle records, caller metadata, `change_summary`, repository-wide discovery, and existing Prizm text must not independently establish a candidate fact or expand the input scope. Existing Prizm documents are target/current-state evidence only. For optional Phase B (`Project Rules Evolution Check`) only, `{artifact_dir}/review-report.md`, `{artifact_dir}/test-report.md`, and `{artifact_dir}/test-result.json` may be inspected strictly read-only alongside validated `change_paths` as defect/regression evidence, while keeping `.prizmkit/` strictly out of `change_paths` and `documentation_paths`.
|
|
48
48
|
5. Map exact changes to only the affected targets and their necessary direct parent summaries or pointers. Never perform an unconditional repository-wide documentation rewrite.
|
|
49
49
|
6. If exact inputs cannot safely establish candidate or target scope, prepare `RETRO_BLOCKED` with the exact blocker.
|
|
50
50
|
|
|
51
|
-
Only targeted `.prizmkit/prizm-docs/` changes and `{artifact_dir}/retrospective-result.json` are outputs.
|
|
51
|
+
Only targeted `.prizmkit/prizm-docs/` changes, governed Phase B updates to existing `.prizmkit/rules/<layer>-rules.md` files, and `{artifact_dir}/retrospective-result.json` are outputs.
|
|
52
52
|
|
|
53
53
|
## Value and Cleanup Gates
|
|
54
54
|
|
|
@@ -67,7 +67,7 @@ For every existing target:
|
|
|
67
67
|
3. Match existing and candidate facts by semantic meaning; update the canonical entry in place, merge synonymous facts, and remove obsolete, stale, derivable, duplicate, conflicting, or parent-copied material.
|
|
68
68
|
4. Add only genuinely new facts that pass the Value Gate and have no equivalent canonical entry. Append-only synchronization is prohibited.
|
|
69
69
|
|
|
70
|
-
Before reading any reference, confirm `.prizmkit/prizm-docs/` exists and `change_paths` is non-empty: if `.prizmkit/prizm-docs/` does not exist,
|
|
70
|
+
Before reading any reference, confirm `.prizmkit/prizm-docs/` exists and `change_paths` is non-empty: if `.prizmkit/prizm-docs/` does not exist, record Phase A `NO_DOC_CHANGE` with `reason: "PRIZM_DOCS_NOT_INITIALIZED"` without reading `${SKILL_DIR}/references/knowledge-injection-steps.md` or `${SKILL_DIR}/references/structural-sync-steps.md` (if `change_paths` is non-empty, still run optional Phase B below before writing `retrospective-result.json`); if `change_paths` is empty or no inspected change produces a Value-Gate-passing durable candidate, record Phase A `NO_DOC_CHANGE` without reading `${SKILL_DIR}/references/structural-sync-steps.md`.
|
|
71
71
|
|
|
72
72
|
Only when `.prizmkit/prizm-docs/` is initialized and eligible changes exist, read `${SKILL_DIR}/references/knowledge-injection-steps.md` to extract candidates and evaluate the Value Gate.
|
|
73
73
|
|
|
@@ -97,6 +97,16 @@ A real source submodule uses mirrored detail identity. An eligible flat module m
|
|
|
97
97
|
|
|
98
98
|
When `.prizmkit/prizm-docs/` does not exist, record `NO_DOC_CHANGE` with reason `PRIZM_DOCS_NOT_INITIALIZED` and recommend initialization as a separate action.
|
|
99
99
|
|
|
100
|
+
## Phase B: Project Rules Evolution Check (Optional)
|
|
101
|
+
|
|
102
|
+
After Phase A documentation synchronization completes (including when Phase A results in `NO_DOC_CHANGE`), run this optional Phase B whenever `change_paths` is non-empty and maps to one or more application layers (`frontend`, `backend`, `database`, or `mobile`):
|
|
103
|
+
|
|
104
|
+
1. Read `${SKILL_DIR}/references/rule-evolution-steps.md` and follow its complete contract.
|
|
105
|
+
2. Consume `{artifact_dir}/review-report.md`, `{artifact_dir}/test-report.md`, and `{artifact_dir}/test-result.json` strictly read-only alongside validated `change_paths`; never place `.prizmkit/` paths in `change_paths` or `.prizmkit/rules/` paths in `documentation_paths`.
|
|
106
|
+
3. Admit a clause only if it passes all four AND gates (cross-task reusable—single-module traps belong in Prizm `TRAPS:`, real-evidence-driven, falsifiable `MUST`/`NEVER` with concrete condition or counterexample, and non-redundant with linters/compilers, built-in `core/rules/`, or Prizm detail docs) and avoids every banned category (one-off details, temporary workarounds, unagreed style preferences, vague slogans, and task/date/branch/worktree/artifact metadata).
|
|
107
|
+
4. Enforce strictly incremental, non-append-only governance: never create a missing `.prizmkit/rules/<layer>-rules.md` from scratch; for existing target files, read in full, preserve exact pre-write bytes, deduplicate/merge in place, remove obsolete evolved rules, append `## 5. Project-Evolved Rules` if missing on a pre-existing file, enforce hard caps of 20 items in `## 5. Project-Evolved Rules` and 16 KB raw UTF-8 (12 KB soft warning), re-read actual bytes, and restore exact pre-write bytes on any validation failure.
|
|
108
|
+
5. Auto-persist evidence-backed non-conflicting clauses into `## 5. Project-Evolved Rules` (`RULES_UPDATED` with empty `proposals`); emit `RULES_PROPOSED` without auto-overwriting when altering `Decision Ledger` core choices, relaxing safety/data redlines, resolving cross-layer conflicts, targeting an absent layer file, or exceeding caps; emit `NO_RULE_CHANGE` when no candidate qualifies or bytes are unchanged.
|
|
109
|
+
|
|
100
110
|
## Capacity Blocker Contract
|
|
101
111
|
|
|
102
112
|
If protected knowledge cannot be compressed safely and no unambiguous stable split exists, do not leave the oversized candidate as final content. Restore any earlier writes from this attempt and write `RETRO_BLOCKED` with `result: null`.
|
|
@@ -105,7 +115,7 @@ The existing seven fields carry all evidence; add no new field. Put the exact ta
|
|
|
105
115
|
|
|
106
116
|
## Result Artifact
|
|
107
117
|
|
|
108
|
-
Read `${SKILL_DIR}/references/retrospective-result-schema.json` and atomically write `{artifact_dir}/retrospective-result.json` with
|
|
118
|
+
Read `${SKILL_DIR}/references/retrospective-result-schema.json` and atomically write `{artifact_dir}/retrospective-result.json` with these seven required keys (plus optional `rule_evolution` on `RETRO_COMPLETE` when Phase B runs):
|
|
109
119
|
|
|
110
120
|
```json
|
|
111
121
|
{
|
|
@@ -115,13 +125,18 @@ Read `${SKILL_DIR}/references/retrospective-result-schema.json` and atomically w
|
|
|
115
125
|
"reason": "Durable module contract changed and affected documentation passed validation",
|
|
116
126
|
"change_paths": ["src/example.py"],
|
|
117
127
|
"documentation_paths": [".prizmkit/prizm-docs/example/module.prizm"],
|
|
118
|
-
"validation": ["target raw UTF-8 capacity check: 3120B <= 5120B", "affected parent/child pointer resolution check: passed"]
|
|
128
|
+
"validation": ["target raw UTF-8 capacity check: 3120B <= 5120B", "affected parent/child pointer resolution check: passed"],
|
|
129
|
+
"rule_evolution": {
|
|
130
|
+
"status": "NO_RULE_CHANGE",
|
|
131
|
+
"updated_paths": [],
|
|
132
|
+
"proposals": []
|
|
133
|
+
}
|
|
119
134
|
}
|
|
120
135
|
```
|
|
121
136
|
|
|
122
|
-
Every retrospective artifact
|
|
137
|
+
Every retrospective artifact requires these seven keys: `schema_version`, `outcome`, `result`, `reason`, `change_paths`, `documentation_paths`, and `validation`, and may include the optional `rule_evolution` object (`status`: `"RULES_UPDATED" | "NO_RULE_CHANGE" | "RULES_PROPOSED"`, `updated_paths`: `[".prizmkit/rules/<layer>-rules.md"]`, `proposals`: `[{"target_path", "clause", "reason"}]`) on `RETRO_COMPLETE`. Legacy seven-key artifacts without `rule_evolution` remain fully valid. `documentation_paths` remains strictly `.prizmkit/prizm-docs/*.prizm`, and top-level `result` remains governed solely by Phase A documentation (`NO_DOC_CHANGE` with empty `documentation_paths` and non-empty `validation` is valid alongside `rule_evolution.status: "RULES_UPDATED"` or `"RULES_PROPOSED"`).
|
|
123
138
|
|
|
124
|
-
A capacity or validation blocker uses the
|
|
139
|
+
A capacity or validation blocker uses only the seven required keys (`rule_evolution` omitted after exact-byte rollback) without adding state:
|
|
125
140
|
|
|
126
141
|
```json
|
|
127
142
|
{
|
|
@@ -136,9 +151,10 @@ A capacity or validation blocker uses the same shape without adding state:
|
|
|
136
151
|
```
|
|
137
152
|
|
|
138
153
|
- `RETRO_COMPLETE` pairs only with `DOCS_UPDATED` or `NO_DOC_CHANGE`.
|
|
139
|
-
- `DOCS_UPDATED` requires non-empty
|
|
140
|
-
- `NO_DOC_CHANGE` uses a concrete reason and truthful empty or unchanged path evidence.
|
|
141
|
-
- `
|
|
154
|
+
- `DOCS_UPDATED` requires non-empty `documentation_paths` and `validation` lists.
|
|
155
|
+
- `NO_DOC_CHANGE` uses a concrete reason and truthful empty or unchanged documentation path evidence.
|
|
156
|
+
- When `rule_evolution` is present on `RETRO_COMPLETE`: `RULES_UPDATED` requires non-empty `updated_paths`, empty `proposals`, and non-empty top-level `validation`; `NO_RULE_CHANGE` requires empty `updated_paths` and empty `proposals`; `RULES_PROPOSED` requires non-empty `proposals` (and non-empty top-level `validation` whenever `updated_paths` is non-empty).
|
|
157
|
+
- `RETRO_BLOCKED` uses `result: null`, omits `rule_evolution`, and records a non-empty exact reason, the exact input paths, only truthful documentation paths, and only checks actually attempted.
|
|
142
158
|
|
|
143
159
|
Do not add checkpoint, routing, capacity-state, caller-state, evidence-manifest, hash, or attestation fields.
|
|
144
160
|
|
|
@@ -149,6 +165,7 @@ Return only:
|
|
|
149
165
|
- `artifact_dir` and `retrospective-result.json` path;
|
|
150
166
|
- `RETRO_COMPLETE` with `DOCS_UPDATED` or `NO_DOC_CHANGE`, or `RETRO_BLOCKED` with the exact blocker;
|
|
151
167
|
- documentation paths updated or intentionally unchanged;
|
|
168
|
+
- optional Phase B `rule_evolution` summary (`RULES_UPDATED`, `NO_RULE_CHANGE`, or `RULES_PROPOSED` with updated paths or proposals);
|
|
152
169
|
- durable knowledge decisions and validation evidence.
|
|
153
170
|
|
|
154
171
|
Return only the listed retrospective outputs. Do not invoke another Skill.
|
|
@@ -24,7 +24,8 @@
|
|
|
24
24
|
},
|
|
25
25
|
"reason": {
|
|
26
26
|
"type": "string",
|
|
27
|
-
"minLength": 1
|
|
27
|
+
"minLength": 1,
|
|
28
|
+
"pattern": "\\S"
|
|
28
29
|
},
|
|
29
30
|
"change_paths": {
|
|
30
31
|
"type": "array",
|
|
@@ -88,8 +89,107 @@
|
|
|
88
89
|
"type": "array",
|
|
89
90
|
"items": {
|
|
90
91
|
"type": "string",
|
|
91
|
-
"minLength": 1
|
|
92
|
+
"minLength": 1,
|
|
93
|
+
"pattern": "\\S"
|
|
92
94
|
}
|
|
95
|
+
},
|
|
96
|
+
"rule_evolution": {
|
|
97
|
+
"type": "object",
|
|
98
|
+
"additionalProperties": false,
|
|
99
|
+
"required": ["status", "updated_paths", "proposals"],
|
|
100
|
+
"properties": {
|
|
101
|
+
"status": {
|
|
102
|
+
"enum": ["RULES_UPDATED", "NO_RULE_CHANGE", "RULES_PROPOSED"]
|
|
103
|
+
},
|
|
104
|
+
"updated_paths": {
|
|
105
|
+
"type": "array",
|
|
106
|
+
"uniqueItems": true,
|
|
107
|
+
"items": {
|
|
108
|
+
"type": "string",
|
|
109
|
+
"pattern": "^\\.prizmkit/rules/(?:frontend|backend|database|mobile)-rules\\.md$"
|
|
110
|
+
}
|
|
111
|
+
},
|
|
112
|
+
"proposals": {
|
|
113
|
+
"type": "array",
|
|
114
|
+
"items": {
|
|
115
|
+
"type": "object",
|
|
116
|
+
"additionalProperties": false,
|
|
117
|
+
"required": ["target_path", "clause", "reason"],
|
|
118
|
+
"properties": {
|
|
119
|
+
"target_path": {
|
|
120
|
+
"type": "string",
|
|
121
|
+
"pattern": "^\\.prizmkit/rules/(?:frontend|backend|database|mobile)-rules\\.md$"
|
|
122
|
+
},
|
|
123
|
+
"clause": {
|
|
124
|
+
"type": "string",
|
|
125
|
+
"minLength": 1,
|
|
126
|
+
"pattern": "\\S"
|
|
127
|
+
},
|
|
128
|
+
"reason": {
|
|
129
|
+
"type": "string",
|
|
130
|
+
"minLength": 1,
|
|
131
|
+
"pattern": "\\S"
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
},
|
|
137
|
+
"allOf": [
|
|
138
|
+
{
|
|
139
|
+
"if": {
|
|
140
|
+
"properties": {
|
|
141
|
+
"status": {
|
|
142
|
+
"const": "RULES_UPDATED"
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
},
|
|
146
|
+
"then": {
|
|
147
|
+
"properties": {
|
|
148
|
+
"updated_paths": {
|
|
149
|
+
"minItems": 1
|
|
150
|
+
},
|
|
151
|
+
"proposals": {
|
|
152
|
+
"maxItems": 0
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
},
|
|
157
|
+
{
|
|
158
|
+
"if": {
|
|
159
|
+
"properties": {
|
|
160
|
+
"status": {
|
|
161
|
+
"const": "NO_RULE_CHANGE"
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
},
|
|
165
|
+
"then": {
|
|
166
|
+
"properties": {
|
|
167
|
+
"updated_paths": {
|
|
168
|
+
"maxItems": 0
|
|
169
|
+
},
|
|
170
|
+
"proposals": {
|
|
171
|
+
"maxItems": 0
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
},
|
|
176
|
+
{
|
|
177
|
+
"if": {
|
|
178
|
+
"properties": {
|
|
179
|
+
"status": {
|
|
180
|
+
"const": "RULES_PROPOSED"
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
},
|
|
184
|
+
"then": {
|
|
185
|
+
"properties": {
|
|
186
|
+
"proposals": {
|
|
187
|
+
"minItems": 1
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
]
|
|
93
193
|
}
|
|
94
194
|
},
|
|
95
195
|
"oneOf": [
|
|
@@ -121,6 +221,27 @@
|
|
|
121
221
|
}
|
|
122
222
|
}
|
|
123
223
|
}
|
|
224
|
+
},
|
|
225
|
+
{
|
|
226
|
+
"if": {
|
|
227
|
+
"required": ["rule_evolution"],
|
|
228
|
+
"properties": {
|
|
229
|
+
"rule_evolution": {
|
|
230
|
+
"properties": {
|
|
231
|
+
"updated_paths": {
|
|
232
|
+
"minItems": 1
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
},
|
|
238
|
+
"then": {
|
|
239
|
+
"properties": {
|
|
240
|
+
"validation": {
|
|
241
|
+
"minItems": 1
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
}
|
|
124
245
|
}
|
|
125
246
|
]
|
|
126
247
|
},
|
|
@@ -132,6 +253,9 @@
|
|
|
132
253
|
"result": {
|
|
133
254
|
"type": "null"
|
|
134
255
|
}
|
|
256
|
+
},
|
|
257
|
+
"not": {
|
|
258
|
+
"required": ["rule_evolution"]
|
|
135
259
|
}
|
|
136
260
|
}
|
|
137
261
|
]
|