@cassiomc1/forgeloop 2.0.0-rc.5 → 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.
Files changed (87) hide show
  1. package/.cursor/rules/project-loop.mdc +1 -1
  2. package/.github/copilot-instructions.md +1 -1
  3. package/AGENTS.md +1 -1
  4. package/CLAUDE.md +1 -1
  5. package/CONTRIBUTING.md +3 -1
  6. package/DOCS_INDEX.md +2 -0
  7. package/ENG/accessibility-eng.md +6 -6
  8. package/ENG/clean-code-eng.md +2 -2
  9. package/ENG/design-code-eng.md +17 -15
  10. package/ENG/documentation-quality-eng.md +10 -2
  11. package/ENG/dotnet-aspnetcore-development-eng.md +8 -4
  12. package/ENG/flutter-development-eng.md +38 -59
  13. package/ENG/games-code-design-web-eng.md +2 -2
  14. package/ENG/nodejs-backend-development-eng.md +7 -4
  15. package/ENG/perf-code-eng.md +3 -3
  16. package/ENG/php-development-eng.md +2 -2
  17. package/ENG/premium-sites-studio-eng.md +9 -2
  18. package/ENG/python-development-eng.md +7 -1
  19. package/ENG/rust-development-eng.md +22 -32
  20. package/ENG/sec-code-eng.md +19 -3
  21. package/ENG/sql-development-eng.md +5 -4
  22. package/ENG/taste-frontend-eng.md +125 -4
  23. package/ENG/test-code-eng.md +2 -2
  24. package/GUIDE_ROUTER.md +18 -4
  25. package/PROTOCOL_INTEGRATION.md +21 -0
  26. package/README.md +15 -13
  27. package/THIRD_PARTY_NOTICES.md +60 -6
  28. package/docs/AGENT_PROTOCOL_SUMMARY.md +1 -1
  29. package/docs/AGENT_SKILL.md +16 -0
  30. package/docs/DOCUMENTATION_GUIDE.md +6 -0
  31. package/docs/FORGELOOP_AUDIT.md +1 -1
  32. package/docs/GETTING_STARTED.md +8 -1
  33. package/docs/GUIDE_MAINTENANCE.md +106 -0
  34. package/docs/PACKAGE_CONTENTS.md +22 -5
  35. package/docs/RELEASE_CHECKLIST.md +68 -35
  36. package/docs/REVENUE_CENTRIC_DESIGN.md +69 -0
  37. package/docs/SECURITY_AUDIT_SKILL.md +131 -0
  38. package/docs/SECURITY_REVIEW.md +6 -0
  39. package/docs/STABLE_2_ACCEPTANCE.md +127 -0
  40. package/docs/TROUBLESHOOTING.md +171 -0
  41. package/docs/documentation-manifest.json +244 -0
  42. package/package.json +12 -7
  43. package/scripts/generate-forgeloop-skill.mjs +8 -0
  44. package/scripts/verify-revenue-design-skill.mjs +37 -0
  45. package/scripts/verify-security-audit-skill.mjs +68 -0
  46. package/skills/forgeloop/SKILL.md +8 -0
  47. package/skills/forgeloop/references/revenue-centric-design/LICENSE +30 -0
  48. package/skills/forgeloop/references/revenue-centric-design/PIN.json +14 -0
  49. package/skills/forgeloop/references/revenue-centric-design/SKILL.md +64 -0
  50. package/skills/forgeloop/references/revenue-centric-design/references/playbook.md +36 -0
  51. package/skills/security-audit/AI-AND-LLM.md +83 -0
  52. package/skills/security-audit/ATTACK-CLASSES.md +130 -0
  53. package/skills/security-audit/CLIENT-SIDE.md +83 -0
  54. package/skills/security-audit/CLOUD-AND-DEPLOYMENT.md +86 -0
  55. package/skills/security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -0
  56. package/skills/security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -0
  57. package/skills/security-audit/HUNTING.md +251 -0
  58. package/skills/security-audit/LICENSE +21 -0
  59. package/skills/security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -0
  60. package/skills/security-audit/PIN.json +30 -0
  61. package/skills/security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -0
  62. package/skills/security-audit/RECONNAISSANCE.md +156 -0
  63. package/skills/security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -0
  64. package/skills/security-audit/SKILL.md +192 -0
  65. package/skills/security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -0
  66. package/skills/security-audit/VALIDATION-AND-REPORTING.md +186 -0
  67. package/skills/security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -0
  68. package/skills/security-audit/report-schema.json +461 -0
  69. package/skills/security-audit/validate-coverage-ledger.cjs +872 -0
  70. package/skills/security-audit/validate-coverage-ledger.test.cjs +740 -0
  71. package/skills/security-audit/validate-findings.cjs +773 -0
  72. package/skills/security-audit/validate-findings.test.cjs +652 -0
  73. package/src/core/completion-artifacts.js +4 -7
  74. package/src/core/diagnosis.js +3 -5
  75. package/src/core/diagnostic-record.js +4 -4
  76. package/src/core/error-codes.js +180 -2
  77. package/src/core/next-action-recovery-phases.js +3 -0
  78. package/src/core/next-action-review-correction.js +26 -0
  79. package/src/core/next-action-review-phase.js +25 -15
  80. package/src/core/parsers/dotnet-project.js +221 -0
  81. package/src/core/parsers/limits.js +9 -0
  82. package/src/core/parsers/pubspec.js +307 -0
  83. package/src/core/parsers/shared.js +4 -0
  84. package/src/core/project-detection.js +6 -527
  85. package/src/core/reconcile-closure.js +5 -0
  86. package/src/core/review-correction.js +51 -0
  87. package/src/storage/capabilities.js +1 -1
@@ -3,7 +3,7 @@ name: rust-development-eng
3
3
  language: en
4
4
  description: "Specialist guidance for architecture, implementation, testing, security, performance, and release of production Rust applications, services, libraries, and workers."
5
5
  version: "2026.09"
6
- last-reviewed: "2026-10-13"
6
+ last-reviewed: "2026-10-17"
7
7
  guide-id: rust
8
8
  requires-gates:
9
9
  - threat-boundary
@@ -113,37 +113,27 @@ does not change a project's declared MSRV, toolchain, or edition.
113
113
 
114
114
  ### Rust 1.99.0 release review
115
115
 
116
- The [Rust 1.99.0 release notes](https://releases.rs/docs/1.99.0/) report a
117
- stable release on 2026-10-01. Apply these changes only when the affected
118
- project's toolchain and compatibility policy permit them:
119
-
120
- - **Language and unsafe code:** C-variadic function definitions are stable;
121
- naked C-variadic functions remain behind the nightly
122
- `c_variadic_naked_functions` feature. The new
123
- `raw_borrows_via_references` lint is allow-by-default, so it does not replace
124
- an explicit lint policy. Review unsafe code that relies on `UnsafeCell`
125
- access or reference-to-raw-borrow behavior alongside the release's adjusted
126
- `invalid_reference_casting` lint; do not infer that these changes relax
127
- aliasing or safety invariants.
128
- - **Cargo and workspaces:** Cargo adds a `debug` profile that is currently
129
- identical to `dev` and prepares for a possible later profile transition.
130
- On edition 2024 or later, a workspace member can override an inherited
131
- dependency's `default-features`; on earlier editions,
132
- `default-features = false` remains ignored with a warning. Check the edition
133
- before relying on the override.
134
- - **Library APIs and targets:** the release stabilizes APIs including
135
- `Vec::into_parts`/`Vec::from_parts`, `Box::into_non_null`/`Box::from_non_null`,
136
- `String::from_utf8_lossy_owned`, `VecDeque::retain_back`, and
137
- `std::fs::set_times`. `riscv64-unknown-linux-musl` is promoted to Tier 2
138
- with host tools. Check each API's stabilization version and target support
139
- against the package MSRV and supported deployment matrix before adoption.
140
- - **Compatibility checks:** legacy integral modules such as `std::i32` are
141
- fully deprecated, `no_mangle_generic_items` is a hard error, and the safety
142
- invariants of `Pin::new_unchecked` have changed slightly. Rust 1.99 also
143
- disables Cargo incremental compilation by default in CI and expands the
144
- non-local macro semicolon warning to macros from dependencies. Review these
145
- changes when diagnosing new warnings, build-time shifts, or compatibility
146
- failures.
116
+ The [official Rust 1.99.0 announcement](https://blog.rust-lang.org/2026/10/01/Rust-1.99.0/)
117
+ and its linked standard-library documentation describe the stable release on
118
+ 2026-10-01. Review changes against the project's toolchain and compatibility
119
+ policy:
120
+
121
+ - **FFI:** C-ABI variadic definitions are stable. Distinguish those from naked
122
+ variadic functions with non-C ABIs, which require inline assembly. Preserve
123
+ ABI, argument-type, and caller-safety invariants.
124
+ - **Raw-pointer layout:** `Layout::for_value_raw`, `mem::size_of_val_raw`, and
125
+ `mem::align_of_val_raw` are stabilized; their availability does not remove
126
+ each API's unsafe preconditions.
127
+ - **Ownership:** the standard-library guidance discourages leaking a `Box`
128
+ and later reconstructing it for deallocation. Use deliberate ownership
129
+ transfer through `Box::into_raw` or `Box::into_non_null` when appropriate.
130
+ - **Library compatibility:** examples of stabilized APIs include
131
+ `Vec::into_parts`/`Vec::from_parts`, `Box::from_non_null`, and
132
+ `VecDeque::retain_back`. Check exact stabilization versions against MSRV.
133
+
134
+ Consult the official detailed release notes for Cargo, target, compiler, and
135
+ lint changes before changing profiles, features, flags, or supported targets.
136
+ Do not infer such changes from a third-party release summary.
147
137
 
148
138
  These release notes are a version-specific review aid, not a reason to raise
149
139
  MSRV or change edition, lint levels, profiles, or targets without an explicit
@@ -3,7 +3,7 @@ name: sec-code-eng
3
3
  language: en
4
4
  description: "Verifiable security guidance for web, mobile, desktop, APIs, and the software supply chain."
5
5
  version: "2026.09"
6
- last-reviewed: "2026-08-10"
6
+ last-reviewed: "2026-10-17"
7
7
  guide-id: security
8
8
  requires-gates:
9
9
  - threat-boundary
@@ -27,11 +27,27 @@ reference; secrets, authorization, cryptography, and OWASP rules live here,
27
27
  not in the other files.
28
28
 
29
29
  **Tooling policy**: identify the stack, stage, and applicable checks; prefer an
30
- already-available equivalent that produces compatible evidence. Ask for
31
- authorization before installing a tool or changing the environment. If no
30
+ already-available equivalent that produces compatible evidence. Installation or environment changes require authority; reuse scoped
31
+ authorization already given rather than asking again. If no
32
32
  safe equivalent exists, record the required check as blocked and never claim
33
33
  it passed. Do not install merely optional resources.
34
34
 
35
+ ## Optional source security audit workflow
36
+
37
+ For security questions and focused vulnerability investigation, the optional
38
+ Cloudflare [security-audit skill](https://github.com/cloudflare/security-audit-skill)
39
+ provides source-first guidance. ForgeLoop ships a pinned copy under
40
+ `skills/security-audit/` in its package and source checkout. See the
41
+ [setup and authority boundaries](https://github.com/cassiomc1/forgeloop/blob/b9a16e9f665116306e9fca3b905b1f0fe2abd633/docs/SECURITY_AUDIT_SKILL.md)
42
+ before enabling host discovery or requesting a full audit.
43
+
44
+ Use guidance mode for focused work. Reserve the complete six-phase audit for
45
+ an explicit audit or report request; it requires independent verification and
46
+ the upstream execution isolation controls. Keep `confirmed`,
47
+ `needs_validation`, and `rejected` distinct, and disclose missing capabilities.
48
+ The companion neither installs itself into target projects nor replaces this
49
+ guide's gates, negative tests, canonical evidence, or completion validation.
50
+
35
51
  ## General principles (valid for any platform)
36
52
 
37
53
  - **Secure by design**: think about security during the design phase, not as a "review" at the end. Perform threat modeling for sensitive features (login, payment, file upload).
@@ -3,7 +3,7 @@ name: sql-development-eng
3
3
  language: en
4
4
  description: "Specialist overlay guidance for SQL schemas, queries, migrations, and database-boundary changes."
5
5
  version: "2026.09"
6
- last-reviewed: "2026-10-13"
6
+ last-reviewed: "2026-11-14"
7
7
  guide-id: sql
8
8
  requires-gates:
9
9
  - threat-boundary
@@ -37,8 +37,9 @@ migration, reads credentials, or introspects a schema.
37
37
  The repository's database engine, version, migration policy, transaction model,
38
38
  compatibility window, and deployment process win over generic SQL advice. Use
39
39
  the matching engine's official reference first, then ISO/IEC 9075:2023 for
40
- portable semantics. The 2026-10-13 reference check covers PostgreSQL 18.6, MySQL 9.7 Innovation
41
- and 8.4 LTS, SQL Server 17 T-SQL, Oracle AI Database 26, and SQLite 3.54.0.
40
+ portable semantics. The 2026-11-14 reference check covers PostgreSQL 18.6, MySQL 9.7 LTS and
41
+ 8.4 LTS (Innovation releases now use calendar versions such as 26.7), SQL
42
+ Server 2025 (17.x) T-SQL, Oracle AI Database 26, and SQLite 3.54.0.
42
43
  These are reference points, not automatic upgrade targets.
43
44
 
44
45
  Never infer a dialect, isolation guarantee, identifier rule, timestamp
@@ -103,6 +104,6 @@ execution.
103
104
 
104
105
  - [SQLite SQL language](https://www.sqlite.org/lang.html)
105
106
  - [PostgreSQL documentation](https://www.postgresql.org/docs/)
106
- - [MySQL reference manuals](https://docs.oracle.com/cd/E17952_01/mysql-8.0-en/)
107
+ - [MySQL 9.7 reference manual](https://docs.oracle.com/cd/E17952_01/mysql-9.7-en/)
107
108
  - [Microsoft T-SQL reference](https://learn.microsoft.com/sql/t-sql/)
108
109
  - [Oracle Database SQL Language Reference](https://docs.oracle.com/en/database/oracle/oracle-database/)
@@ -3,7 +3,7 @@ name: taste-frontend-eng
3
3
  language: en
4
4
  description: "Contextual visual-taste review for premium frontend and brand-heavy work."
5
5
  version: "2026.09"
6
- last-reviewed: "2026-08-17"
6
+ last-reviewed: "2026-11-14"
7
7
  guide-id: taste
8
8
  ---
9
9
 
@@ -15,11 +15,40 @@ ForgeLoop router only when the work has that visual context. It is advisory: it
15
15
  does not create an approval gate, block an autonomous task, or require a
16
16
  specific framework, font, layout, animation library, or visual tool.
17
17
 
18
- The upstream inspiration is Taste Skill's design-read and anti-default
19
- approach. ForgeLoop keeps the useful review vocabulary while applying its own
18
+ The upstream inspiration is [Taste Skill](https://www.tasteskill.dev/)
19
+ ([source](https://github.com/Leonxlnx/taste-skill), MIT) and its design-read and
20
+ anti-default approach. ForgeLoop keeps the useful review vocabulary while applying its own
20
21
  protocol boundaries: user evidence, accessibility, performance, security, and
21
22
  the active product constraints have priority over aesthetic preference.
22
23
 
24
+ ## Upstream Baseline and Intentional Differences
25
+
26
+ Reviewed baseline: [Taste Skill v2.0.0](https://github.com/Leonxlnx/taste-skill/tree/v2.0.0/skills/taste-skill),
27
+ released 2026-10-13 and reviewed for this adaptation on 2026-10-16. See the
28
+ [versioned instructions](https://github.com/Leonxlnx/taste-skill/blob/v2.0.0/skills/taste-skill/SKILL.md)
29
+ and [changelog](https://github.com/Leonxlnx/taste-skill/blob/v2.0.0/CHANGELOG.md).
30
+ This identifies the upstream reference, not full feature parity or automatic
31
+ synchronization. The guide's frontmatter version follows ForgeLoop's guide
32
+ versioning separately.
33
+
34
+ As of 2026-11-14 the upstream repository is at
35
+ [v2.5.1](https://github.com/Leonxlnx/taste-skill/releases/tag/v2.5.1); that
36
+ release is not yet reviewed for this adaptation, so the guidance above still
37
+ reflects v2.0.0. When the optional upstream tools are used, use a copy whose
38
+ `design-taste-frontend` skill is 2.1.5 or later (see the
39
+ [upstream changelog](https://www.tasteskill.dev/changelog)): 2.1.5 escapes text
40
+ that `charts.js` and the split-heading fallback insert from user data, and
41
+ 2.1.4 stops one inspector run from deleting another run's browser profile.
42
+
43
+ ForgeLoop adapts the content inventory, subject-specific concept, and screenshot
44
+ correction practices. It deliberately keeps direction selection contextual
45
+ rather than requiring a scripted draw. It does not adopt universal bans on
46
+ colors, gradients, borders, fonts, or headline line counts, or minimum image
47
+ and animated-element counts. Existing brand constraints, language expansion,
48
+ content needs, reduced motion, accessibility, and performance determine those
49
+ choices. An aesthetic preference never becomes lifecycle or completion
50
+ authority.
51
+
23
52
  ## Design Read
24
53
 
25
54
  Before editing, describe the existing or proposed system in observable terms:
@@ -35,6 +64,39 @@ Before editing, describe the existing or proposed system in observable terms:
35
64
  Separate observed evidence from inference. If the implementation is not yet
36
65
  available, record the read as a hypothesis and keep it reversible.
37
66
 
67
+ ## Client Content Inventory
68
+
69
+ Collect a small, source-backed inventory before choosing a visual direction:
70
+
71
+ - the client's actual product, audience, vocabulary, location, materials, and
72
+ distinguishing constraints, where relevant and supported;
73
+ - available product views, photographs, illustrations, documents, and brand
74
+ assets, with their source and permitted use;
75
+ - the content each requested section must deliver and the evidence supporting
76
+ its claims;
77
+ - missing content, representative examples, and facts requiring confirmation.
78
+
79
+ Reuse the inventory from the premium website brief when it exists. Do not
80
+ invent a differentiator, price, metric, testimonial, customer, or asset to make
81
+ the direction work. Label representative content and keep unsupported proof
82
+ out of release claims. For each section, connect the visitor's question, the
83
+ proposed claim, and its supporting source before committing to a layout.
84
+
85
+ ## Visual Concept
86
+
87
+ Write one sentence connecting an evidenced client detail to a concrete visual
88
+ decision and the visitor's goal. For example, an existing product workflow can
89
+ organize the page's composition and sequence. Explain how that decision
90
+ extends beyond the hero into supporting sections and narrow layouts.
91
+
92
+ Check whether the sentence would fit a nearby competitor unchanged. If it
93
+ would, refine it using the inventory rather than inventing a distinction.
94
+ Keep an established brand or design system when appropriate. Add a distinctive
95
+ interaction only when it serves the authorized scope and has an accessible
96
+ fallback; a new interaction is not required merely to make the page unusual.
97
+ Record reversible choices in the existing design artifact or contract
98
+ assumptions, following the normal decision policy.
99
+
38
100
  ## Design Dials
39
101
 
40
102
  Use three lightweight dials to make an intentional decision rather than a
@@ -130,12 +192,71 @@ If visual evidence is unavailable, record `NOT_VERIFIED` or a bounded
130
192
  limitation. Never turn an imagined screenshot or an unrun browser check into
131
193
  an observed result.
132
194
 
195
+ ## Screenshot Review
196
+
197
+ Use an already available, authorized browser to capture and inspect the real
198
+ page. A useful starting set is 1440, 768, and 390 CSS pixels wide; adapt it to
199
+ the supported device matrix and include required reflow, zoom, and interaction
200
+ checks. These widths do not replace accessibility requirements.
201
+
202
+ 1. Record the tested URL or build, browser, viewport dimensions, relevant
203
+ state, and screenshot references in the task's evidence.
204
+ 2. Inspect each capture for hierarchy, content completeness, concept continuity,
205
+ typography, contrast, crops, overflow, and obscured or missing content.
206
+ Check interactive behavior separately; a screenshot alone cannot establish
207
+ keyboard access, form behavior, or runtime performance.
208
+ 3. Identify up to three actionable problems with their location, visible
209
+ evidence, and user impact. Prioritize required acceptance criteria over
210
+ stylistic preferences.
211
+ 4. Correct the scoped issues through the existing ForgeLoop diagnosis and
212
+ correction loop when verification fails. Re-run affected checks, capture
213
+ the changed states, and inspect them again.
214
+
215
+ Use at most three review rounds by default, within the task contract's limits.
216
+ Stop earlier when the applicable criteria are satisfied. The round limit does
217
+ not waive a failure: report unresolved issues and their verification status,
218
+ then follow the canonical next action or blocker. Do not fabricate aesthetic
219
+ scores or claim browser, inspector, or screenshot evidence that was not
220
+ actually obtained. This procedure adds no separate approval gate.
221
+
222
+ ## Optional Upstream Tools
223
+
224
+ The upstream v2 scripts, direction library, and reference collection are not
225
+ bundled with this guide or required by ForgeLoop runtime:
226
+
227
+ | Upstream tool | Optional purpose |
228
+ | --- | --- |
229
+ | `scripts/draw.mjs` | Propose directions and composition blueprints |
230
+ | `scripts/lint.mjs` | Review source against upstream style patterns |
231
+ | `scripts/inspect.mjs` | Measure a page in a browser and capture screenshots |
232
+ | `scripts/assets.mjs` | Find external media and record source and credit information |
233
+
234
+ Use a separately available, reviewed copy only when appropriate and authorized;
235
+ do not install, fetch, or execute it automatically. The reviewed inspector
236
+ requires Node 22+ and an installed Chrome, Edge, or Chromium; the other scripts
237
+ require Node 18+, and media discovery requires network access. Check the
238
+ selected copy's requirements and output paths before use. Upstream tools may
239
+ write project artifacts and user-level history outside ForgeLoop's evidence
240
+ store; those files do not become attested evidence merely by existing.
241
+
242
+ Prefer an available equivalent when it supports the same task checks; for
243
+ example, [Impeccable](https://impeccable.style/)'s `audit` and `critique`
244
+ commands cover a comparable interface review (see the Design guide). Treat
245
+ upstream style findings as contextual recommendations, not new ForgeLoop gates.
246
+ For external media, confirm the exact asset's license, attribution, and
247
+ relevance; search results alone do not establish reuse rights. Identify found
248
+ or generated imagery honestly rather than presenting it as the client's own.
249
+ Record the tool version and checks actually run, and mark unavailable required
250
+ evidence `NOT_VERIFIED` without claiming upstream tool coverage.
251
+
133
252
  ## Redesign Audit
134
253
 
135
254
  For an existing interface, scan first and classify each issue as hierarchy,
136
255
  typography, color/contrast, composition, content, interaction, responsive
137
256
  behavior, accessibility, performance, or evidence. Fix the highest-leverage
138
- issues in small coherent batches. Re-read the whole system after each batch so
257
+ issues in small coherent batches. An optional interface auditor such as
258
+ Impeccable's `audit`/`critique` can seed this scan when it is already
259
+ available; its findings are recommendations, not ForgeLoop evidence. Re-read the whole system after each batch so
139
260
  local polish does not create a new inconsistency elsewhere.
140
261
 
141
262
  The final decision remains protocol-owned: this guide can recommend a visual
@@ -3,7 +3,7 @@ name: test-code-eng
3
3
  language: en
4
4
  description: "Risk-based testing strategy and tools for modern languages and platforms."
5
5
  version: "2026.09"
6
- last-reviewed: "2026-08-10"
6
+ last-reviewed: "2026-10-17"
7
7
  guide-id: test
8
8
  completion-evidence:
9
9
  - tests
@@ -15,7 +15,7 @@ completion-evidence:
15
15
 
16
16
  **Related documents**: for general clean code principles (names, small functions, formatting), see [`clean-code-eng.md`](./clean-code-eng.md). For security, including SAST/DAST, see [`sec-code-eng.md`](./sec-code-eng.md). For accessibility, use the repository's specific guide together with [WCAG 2.2](https://www.w3.org/TR/WCAG22/). For HTML video and motion, see [HyperFrames](https://hyperframes.heygen.com). This file is the canonical reference for deciding the testing strategy by language and platform.
17
17
 
18
- **Tooling policy**: identify the stack, the stage, and the applicable checks; prefer an already available equivalent that produces compatible evidence. Ask for authorization before installing a tool or changing the environment. If no safe equivalent exists, record the required check as blocked and never claim that it passed. Do not install merely optional resources.
18
+ **Tooling policy**: identify the stack, the stage, and the applicable checks; prefer an already available equivalent that produces compatible evidence. Installation or environment changes require authority; reuse scoped authorization already given rather than asking again. If no safe equivalent exists, record the required check as blocked and never claim that it passed. Do not install merely optional resources.
19
19
 
20
20
  ## Start with risk, not a tool
21
21
 
package/GUIDE_ROUTER.md CHANGED
@@ -73,6 +73,10 @@ structural detection and route tests are implemented.
73
73
 
74
74
  ## Domain rules
75
75
 
76
+ For catalog upkeep, use the [engineering guide maintenance map](https://github.com/cassiomc1/forgeloop/blob/b9a16e9f665116306e9fca3b905b1f0fe2abd633/docs/GUIDE_MAINTENANCE.md).
77
+ It distinguishes guide discovery, implemented routing, contextual defaults,
78
+ and observed verification; it does not add runtime routing rules.
79
+
76
80
  ### `clean` — code and structure
77
81
 
78
82
  **Activate when:** creating or modifying code, fixing a bug, refactoring, changing architecture, reviewing quality, or producing development instructions.
@@ -117,6 +121,12 @@ rg -n '^## |authentication|authorization|upload|SSRF|CSP|OAuth|JWT|secrets|suppl
117
121
 
118
122
  **Expected evidence:** explicit trust boundaries, server-side validation, least privilege, no secrets in Git, and negative tests.
119
123
 
124
+ For requested source audits or focused vulnerability investigations, consult
125
+ the optional bundled Cloudflare `security-audit` companion described by the
126
+ security guide. Ordinary security routing does not start a full audit or
127
+ require the companion. Its reports remain advisory; canonical security gates
128
+ and verification remain unchanged.
129
+
120
130
  ### `performance` — measurable cost
121
131
 
122
132
  **Activate when:** the request involves latency, scale, a critical path, rendering, bundles, databases, networking, memory, battery, load, Web Vitals, FPS, or a budget.
@@ -188,12 +198,16 @@ require GSAP or a static-site approach, prescribe fonts/layouts, or override
188
198
  accessibility, performance, security, or product evidence.
189
199
 
190
200
  ```bash
191
- rg -n '^## (Design Read|Design Dials|Anti-Slop Checks|Typography Quality|Layout Composition|Motion Restraint|Responsive Composition|Design-System Selection|Visual Pre-Flight|Redesign Audit)' ENG/taste-frontend-eng.md
201
+ rg -n '^## (Upstream Baseline and Intentional Differences|Design Read|Client Content Inventory|Visual Concept|Design Dials|Anti-Slop Checks|Typography Quality|Layout Composition|Motion Restraint|Responsive Composition|Design-System Selection|Visual Pre-Flight|Screenshot Review|Optional Upstream Tools|Redesign Audit)' ENG/taste-frontend-eng.md
192
202
  ```
193
203
 
194
- **Expected evidence:** a contextual design read, intentional dials, bounded
195
- anti-slop review, and only the visual/accessibility/performance checks that are
196
- in scope. Mark unavailable visual evidence `NOT_VERIFIED`.
204
+ **Expected evidence:** a source-backed client inventory, contextual design read,
205
+ visual concept, intentional dials, bounded anti-slop review, and screenshot
206
+ review with up to three correction rounds within the task contract. Run only
207
+ the visual/accessibility/performance checks in scope and retain unresolved
208
+ failures. Upstream scripts remain optional and unbundled; see the guide's
209
+ versioned baseline and intentional differences. Mark unavailable visual
210
+ evidence `NOT_VERIFIED`.
197
211
 
198
212
  ### `games` — web game architecture and operation
199
213
 
@@ -8,6 +8,27 @@ an execution environment appears in a compatibility list.
8
8
 
9
9
  <!-- FORGELOOP_PROJECT_PROTOCOL=REQUIRED -->
10
10
 
11
+ ## Navigation
12
+
13
+ - [Universal applicability](#universal-applicability)
14
+ - [Integration levels](#integration-levels)
15
+ - [Discovery surfaces](#discovery-surfaces)
16
+ - [Adaptive execution profiles and context presentation](#adaptive-execution-profiles-and-context-presentation)
17
+ - [Capability negotiation](#capability-negotiation)
18
+ - [CLI resolution policy](#cli-resolution-policy)
19
+ - [Protocol-owned state and no-simulation policy](#protocol-owned-state-and-no-simulation-policy)
20
+ - [Trusted command provenance](#trusted-command-provenance)
21
+ - [Missing tool capability](#missing-tool-capability)
22
+ - [Optional capability extensions](#optional-capability-extensions)
23
+ - [Delegation scope](#delegation-scope)
24
+ - [Instruction precedence](#instruction-precedence)
25
+ - [External workflow interaction](#external-workflow-interaction)
26
+ - [Harness and session continuity](#harness-and-session-continuity)
27
+ - [Structural quality integration](#structural-quality-integration)
28
+ - [Executable Policy Protocol Integration](#executable-policy-protocol-integration)
29
+ - [Structured integration surfaces](#structured-integration-surfaces)
30
+ - [Durable actions and authority boundary](#durable-actions-and-authority-boundary)
31
+
11
32
  ## Universal applicability
12
33
 
13
34
  If the active execution environment discovers a ForgeLoop project adapter,
package/README.md CHANGED
@@ -74,11 +74,13 @@ Routing uses bounded structural evidence; SQL remains a schema/query/migration
74
74
  overlay. Extensions, tool files, lockfiles, runtime images, and prose alone do
75
75
  not establish project identity. Public project evidence remains v1.
76
76
 
77
+ See the [23-guide maintenance map](./docs/GUIDE_MAINTENANCE.md) for review scope and revalidation.
78
+
77
79
  ## Distribution and license
78
80
 
79
81
  GitHub hosts source and issues. The core npm package is publicly available;
80
- the MCP companion retains restricted distribution. RC5 targets `next`; `latest`
81
- remains at RC4. Stable SQLite acceptance is incomplete.
82
+ the MCP companion retains restricted distribution. Stable `2.0.0` is published
83
+ on npm `latest`, with verified identity and native user audits.
82
84
  ForgeLoop-owned source and documentation are licensed under the
83
85
  [PolyForm Noncommercial License 1.0.0](./LICENSE). Commercial use is not granted
84
86
  by this license. Third-party notices are documented in
@@ -497,22 +499,18 @@ see [CONTRIBUTING.md](./CONTRIBUTING.md#focused-verification-and-maintenance).
497
499
 
498
500
  ## ForgeLoopAudit workspace
499
501
 
500
- The read-only auditor lives in `ForgeLoopAudit/`. See
501
- [setup, usage and screenshots](./docs/FORGELOOP_AUDIT.md) for the demo,
502
- project inspection and audit views.
502
+ The read-only auditor lives in `ForgeLoopAudit/`; see its
503
+ [setup, demo and screenshots](./docs/FORGELOOP_AUDIT.md).
503
504
 
504
505
  ## Protocol compatibility
505
506
 
506
- The npm package version is independent of protocol version. The current
507
- serializable artifact contract is `schemaVersion: 1` and `protocolVersion: 1`.
507
+ The npm package version is independent of protocol version. Artifacts use
508
+ `schemaVersion: 1` and `protocolVersion: 1`.
508
509
 
509
- - Patch releases preserve the v1 schemas, enums, transitions, and existing
510
- command contracts while correcting implementation defects.
511
- - Minor releases preserve existing v1 artifacts and commands; they may add
512
- documentation, commands, guides, or an explicitly named schema.
510
+ - Patch releases preserve the v1 schemas and existing command contracts.
511
+ - Minor releases preserve existing v1 artifacts; additions remain compatible.
513
512
  - Major releases may change required fields, enums, transitions, or safety
514
- semantics and must document migration requirements with a protocol version
515
- change.
513
+ semantics, requiring a new protocol version and documented migration.
516
514
 
517
515
  Consumers must reject unknown artifact fields rather than silently treating
518
516
  unrecognized protocol data as valid. The compatibility marker is
@@ -525,6 +523,10 @@ it must not infer current ownership from `task.json` or `recovery.json` alone.
525
523
 
526
524
  ## Security and dependency boundary
527
525
 
526
+ Optional [security audits](./docs/SECURITY_AUDIT_SKILL.md) and
527
+ [product design](./docs/REVENUE_CENTRIC_DESIGN.md) ship with pinned attribution,
528
+ integrity checks and their respective licenses; guidance remains advisory.
529
+
528
530
  Runtime uses Node built-ins and the approved exact `@typesafe-ai/sdk` and
529
531
  `smol-toml` dependencies; it installs no agents, providers, plugins, services,
530
532
  or telemetry. Paths, symlinks, JSON,
@@ -97,13 +97,31 @@ dependencies, version, and distribution conditions before adoption.
97
97
  configure, or enable its CI/agent integrations. Verify current upstream
98
98
  license, CLI, telemetry, network behavior, and dependencies before use.
99
99
 
100
+ ### Cloudflare security audit skill — optional bundled companion
101
+
102
+ - Project: [cloudflare/security-audit-skill](https://github.com/cloudflare/security-audit-skill).
103
+ - Pinned source commit: `c1c8a8c1471069fb0e188eeaff69b8e8db6564a8`.
104
+ - License: MIT, copyright (c) 2025-2026 Cloudflare, Inc.; the complete upstream
105
+ notice is preserved at `skills/security-audit/LICENSE`.
106
+ - Use in this collection: the unchanged upstream `skills/security-audit/`
107
+ tree, including references, schema, validators and tests, is bundled for
108
+ optional agent guidance and explicitly requested source audits. The root
109
+ upstream license is copied alongside it. ForgeLoop-owned `PIN.json` records
110
+ the source and per-file SHA-256 digests.
111
+ - Boundary: instruction content and local report validators, not a runtime
112
+ dependency, automatic scanner, Security Review provider, evidence importer,
113
+ or completion gate. It is not installed into a host by `init` or `update`.
114
+ The upstream files retain MIT terms independently of ForgeLoop's license.
115
+
100
116
  ### Runtime and validator boundary
101
117
 
102
118
  The distributed CLI and repository validators use Node.js and Python standard
103
119
  libraries plus the JSON Schema documents shipped in this repository. The core
104
- CLI has one approved runtime package, `smol-toml`, for structural Cargo
105
- manifest parsing; it is not used as an agent, provider, plugin, remote trace
106
- service, or model. Every future runtime capability must review its own license,
120
+ CLI exact-pins `smol-toml` for structural Cargo manifest parsing and
121
+ `@typesafe-ai/sdk` for the semantic decision plane. Parsing is local; configured
122
+ semantic-required operations use the external TypeSafe service under the
123
+ canonical decision contract. Neither dependency gains lifecycle or evidence
124
+ authority. Every future runtime capability must review its own license,
107
125
  dependency tree, credentials, network behavior, and distribution terms
108
126
  separately.
109
127
 
@@ -207,14 +225,20 @@ The contextual frontend taste guide is informed by Taste Skill:
207
225
 
208
226
  - Taste Skill, Copyright (c) 2026 Leonxlnx, MIT License.
209
227
  - Source: <https://github.com/leonxlnx/taste-skill>
228
+ - Project site: <https://www.tasteskill.dev/>
229
+ - Reviewed baseline: [v2.0.0](https://github.com/Leonxlnx/taste-skill/tree/v2.0.0/skills/taste-skill),
230
+ released 2026-10-13; adaptation reviewed 2026-10-16.
210
231
 
211
232
  ForgeLoop includes a short, adapted guide under `ENG/taste-frontend-eng.md`.
212
- It does not vendor upstream runtime code, depend on its repository at runtime,
213
- or make its prescriptive examples universal.
233
+ It incorporates selected content-inventory, visual-concept, and screenshot-review
234
+ practices. It does not vendor upstream scripts or the direction library,
235
+ depend on its repository at runtime, or claim full upstream feature parity.
236
+ Upstream tooling is optional and separately supplied; its prescriptive style
237
+ rules and media or motion counts are not universal ForgeLoop requirements.
214
238
 
215
239
  ## Runtime dependencies with upstream notices
216
240
 
217
- ### smol-toml 1.8.0
241
+ ### smol-toml 1.9.0
218
242
 
219
243
  - Project/source: [squirrelchat/smol-toml](https://github.com/squirrelchat/smol-toml).
220
244
  - License declared by the upstream package: BSD-3-Clause.
@@ -224,6 +248,18 @@ or make its prescriptive examples universal.
224
248
  `package-lock.json`; the dependency has no role in routing authority beyond
225
249
  the parser result and is not exposed as a public ForgeLoop integration.
226
250
 
251
+ ### TypeSafe AI SDK 0.6.0
252
+
253
+ - Package: `@typesafe-ai/sdk`; source:
254
+ [typesafe-ai/typesafe-sdk-js](https://github.com/typesafe-ai/typesafe-sdk-js).
255
+ - License declared by the installed upstream package: MIT.
256
+ - Use in this collection: exact-pinned client for the bounded semantic
257
+ decision plane documented in `docs/SEMANTIC_DECISION_PLANE.md`.
258
+ - Boundary: credentials stay outside protocol artifacts. The SDK's responses
259
+ cannot execute commands, grant ownership, record evidence, or establish
260
+ completion. Network requirements remain explicit for semantic-required
261
+ operations; this is separate from optional security audit guidance.
262
+
227
263
  ### Microsoft tgrep
228
264
 
229
265
  - Project: [microsoft/tgrep](https://github.com/microsoft/tgrep).
@@ -247,3 +283,21 @@ or make its prescriptive examples universal.
247
283
  - Boundary: the ForgeLoop core package (`@cassiomc1/forgeloop`) has no
248
284
  dependency on the MCP SDK; the SDK ships only inside
249
285
  `@cassiomc1/forgeloop-mcp`. Review upstream terms before redistribution.
286
+
287
+ ## Revenue-centric design companion
288
+
289
+ - Source: [heliocosta-dev/revenue-centric-design](https://github.com/heliocosta-dev/revenue-centric-design/tree/1942760c2242f609bf63ce2c97204f5a1791bd68).
290
+ - Ideas, frameworks and the term Revenue-Centric Design: Richard
291
+ ([@richardrx](https://x.com/richardrx)); upstream curation is used with permission.
292
+ - Terms: [complete custom source-available license](./skills/forgeloop/references/revenue-centric-design/LICENSE),
293
+ retained in full. Attribution and preservation of those terms are required.
294
+ Gambling, betting, casino and real-money games-of-chance uses, including
295
+ loot boxes, are excluded by the author's permission. These terms apply to
296
+ this companion, separately from ForgeLoop's PolyForm license; they are not
297
+ an OSI-approved open-source license.
298
+ - Adaptation: a focused advisory skill and offline journey playbook under
299
+ `skills/forgeloop/references/revenue-centric-design/`, with a reviewed commit
300
+ and normalized-text integrity pin. Upstream themes are pinned links; media,
301
+ updater scripts and scraping dependencies are not bundled.
302
+ - Authority: the companion adds no runtime dependency, guide ID, automatic
303
+ gate or completion authority. See [setup and boundaries](./docs/REVENUE_CENTRIC_DESIGN.md).
@@ -7,7 +7,7 @@
7
7
  ForgeLoop is a portable protocol and support CLI for verifiable engineering workflows. It records and validates task state, contracts, routing, checks, evidence, continuity, and optional code attestations. It does not become an agent scheduler, delegation service, source-control authority, or secret manager.
8
8
 
9
9
  Protocol version: 1
10
- Package version: 2.0.0-rc.5
10
+ Package version: 2.1.0
11
11
 
12
12
  ## Canonical loop
13
13
 
@@ -74,8 +74,24 @@ authorization headers must never be persisted in ForgeLoop artifacts.
74
74
  External Agent Skills tooling is not a ForgeLoop dependency and is not used in
75
75
  CI. ForgeLoop adds no runtime Skill installation or synchronization command.
76
76
 
77
+ ## Optional product design guidance
78
+
79
+ The [revenue-centric design companion](./REVENUE_CENTRIC_DESIGN.md) lives under
80
+ `skills/forgeloop/references/revenue-centric-design/`. Its focused skill and
81
+ local journey playbook support relevant product work with source attribution,
82
+ custom license terms, informed choice and measurable hypotheses. It adds no
83
+ runtime dependency, guide ID or lifecycle authority. The generator links to
84
+ this maintained reference tree and does not overwrite or install it.
85
+
77
86
  ## Packaging
78
87
 
88
+ The optional [Cloudflare security audit companion](./SECURITY_AUDIT_SKILL.md)
89
+ ships separately at `skills/security-audit/`. The generated ForgeLoop Skill
90
+ points to it for requested security work without starting a full audit or
91
+ requiring installation. Its upstream files, license, and hash manifest remain
92
+ separate from the generated ForgeLoop Skill. Host discovery copies are opt-in
93
+ and are not synchronized by the generator or by `init`/`update`.
94
+
79
95
  The generated Skill, this document, and the bounded generator ship in the npm
80
96
  package as instruction/documentation content. They add no runtime dependency.
81
97
  Harness-specific installed copies and caches are not shipped.
@@ -40,6 +40,12 @@ Persistent transport truth -> src/persistent-transport/*, CLI search dispatcher,
40
40
 
41
41
  Operational documentation must explain canonical behavior, not redefine it.
42
42
 
43
+ For the 23 engineering guides, use the
44
+ [guide maintenance map](./GUIDE_MAINTENANCE.md). Check activation descriptions
45
+ against the detector/router and frontmatter requirements before changing a
46
+ guide. Keep contextual styling and optional tools separate from lifecycle
47
+ gates; do not update review dates on untouched material.
48
+
43
49
  Terminology must remain consistent across active documents: say “advisory
44
50
  context,” not “canonical memory”; “handoff acceptance,” not “ownership
45
51
  transfer”; and “operational receipt,” not “delegation.” Advisory output is
@@ -50,7 +50,7 @@ uploading a repository through the browser.
50
50
 
51
51
  These are existing captures of the ForgeShop demo, taken from the production
52
52
  renderer at 1440 × 900 in the dark theme, aligned to Audit `0.3.0-rc.3` and
53
- ForgeLoop `2.0.0-rc.4`. The demo deliberately includes invalid, stale, blocked and
53
+ ForgeLoop `2.0.0`. The demo deliberately includes invalid, stale, blocked and
54
54
  unverified scenarios. Its warnings and coverage values do not establish
55
55
  completion or production readiness for your project.
56
56
 
@@ -227,7 +227,7 @@ Discover the deterministic task state path using `task-show`:
227
227
  forgeloop task-show --task task-contact-form-001 --json
228
228
  ```
229
229
 
230
- Then write the task contract to `.forgeloop/task-state/<taskKey>/contract.json`:
230
+ Write the contract to a project-relative input file outside `.forgeloop/task-state/` (for example `contract-input.json`). Writing it directly into the task-state directory creates legacy operational state next to canonical SQLite and makes later commands fail with `E_STORAGE_MIGRATION_REQUIRED`:
231
231
 
232
232
  ```json
233
233
  {
@@ -271,6 +271,13 @@ Then write the task contract to `.forgeloop/task-state/<taskKey>/contract.json`:
271
271
  }
272
272
  ```
273
273
 
274
+ Then let ForgeLoop record it transactionally (discovery first, when `next` asks for it):
275
+
276
+ ```bash
277
+ forgeloop discover --task task-contact-form-001 --json
278
+ forgeloop contract-create --task task-contact-form-001 --contract-file contract-input.json --json
279
+ ```
280
+
274
281
  ---
275
282
 
276
283
  ### Step 2 — Route Guides Deterministically