nimai-core 0.4.8 → 0.5.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/data/FORGE-quickref.md +326 -0
- package/data/nimai-spec-full.md +63 -0
- package/data/nimai-spec-lite.md +39 -0
- package/dist/forge-root.d.ts +2 -0
- package/dist/forge-root.d.ts.map +1 -0
- package/dist/forge-root.js +61 -0
- package/dist/forge-root.js.map +1 -0
- package/dist/index.d.ts +1 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -2
- package/dist/index.js.map +1 -1
- package/dist/lint.d.ts.map +1 -1
- package/dist/lint.js +88 -311
- package/dist/lint.js.map +1 -1
- package/dist/prompts.d.ts +18 -8
- package/dist/prompts.d.ts.map +1 -1
- package/dist/prompts.js +108 -53
- package/dist/prompts.js.map +1 -1
- package/dist/template.d.ts +12 -1
- package/dist/template.d.ts.map +1 -1
- package/dist/template.js +32 -0
- package/dist/template.js.map +1 -1
- package/dist/types.d.ts +3 -7
- package/dist/types.d.ts.map +1 -1
- package/package.json +3 -2
- package/dist/clarification.d.ts +0 -22
- package/dist/clarification.d.ts.map +0 -1
- package/dist/clarification.js +0 -106
- package/dist/clarification.js.map +0 -1
- package/dist/context.d.ts +0 -3
- package/dist/context.d.ts.map +0 -1
- package/dist/context.js +0 -186
- package/dist/context.js.map +0 -1
|
@@ -0,0 +1,326 @@
|
|
|
1
|
+
# FORGE Quick Reference
|
|
2
|
+
> **You are here:** This is the operational tool — the doc an agent uses during active work.
|
|
3
|
+
>
|
|
4
|
+
> **The other docs in this system:**
|
|
5
|
+
> - **Canonical Framework** (`FORGE-canonical.md`) — deep explanation of every concept. Go there to understand *why* something works, not just *what* to do.
|
|
6
|
+
> - **Spec Template** (`FORGE-spec-template.md`) — fill-in-the-blank form for a concrete project. Go there when you have a direction and need to turn it into an agent-ready brief.
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Agent Routing: What To Do Based On The Request
|
|
11
|
+
|
|
12
|
+
*Read the request and match it to a route before doing anything else.*
|
|
13
|
+
|
|
14
|
+
| If the request is… | Route |
|
|
15
|
+
|---|---|
|
|
16
|
+
| A new idea or creative problem — no direction yet | Run **Divergence → Convergence Loop** below. Stay in this doc. |
|
|
17
|
+
| A loose or vague request that needs structuring | Run **Self-Spec Agent** prompt (see below) to generate a draft spec. |
|
|
18
|
+
| A specific project ready to execute | Go to **Spec Template** → fill it out → deploy. |
|
|
19
|
+
| How to approach or frame something | Use **4 Layers + 5 Primitives** below. Deeper detail in Canonical doc. |
|
|
20
|
+
| Reviewing, validating, or debugging existing work | Run **Failure Mode Taxonomy** red-team below. |
|
|
21
|
+
| Something feels wrong mid-project | Check **Failure Mode Taxonomy** first, then check Intent Layer for drift. |
|
|
22
|
+
| A concept here that needs deeper explanation | Go to **Canonical Framework** for the full treatment. |
|
|
23
|
+
| Building a multi-agent or long-running system | Go to **Canonical Framework** → Execution Architecture + Extended Patterns. |
|
|
24
|
+
|
|
25
|
+
**Default rule:** Start here. Go to Canonical to understand. Go to Spec Template to execute.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## The Deeper Thesis
|
|
30
|
+
Agents fail not from lack of intelligence but from **underspecified control surfaces**. The four control surfaces are specification, intent, context, and prompt. Engineer all four.
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## The 4 Engineering Disciplines / Control Surfaces
|
|
35
|
+
|
|
36
|
+
| Discipline | Control Surface | Skip It And… |
|
|
37
|
+
|---|---|---|
|
|
38
|
+
| **Prompt Craft** | Sub-task trigger | Agent doesn't know what to do right now |
|
|
39
|
+
| **Context Engineering** | Information environment | Agent works from noise or stale data |
|
|
40
|
+
| **Intent Engineering** | Values, trade-offs, deployment purpose | Agent resolves ambiguity the wrong way |
|
|
41
|
+
| **Specification Engineering** | Complete blueprint for "done" | Agent can't define done and never stops |
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## The 4 Layers (in order of leverage)
|
|
46
|
+
|
|
47
|
+
| Layer | Role | Anti-Pattern |
|
|
48
|
+
|---|---|---|
|
|
49
|
+
| **1. Specification** | Defines exact "done" state + scope | Vague goals ("improve this") |
|
|
50
|
+
| **2. Intent** | Agent's deployment purpose + trade-off hierarchy | Agent doesn't know its own role |
|
|
51
|
+
| **3. Context** | Curated information environment | Dumping everything you have |
|
|
52
|
+
| **4. Prompt** | Fires sub-task + assigns cognitive mode | Over-engineering this layer |
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## The 5 Primitives (every sub-task must pass all 5)
|
|
57
|
+
|
|
58
|
+
1. **Self-Contained** — Zero questions needed to start
|
|
59
|
+
2. **Constrained** — Must / Must-Not / Prefer / Escalate defined
|
|
60
|
+
3. **Modular** — Under 2 hours; independently verifiable
|
|
61
|
+
4. **Acceptance Criteria** — Binary, measurable (not "looks good")
|
|
62
|
+
5. **Evaluation** — Built-in check before reporting complete
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Pre-Execution Decisions (set BEFORE decomposition)
|
|
67
|
+
|
|
68
|
+
**Risk Tier:**
|
|
69
|
+
| Tier | Validation |
|
|
70
|
+
|---|---|
|
|
71
|
+
| Low | Self-check only |
|
|
72
|
+
| Medium | Validator pass |
|
|
73
|
+
| High | Validator + Adversarial Reflection + Human gate |
|
|
74
|
+
|
|
75
|
+
**Resource Governance:** Model tier · Max runtime · Cost budget · Retry limit · Cost escalation trigger
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Cognitive Modes (reasoning postures, not personas)
|
|
80
|
+
|
|
81
|
+
| Mode | Use When |
|
|
82
|
+
|---|---|
|
|
83
|
+
| **Deterministic** | Implementation; answer is knowable |
|
|
84
|
+
| **Exploratory** | Research, brainstorming, hypothesis generation |
|
|
85
|
+
| **Adversarial** | Security, risk, stress-testing |
|
|
86
|
+
| **Synthesis** | Integrating multiple outputs |
|
|
87
|
+
| **Audit** | Validation only — do not produce |
|
|
88
|
+
|
|
89
|
+
**Over-specification warning:** Constrain evaluation, not divergence. In Exploratory phases, tight constraints on generation defeat the purpose. Reserve hard constraints for Adversarial and Deterministic phases.
|
|
90
|
+
|
|
91
|
+
**Mode × Risk compatibility:** Exploratory mode is a pre-commitment mode. High risk tasks should be in Deterministic or Audit by final delivery. Exploratory + High risk as a final-delivery combination is a design error.
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## Divergence → Convergence Loop (brainstorming)
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
Exploratory → Synthesis → Adversarial → Deterministic
|
|
99
|
+
DIVERGE CLUSTER STRESS-TEST FORMALIZE
|
|
100
|
+
```
|
|
101
|
+
Generate wide → cluster patterns → attack top candidates → execute selected direction.
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## Failure Mode Taxonomy (red-team before deployment)
|
|
106
|
+
|
|
107
|
+
| Failure | Cause | Fix |
|
|
108
|
+
|---|---|---|
|
|
109
|
+
| Scope Creep | Ambiguous boundaries | Explicit Must-Not list |
|
|
110
|
+
| Hallucinated Completion | Subjective criteria | Binary acceptance criteria |
|
|
111
|
+
| Intent Drift | Unclear trade-offs or role | Ranked priorities + deployment purpose |
|
|
112
|
+
| Context Collapse | Too much noise | Aggressive curation; MCP for live sources |
|
|
113
|
+
| Runaway Cost | No resource ceiling | Hard caps before decomposition |
|
|
114
|
+
| Overconfident Output | No uncertainty surfacing | Uncertainty reporting for high-stakes tasks |
|
|
115
|
+
|
|
116
|
+
*If a failure doesn't fit these categories, extend the taxonomy — log it, identify root cause, add prevention.*
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Intent = Deployment Purpose + Trade-offs
|
|
121
|
+
Every agent must know: **what it is · what it isn't · who consumes its output · what to optimize for when uncertain**
|
|
122
|
+
|
|
123
|
+
## Adversarial Reflection (Medium/High risk)
|
|
124
|
+
Produce → steelman critique → evaluate → revise → re-validate
|
|
125
|
+
|
|
126
|
+
## Uncertainty Reporting (non-deterministic domains)
|
|
127
|
+
Confidence % · uncertainty drivers · what would change the answer · alternative interpretations
|
|
128
|
+
|
|
129
|
+
## Escalation Contract
|
|
130
|
+
WHEN to stop · WHAT to report (include confidence) · WHO decides (named + SLA) · WHAT if no response
|
|
131
|
+
|
|
132
|
+
## Context Hygiene
|
|
133
|
+
2k high-signal tokens > 20k low-signal tokens · MCP for live sources · specify when to re-fetch
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## When To Use This Framework
|
|
138
|
+
|
|
139
|
+
The overhead should be proportional to the cost of failure. Use this as your guide:
|
|
140
|
+
|
|
141
|
+
| Situation | What to use |
|
|
142
|
+
|---|---|
|
|
143
|
+
| Task is reversible, low-stakes, under 1 hour | Routing table above + nothing else. Just start. |
|
|
144
|
+
| Task is consequential or takes more than 1 hour | Quickref checklist minimum. Self-Spec agent if unsure. |
|
|
145
|
+
| Task is high-risk, irreversible, or affects others | Full Spec Template + Adversarial Reflection + Validator |
|
|
146
|
+
| You're not sure | Ask: "What's the cost if this goes wrong?" Scale accordingly. |
|
|
147
|
+
|
|
148
|
+
**The philosophy:** This framework exists to absorb any project — coding, science, writing, business, anything — and give it the structure needed to succeed without fail. Use as much or as little as the project demands. The principles apply universally; the overhead scales with stakes.
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## Solo Operator Mode
|
|
153
|
+
|
|
154
|
+
If you are working alone without a team, validators, or named escalation contacts, adapt as follows:
|
|
155
|
+
|
|
156
|
+
**Escalation contract:** You are the reviewer. Set a time delay instead of an SLA — *"I will not proceed on this decision for 24 hours."* Distance and time create the same circuit-break that a second person would.
|
|
157
|
+
|
|
158
|
+
**Validation:** For Medium risk, run the Adversarial Reflection yourself or have a second agent session do it cold — paste the output into a fresh context with no prior history and ask it to find flaws.
|
|
159
|
+
|
|
160
|
+
**High risk solo:** Add a mandatory pause before any irreversible action. Write out the decision, the alternatives you considered, and your confidence level before executing. This is your human gate.
|
|
161
|
+
|
|
162
|
+
**The Self-Spec + Reviewer pipeline replaces team infrastructure** — see below.
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## Self-Spec Agent + Reviewer Pipeline
|
|
167
|
+
|
|
168
|
+
This is the solo operator's complete workflow. Two prompts replace an entire team process.
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
### Prompt 1 — Self-Spec Agent
|
|
173
|
+
*Use when you have a loose idea or vague request and need it turned into a complete spec.*
|
|
174
|
+
|
|
175
|
+
Paste this prompt to any capable model along with your loose request:
|
|
176
|
+
|
|
177
|
+
```
|
|
178
|
+
You are a Specification Engineering agent operating under the FORGE.
|
|
179
|
+
|
|
180
|
+
Your job is to take the loose request below and generate a complete draft spec
|
|
181
|
+
using the framework's structure. Do not execute the request — only spec it.
|
|
182
|
+
|
|
183
|
+
For each section, fill in what you can infer and mark anything uncertain
|
|
184
|
+
with [NEEDS HUMAN INPUT: reason].
|
|
185
|
+
|
|
186
|
+
Generate:
|
|
187
|
+
1. Final deliverable (precise, format, measurable quality bar)
|
|
188
|
+
2. Scope boundaries (in / out)
|
|
189
|
+
3. Agent deployment purpose (what it is, is not, who consumes output)
|
|
190
|
+
4. Trade-off hierarchy (ranked: accuracy / speed / cost / safety / other)
|
|
191
|
+
5. Constraint architecture (Must / Must-Not / Prefer / Escalate)
|
|
192
|
+
6. Task decomposition (sub-tasks under 2 hours, with acceptance criteria)
|
|
193
|
+
7. Risk tier (Low / Medium / High with reasoning)
|
|
194
|
+
8. Cognitive mode per sub-task
|
|
195
|
+
9. Context needed (what the executing agent requires)
|
|
196
|
+
10. Architecture Lock details for medium/high coding specs (Persistence layer, File/object storage, External model/service + env var, API trigger flow, Entity status state machine, Auth implementation)
|
|
197
|
+
11. Proposed validator prompt (what a reviewer should check)
|
|
198
|
+
|
|
199
|
+
Loose request: [PASTE YOUR REQUEST HERE]
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Review the output. Resolve all [NEEDS HUMAN INPUT] flags. Adjust anything that
|
|
203
|
+
doesn't match your intent. Approved spec = your deployment brief.
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
### Prompt 1.5 — Spec-Quality Reviewer
|
|
208
|
+
*Run this on a draft spec before approving it. The reviewing LLM checks whether the spec is agent-ready.*
|
|
209
|
+
|
|
210
|
+
```
|
|
211
|
+
You are the independent reviewer for this draft spec. Evaluate it now.
|
|
212
|
+
You are a Specification Quality Reviewer operating under the FORGE framework.
|
|
213
|
+
|
|
214
|
+
Your job is to evaluate the draft spec below for spec quality only — not implementation correctness.
|
|
215
|
+
Do NOT assess any code, code diffs, or implementation output.
|
|
216
|
+
|
|
217
|
+
Evaluate each dimension. Cite evidence for every verdict — a verdict without citation is treated as NO_GO.
|
|
218
|
+
Classify each issue as HARD_FAIL, SOFT_FAIL, or NOTE. passed: true requires zero HARD_FAILs.
|
|
219
|
+
|
|
220
|
+
1. Binary acceptance criteria — are all sub-task ACs measurable and unambiguous? Pre-checked [x] ACs are always invalid.
|
|
221
|
+
2. Scope coherence — are in-scope/out-of-scope boundaries clear and non-contradictory? Terminology mismatches between conceptual and persisted representations are a HARD_FAIL.
|
|
222
|
+
3. Constraint sufficiency — do Must/Must-Not/Prefer/Escalate constraints cover the key risks?
|
|
223
|
+
4. Decomposition realism — can each sub-task be done within 2 hours? Sub-task dependencies must be explicit.
|
|
224
|
+
5. Start-without-clarification viability — can an agent begin immediately with the context provided?
|
|
225
|
+
6. Internal consistency — are terms, names, and concepts used consistently throughout?
|
|
226
|
+
7. Mechanism lock — does every core flow commit to exactly ONE implementation path? Any "e.g./or/could/might/such as" in Deliverable, Scope, Constraints, or Tasks is a HARD_FAIL.
|
|
227
|
+
8. Convergence declaration — does the spec include a Spec Convergence section with open_questions: 0 and ambiguities_remaining: 0? Absent, non-zero, or ready_for_build: no is a HARD_FAIL.
|
|
228
|
+
9. Adversarial gap scan — does the spec include a substantively filled Edge Cases and Failure Modes section? Steelman as a builder following it exactly: what failure modes are unaddressed? Absent or placeholder-only is a HARD_FAIL for medium/high risk specs.
|
|
229
|
+
10. Architecture completeness — for medium/high coding specs, does the spec include `## 1.6 Architecture Lock` with resolved fields for Persistence layer, File/object storage, External model/service + env var, API trigger flow, Entity status state machine, and Auth implementation? Missing, blank, `___`, or `TBD` is a HARD_FAIL.
|
|
230
|
+
|
|
231
|
+
Always end your response with:
|
|
232
|
+
## Verdict
|
|
233
|
+
```json
|
|
234
|
+
{"passed": <true|false>, "schema_version": "2", "issues": [{"dimension": "<name>", "severity": "<HARD_FAIL|SOFT_FAIL|NOTE>", "detail": "<cited evidence>"}]}
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
Draft spec: [PASTE DRAFT SPEC HERE]
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
The host agent parses the `## Verdict` JSON block to drive the review loop:
|
|
241
|
+
- `passed: true` → proceed to implementation
|
|
242
|
+
- `passed: false` → refine the spec using the `issues` list, then re-review
|
|
243
|
+
- Block absent or malformed → escalate to the human
|
|
244
|
+
|
|
245
|
+
Use `nimai_spec_review` to generate this prompt automatically from a spec file.
|
|
246
|
+
|
|
247
|
+
When Prompt 1.5 fails, the reviewer should append a `## Builder Brief` section after the verdict with one actionable fix per issue (section to edit + concrete fix direction).
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
### Prompt 2 — Reviewer / Validator Prompt Generator
|
|
252
|
+
*Run this after Self-Spec is approved. Paste along with the approved spec.*
|
|
253
|
+
|
|
254
|
+
```
|
|
255
|
+
You are a Specification Engineering agent.
|
|
256
|
+
|
|
257
|
+
Given the approved spec below, generate a Reviewer Prompt — precise instructions
|
|
258
|
+
for a validator agent or solo reviewer to check the executing agent's output.
|
|
259
|
+
|
|
260
|
+
The Reviewer Prompt must:
|
|
261
|
+
- State exactly what is being checked and why
|
|
262
|
+
- List binary pass/fail criteria from the spec's acceptance criteria
|
|
263
|
+
- Include Adversarial Reflection sequence if risk tier is Medium or High
|
|
264
|
+
- Include uncertainty reporting requirements if domain is non-deterministic
|
|
265
|
+
- Specify what PASS looks like and what FAIL triggers (revise / escalate / abort)
|
|
266
|
+
- Be usable by a solo operator with no additional context
|
|
267
|
+
|
|
268
|
+
Approved spec: [PASTE APPROVED SPEC HERE]
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
---
|
|
272
|
+
|
|
273
|
+
### The Complete Solo Pipeline
|
|
274
|
+
|
|
275
|
+
```
|
|
276
|
+
Loose request
|
|
277
|
+
↓
|
|
278
|
+
Self-Spec Agent (Prompt 1) → draft spec
|
|
279
|
+
↓
|
|
280
|
+
Spec-Quality Reviewer (Prompt 1.5) → passed? → NO → refine spec → loop
|
|
281
|
+
↓ YES
|
|
282
|
+
Human reviews + resolves [NEEDS HUMAN INPUT] flags
|
|
283
|
+
↓
|
|
284
|
+
Approved spec → Reviewer Prompt Generator (Prompt 2) → validator prompt
|
|
285
|
+
↓
|
|
286
|
+
Deploy executing agent with approved spec
|
|
287
|
+
↓
|
|
288
|
+
Paste output + validator prompt into fresh agent session
|
|
289
|
+
↓
|
|
290
|
+
PASS → done | FAIL → revise or escalate
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
---
|
|
294
|
+
|
|
295
|
+
## Pre-Deployment Checklist
|
|
296
|
+
|
|
297
|
+
**Specification**
|
|
298
|
+
- [ ] Deliverable precise; scope boundaries explicit
|
|
299
|
+
- [ ] Sub-tasks satisfy all 5 Primitives
|
|
300
|
+
- [ ] For medium/high coding specs, `## 1.6 Architecture Lock` is present and fully resolved (no blank/`___`/`TBD` fields)
|
|
301
|
+
|
|
302
|
+
**Intent**
|
|
303
|
+
- [ ] Each agent has explicit deployment purpose
|
|
304
|
+
- [ ] Trade-off hierarchy ranked; escalation contract complete
|
|
305
|
+
|
|
306
|
+
**Context**
|
|
307
|
+
- [ ] Context curated; MCP for live sources; freshness strategy set
|
|
308
|
+
|
|
309
|
+
**Execution** *(set before decomposition)*
|
|
310
|
+
- [ ] Risk tier assigned
|
|
311
|
+
- [ ] Resource Governance parameters set
|
|
312
|
+
- [ ] Cognitive mode per sub-task assigned
|
|
313
|
+
- [ ] Validation routes by risk tier
|
|
314
|
+
- [ ] Adversarial Reflection for medium/high risk
|
|
315
|
+
- [ ] Uncertainty reporting for non-deterministic domains
|
|
316
|
+
|
|
317
|
+
**Meta**
|
|
318
|
+
- [ ] Spec red-teamed against Failure Mode Taxonomy
|
|
319
|
+
- [ ] Planner execution plan will be saved as artifact
|
|
320
|
+
- [ ] Living Specification log set up (multi-session)
|
|
321
|
+
- [ ] Spec Convergence section filled — `open_questions: 0`, `ambiguities_remaining: 0`, `ready_for_build: yes`
|
|
322
|
+
|
|
323
|
+
---
|
|
324
|
+
|
|
325
|
+
*FORGE v1.0 — Framework for Orchestrating Reliable Generative Execution*
|
|
326
|
+
*System docs: Quick Reference (this doc) · Canonical Framework · Spec Template*
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Spec: [title]
|
|
2
|
+
|
|
3
|
+
## Deliverable
|
|
4
|
+
*What exists when this is done. Name the artifact, not the activity.*
|
|
5
|
+
|
|
6
|
+
- Artifact:
|
|
7
|
+
- Format:
|
|
8
|
+
- Quality bar (measurable — a number, a passing command, a checkable property):
|
|
9
|
+
|
|
10
|
+
## Scope
|
|
11
|
+
**In scope:**
|
|
12
|
+
-
|
|
13
|
+
|
|
14
|
+
**Out of scope (will not be built — be explicit, this is what prevents drift):**
|
|
15
|
+
-
|
|
16
|
+
|
|
17
|
+
## Task Decomposition
|
|
18
|
+
*Each sub-task completable in under 2 hours, with its own binary acceptance criteria. State dependencies between sub-tasks explicitly.*
|
|
19
|
+
|
|
20
|
+
| # | Sub-task | Depends on | Acceptance criteria | How it is checked |
|
|
21
|
+
|---|---|---|---|---|
|
|
22
|
+
| 1 | | — | | |
|
|
23
|
+
|
|
24
|
+
## Mechanism Decisions
|
|
25
|
+
*One block per core choice. A builder must never have to pick an approach mid-build.*
|
|
26
|
+
|
|
27
|
+
**Decision: [short name]**
|
|
28
|
+
- Chosen: [exactly one approach]
|
|
29
|
+
- Rejected: [the alternatives considered]
|
|
30
|
+
- Why: [one sentence]
|
|
31
|
+
|
|
32
|
+
## Architecture Lock
|
|
33
|
+
*Resolve every line. "TBD" and blanks mean the spec is not ready. Write "none" where a field genuinely does not apply, with a reason.*
|
|
34
|
+
|
|
35
|
+
- Persistence layer:
|
|
36
|
+
- File/object storage:
|
|
37
|
+
- External services + env vars:
|
|
38
|
+
- API/trigger flow:
|
|
39
|
+
- Entity states and transitions:
|
|
40
|
+
- Auth:
|
|
41
|
+
|
|
42
|
+
## Change Surface
|
|
43
|
+
*Every existing file this work touches, classified. The builder may not touch anything outside this table.*
|
|
44
|
+
*Greenfield project? Replace the table with the single line: "Greenfield — no existing code to change."*
|
|
45
|
+
|
|
46
|
+
| Path | Verb (DELETE / REWRITE / EDIT / KEEP) | Why |
|
|
47
|
+
|---|---|---|
|
|
48
|
+
| | | |
|
|
49
|
+
|
|
50
|
+
## Edge Cases and Failure Modes
|
|
51
|
+
*What will the builder hit mid-execution that the sections above do not answer? An empty list here is a red flag, not a green one.*
|
|
52
|
+
|
|
53
|
+
-
|
|
54
|
+
-
|
|
55
|
+
|
|
56
|
+
## Spec Convergence
|
|
57
|
+
*Non-zero counts mean this spec is not ready. Fix the spec, not the numbers.*
|
|
58
|
+
|
|
59
|
+
open_questions: 0
|
|
60
|
+
ambiguities_remaining: 0
|
|
61
|
+
ready_for_build: yes
|
|
62
|
+
|
|
63
|
+
<!-- nimai-spec tier=full -->
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Spec: [title]
|
|
2
|
+
|
|
3
|
+
## Deliverable
|
|
4
|
+
*What exists when this is done. Name the artifact, not the activity.*
|
|
5
|
+
|
|
6
|
+
- Artifact:
|
|
7
|
+
- Format:
|
|
8
|
+
- Quality bar (measurable — a number, a passing command, a checkable property):
|
|
9
|
+
|
|
10
|
+
## Scope
|
|
11
|
+
**In scope:**
|
|
12
|
+
-
|
|
13
|
+
|
|
14
|
+
**Out of scope (will not be built — be explicit, this is what prevents drift):**
|
|
15
|
+
-
|
|
16
|
+
|
|
17
|
+
## Acceptance Criteria
|
|
18
|
+
*Binary and checkable. Leave every box unchecked — they are checked by the reviewer, not the author.*
|
|
19
|
+
|
|
20
|
+
Done when ALL of these are true:
|
|
21
|
+
- [ ]
|
|
22
|
+
- [ ]
|
|
23
|
+
|
|
24
|
+
## Mechanism Decisions
|
|
25
|
+
*One block per core choice. A builder must never have to pick an approach mid-build.*
|
|
26
|
+
|
|
27
|
+
**Decision: [short name]**
|
|
28
|
+
- Chosen: [exactly one approach]
|
|
29
|
+
- Rejected: [the alternatives considered]
|
|
30
|
+
- Why: [one sentence]
|
|
31
|
+
|
|
32
|
+
## Spec Convergence
|
|
33
|
+
*Non-zero counts mean this spec is not ready. Fix the spec, not the numbers.*
|
|
34
|
+
|
|
35
|
+
open_questions: 0
|
|
36
|
+
ambiguities_remaining: 0
|
|
37
|
+
ready_for_build: yes
|
|
38
|
+
|
|
39
|
+
<!-- nimai-spec tier=lite -->
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"forge-root.d.ts","sourceRoot":"","sources":["../src/forge-root.ts"],"names":[],"mappings":"AAyBA,eAAO,MAAM,UAAU,QAAkB,CAAC"}
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
14
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
15
|
+
}) : function(o, v) {
|
|
16
|
+
o["default"] = v;
|
|
17
|
+
});
|
|
18
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
+
var ownKeys = function(o) {
|
|
20
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
+
var ar = [];
|
|
22
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
+
return ar;
|
|
24
|
+
};
|
|
25
|
+
return ownKeys(o);
|
|
26
|
+
};
|
|
27
|
+
return function (mod) {
|
|
28
|
+
if (mod && mod.__esModule) return mod;
|
|
29
|
+
var result = {};
|
|
30
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
+
__setModuleDefault(result, mod);
|
|
32
|
+
return result;
|
|
33
|
+
};
|
|
34
|
+
})();
|
|
35
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.FORGE_ROOT = void 0;
|
|
37
|
+
const fs = __importStar(require("fs"));
|
|
38
|
+
const path = __importStar(require("path"));
|
|
39
|
+
/**
|
|
40
|
+
* Locate the FORGE docs root by walking up from __dirname until we find
|
|
41
|
+
* FORGE-quickref.md. Works regardless of where the package is installed.
|
|
42
|
+
*/
|
|
43
|
+
function findForgeRoot() {
|
|
44
|
+
// 1. Check bundled data/ directory (works when installed via npm)
|
|
45
|
+
const bundled = path.join(__dirname, '..', 'data');
|
|
46
|
+
if (fs.existsSync(path.join(bundled, 'FORGE-quickref.md')))
|
|
47
|
+
return bundled;
|
|
48
|
+
// 2. Walk up from __dirname (works in monorepo dev)
|
|
49
|
+
let dir = __dirname;
|
|
50
|
+
for (let i = 0; i < 10; i++) {
|
|
51
|
+
if (fs.existsSync(path.join(dir, 'FORGE-quickref.md')))
|
|
52
|
+
return dir;
|
|
53
|
+
const parent = path.dirname(dir);
|
|
54
|
+
if (parent === dir)
|
|
55
|
+
break;
|
|
56
|
+
dir = parent;
|
|
57
|
+
}
|
|
58
|
+
throw new Error('Cannot locate FORGE-quickref.md. Ensure the FORGE docs are present at the repo root.');
|
|
59
|
+
}
|
|
60
|
+
exports.FORGE_ROOT = findForgeRoot();
|
|
61
|
+
//# sourceMappingURL=forge-root.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"forge-root.js","sourceRoot":"","sources":["../src/forge-root.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,uCAAyB;AACzB,2CAA6B;AAE7B;;;GAGG;AACH,SAAS,aAAa;IACpB,kEAAkE;IAClE,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACnD,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;QAAE,OAAO,OAAO,CAAC;IAE3E,oDAAoD;IACpD,IAAI,GAAG,GAAG,SAAS,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QACnE,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IACD,MAAM,IAAI,KAAK,CACb,sFAAsF,CACvF,CAAC;AACJ,CAAC;AAEY,QAAA,UAAU,GAAG,aAAa,EAAE,CAAC"}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,9 +1,8 @@
|
|
|
1
1
|
export * from './types';
|
|
2
2
|
export * from './template';
|
|
3
3
|
export * from './lint';
|
|
4
|
-
export * from './context';
|
|
5
4
|
export * from './prompts';
|
|
6
|
-
export * from './clarification';
|
|
7
5
|
export * from './discovery';
|
|
8
6
|
export * from './verdict';
|
|
7
|
+
export * from './forge-root';
|
|
9
8
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -17,9 +17,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
17
17
|
__exportStar(require("./types"), exports);
|
|
18
18
|
__exportStar(require("./template"), exports);
|
|
19
19
|
__exportStar(require("./lint"), exports);
|
|
20
|
-
__exportStar(require("./context"), exports);
|
|
21
20
|
__exportStar(require("./prompts"), exports);
|
|
22
|
-
__exportStar(require("./clarification"), exports);
|
|
23
21
|
__exportStar(require("./discovery"), exports);
|
|
24
22
|
__exportStar(require("./verdict"), exports);
|
|
23
|
+
__exportStar(require("./forge-root"), exports);
|
|
25
24
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,6CAA2B;AAC3B,yCAAuB;AACvB,4CAA0B;AAC1B,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,6CAA2B;AAC3B,yCAAuB;AACvB,4CAA0B;AAC1B,8CAA4B;AAC5B,4CAA0B;AAC1B,+CAA6B"}
|
package/dist/lint.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAiB,MAAM,SAAS,CAAC;
|
|
1
|
+
{"version":3,"file":"lint.d.ts","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAiB,MAAM,SAAS,CAAC;AA6GnD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,CAQtD;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAkDxD"}
|