@mriekki/project-forge 1.0.0 → 2.1.0
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/README.md +135 -135
- package/assets/components.json +33 -33
- package/assets/core/distribution.json +73 -66
- package/assets/deployment/distribution.json +54 -54
- package/assets/generated/ASSEMBLY.json +46 -11
- package/assets/generated/core/core/process/APPLICATION_VERSIONING.md +137 -0
- package/assets/generated/core/core/process/OPERATION_JOURNAL.md +140 -0
- package/assets/generated/core/core/process/PROJECT_FORGE_ENGINEERING_GUIDE.md +3 -3
- package/assets/generated/core/core/process/PROJECT_REQUIREMENTS_EXPORT.md +165 -0
- package/assets/generated/core/core/skills/build/SKILL.md +70 -0
- package/assets/generated/core/core/skills/deploy/SKILL.md +1 -1
- package/assets/generated/core/core/skills/deployment-readiness/SKILL.md +1 -1
- package/assets/generated/core/core/skills/developer-env-mode/SKILL.md +1 -1
- package/assets/generated/core/core/skills/export-requirements/SKILL.md +132 -0
- package/assets/generated/core/core/skills/progress/SKILL.md +2 -2
- package/assets/generated/core/core/skills/project-forge-update/SKILL.md +10 -10
- package/assets/generated/core/core/skills/replatform/SKILL.md +122 -0
- package/assets/generated/core/core/skills/run/SKILL.md +75 -0
- package/assets/generated/core/core/skills/setup/SKILL.md +3 -3
- package/assets/generated/core/core/skills/tear-down/SKILL.md +1 -1
- package/bin/project-forge.mjs +9 -9
- package/package.json +33 -33
- package/src/cli.mjs +150 -150
- package/src/engine.mjs +243 -243
- package/src/package-data.mjs +18 -18
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
# Project Requirements Export
|
|
2
|
+
|
|
3
|
+
`PROJECT_REQUIREMENTS.json` is the canonical portable Project Forge interchange artifact for durable product, domain, experience, roadmap, and approved cross-cutting intent.
|
|
4
|
+
|
|
5
|
+
It exists to support workflows such as replatforming the same product onto a different implementation stack without treating the source repository's framework/tool choices as product requirements.
|
|
6
|
+
|
|
7
|
+
## Authority
|
|
8
|
+
|
|
9
|
+
The JSON file is a **derived export**, not a competing source of truth.
|
|
10
|
+
|
|
11
|
+
Repository authorities continue to own their facts. In a normal generated workspace that commonly means:
|
|
12
|
+
|
|
13
|
+
```text
|
|
14
|
+
docs/product/PRODUCT_BRIEF.md
|
|
15
|
+
→ docs/work-items/<FB-...>/brief.md
|
|
16
|
+
→ approved requirements.md when present
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Additional product/domain authorities may include roadmap, system-design/domain invariants, product-level design/accessibility guidance, accepted ADR consequences, and project-owned decisions.
|
|
20
|
+
|
|
21
|
+
The export must retain source paths/authority/provenance so a consumer can trace normalized facts back to their repository authorities.
|
|
22
|
+
|
|
23
|
+
## Canonical filename and state
|
|
24
|
+
|
|
25
|
+
Only this filename is canonical:
|
|
26
|
+
|
|
27
|
+
```text
|
|
28
|
+
PROJECT_REQUIREMENTS.json
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
The contract has no compatibility alias or alternate export filename.
|
|
32
|
+
|
|
33
|
+
State is explicit:
|
|
34
|
+
|
|
35
|
+
```text
|
|
36
|
+
draft
|
|
37
|
+
review
|
|
38
|
+
approved
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Only `approved` may be consumed as replatform input.
|
|
42
|
+
|
|
43
|
+
## Portable content model
|
|
44
|
+
|
|
45
|
+
The export should represent, when present:
|
|
46
|
+
|
|
47
|
+
- project/product identity;
|
|
48
|
+
- problem, users/stakeholders, desired outcomes, scope/non-scope;
|
|
49
|
+
- product workflows/capabilities and success measures;
|
|
50
|
+
- Feature Briefs with source ID, title, target milestone, target disposition, authority/status/maturity, outcomes, scope/non-scope, workflows, business/domain rules, dependencies, acceptance criteria, learning objectives, and open questions;
|
|
51
|
+
- domain concepts and relationships;
|
|
52
|
+
- domain invariants, lifecycle/state semantics, and business rules;
|
|
53
|
+
- cross-cutting security/privacy, accessibility, reliability, performance, and data requirements;
|
|
54
|
+
- portable product/UX principles, responsive constraints, and interaction intent;
|
|
55
|
+
- roadmap milestones/sequencing facts that express product intent;
|
|
56
|
+
- accepted decisions whose consequences are portable;
|
|
57
|
+
- explicit learning intent/future ideas while preserving their non-authorizing maturity;
|
|
58
|
+
- exact source repository/commit and contributing artifact paths.
|
|
59
|
+
|
|
60
|
+
## Product Brief model
|
|
61
|
+
|
|
62
|
+
Project Forge generated workspaces currently use one canonical product authority:
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
docs/product/PRODUCT_BRIEF.md
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
The export therefore uses one normalized `product` object rather than inventing a multi-Product-Brief hierarchy.
|
|
69
|
+
|
|
70
|
+
If a non-generated/adopted workspace declares a different authority model, export only what that model actually establishes. Do not manufacture a second Product Brief merely to fit Project Forge defaults.
|
|
71
|
+
|
|
72
|
+
## Work-item maturity
|
|
73
|
+
|
|
74
|
+
Preserve maturity exactly.
|
|
75
|
+
|
|
76
|
+
Typical generated-project semantics include:
|
|
77
|
+
|
|
78
|
+
```text
|
|
79
|
+
V1 + committed
|
|
80
|
+
V2 + planned
|
|
81
|
+
V3 + directional
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Presence in `PROJECT_REQUIREMENTS.json` is never implementation authorization. A roadmap Feature remains roadmap/directional until separately promoted through the normal requirements/work-item process.
|
|
85
|
+
|
|
86
|
+
## Engineering Enablers
|
|
87
|
+
|
|
88
|
+
Engineering Enablers are usually implementation-specific and are not portable product requirements.
|
|
89
|
+
|
|
90
|
+
The export may retain an enabler in source traceability when it establishes a durable cross-cutting requirement, but replatforming normally re-derives stack-specific enablers rather than copying their IDs/scope.
|
|
91
|
+
|
|
92
|
+
Examples:
|
|
93
|
+
|
|
94
|
+
```text
|
|
95
|
+
PRESERVE: secure individual authentication is required for remote internet use
|
|
96
|
+
RE-DERIVE: configure ASP.NET authentication middleware
|
|
97
|
+
|
|
98
|
+
PRESERVE: database schema changes must be reproducible and controlled
|
|
99
|
+
RE-DERIVE: use EF Core migrations
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Mixed authorities
|
|
103
|
+
|
|
104
|
+
Some documents mix durable intent with implementation choices. Treat these as classification inputs rather than all-or-nothing copies.
|
|
105
|
+
|
|
106
|
+
Examples:
|
|
107
|
+
|
|
108
|
+
- a Project Blueprint may contain product/domain facts plus current technology baseline;
|
|
109
|
+
- a System Design may contain portable domain invariants plus React/.NET/SQLite topology;
|
|
110
|
+
- a UX pattern may contain portable interaction behavior plus component-library details;
|
|
111
|
+
- an ADR may establish both a product/security consequence and a stack-specific mechanism.
|
|
112
|
+
|
|
113
|
+
Extract the portable fact, retain source traceability, and exclude/reconcile the mechanism.
|
|
114
|
+
|
|
115
|
+
## Exclusions
|
|
116
|
+
|
|
117
|
+
Do not export as portable requirements unless the repository explicitly makes them true product constraints:
|
|
118
|
+
|
|
119
|
+
- programming languages/frameworks/component libraries;
|
|
120
|
+
- ORMs, package managers, build tools, test runners;
|
|
121
|
+
- repository/project directory layouts;
|
|
122
|
+
- generated client/tooling mechanisms;
|
|
123
|
+
- CI implementation commands;
|
|
124
|
+
- current deployment host/provider bindings;
|
|
125
|
+
- secrets/credentials/private runtime values;
|
|
126
|
+
- application source code;
|
|
127
|
+
- work-item plans/review/delivery history;
|
|
128
|
+
- Git/PR/CI evidence;
|
|
129
|
+
- Project Forge/Core/Bootstrap baseline state.
|
|
130
|
+
|
|
131
|
+
## Replatform relationship
|
|
132
|
+
|
|
133
|
+
The canonical flow is:
|
|
134
|
+
|
|
135
|
+
```text
|
|
136
|
+
project authorities
|
|
137
|
+
→ /export-requirements
|
|
138
|
+
→ PROJECT_REQUIREMENTS.json state=review
|
|
139
|
+
→ human approval
|
|
140
|
+
→ PROJECT_REQUIREMENTS.json state=approved
|
|
141
|
+
→ /replatform <target-stack>
|
|
142
|
+
→ current Bootstrap catalog reconciliation
|
|
143
|
+
→ PROJECT_BOOTSTRAP.json state=review
|
|
144
|
+
→ human Bootstrap approval
|
|
145
|
+
→ deterministic generation into a new repository
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`PROJECT_BOOTSTRAP.json` remains the generation/provenance contract for one implementation. `PROJECT_REQUIREMENTS.json` remains the portable product/domain interchange contract.
|
|
149
|
+
|
|
150
|
+
## No in-place replatforming
|
|
151
|
+
|
|
152
|
+
Replatforming creates a sibling/new implementation repository. It never rewrites the source application in place.
|
|
153
|
+
|
|
154
|
+
This preserves historical truth and allows multiple implementations of the same product intent to coexist, such as:
|
|
155
|
+
|
|
156
|
+
```text
|
|
157
|
+
Family Meal Planner requirements
|
|
158
|
+
├── React + ASP.NET Core implementation
|
|
159
|
+
├── Angular + Spring Boot implementation
|
|
160
|
+
└── Blazor + ASP.NET Core implementation
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## Security
|
|
164
|
+
|
|
165
|
+
The export must not contain secrets, credentials, private keys, access tokens, production data, machine-local bindings, or arbitrary runtime/log transcripts.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: build
|
|
3
|
+
description: "Build the current project through its repository-owned build command without turning local compilation into setup, testing, delivery, or deployment."
|
|
4
|
+
argument-hint: "[target|all]"
|
|
5
|
+
user-invocable: true
|
|
6
|
+
disable-model-invocation: true
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Build
|
|
10
|
+
|
|
11
|
+
`/build` is a thin local helper. It hides framework-specific command details while preserving the repository as the authority for how the project builds.
|
|
12
|
+
|
|
13
|
+
## Contract
|
|
14
|
+
|
|
15
|
+
Invoking `/build` authorizes one bounded local build attempt for the requested target. It does not authorize setup, dependency upgrades, source edits, delivery, release publication, deployment, or Production access.
|
|
16
|
+
|
|
17
|
+
Resolve the build command from current repository evidence in this order:
|
|
18
|
+
|
|
19
|
+
1. an explicit repository-owned build wrapper or documented build command;
|
|
20
|
+
2. an explicit package/task script whose purpose is build;
|
|
21
|
+
3. an unambiguous ecosystem-native build entry point already present in the repository.
|
|
22
|
+
|
|
23
|
+
Do not invent a command because a framework is recognizable. If multiple materially different build targets exist and no default is documented, require a target such as `/build web`, `/build api`, or `/build all`.
|
|
24
|
+
|
|
25
|
+
## Preconditions
|
|
26
|
+
|
|
27
|
+
Before execution:
|
|
28
|
+
|
|
29
|
+
- identify the repository root and current Git state;
|
|
30
|
+
- inspect `PROJECT_BOOTSTRAP.json` and scaffold/readiness evidence when present;
|
|
31
|
+
- verify that the selected build entry point exists;
|
|
32
|
+
- do not create an intentionally deferred scaffold merely to make `/build` succeed.
|
|
33
|
+
|
|
34
|
+
If the approved scaffold is deferred or required build markers do not exist, return `BUILD NOT AVAILABLE` with the smallest relevant reason. Do not run installation/scaffolding commands as an implicit repair.
|
|
35
|
+
|
|
36
|
+
If dependencies or workstation tools are missing, recommend `/setup` rather than broadening `/build`.
|
|
37
|
+
|
|
38
|
+
## Execution
|
|
39
|
+
|
|
40
|
+
Run the selected build visibly and report:
|
|
41
|
+
|
|
42
|
+
- target;
|
|
43
|
+
- resolved repository-owned command identity;
|
|
44
|
+
- success/failure and exit code when available;
|
|
45
|
+
- produced artifact/output locations when the build contract makes them explicit;
|
|
46
|
+
- effective application release/build identity when the build exposes it;
|
|
47
|
+
- a concise actionable failure summary.
|
|
48
|
+
|
|
49
|
+
Do not add linting, tests, formatting, packaging, container publishing, or code generation unless the repository's selected build command already defines them as part of that build.
|
|
50
|
+
|
|
51
|
+
When the project implements `docs/process/APPLICATION_VERSIONING.md`, report observed version evidence from the build output/artifact metadata. Do not synthesize a build number, commit, or display version when the repository did not produce it.
|
|
52
|
+
|
|
53
|
+
## Operation journal
|
|
54
|
+
|
|
55
|
+
A consequential build may write a concise sanitized journal under `.project-forge/logs/build/` following `docs/process/OPERATION_JOURNAL.md`.
|
|
56
|
+
|
|
57
|
+
Record the command identity, target, timestamps, exit status, explicit artifact paths, and observed application version/build identity when available. Do not blindly capture unlimited compiler/application output or secrets.
|
|
58
|
+
|
|
59
|
+
## Git and lifecycle boundary
|
|
60
|
+
|
|
61
|
+
`/build` must not:
|
|
62
|
+
|
|
63
|
+
- edit source or configuration to fix a build;
|
|
64
|
+
- stage, commit, push, open/update PRs, merge, or clean branches;
|
|
65
|
+
- mark a work item accepted or delivered;
|
|
66
|
+
- bump the application's release version merely to create a unique build;
|
|
67
|
+
- publish a package/image/release;
|
|
68
|
+
- deploy locally or remotely.
|
|
69
|
+
|
|
70
|
+
A successful build is local machine evidence only.
|
|
@@ -27,7 +27,7 @@ Prefer:
|
|
|
27
27
|
DEPLOYMENT_TOPOLOGY.json
|
|
28
28
|
```
|
|
29
29
|
|
|
30
|
-
Use `
|
|
30
|
+
Use `PROJECT_BOOTSTRAP.json` deployment topology only as the initial topology fallback.
|
|
31
31
|
|
|
32
32
|
Resolve exact configured name, purpose/Production classification, placement, isolation, exposure, binding, adapter, target/provider, and failure domain.
|
|
33
33
|
|
|
@@ -29,7 +29,7 @@ Prefer the project-owned mutable topology:
|
|
|
29
29
|
DEPLOYMENT_TOPOLOGY.json
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
-
Use `
|
|
32
|
+
Use `PROJECT_BOOTSTRAP.json` deployment topology only as the initial topology fallback. Do not rewrite Bootstrap provenance merely because a later environment changes.
|
|
33
33
|
|
|
34
34
|
Resolve the exact configured environment name plus, when present:
|
|
35
35
|
|
|
@@ -31,7 +31,7 @@ Never record a requested mode as ready until its readiness contract passes. If c
|
|
|
31
31
|
|
|
32
32
|
From the repository root inspect, when present:
|
|
33
33
|
|
|
34
|
-
- `
|
|
34
|
+
- `PROJECT_BOOTSTRAP.json`;
|
|
35
35
|
- `PROJECT_FORGE_BASELINE.json` and component baselines;
|
|
36
36
|
- `DEV_ENVIRONMENT.json`;
|
|
37
37
|
- application setup/build/test commands and project-owned persistence configuration;
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: export-requirements
|
|
3
|
+
description: "Export the workspace's durable product, domain, UX, roadmap, and approved feature intent into canonical PROJECT_REQUIREMENTS.json without copying stack-specific implementation choices."
|
|
4
|
+
argument-hint: "[review|approve]"
|
|
5
|
+
user-invocable: true
|
|
6
|
+
disable-model-invocation: true
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Export Project Requirements
|
|
10
|
+
|
|
11
|
+
`/export-requirements` creates the portable Project Forge requirements interchange artifact:
|
|
12
|
+
|
|
13
|
+
```text
|
|
14
|
+
PROJECT_REQUIREMENTS.json
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
It is a derived export of the workspace's existing authorities. It is not a competing requirements database and it never outranks the source Product Brief, Feature Briefs, approved detailed requirements, accepted product/domain decisions, or other repository authorities.
|
|
18
|
+
|
|
19
|
+
## Purpose
|
|
20
|
+
|
|
21
|
+
Use this export when the same product/system intent should be carried into a new implementation, especially `/replatform`.
|
|
22
|
+
|
|
23
|
+
The export answers:
|
|
24
|
+
|
|
25
|
+
> What must remain true about the product, domain, user experience, roadmap, and accepted cross-cutting behavior independent of this implementation stack?
|
|
26
|
+
|
|
27
|
+
It must not answer:
|
|
28
|
+
|
|
29
|
+
> Which framework, language, ORM, build tool, folder layout, or CI implementation should the next repository use?
|
|
30
|
+
|
|
31
|
+
## Source model
|
|
32
|
+
|
|
33
|
+
Start from the workspace's declared authority model. In a normal generated Project Forge workspace, inspect as applicable:
|
|
34
|
+
|
|
35
|
+
1. `docs/product/PRODUCT_BRIEF.md` as product authority;
|
|
36
|
+
2. `docs/product/IMPLEMENTATION_ROADMAP.md` for milestone/feature maturity and product sequencing facts;
|
|
37
|
+
3. Product Feature folders under `docs/work-items/`, including `brief.md` and approved `requirements.md`;
|
|
38
|
+
4. product/domain portions of architecture or system-design documents;
|
|
39
|
+
5. durable domain concepts, relationships, invariants, and business rules;
|
|
40
|
+
6. product-level design principles, accessibility/responsive requirements, and relevant interaction patterns;
|
|
41
|
+
7. accepted ADRs/decisions that constrain product/domain behavior;
|
|
42
|
+
8. approved cross-cutting security/privacy, reliability, performance, and data requirements;
|
|
43
|
+
9. learning goals/future ideas when they are explicitly part of project intent, preserving their non-authorizing status.
|
|
44
|
+
|
|
45
|
+
Treat summaries such as AI context briefs as reference/navigation unless the repository declares them authoritative.
|
|
46
|
+
|
|
47
|
+
## Preserve authority and maturity
|
|
48
|
+
|
|
49
|
+
Do not flatten roadmap maturity.
|
|
50
|
+
|
|
51
|
+
Preserve distinctions such as:
|
|
52
|
+
|
|
53
|
+
```text
|
|
54
|
+
V1 / committed / approved
|
|
55
|
+
V2 / planned / roadmap
|
|
56
|
+
V3 / directional / roadmap
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
A directional Feature remains directional in the export. Exporting it must not promote it into implementation scope.
|
|
60
|
+
|
|
61
|
+
## Classification
|
|
62
|
+
|
|
63
|
+
Classify source material before export.
|
|
64
|
+
|
|
65
|
+
### Preserve
|
|
66
|
+
|
|
67
|
+
Normally portable:
|
|
68
|
+
|
|
69
|
+
- product problem, goals, users, outcomes, scope/non-scope;
|
|
70
|
+
- Feature Brief intent and product dependencies;
|
|
71
|
+
- approved functional/domain requirements and acceptance criteria;
|
|
72
|
+
- domain concepts, relationships, invariants, lifecycle/state semantics, business rules;
|
|
73
|
+
- security/privacy outcomes and constraints;
|
|
74
|
+
- accessibility/responsive/product-experience requirements;
|
|
75
|
+
- product-level design principles and interaction intent;
|
|
76
|
+
- milestone/roadmap target and maturity;
|
|
77
|
+
- learning intent when explicitly part of the project.
|
|
78
|
+
|
|
79
|
+
### Reconcile
|
|
80
|
+
|
|
81
|
+
Require human review when a durable requirement is mixed with implementation detail, for example:
|
|
82
|
+
|
|
83
|
+
- API/persistence semantics expressed using a current framework;
|
|
84
|
+
- architecture documents containing both domain invariants and technology topology;
|
|
85
|
+
- ADRs that combine product consequences with stack choices;
|
|
86
|
+
- UX patterns containing both user behavior and component-library detail.
|
|
87
|
+
|
|
88
|
+
Preserve the durable intent and exclude/rephrase the implementation-specific mechanism.
|
|
89
|
+
|
|
90
|
+
### Exclude / re-derive
|
|
91
|
+
|
|
92
|
+
Do not export as portable requirements:
|
|
93
|
+
|
|
94
|
+
- React, Angular, Blazor, Java, C#, Spring Boot, ASP.NET Core, ORM, package-manager, or build-tool choices unless they are explicitly approved product constraints;
|
|
95
|
+
- source directory/project layout;
|
|
96
|
+
- framework/component-library implementation details;
|
|
97
|
+
- stack-specific Engineering Enablers;
|
|
98
|
+
- CI implementation commands;
|
|
99
|
+
- deployment scripts/bindings/credentials;
|
|
100
|
+
- implementation plans, code, review history, branch/PR/CI evidence;
|
|
101
|
+
- generated Project Forge/Core provenance.
|
|
102
|
+
|
|
103
|
+
## Artifact state and human gate
|
|
104
|
+
|
|
105
|
+
Default `/export-requirements` writes or refreshes `PROJECT_REQUIREMENTS.json` with `state: "review"` and exact source repository/commit provenance.
|
|
106
|
+
|
|
107
|
+
Before calling it approved, present a compact reconciliation summary:
|
|
108
|
+
|
|
109
|
+
```text
|
|
110
|
+
PROJECT REQUIREMENTS EXPORT
|
|
111
|
+
|
|
112
|
+
Preserved product/features: ...
|
|
113
|
+
Preserved domain rules: ...
|
|
114
|
+
Preserved UX/cross-cutting constraints: ...
|
|
115
|
+
Roadmap maturity retained: ...
|
|
116
|
+
Implementation-specific material excluded: ...
|
|
117
|
+
Items requiring reconciliation: ...
|
|
118
|
+
|
|
119
|
+
Approve PROJECT_REQUIREMENTS.json as the portable requirements baseline?
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Only explicit human approval may set `state: "approved"`.
|
|
123
|
+
|
|
124
|
+
`/export-requirements approve` may perform only that bounded finalization after confirming the reviewed content/evidence has not materially changed.
|
|
125
|
+
|
|
126
|
+
## Safety and scope
|
|
127
|
+
|
|
128
|
+
The skill may create/update only `PROJECT_REQUIREMENTS.json` unless the human separately authorizes source-document edits.
|
|
129
|
+
|
|
130
|
+
It must not silently rewrite source Product/Feature Briefs, requirements, architecture, ADRs, roadmap, or design documents to make export easier.
|
|
131
|
+
|
|
132
|
+
Do not export secrets, credentials, production values, personal runtime data, or machine-local bindings.
|
|
@@ -16,7 +16,7 @@ Invocation is read-only. `/progress` is a navigation/status surface, not a secon
|
|
|
16
16
|
|
|
17
17
|
Inspect only the evidence needed for the current lifecycle position. Useful sources include:
|
|
18
18
|
|
|
19
|
-
- `
|
|
19
|
+
- `PROJECT_BOOTSTRAP.json`, generated baselines, and repository history for project creation/provenance;
|
|
20
20
|
- `DEPLOYMENT_TOPOLOGY.json` as preferred project-owned mutable environment topology when present;
|
|
21
21
|
- `DEV_ENVIRONMENT.json`, generated setup scripts, workstation-local setup/developer-mode evidence, and safe setup checks for local readiness;
|
|
22
22
|
- observed OS/platform and machine-local evidence for **this workspace instance**;
|
|
@@ -24,7 +24,7 @@ Inspect only the evidence needed for the current lifecycle position. Useful sour
|
|
|
24
24
|
- work-item docs, Reviewer evidence, PR/CI state, and default-branch evidence;
|
|
25
25
|
- environment proof/readiness/deployment evidence for exact project-defined environments.
|
|
26
26
|
|
|
27
|
-
If `DEPLOYMENT_TOPOLOGY.json` does not exist, use `
|
|
27
|
+
If `DEPLOYMENT_TOPOLOGY.json` does not exist, use `PROJECT_BOOTSTRAP.json` deployment topology only as the initial topology fallback.
|
|
28
28
|
|
|
29
29
|
Never invent completion because a prior step normally happens. Prefer `UNKNOWN`/`NOT EVIDENCED` over false green state.
|
|
30
30
|
|
|
@@ -30,7 +30,7 @@ From the consumer root read:
|
|
|
30
30
|
- `PROJECT_FORGE_BASELINE.json`;
|
|
31
31
|
- `CORE_BASELINE.json` when present;
|
|
32
32
|
- `DEPLOYMENT_BASELINE.json` when present;
|
|
33
|
-
- `
|
|
33
|
+
- `PROJECT_BOOTSTRAP.json` when present;
|
|
34
34
|
- current Git status, branch, remotes, and default branch when observable.
|
|
35
35
|
|
|
36
36
|
Require `PROJECT_FORGE_BASELINE.json` to identify:
|
|
@@ -47,13 +47,13 @@ Do not synthesize or repair missing umbrella provenance by hand.
|
|
|
47
47
|
|
|
48
48
|
### Bootstrap-generated consumers
|
|
49
49
|
|
|
50
|
-
If `
|
|
50
|
+
If `PROJECT_BOOTSTRAP.json` exists, treat it as approved generated-consumer provenance, not unrelated product data.
|
|
51
51
|
|
|
52
52
|
Before planning an update, require `generation.projectForge.package`, `generation.projectForge.version`, and `generation.projectForge.profile` to agree exactly with the installed `PROJECT_FORGE_BASELINE.json`. Require `generation.projectForge.integrity` to be a non-empty exact registry integrity value for that installed package/version. Verify that integrity read-only from the registry when registry access is available.
|
|
53
53
|
|
|
54
54
|
If those values disagree before the update, report `GENERATED PROJECT FORGE METADATA DRIFT` and stop. Do not use `/project-forge-update` to silently reconcile an already-incoherent generated consumer.
|
|
55
55
|
|
|
56
|
-
Also inspect generated package-verification surfaces such as `.github/workflows/ci.yml` when present. If they duplicate the approved package version/integrity literally, record that current shape as companion generated metadata that must remain coherent with `
|
|
56
|
+
Also inspect generated package-verification surfaces such as `.github/workflows/ci.yml` when present. If they duplicate the approved package version/integrity literally, record that current shape as companion generated metadata that must remain coherent with `PROJECT_BOOTSTRAP.json` during the update. Do not rewrite locally customized or unrecognized generated surfaces by guesswork.
|
|
57
57
|
|
|
58
58
|
## 2. Verify the installed package baseline first
|
|
59
59
|
|
|
@@ -117,8 +117,8 @@ A modified retired Core path is different: never auto-add `--accept-retired core
|
|
|
117
117
|
|
|
118
118
|
For a Bootstrap-generated consumer, also preview the companion generated-consumer changes:
|
|
119
119
|
|
|
120
|
-
- `
|
|
121
|
-
- generated package-verification surfaces should consume `
|
|
120
|
+
- `PROJECT_BOOTSTRAP.json` keeps the same package/profile but changes `generation.projectForge.version` and `generation.projectForge.integrity` to the exact reviewed target;
|
|
121
|
+
- generated package-verification surfaces should consume `PROJECT_BOOTSTRAP.json` dynamically when the accepted Bootstrap contract supports that form;
|
|
122
122
|
- a recognized older Bootstrap-generated verification block may be migrated only when its embedded old package/version/integrity exactly match the currently approved manifest metadata;
|
|
123
123
|
- an unrecognized or locally modified generated verification surface is a stop condition, not permission to reconstruct Bootstrap output by hand.
|
|
124
124
|
|
|
@@ -148,7 +148,7 @@ Choosing option 1 authorizes only:
|
|
|
148
148
|
- creation/switch to one repository-appropriate short-lived update branch when needed;
|
|
149
149
|
- exact target package apply;
|
|
150
150
|
- removal of unchanged retired package-managed files that the reviewed preview classified as `REMOVE`;
|
|
151
|
-
- when `
|
|
151
|
+
- when `PROJECT_BOOTSTRAP.json` is present, update of its exact `generation.projectForge.version` and `generation.projectForge.integrity` to the reviewed target while preserving package/profile;
|
|
152
152
|
- migration of a recognized Bootstrap-generated package-verification block from duplicated current literals to the accepted manifest-driven form, only when the existing block still exactly matches the current approved metadata;
|
|
153
153
|
- package/baseline/generated-consumer verification;
|
|
154
154
|
- inspection of the resulting meaningful diff.
|
|
@@ -173,7 +173,7 @@ npx --yes @mriekki/project-forge@<target-version> update --apply
|
|
|
173
173
|
|
|
174
174
|
If explicit Core retired-path ownership transfer was separately approved, pass only the exact reviewed modified paths using the package's `--accept-retired core:<path>` contract. Never widen that set implicitly. Unchanged retired managed paths do not need this flag; the package updater removes them according to the reviewed `REMOVE` plan.
|
|
175
175
|
|
|
176
|
-
For a Bootstrap-generated consumer, complete the reviewed companion metadata changes in the same bounded update before declaring success. Preserve every unrelated `
|
|
176
|
+
For a Bootstrap-generated consumer, complete the reviewed companion metadata changes in the same bounded update before declaring success. Preserve every unrelated `PROJECT_BOOTSTRAP.json` field. Never change package identity or profile as an incidental version update.
|
|
177
177
|
|
|
178
178
|
Do not run direct `tools/package/sync.py`, Deployment Kit sync, or a remote `[sync-core]` request as part of a package-managed update.
|
|
179
179
|
|
|
@@ -190,7 +190,7 @@ Then inspect:
|
|
|
190
190
|
```text
|
|
191
191
|
git status --short --branch
|
|
192
192
|
git diff --stat
|
|
193
|
-
git diff -- PROJECT_FORGE_BASELINE.json CORE_BASELINE.json DEPLOYMENT_BASELINE.json
|
|
193
|
+
git diff -- PROJECT_FORGE_BASELINE.json CORE_BASELINE.json DEPLOYMENT_BASELINE.json PROJECT_BOOTSTRAP.json .github/workflows/ci.yml
|
|
194
194
|
```
|
|
195
195
|
|
|
196
196
|
Confirm:
|
|
@@ -199,7 +199,7 @@ Confirm:
|
|
|
199
199
|
- component baseline commits/distributions match the umbrella baseline;
|
|
200
200
|
- package check passes for the whole profile;
|
|
201
201
|
- unchanged retired managed files shown as `REMOVE` in the preview are actually absent after apply, while any explicitly transferred modified retired Core file remains present and is no longer Core-managed;
|
|
202
|
-
- when `
|
|
202
|
+
- when `PROJECT_BOOTSTRAP.json` exists, its package/version/profile agree with `PROJECT_FORGE_BASELINE.json` and its integrity equals the exact reviewed target registry integrity;
|
|
203
203
|
- when the repository contains `tools/project-forge-package/check-managed-baselines.py`, that generated baseline checker passes after all companion metadata changes;
|
|
204
204
|
- generated package-verification surfaces no longer contradict the approved manifest metadata;
|
|
205
205
|
- consumer-owned content was not overwritten;
|
|
@@ -218,7 +218,7 @@ Present the meaningful diff for human review. After acceptance, recommend `/deli
|
|
|
218
218
|
- performs a downgrade/rollback as an ordinary update;
|
|
219
219
|
- overwrites unexplained managed drift;
|
|
220
220
|
- auto-accepts Core retired-path ownership transfer for a modified retired file;
|
|
221
|
-
- silently repairs a pre-existing mismatch between `
|
|
221
|
+
- silently repairs a pre-existing mismatch between `PROJECT_BOOTSTRAP.json` and `PROJECT_FORGE_BASELINE.json`;
|
|
222
222
|
- changes a generated consumer's package identity/profile or regenerates the repository as an incidental version update;
|
|
223
223
|
- guesses at locally modified/unrecognized Bootstrap-generated verification logic;
|
|
224
224
|
- publishes npm/Core/Deployment/Bootstrap releases or tags;
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: replatform
|
|
3
|
+
description: "Create a new implementation proposal from approved PROJECT_REQUIREMENTS.json and a requested target stack without rewriting the source project in place."
|
|
4
|
+
argument-hint: "<target-stack-or-recipe>"
|
|
5
|
+
user-invocable: true
|
|
6
|
+
disable-model-invocation: true
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Replatform
|
|
10
|
+
|
|
11
|
+
`/replatform` creates a new implementation proposal for the same product/system intent using a different technology stack.
|
|
12
|
+
|
|
13
|
+
It never rewrites the source application in place.
|
|
14
|
+
|
|
15
|
+
## Required input
|
|
16
|
+
|
|
17
|
+
Use only the canonical portable export:
|
|
18
|
+
|
|
19
|
+
```text
|
|
20
|
+
PROJECT_REQUIREMENTS.json
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The file must be `state: "approved"`. Do not accept alternate/legacy requirements-export filenames or infer approval from file existence.
|
|
24
|
+
|
|
25
|
+
If the export is missing or stale relative to material source-requirement changes, use `/export-requirements` first.
|
|
26
|
+
|
|
27
|
+
## Target
|
|
28
|
+
|
|
29
|
+
The invocation supplies a target stack or current Bootstrap recipe, for example:
|
|
30
|
+
|
|
31
|
+
```text
|
|
32
|
+
/replatform angular java
|
|
33
|
+
/replatform java-angular-sqlite
|
|
34
|
+
/replatform blazor sqlite
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Resolve support against the current canonical Project Forge Bootstrap catalog. General model knowledge may explain an uncataloged technology, but label it `CATALOG GAP` and do not fabricate Bootstrap automation/support.
|
|
38
|
+
|
|
39
|
+
## Output boundary
|
|
40
|
+
|
|
41
|
+
The operation produces a new `PROJECT_BOOTSTRAP.json` proposal with `state: "review"` for a new target repository.
|
|
42
|
+
|
|
43
|
+
It must record derivation provenance back to the approved requirements export/source repository and identify the selected current Bootstrap catalog/protocol and Project Forge package provenance.
|
|
44
|
+
|
|
45
|
+
Do not generate application source or mutate the target repository until the normal Bootstrap manifest review/approval gate is complete.
|
|
46
|
+
|
|
47
|
+
## Reconciliation rules
|
|
48
|
+
|
|
49
|
+
Preserve from the approved requirements export:
|
|
50
|
+
|
|
51
|
+
- product problem/goals/users/outcomes;
|
|
52
|
+
- Product Feature intent and target maturity;
|
|
53
|
+
- approved functional/domain requirements and acceptance criteria;
|
|
54
|
+
- domain concepts, relationships, invariants, lifecycle/state semantics, and business rules;
|
|
55
|
+
- portable security/privacy/reliability/data constraints;
|
|
56
|
+
- portable design, accessibility, responsive, and interaction intent;
|
|
57
|
+
- roadmap maturity (`committed`, `planned`, `directional`);
|
|
58
|
+
- explicitly preserved learning intent.
|
|
59
|
+
|
|
60
|
+
Re-derive for the requested stack:
|
|
61
|
+
|
|
62
|
+
- Engineering Enablers;
|
|
63
|
+
- framework/application shell work;
|
|
64
|
+
- implementation architecture/topology;
|
|
65
|
+
- persistence/ORM implementation;
|
|
66
|
+
- API/client implementation choices;
|
|
67
|
+
- build/run/test commands and package tooling;
|
|
68
|
+
- stack-specific ADRs;
|
|
69
|
+
- CI implementation details;
|
|
70
|
+
- deployment mechanics that depend on the new architecture.
|
|
71
|
+
|
|
72
|
+
Do not automatically preserve source Engineering Enabler IDs. Product Feature IDs may remain traceable when the semantic Feature is unchanged; record source IDs even when the new implementation re-slices or renumbers work.
|
|
73
|
+
|
|
74
|
+
## New-repository rule
|
|
75
|
+
|
|
76
|
+
Replatforming requires a new target repository identity. The source repository is read-only evidence.
|
|
77
|
+
|
|
78
|
+
Never:
|
|
79
|
+
|
|
80
|
+
- overwrite the source repository;
|
|
81
|
+
- replace its `PROJECT_BOOTSTRAP.json`;
|
|
82
|
+
- delete or rewrite source implementation history;
|
|
83
|
+
- copy source application code by default;
|
|
84
|
+
- copy secrets, production data, credentials, machine bindings, or execution evidence.
|
|
85
|
+
|
|
86
|
+
## Bootstrap execution
|
|
87
|
+
|
|
88
|
+
Use the current canonical Bootstrap replatform tooling when available. The expected deterministic boundary is:
|
|
89
|
+
|
|
90
|
+
```text
|
|
91
|
+
approved PROJECT_REQUIREMENTS.json
|
|
92
|
+
+ requested current catalog recipe/stack
|
|
93
|
+
+ target repository identity
|
|
94
|
+
→ PROJECT_BOOTSTRAP.json state=review
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
If canonical Bootstrap replatform tooling/current catalog evidence is unavailable in the current environment, stop with `REPLATFORM HANDOFF REQUIRED`. Do not invent a manifest from stale remembered catalog facts.
|
|
98
|
+
|
|
99
|
+
## Human gate
|
|
100
|
+
|
|
101
|
+
Before generation, summarize at minimum:
|
|
102
|
+
|
|
103
|
+
```text
|
|
104
|
+
SOURCE REQUIREMENTS
|
|
105
|
+
source repository/commit
|
|
106
|
+
portable requirements export provenance
|
|
107
|
+
|
|
108
|
+
PRESERVED
|
|
109
|
+
product/features/domain/UX/cross-cutting intent
|
|
110
|
+
roadmap maturity
|
|
111
|
+
|
|
112
|
+
RE-DERIVED
|
|
113
|
+
stack-specific architecture and Engineering Enablers
|
|
114
|
+
|
|
115
|
+
TARGET STACK
|
|
116
|
+
resolved current catalog recipe and support state
|
|
117
|
+
|
|
118
|
+
OUTPUT
|
|
119
|
+
PROJECT_BOOTSTRAP.json — REVIEW
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Then use the normal material Bootstrap manifest approval gate. Approval of replatform intent is not approval to merge, release, or deploy the resulting implementation.
|