@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.
- package/.cursor/rules/project-loop.mdc +1 -1
- package/.github/copilot-instructions.md +1 -1
- package/AGENTS.md +1 -1
- package/CLAUDE.md +1 -1
- package/CONTRIBUTING.md +3 -1
- package/DOCS_INDEX.md +2 -0
- package/ENG/accessibility-eng.md +6 -6
- package/ENG/clean-code-eng.md +2 -2
- package/ENG/design-code-eng.md +17 -15
- package/ENG/documentation-quality-eng.md +10 -2
- package/ENG/dotnet-aspnetcore-development-eng.md +8 -4
- package/ENG/flutter-development-eng.md +38 -59
- package/ENG/games-code-design-web-eng.md +2 -2
- package/ENG/nodejs-backend-development-eng.md +7 -4
- package/ENG/perf-code-eng.md +3 -3
- package/ENG/php-development-eng.md +2 -2
- package/ENG/premium-sites-studio-eng.md +9 -2
- package/ENG/python-development-eng.md +7 -1
- package/ENG/rust-development-eng.md +22 -32
- package/ENG/sec-code-eng.md +19 -3
- package/ENG/sql-development-eng.md +5 -4
- package/ENG/taste-frontend-eng.md +125 -4
- package/ENG/test-code-eng.md +2 -2
- package/GUIDE_ROUTER.md +18 -4
- package/PROTOCOL_INTEGRATION.md +21 -0
- package/README.md +15 -13
- package/THIRD_PARTY_NOTICES.md +60 -6
- package/docs/AGENT_PROTOCOL_SUMMARY.md +1 -1
- package/docs/AGENT_SKILL.md +16 -0
- package/docs/DOCUMENTATION_GUIDE.md +6 -0
- package/docs/FORGELOOP_AUDIT.md +1 -1
- package/docs/GETTING_STARTED.md +8 -1
- package/docs/GUIDE_MAINTENANCE.md +106 -0
- package/docs/PACKAGE_CONTENTS.md +22 -5
- package/docs/RELEASE_CHECKLIST.md +68 -35
- package/docs/REVENUE_CENTRIC_DESIGN.md +69 -0
- package/docs/SECURITY_AUDIT_SKILL.md +131 -0
- package/docs/SECURITY_REVIEW.md +6 -0
- package/docs/STABLE_2_ACCEPTANCE.md +127 -0
- package/docs/TROUBLESHOOTING.md +171 -0
- package/docs/documentation-manifest.json +244 -0
- package/package.json +12 -7
- package/scripts/generate-forgeloop-skill.mjs +8 -0
- package/scripts/verify-revenue-design-skill.mjs +37 -0
- package/scripts/verify-security-audit-skill.mjs +68 -0
- package/skills/forgeloop/SKILL.md +8 -0
- package/skills/forgeloop/references/revenue-centric-design/LICENSE +30 -0
- package/skills/forgeloop/references/revenue-centric-design/PIN.json +14 -0
- package/skills/forgeloop/references/revenue-centric-design/SKILL.md +64 -0
- package/skills/forgeloop/references/revenue-centric-design/references/playbook.md +36 -0
- package/skills/security-audit/AI-AND-LLM.md +83 -0
- package/skills/security-audit/ATTACK-CLASSES.md +130 -0
- package/skills/security-audit/CLIENT-SIDE.md +83 -0
- package/skills/security-audit/CLOUD-AND-DEPLOYMENT.md +86 -0
- package/skills/security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -0
- package/skills/security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -0
- package/skills/security-audit/HUNTING.md +251 -0
- package/skills/security-audit/LICENSE +21 -0
- package/skills/security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -0
- package/skills/security-audit/PIN.json +30 -0
- package/skills/security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -0
- package/skills/security-audit/RECONNAISSANCE.md +156 -0
- package/skills/security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -0
- package/skills/security-audit/SKILL.md +192 -0
- package/skills/security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -0
- package/skills/security-audit/VALIDATION-AND-REPORTING.md +186 -0
- package/skills/security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -0
- package/skills/security-audit/report-schema.json +461 -0
- package/skills/security-audit/validate-coverage-ledger.cjs +872 -0
- package/skills/security-audit/validate-coverage-ledger.test.cjs +740 -0
- package/skills/security-audit/validate-findings.cjs +773 -0
- package/skills/security-audit/validate-findings.test.cjs +652 -0
- package/src/core/completion-artifacts.js +4 -7
- package/src/core/diagnosis.js +3 -5
- package/src/core/diagnostic-record.js +4 -4
- package/src/core/error-codes.js +180 -2
- package/src/core/next-action-recovery-phases.js +3 -0
- package/src/core/next-action-review-correction.js +26 -0
- package/src/core/next-action-review-phase.js +25 -15
- package/src/core/parsers/dotnet-project.js +221 -0
- package/src/core/parsers/limits.js +9 -0
- package/src/core/parsers/pubspec.js +307 -0
- package/src/core/parsers/shared.js +4 -0
- package/src/core/project-detection.js +6 -527
- package/src/core/reconcile-closure.js +5 -0
- package/src/core/review-correction.js +51 -0
- package/src/storage/capabilities.js +1 -1
|
@@ -7,7 +7,7 @@ alwaysApply: true
|
|
|
7
7
|
This project is ForgeLoop-enabled. If your execution environment loaded this
|
|
8
8
|
file, ForgeLoop applies regardless of model, provider, IDE, agent, or runtime.
|
|
9
9
|
Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spirit".
|
|
10
|
-
1. Read [`LOOP_ENGINEERING.md`](../../LOOP_ENGINEERING.md) and [`PROTOCOL_INTEGRATION.md`](../../PROTOCOL_INTEGRATION.md).
|
|
10
|
+
1. Read [`LOOP_ENGINEERING.md`](../../LOOP_ENGINEERING.md) from its Navigation section, loading each section before the phase it governs, and [`PROTOCOL_INTEGRATION.md`](../../PROTOCOL_INTEGRATION.md).
|
|
11
11
|
2. Confirm [`PROJECT_PROFILE.md`](../../PROJECT_PROFILE.md) from real sources; initialize if in `template` mode.
|
|
12
12
|
3. Use [`GUIDE_ROUTER.md`](../../GUIDE_ROUTER.md) to activate relevant guides and report IDs.
|
|
13
13
|
3. For repository-wide textual discovery, prefer `forgeloop search` and treat its results as discovery only; do not use them as verification evidence or scope authority.
|
|
@@ -7,7 +7,7 @@ Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spiri
|
|
|
7
7
|
|
|
8
8
|
Use these instructions across the repository while preserving local rules.
|
|
9
9
|
|
|
10
|
-
- Read [`LOOP_ENGINEERING.md`](../LOOP_ENGINEERING.md) and [`PROTOCOL_INTEGRATION.md`](../PROTOCOL_INTEGRATION.md).
|
|
10
|
+
- Read [`LOOP_ENGINEERING.md`](../LOOP_ENGINEERING.md) from its Navigation section, loading each section before the phase it governs, and [`PROTOCOL_INTEGRATION.md`](../PROTOCOL_INTEGRATION.md).
|
|
11
11
|
- If an official ForgeLoop structured integration is available in your host, prefer it for protocol operations; otherwise use the project-local ForgeLoop CLI. Never simulate ForgeLoop-managed lifecycle, claim, recovery, ledger, or completion state directly.
|
|
12
12
|
- Confirm [`PROJECT_PROFILE.md`](../PROJECT_PROFILE.md) from evidence; initialize if in `template` mode.
|
|
13
13
|
- Select context with [`GUIDE_ROUTER.md`](../GUIDE_ROUTER.md) and report activated guide IDs.
|
package/AGENTS.md
CHANGED
|
@@ -6,7 +6,7 @@ file, ForgeLoop applies regardless of model, provider, IDE, agent, or runtime.
|
|
|
6
6
|
Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spirit".
|
|
7
7
|
|
|
8
8
|
1. Follow platform rules, the user's latest request, and local instructions first.
|
|
9
|
-
1. Read [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) and [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md).
|
|
9
|
+
1. Read [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) from its Navigation section, loading each section before the phase it governs, and [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md).
|
|
10
10
|
1. If an official ForgeLoop structured integration is available in your host, prefer it for protocol operations; otherwise use the project-local ForgeLoop CLI. Never simulate ForgeLoop-managed lifecycle, claim, recovery, ledger, or completion state directly.
|
|
11
11
|
1. Inspect [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md). Confirm facts from sources; initialize if in `template` mode.
|
|
12
12
|
1. Use [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) to select relevant guides and report activated guide IDs.
|
package/CLAUDE.md
CHANGED
|
@@ -8,7 +8,7 @@ Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spiri
|
|
|
8
8
|
When working in this repository:
|
|
9
9
|
|
|
10
10
|
1. Follow higher-level instructions, the user's latest request, and local rules first.
|
|
11
|
-
1. Read [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) and [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md).
|
|
11
|
+
1. Read [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) from its Navigation section, loading each section before the phase it governs, and [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md).
|
|
12
12
|
1. If an official ForgeLoop structured integration is available in your host, prefer it for protocol operations; otherwise use the project-local ForgeLoop CLI. Never simulate ForgeLoop-managed lifecycle, claim, recovery, ledger, or completion state directly.
|
|
13
13
|
1. Verify [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) against real sources; initialize if in `template` mode.
|
|
14
14
|
1. Consult [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md), select relevant guides, and announce their IDs.
|
package/CONTRIBUTING.md
CHANGED
|
@@ -86,7 +86,9 @@ forwarded to Node. Unsupported options and unmatched selectors fail explicitly.
|
|
|
86
86
|
Run `npm run complexity:check` with lint. Reductions are welcome; increases to
|
|
87
87
|
the committed hotspot budget require an explicit explanation and review.
|
|
88
88
|
TypeScript and YAML are development-only dependencies for packed-consumer and
|
|
89
|
-
semantic workflow verification
|
|
89
|
+
semantic workflow verification. The core runtime exact-pins `@typesafe-ai/sdk`
|
|
90
|
+
for the mandatory semantic decision plane and `smol-toml` for structural Cargo
|
|
91
|
+
parsing; `scripts/check-dependency-policy.mjs` owns the allowlist.
|
|
90
92
|
|
|
91
93
|
Filesystem transaction-payload maintenance is retired with the SQLite
|
|
92
94
|
migration. Preserve legacy evidence for explicit migration and diagnosis. See
|
package/DOCS_INDEX.md
CHANGED
|
@@ -19,6 +19,7 @@ integration and guide context. Use this map before editing documentation.
|
|
|
19
19
|
| Cross-harness continuity | [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) | Operational resume guidance, immutable handoffs, and multi-tool resumption |
|
|
20
20
|
| Agent bootstrap summary | [`docs/AGENT_PROTOCOL_SUMMARY.md`](./docs/AGENT_PROTOCOL_SUMMARY.md) | Generated concise navigation aid for protocol invariants and commands |
|
|
21
21
|
| Agent Skill integration | [`docs/AGENT_SKILL.md`](./docs/AGENT_SKILL.md) | Generated portable, non-authoritative agent guidance and freshness contract |
|
|
22
|
+
| Engineering guide maintenance | [`docs/GUIDE_MAINTENANCE.md`](./docs/GUIDE_MAINTENANCE.md) | Full catalog review scope, policy boundaries, source map, and revalidation procedure |
|
|
22
23
|
| CLI command reference | [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) | Full syntax, options, and JSON examples for all commands |
|
|
23
24
|
| Repository Index and Search | [`docs/REPOSITORY_INDEX.md`](./docs/REPOSITORY_INDEX.md) | Mandatory managed engine, indexed search contract, lifecycle, resource, security, and benchmark behavior |
|
|
24
25
|
| Persistent CLI search transport | [`docs/PERSISTENT_SEARCH_TRANSPORT.md`](./docs/PERSISTENT_SEARCH_TRANSPORT.md) | CLI-only local IPC, host lifecycle, ownership, recovery, bounds, privacy, and direct API/MCP boundary |
|
|
@@ -41,6 +42,7 @@ integration and guide context. Use this map before editing documentation.
|
|
|
41
42
|
| Provider extension architecture | [`docs/PROVIDER_ARCHITECTURE.md`](./docs/PROVIDER_ARCHITECTURE.md) | Provider-neutral architecture, invocation lifecycle, strict snapshots, cancellation, trust, and authority boundaries |
|
|
42
43
|
| Provider extension reference | [`docs/PROVIDERS.md`](./docs/PROVIDERS.md) | Capability discovery, provider kinds, common contract, limits, errors, and maintainer checklist |
|
|
43
44
|
| Security Review provider | [`docs/SECURITY_REVIEW.md`](./docs/SECURITY_REVIEW.md) | Bounded host-injected observation API, strict findings, timeout/cancellation, and non-authority boundary |
|
|
45
|
+
| Cloudflare security audit companion | [`docs/SECURITY_AUDIT_SKILL.md`](./docs/SECURITY_AUDIT_SKILL.md) | Pinned optional source-audit workflow, host setup, report validation, and ForgeLoop authority boundary |
|
|
44
46
|
| Ripwire advisory adapter | [`docs/RIPWIRE_ADAPTER.md`](./docs/RIPWIRE_ADAPTER.md) | Ripwire-specific registration, process contract, JSON mapping, limits, and verification |
|
|
45
47
|
| OpenSrc advisory adapter | [`docs/OPENSRC_ADAPTER.md`](./docs/OPENSRC_ADAPTER.md) | OpenSrc-specific registration, version qualification, cache containment, deterministic search, limits, and verification |
|
|
46
48
|
| Agent Browser verification adapter | [`docs/AGENT_BROWSER_ADAPTER.md`](./docs/AGENT_BROWSER_ADAPTER.md) | Optional host-owned browser executable, bounded observation mapping, isolation, exact origins, screenshots, and trust boundary |
|
package/ENG/accessibility-eng.md
CHANGED
|
@@ -3,7 +3,7 @@ name: accessibility-eng
|
|
|
3
3
|
language: en
|
|
4
4
|
description: "Practical WCAG 2.2-oriented accessibility protocol for web, mobile, and desktop."
|
|
5
5
|
version: "2026.09"
|
|
6
|
-
last-reviewed: "2026-
|
|
6
|
+
last-reviewed: "2026-10-17"
|
|
7
7
|
guide-id: accessibility
|
|
8
8
|
completion-evidence:
|
|
9
9
|
- keyboard-navigation
|
|
@@ -15,7 +15,7 @@ completion-evidence:
|
|
|
15
15
|
|
|
16
16
|
> Accessibility instructions adapted from the [A11Y.md](https://github.com/fecarrico/A11Y.md) project (Felipe A. Carriço, MIT license) — a validation protocol and persistent context system for building accessible software from the very first line of code, informed by **WCAG 2.2** and **ISO 9241-171**. It can support evidence for applicable **ADA** or **EAA** obligations, but does not itself determine legal compliance.
|
|
17
17
|
> **Related documents**: for visual/UX direction (palettes, typography, motion), see [`design-code-eng.md`](./design-code-eng.md). For automated testing tools (axe-core, Lighthouse, visual regression), see [`test-code-eng.md`](./test-code-eng.md). For code quality/structure, see [`clean-code-eng.md`](./clean-code-eng.md). For HTML-based video and motion, also see [HyperFrames](https://hyperframes.heygen.com). This file is the canonical reference for **accessibility rules** (WCAG, ARIA, keyboard, focus, screen readers) — it does not repeat the content of the others.
|
|
18
|
-
> **Tooling policy**: identify the stack, the stage, and the applicable checks; prefer an already available equivalent that produces compatible evidence.
|
|
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
|
## 0. Principle Zero: accessibility as a pre-condition
|
|
21
21
|
|
|
@@ -25,7 +25,7 @@ completion-evidence:
|
|
|
25
25
|
|
|
26
26
|
## 0.1. Compliance profiles
|
|
27
27
|
|
|
28
|
-
This document's default implementation target is **Standard (AA)**.
|
|
28
|
+
This document's default implementation target is **Standard (AA)**. Preserve a stronger existing requirement. If no profile is specified, record AA as a reversible assumption and continue; profile selection alone is not a user-approval gate. Ask only when a genuine blocking obligation cannot be established from project evidence, following Loop Engineering's decision classification. This guide supports WCAG-oriented implementation; it does not certify a product or establish automatic legal compliance. Certification and legal obligations depend on an assessment with defined scope, evidence, and the applicable jurisdiction.
|
|
29
29
|
|
|
30
30
|
| Profile | Target | Contrast (text / UI) | Min font† | Min target | Use case |
|
|
31
31
|
| :--- | :--- | :--- | :--- | :--- | :--- |
|
|
@@ -67,14 +67,14 @@ To ensure technical integrity, any AI interacting with the project **MUST**:
|
|
|
67
67
|
|
|
68
68
|
### Perceivable
|
|
69
69
|
|
|
70
|
-
- **Contrast (SC 1.4.3, 1.4.11):** text
|
|
70
|
+
- **Contrast (SC 1.4.3, 1.4.6, 1.4.11):** at AA, normal text needs at least 4.5:1 and large-scale text at least 3:1; at AAA, those thresholds are 7:1 and 4.5:1. Use WCAG's large-scale definition and applicable exceptions, not an arbitrary heading label. Required non-text component/state and graphic contrast is 3:1 where SC 1.4.11 applies. Do not round a failing ratio up. See the [W3C contrast explanation](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html); prioritize luminance difference beyond hue.
|
|
71
71
|
- **Alt text (SC 1.1.1):** informative images **MUST** have a functional description in `alt`; decorative images use `alt=""` or `aria-hidden="true"`.
|
|
72
72
|
- **Channels beyond color (SC 1.4.1):** **MUST NOT** convey state, action, response, or information with color alone. Choose the additional channel appropriate to the meaning — visible text, icon, pattern, or programmatic semantics — without imposing the same visual redundancy in every case.
|
|
73
73
|
- **Visual patterns:** when differentiation in charts or dashboards depends on color, patterns, labels, textures, or distinct line styles **MUST** enable users to distinguish series without color.
|
|
74
74
|
|
|
75
75
|
### Operable
|
|
76
76
|
|
|
77
|
-
- **Keyboard (SC 2.1.1):** all functionality **MUST** be operable without a mouse. Where the function depends on the path of movement rather than only its endpoints, document why the WCAG exception applies and provide a practical alternative when possible.
|
|
77
|
+
- **Keyboard (SC 2.1.1):** all functionality **MUST** be operable without a mouse. Prefer native controls and their built-in keyboard activation; do not add duplicate `onKeyDown` activation to a native button. Custom widgets need the complete applicable keyboard pattern. Where the function depends on the path of movement rather than only its endpoints, document why the WCAG exception applies and provide a practical alternative when possible.
|
|
78
78
|
- **Focus (SC 2.4.7, 2.4.11):** focus **MUST** be visible, never entirely obscured by author content (e.g., sticky headers/footers), persistent, and never suppressed via CSS (`outline: none` without fallback is forbidden).
|
|
79
79
|
- **SPA routing:** after client-side routing changes, focus **MUST** be managed and properly reset (e.g., sending focus to the top or an `h1`). Avoid lost focus on the screen.
|
|
80
80
|
- **Focus order and lifecycle (SC 2.4.3):** the sequential keyboard path **MUST** preserve meaning and operability. Prefer alignment between DOM order, reading order, and visual order when divergence would create confusing or illogical navigation. Avoid positive `tabindex` as a ForgeLoop accessibility best practice; repair the document structure whenever practical. When content is inserted, removed, expanded, collapsed, replaced, or routed, define the next logical focus destination and do not leave focus on a removed or unavailable node.
|
|
@@ -118,7 +118,7 @@ These directives combine WCAG requirements where identified and this guide's erg
|
|
|
118
118
|
When identifying an unmapped or highly complex component (e.g., charts, dynamic grids):
|
|
119
119
|
|
|
120
120
|
1. **Identify:** look for a similar pattern in the [WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/).
|
|
121
|
-
2. **Validate:**
|
|
121
|
+
2. **Validate:** test the pattern in the supported screen-reader/browser combinations when available. If human validation is required and unavailable, record the exact unverified combination and owner action; continue independent work. An AI **MUST NOT** claim an unperformed test or fabricate its results.
|
|
122
122
|
3. **Document:** document the expected behavior (keyboard and announcements).
|
|
123
123
|
4. **Scale:** record the resolved pattern in `A11Y-DECISIONS.md` so future components reuse it instead of re-deriving it.
|
|
124
124
|
|
package/ENG/clean-code-eng.md
CHANGED
|
@@ -3,7 +3,7 @@ name: clean-code-eng
|
|
|
3
3
|
language: en
|
|
4
4
|
description: "Practices for readable, observable, secure code operated by AI agents."
|
|
5
5
|
version: "2026.09"
|
|
6
|
-
last-reviewed: "2026-
|
|
6
|
+
last-reviewed: "2026-10-17"
|
|
7
7
|
guide-id: clean
|
|
8
8
|
---
|
|
9
9
|
|
|
@@ -13,7 +13,7 @@ guide-id: clean
|
|
|
13
13
|
>
|
|
14
14
|
> **Related documents**: for language-specific testing frameworks and tools, see [`test-code-eng.md`](./test-code-eng.md). For security, see [`sec-code-eng.md`](./sec-code-eng.md), the canonical reference for secrets, authorization, cryptography, and sensitive-data redaction. For visual/UX guidelines, see [`design-code-eng.md`](./design-code-eng.md). For HTML-based video and motion, see [HyperFrames](https://hyperframes.heygen.com). This guide focuses on code quality, structure, and operation.
|
|
15
15
|
>
|
|
16
|
-
> **Tooling policy**: identify the stack, the stage, and the applicable checks; prefer an already available equivalent that produces compatible evidence.
|
|
16
|
+
> **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.
|
|
17
17
|
|
|
18
18
|
## Context
|
|
19
19
|
|
package/ENG/design-code-eng.md
CHANGED
|
@@ -3,7 +3,7 @@ name: design-code-eng
|
|
|
3
3
|
language: en
|
|
4
4
|
description: "Visual direction, UX, motion, and perceived performance for premium digital experiences."
|
|
5
5
|
version: "2026.09"
|
|
6
|
-
last-reviewed: "2026-
|
|
6
|
+
last-reviewed: "2026-11-14"
|
|
7
7
|
guide-id: design
|
|
8
8
|
requires-gates:
|
|
9
9
|
- design
|
|
@@ -13,25 +13,25 @@ completion-evidence:
|
|
|
13
13
|
|
|
14
14
|
# Web Design Premium v2 — Practical Guidelines
|
|
15
15
|
|
|
16
|
-
> This guide provides
|
|
16
|
+
> This guide provides starting points for a coherent interface. Preserve the product's existing tokens, components, platform conventions, and brand before selecting a new palette or font. Numeric values, example layouts, aesthetic bans, and snippets below are contextual defaults, not universal compliance rules or approval gates. Record meaningful departures with a short rationale and validate hierarchy, accessibility, and performance.
|
|
17
17
|
> **Related documents**: for the complete studio-level website production process, see [`premium-sites-studio-eng.md`](./premium-sites-studio-eng.md). For the quality/structure of the code that implements this design, see [`clean-code-eng.md`](./clean-code-eng.md). For accessibility/visual/E2E testing, see [`test-code-eng.md`](./test-code-eng.md). For form security, authentication, and client-side storage, see [`sec-code-eng.md`](./sec-code-eng.md). To translate visual direction into HTML video, see [HyperFrames](https://hyperframes.heygen.com). This file focuses exclusively on UI/UX/visuals — it does not repeat code, testing, or security rules.
|
|
18
18
|
>
|
|
19
|
-
> **Tooling policy**: identify the stack, the stage, and the applicable checks; prefer an already available equivalent that produces compatible evidence.
|
|
19
|
+
> **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.
|
|
20
20
|
|
|
21
21
|
## How to use this guide (strong default process)
|
|
22
22
|
|
|
23
23
|
Adopt this order as the default when creating a page from scratch; document an exception when the product, platform, or user requires a different sequence:
|
|
24
24
|
|
|
25
|
-
1. **
|
|
26
|
-
2. **
|
|
27
|
-
3. **Define the
|
|
28
|
-
4. **Apply
|
|
29
|
-
5. **
|
|
30
|
-
6. **Add motion** only
|
|
25
|
+
1. **Confirm semantic color roles** from the existing design system; use a sample palette when no system exists.
|
|
26
|
+
2. **Confirm typography roles and language coverage**; use a sample combination when appropriate.
|
|
27
|
+
3. **Define the section list from the content and user journey**; use the anatomy as a reference.
|
|
28
|
+
4. **Apply a coherent grid and spacing scale** with responsive content checks.
|
|
29
|
+
5. **Reuse components and their interaction states**; adapt sample specifications to the product.
|
|
30
|
+
6. **Add purposeful motion** only when it helps the experience, with reduced-motion and static fallbacks.
|
|
31
31
|
7. **Run the Anti-Slop Checklist** before considering it ready.
|
|
32
|
-
8. **Audit and polish the
|
|
32
|
+
8. **Audit and polish the affected experience** with the available project tools and direct browser/device inspection. When [Impeccable](https://impeccable.style/) is already available, its `audit` and `critique` commands can surface quality issues and `polish`/`harden` can address them in the changed scope; record the Impeccable version and the commands actually run. It is an optional aid: its availability or findings are not a completion gate, and it must not override the project's design system. Preserve the design system and recheck the changed states.
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
Keep color and type decisions intentional. A familiar font, framework default, or repeated component is not a defect by itself; assess its fit, readability, hierarchy, and consistency in the actual interface.
|
|
35
35
|
|
|
36
36
|
> **This guide covers 3 contexts.** For web sites/products (desktop and mobile), follow the flow above normally. For **native mobile apps** (iOS/Android), go directly to the "Premium Mobile Apps" section. For **native desktop apps** (Windows/macOS), go to "Premium Desktop Apps". In the latter two cases, this guide's palettes and typography still serve as tone references, but platform guidelines (HIG, Material Design, Fluent) take priority over the generic values defined here.
|
|
37
37
|
|
|
@@ -227,7 +227,7 @@ When the output is a video, trailer, product demo, or motion graphic rendered fr
|
|
|
227
227
|
- Prefer deterministic, frame-controllable animation with a paused/seekable timeline so preview, tests, and rendering reproduce the same result.
|
|
228
228
|
- Keep text large enough for the output format, maintain AA contrast and safe areas, and do not make meaning depend on audio or motion.
|
|
229
229
|
- Respect `prefers-reduced-motion` in interactive previews and provide a static or reduced-motion alternative when appropriate.
|
|
230
|
-
- Start with the [official quickstart](https://hyperframes.heygen.com/quickstart)
|
|
230
|
+
- Start with the [official quickstart](https://hyperframes.heygen.com/quickstart). Use the project's pinned, already-installed CLI for `preview`, `lint`, `check`, and `render`, verifying the installed command help. Do not use an install-capable launcher merely to obtain a missing verifier; installation authority remains separate.
|
|
231
231
|
|
|
232
232
|
Motion rules:
|
|
233
233
|
|
|
@@ -324,6 +324,7 @@ appearance but cannot prove the state behavior or accessibility.
|
|
|
324
324
|
|
|
325
325
|
**UI libraries and data visualization**
|
|
326
326
|
|
|
327
|
+
- Before adding JavaScript or a dependency for a UI behavior the platform may already provide (dialogs, popovers, tooltips via anchor positioning, view/entry-exit transitions, container queries, `field-sizing`, `:user-invalid` validation, scroll-driven effects), consult [Modern Web Guidance](https://developer.chrome.com/docs/modern-web-guidance) for the current native pattern and its fallback. Confirm each feature's Baseline status against the project's supported browser matrix, keep a lightweight fallback or progressive enhancement where support is incomplete, and preserve the design system and accessibility semantics. It is optional reference material: do not auto-install its CLI or skill, and treat its guidance as advice, not ForgeLoop evidence.
|
|
327
328
|
- For accessible, composable, and customizable web components, consult [shadcn/ui](https://ui.shadcn.com/); adapt tokens, states, and composition to the project's visual system instead of copying defaults without intent.
|
|
328
329
|
- For charts and data visualization, consult [TanStack Charts](https://github.com/TanStack/charts); preserve responsiveness, contrast, keyboard readability, and never rely on color alone to communicate series or states.
|
|
329
330
|
- For subtle interaction sounds, consult [Cuelume](https://cuelume-site.pages.dev/); provide volume/mute controls and never rely on audio to communicate essential information.
|
|
@@ -594,7 +595,7 @@ For React-specific supplemental diagnostics after implementation, including desi
|
|
|
594
595
|
- [ ] Where the platform exposes contrast/transparency preferences, including `prefers-contrast` or `forced-colors` when applicable, the opaque/less-transparent variant works; without a reliable media query, there is an equivalent in-product control.
|
|
595
596
|
- [ ] No item from the "Blacklist" is present.
|
|
596
597
|
- [ ] Tested at 320 CSS px reflow and desktop (1440px).
|
|
597
|
-
- [ ]
|
|
598
|
+
- [ ] Reviewed the affected interface and states with available tools and browser/device evidence; optional Impeccable findings (with the version and commands run) were addressed when that tool was used.
|
|
598
599
|
|
|
599
600
|
---
|
|
600
601
|
|
|
@@ -696,7 +697,7 @@ For React-specific supplemental diagnostics after implementation, including desi
|
|
|
696
697
|
|
|
697
698
|
## Sources and References (Base Skills)
|
|
698
699
|
|
|
699
|
-
-
|
|
700
|
+
- Taste Skill (art direction and anti-slop review; MIT; adapted and version-pinned in the [Taste frontend guide](./taste-frontend-eng.md)): https://www.tasteskill.dev/ | https://github.com/Leonxlnx/taste-skill
|
|
700
701
|
- Emil Kowalski (Design Engineering / Motion): https://github.com/emilkowalski/skills
|
|
701
702
|
- GSAP: https://github.com/greensock/gsap-skills
|
|
702
703
|
- ScrollWorld: https://github.com/oso95/scroll-world
|
|
@@ -706,6 +707,7 @@ For React-specific supplemental diagnostics after implementation, including desi
|
|
|
706
707
|
- Apple Human Interface Guidelines (iOS/macOS): https://developer.apple.com/design/human-interface-guidelines/
|
|
707
708
|
- Material Design 3 (Android): https://m3.material.io/
|
|
708
709
|
- Microsoft Fluent Design / WinUI 3 (Windows): https://learn.microsoft.com/windows/apps/design/
|
|
710
|
+
- Modern Web Guidance (native web-platform patterns, fallbacks, and Baseline browser-compatibility guidance for coding agents; stewarded by the Chrome, Edge, Firefox, and MDN teams; Apache-2.0; referenced, not adapted; v1.0.0 current as of 2026-11-14): https://developer.chrome.com/docs/modern-web-guidance | https://github.com/GoogleChrome/modern-web-guidance
|
|
709
711
|
- shadcn/ui (accessible, composable web components): https://ui.shadcn.com/
|
|
710
712
|
- TanStack Charts (data visualization): https://github.com/TanStack/charts
|
|
711
713
|
- Cuelume (web interaction sounds): https://cuelume-site.pages.dev/
|
|
@@ -716,7 +718,7 @@ For React-specific supplemental diagnostics after implementation, including desi
|
|
|
716
718
|
- Pointer enhancement (only when `(hover: hover) and (pointer: fine)`; retain native controls/default cursor and equivalent tap interaction for touch/coarse pointers): https://cursify.ui-layouts.com/
|
|
717
719
|
- Typography discovery (verify each font's author, license, weights, and hosting rights): https://uncut.wtf/
|
|
718
720
|
- Creative coding and WebGL (semantic fallback, pause/offscreen behavior, performance budget, and asset/operator provenance): https://cables.gl/
|
|
719
|
-
- Impeccable (
|
|
721
|
+
- Impeccable (design vocabulary and commands for building, auditing, refining, hardening, and documenting interfaces; Apache-2.0; referenced, not adapted; v4.9.1 current as of 2026-11-14): https://impeccable.style/ | https://github.com/pbakaus/impeccable | [command reference](https://impeccable.style/docs)
|
|
720
722
|
- Gradient Studio (external procedural gradient exploration with CSS, Tailwind, and SCSS export by Amit Gajare; validate current provenance, reuse terms, output contrast, and performance budgets before adoption): https://gradientsaas.blogspot.com/
|
|
721
723
|
- Liquid Glass Design (an independent inspiration gallery, not affiliated with Apple; not a specification or asset library): https://liquidglassdesign.com/
|
|
722
724
|
- Guide to the material, glassmorphism, and web implementation: https://liquidglassdesign.com/what-is-liquid-glass
|
|
@@ -3,7 +3,7 @@ name: documentation-quality-eng
|
|
|
3
3
|
language: en
|
|
4
4
|
description: "Quality standards for accurate, task-oriented, maintainable, accessible, and verifiable technical documentation."
|
|
5
5
|
version: "2026.09"
|
|
6
|
-
last-reviewed: "2026-
|
|
6
|
+
last-reviewed: "2026-10-17"
|
|
7
7
|
guide-id: documentation
|
|
8
8
|
---
|
|
9
9
|
|
|
@@ -11,7 +11,7 @@ guide-id: documentation
|
|
|
11
11
|
|
|
12
12
|
> **Related documents**: use [`clean-code-eng.md`](./clean-code-eng.md) when software behavior or code structure changes; [`test-code-eng.md`](./test-code-eng.md) for executable examples and verification strategy; [`sec-code-eng.md`](./sec-code-eng.md) for secrets, authentication, authorization, privacy, and sensitive examples; [`accessibility-eng.md`](./accessibility-eng.md) when a published documentation surface has additional accessibility requirements. This guide owns documentation architecture, factual quality, freshness, maintainability, and reader usability.
|
|
13
13
|
>
|
|
14
|
-
> **Tooling policy**: identify the documentation surface, canonical sources, and existing project checks first. Prefer already available project-native tools.
|
|
14
|
+
> **Tooling policy**: identify the documentation surface, canonical sources, and existing project checks first. Prefer already available project-native tools. Installation or environment changes require authority; reuse scoped authorization already given rather than asking again. If a required check cannot be executed, record it as blocked or `NOT_VERIFIED`; never claim it passed.
|
|
15
15
|
|
|
16
16
|
## Context
|
|
17
17
|
|
|
@@ -128,6 +128,14 @@ Update affected documentation in the same task when the change is required for c
|
|
|
128
128
|
|
|
129
129
|
## Freshness and timeless wording
|
|
130
130
|
|
|
131
|
+
When reviewing engineering guides, compare the full catalog with its registry,
|
|
132
|
+
activation implementation, and metadata. Separate implemented capability from
|
|
133
|
+
proposed integration, sample check names from required evidence identifiers,
|
|
134
|
+
and contextual defaults from protocol or user-approval gates. A named tool
|
|
135
|
+
does not become mandatory merely because an example uses it. Record the
|
|
136
|
+
review's scope and unavailable consumer/platform checks; a fresh review date
|
|
137
|
+
does not certify every referenced API or framework.
|
|
138
|
+
|
|
131
139
|
Avoid time-sensitive words such as `new`, `currently`, `latest`, `now`, or `soon` in evergreen technical documentation when they will age without adding information.
|
|
132
140
|
|
|
133
141
|
Use explicit versions or dates when history or compatibility requires them.
|
|
@@ -3,7 +3,7 @@ name: dotnet-aspnetcore-development-eng
|
|
|
3
3
|
language: en
|
|
4
4
|
description: "Specialist guide for architecture, implementation, testing, performance, security, data access, hosting, observability, and release of production .NET and ASP.NET Core applications."
|
|
5
5
|
version: "2026.09"
|
|
6
|
-
last-reviewed: "2026-
|
|
6
|
+
last-reviewed: "2026-11-14"
|
|
7
7
|
guide-id: dotnet
|
|
8
8
|
---
|
|
9
9
|
|
|
@@ -75,9 +75,13 @@ Use structural project evidence for routing, but use source and configuration in
|
|
|
75
75
|
|
|
76
76
|
## 4. Version-sensitive decisions
|
|
77
77
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
78
|
+
.NET 10 is the current LTS line (supported until 2028-11-14; latest patch 10.0.15). .NET 8 and .NET 9
|
|
79
|
+
both reached end of support on 2026-11-10 and no longer receive security
|
|
80
|
+
updates; treat a repository still targeting them as carrying a supported-runtime
|
|
81
|
+
risk, and plan migration explicitly rather than as incidental cleanup. These are
|
|
82
|
+
dated references (reviewed 2026-11-14): use the repository's pinned SDK and
|
|
83
|
+
target framework, and check the official .NET support policy for the current
|
|
84
|
+
patch.
|
|
81
85
|
|
|
82
86
|
Treat these as version-sensitive:
|
|
83
87
|
|
|
@@ -3,7 +3,7 @@ name: flutter-development-eng
|
|
|
3
3
|
language: en
|
|
4
4
|
description: "Specialist guide for architecture, implementation, testing, performance, accessibility, platform integration, and release of production Flutter applications."
|
|
5
5
|
version: "2026.09"
|
|
6
|
-
last-reviewed: "2026-10-
|
|
6
|
+
last-reviewed: "2026-10-17"
|
|
7
7
|
guide-id: flutter
|
|
8
8
|
---
|
|
9
9
|
# Flutter Development Engineering Guide
|
|
@@ -1922,39 +1922,13 @@ A Flutter task is complete only when the applicable items are satisfied.
|
|
|
1922
1922
|
|
|
1923
1923
|
## 53. ForgeLoop guide routing integration
|
|
1924
1924
|
|
|
1925
|
-
|
|
1925
|
+
The `flutter` guide is registered in `src/config/guides.json` and already
|
|
1926
|
+
participates in the canonical router. The bounded project detector confirms
|
|
1927
|
+
Flutter from a parsed `pubspec.yaml` with an actual Flutter SDK dependency,
|
|
1928
|
+
then matches the affected claims to that project root. It does not execute
|
|
1929
|
+
Flutter, Dart, package scripts, generators, or SDK discovery during routing.
|
|
1926
1930
|
|
|
1927
|
-
|
|
1928
|
-
ENG/flutter-development-eng.md
|
|
1929
|
-
```
|
|
1930
|
-
|
|
1931
|
-
To make the current ForgeLoop `GUIDE_ROUTER.md` select it automatically, the repository should add a canonical catalog entry similar to:
|
|
1932
|
-
|
|
1933
|
-
```markdown
|
|
1934
|
-
| `flutter` | [Flutter development](ENG/flutter-development-eng.md) | Architecture, UI, state, platform integration, testing, performance, and release for Flutter applications |
|
|
1935
|
-
```
|
|
1936
|
-
|
|
1937
|
-
Add a domain rule similar to:
|
|
1938
|
-
|
|
1939
|
-
```markdown
|
|
1940
|
-
### `flutter` — Flutter application engineering
|
|
1941
|
-
|
|
1942
|
-
Activate when: designing, implementing, testing, debugging, profiling, integrating, or releasing a Flutter or Dart application where Flutter is an actual project stack.
|
|
1943
|
-
|
|
1944
|
-
Do not activate merely because: documentation mentions Flutter, a generated Flutter example exists, or a dependency name contains "flutter" without the affected application being a Flutter project.
|
|
1945
|
-
|
|
1946
|
-
Usually combine with: `clean` and `test`; add `design` and `accessibility` for user-facing UI, `security` for networking/auth/data/plugins/release, and `performance` for rendering/startup/memory/network critical paths.
|
|
1947
|
-
|
|
1948
|
-
rg -n '^## |architecture|ViewModel|state|widget|layout|navigation|deep link|network|serialization|isolate|platform|plugin|FFI|web|accessibility|performance|test|release|Definition of Done' ENG/flutter-development-eng.md
|
|
1949
|
-
|
|
1950
|
-
Expected evidence: Flutter/Dart version awareness, architecture-consistent implementation, analyzer/test evidence, accessibility/adaptive checks for UI, platform-boundary validation where changed, and an affected-target build when feasible.
|
|
1951
|
-
```
|
|
1952
|
-
|
|
1953
|
-
The deterministic router may also need an explicit stack signal or routing rule if the current schema cannot identify Flutter from verified project manifests. Do not make natural-language string matching the sole proof that a project is Flutter. A strong deterministic signal is the presence and parsed content of `pubspec.yaml` with an actual Flutter SDK dependency, combined with affected surfaces/platform signals.
|
|
1954
|
-
|
|
1955
|
-
## 54. Suggested deterministic Flutter stack evidence
|
|
1956
|
-
|
|
1957
|
-
A repository can be classified as Flutter when evidence such as the following is confirmed:
|
|
1931
|
+
The primary manifest signal is:
|
|
1958
1932
|
|
|
1959
1933
|
```yaml
|
|
1960
1934
|
dependencies:
|
|
@@ -1962,32 +1936,37 @@ dependencies:
|
|
|
1962
1936
|
sdk: flutter
|
|
1963
1937
|
```
|
|
1964
1938
|
|
|
1965
|
-
|
|
1966
|
-
|
|
1967
|
-
|
|
1968
|
-
|
|
1969
|
-
|
|
1970
|
-
|
|
1971
|
-
|
|
1972
|
-
|
|
1973
|
-
|
|
1974
|
-
|
|
1975
|
-
|
|
1976
|
-
|
|
1977
|
-
|
|
1978
|
-
|
|
1979
|
-
|
|
1980
|
-
|
|
1981
|
-
|
|
1982
|
-
|
|
1983
|
-
|
|
1984
|
-
|
|
1985
|
-
|
|
1986
|
-
flutter-
|
|
1987
|
-
flutter-
|
|
1988
|
-
|
|
1989
|
-
|
|
1990
|
-
|
|
1939
|
+
Pure Dart packages, platform runner directories, `.metadata`, `flutter_test`,
|
|
1940
|
+
CI tooling, generated examples, and transitive package names do not substitute
|
|
1941
|
+
for that primary Flutter identity. Preserve nested project ownership.
|
|
1942
|
+
|
|
1943
|
+
For implementation, use the route returned by the current runtime and combine
|
|
1944
|
+
it with the guides selected for the actual surfaces and risks. UI may require
|
|
1945
|
+
design/accessibility checks; trust boundaries require security checks;
|
|
1946
|
+
performance work requires measured evidence. Do not manually invent a routed
|
|
1947
|
+
guide set or duplicate routing rules in a host integration.
|
|
1948
|
+
|
|
1949
|
+
## 54. Discovery versus verification
|
|
1950
|
+
|
|
1951
|
+
A confirmed manifest establishes project identity, not analyzer success,
|
|
1952
|
+
compilation, device support, accessibility, or release readiness. Inspect the
|
|
1953
|
+
repository's pinned SDK, dependency graph, platform configuration, and actual
|
|
1954
|
+
commands after routing. Collect those outcomes separately through the normal
|
|
1955
|
+
verification flow; missing SDKs, devices, signing, and platform checks remain
|
|
1956
|
+
explicitly unverified.
|
|
1957
|
+
|
|
1958
|
+
## 55. Task-specific verification checks
|
|
1959
|
+
|
|
1960
|
+
Choose check IDs that explain the observation, such as `flutter-analyze`,
|
|
1961
|
+
`flutter-unit-widget-tests`, `flutter-target-build`, or
|
|
1962
|
+
`flutter-deep-link-validation`, and bind each check to a requirement from the
|
|
1963
|
+
active contract or selected guide metadata. These are example check names,
|
|
1964
|
+
not new protocol enums or automatic completion requirements.
|
|
1965
|
+
|
|
1966
|
+
This guide's frontmatter does not declare an extra Flutter-specific gate or
|
|
1967
|
+
completion-evidence ID. Required gates and evidence come from the actual
|
|
1968
|
+
contract, route, metadata, and canonical runtime. Record executed commands
|
|
1969
|
+
with `run-check`; a formatted check name or manifest match is not evidence.
|
|
1991
1970
|
|
|
1992
1971
|
## 56. Official documentation map
|
|
1993
1972
|
|
|
@@ -3,7 +3,7 @@ name: games-code-design-web-eng
|
|
|
3
3
|
language: en
|
|
4
4
|
description: "Architecture, design, testing, and operation of 2D, 3D, and procedural web games."
|
|
5
5
|
version: "2026.09"
|
|
6
|
-
last-reviewed: "2026-
|
|
6
|
+
last-reviewed: "2026-10-17"
|
|
7
7
|
guide-id: games
|
|
8
8
|
requires-gates:
|
|
9
9
|
- simulation
|
|
@@ -18,7 +18,7 @@ completion-evidence:
|
|
|
18
18
|
>
|
|
19
19
|
> **Related documents**: for general code structure, naming, dependency injection, and debugging, see [`clean-code-eng.md`](./clean-code-eng.md). For test strategy and tools such as Vitest and Playwright, see [`test-code-eng.md`](./test-code-eng.md). For browser security, CSP, dependency scanning, and multiplayer threat models, see [`sec-code-eng.md`](./sec-code-eng.md). For budgets, profiling, WebAssembly, PWA, CDN, and device performance, see [`perf-code-eng.md`](./perf-code-eng.md). For visual direction, UX, motion, and responsive design, see [`design-code-eng.md`](./design-code-eng.md). For WCAG 2.2-oriented implementation, assistive technology, and manual testing, see [`accessibility-eng.md`](./accessibility-eng.md). For HTML-based gameplay trailers, devlogs, and demos, see [HyperFrames](https://hyperframes.heygen.com). This guide focuses on game architecture and delivery; it does not replace those documents.
|
|
20
20
|
>
|
|
21
|
-
> **Tooling policy**: identify the stack, the stage, and the applicable checks; prefer an already available equivalent that produces compatible evidence.
|
|
21
|
+
> **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.
|
|
22
22
|
|
|
23
23
|
## How to use this guide (mandatory process)
|
|
24
24
|
|
|
@@ -3,7 +3,7 @@ name: nodejs-backend-development-eng
|
|
|
3
3
|
language: en
|
|
4
4
|
description: "Specialist guidance for architecture, implementation, testing, security, performance, observability, and release of production Node.js backend services and workers."
|
|
5
5
|
version: "2026.09"
|
|
6
|
-
last-reviewed: "2026-
|
|
6
|
+
last-reviewed: "2026-11-14"
|
|
7
7
|
guide-id: nodejs
|
|
8
8
|
requires-gates:
|
|
9
9
|
- threat-boundary
|
|
@@ -148,9 +148,12 @@ descendants; unrelated frontend packages remain isolated.
|
|
|
148
148
|
|
|
149
149
|
## 3. Runtime and module-system decisions
|
|
150
150
|
|
|
151
|
-
As of 2026-
|
|
152
|
-
|
|
153
|
-
|
|
151
|
+
As of 2026-11-14, Node.js 26 is Active LTS (promoted 2026-10-28) and Node.js 24
|
|
152
|
+
is Maintenance LTS. Node.js 26 is the last release on the twice-yearly
|
|
153
|
+
schedule; from Node.js 27 the project ships one major per year (April) and
|
|
154
|
+
promotes it to LTS each October. Production deployments should use an Active or
|
|
155
|
+
Maintenance LTS line; check the official release schedule again when selecting
|
|
156
|
+
a runtime.
|
|
154
157
|
|
|
155
158
|
Record the actual runtime range before changing APIs:
|
|
156
159
|
|
package/ENG/perf-code-eng.md
CHANGED
|
@@ -3,7 +3,7 @@ name: perf-code-eng
|
|
|
3
3
|
language: en
|
|
4
4
|
description: "Performance measurement, diagnosis, and improvement for web, mobile, desktop, APIs, and data."
|
|
5
5
|
version: "2026.09"
|
|
6
|
-
last-reviewed: "2026-
|
|
6
|
+
last-reviewed: "2026-10-17"
|
|
7
7
|
guide-id: performance
|
|
8
8
|
completion-evidence:
|
|
9
9
|
- performance-validation
|
|
@@ -13,7 +13,7 @@ completion-evidence:
|
|
|
13
13
|
|
|
14
14
|
> Practical instructions for designing, measuring, diagnosing, and improving performance in web, mobile (iOS/Android), desktop (Windows/macOS), APIs, infrastructure, and databases. Use this document to guide AI agents and developers. Performance must be measured in real scenarios before and after the change — do not optimize based on assumptions.
|
|
15
15
|
> **Related documents**: for code structure and readability, see [`clean-code-eng.md`](./clean-code-eng.md). For functional, integration, and E2E testing, see [`test-code-eng.md`](./test-code-eng.md). For security and cache, secrets, and infrastructure trade-offs, see [`sec-code-eng.md`](./sec-code-eng.md). For perceived performance, UX, motion, and responsive design, see [`design-code-eng.md`](./design-code-eng.md). For HTML video preview and rendering performance, see [HyperFrames](https://hyperframes.heygen.com). This file is the canonical performance reference.
|
|
16
|
-
> **Tooling policy**: identify the stack, the stage, and the applicable checks; prefer an already available equivalent that produces compatible evidence.
|
|
16
|
+
> **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.
|
|
17
17
|
|
|
18
18
|
## General principles
|
|
19
19
|
|
|
@@ -22,7 +22,7 @@ completion-evidence:
|
|
|
22
22
|
- **Optimize the critical path**: prioritize what blocks the first render, the first interaction, the most-used operation, or the flow that has the greatest impact on the user.
|
|
23
23
|
- **Distribution metrics**: track median (p50), p75, p95, and p99. A healthy average can hide a minority of users with a very poor experience.
|
|
24
24
|
- **Perceived performance matters**: immediate feedback, skeleton/loading state, streaming, and progressive updates can improve the experience without masking a slow operation.
|
|
25
|
-
- **Do not block the main thread**:
|
|
25
|
+
- **Do not block the main thread**: use asynchronous APIs for I/O and bound parsing, serialization, and CPU-heavy work. An `async` function or Promise does not move CPU work off the event loop. Measure whether partitioning work or a bounded worker/background pool improves responsiveness, including transfer and scheduling cost. See [Node.js event-loop guidance](https://nodejs.org/en/learn/asynchronous-work/dont-block-the-event-loop).
|
|
26
26
|
- **Less work is better than faster work**: eliminate unnecessary calls, renders, queries, allocations, payloads, and initializations before micro-optimizing an algorithm.
|
|
27
27
|
- **Avoid speculative optimization**: do not add cache, pooling, memoization, or complexity without evidence of a bottleneck and without measuring invalidation, memory, and maintenance cost.
|
|
28
28
|
- **Control concurrency and resources**: use timeouts, queue limits, backpressure, quotas, circuit breakers, and cancellation to prevent slowness from becoming resource exhaustion.
|
|
@@ -3,7 +3,7 @@ name: php-development-eng
|
|
|
3
3
|
language: en
|
|
4
4
|
description: "Specialist guidance for production PHP applications, Composer packages, web services, and command-line workers."
|
|
5
5
|
version: "2026.09"
|
|
6
|
-
last-reviewed: "2026-10-
|
|
6
|
+
last-reviewed: "2026-10-17"
|
|
7
7
|
guide-id: php
|
|
8
8
|
requires-gates:
|
|
9
9
|
- threat-boundary
|
|
@@ -51,7 +51,7 @@ do not edit generated/vendor content as if it were application source.
|
|
|
51
51
|
PHP extensions deserve special care: an extension or C-extension package may
|
|
52
52
|
compose with the C specialist, but does not imply PHP implementation. Keep
|
|
53
53
|
Composer-less source fallback limited to owned files with an executable
|
|
54
|
-
`<?php` opening tag and do not promote generated/vendor trees.
|
|
54
|
+
`<?php` or `<?=` opening tag and do not promote generated/vendor trees.
|
|
55
55
|
|
|
56
56
|
## Architecture and language semantics
|
|
57
57
|
|
|
@@ -3,7 +3,7 @@ name: premium-sites-studio-eng
|
|
|
3
3
|
language: en
|
|
4
4
|
description: "Complete process for building premium websites at major design-studio quality."
|
|
5
5
|
version: "2026.09"
|
|
6
|
-
last-reviewed: "2026-
|
|
6
|
+
last-reviewed: "2026-10-17"
|
|
7
7
|
guide-id: premium
|
|
8
8
|
requires-gates:
|
|
9
9
|
- design
|
|
@@ -19,7 +19,7 @@ completion-evidence:
|
|
|
19
19
|
|
|
20
20
|
> This guide defines the production process. For detailed visual rules, also use [`design-code-eng.md`](./design-code-eng.md). For accessibility, code quality, testing, security, and performance, consult the related documents at the end. A high-end website is not only a beautiful interface: it is a coherent, useful, fast, accessible, measurable, and maintainable experience.
|
|
21
21
|
>
|
|
22
|
-
> **Tooling policy**: identify the stack, the stage, and the applicable checks; prefer an already available equivalent that produces compatible evidence.
|
|
22
|
+
> **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.
|
|
23
23
|
|
|
24
24
|
## 1. Quality bar
|
|
25
25
|
|
|
@@ -49,6 +49,13 @@ Follow the gates in order. Within each gate, use the canonical [Loop Engineering
|
|
|
49
49
|
|
|
50
50
|
Each gate must have a verifiable output. If a decision remains ambiguous, record the hypothesis, risk, owner, and next test; do not hide uncertainty behind aesthetics.
|
|
51
51
|
|
|
52
|
+
These production stages do not create extra ForgeLoop lifecycle gates or
|
|
53
|
+
mandatory user approvals. In autonomous work, resolve reversible brief,
|
|
54
|
+
layout, and direction choices as recorded assumptions and continue. Ask only
|
|
55
|
+
for a genuine blocking decision under Loop Engineering. Client approval and
|
|
56
|
+
publication authority remain required when the actual engagement or requested
|
|
57
|
+
external action requires them; a generic checklist cannot invent that boundary.
|
|
58
|
+
|
|
52
59
|
## 3. Gate 1 — Brief, strategy, and success
|
|
53
60
|
|
|
54
61
|
Before choosing colors or components, produce a short brief:
|
|
@@ -3,7 +3,7 @@ name: python-development-eng
|
|
|
3
3
|
language: en
|
|
4
4
|
description: "Specialist guidance for production Python applications, libraries, command-line tools, data pipelines, and native extensions."
|
|
5
5
|
version: "2026.09"
|
|
6
|
-
last-reviewed: "2026-10-
|
|
6
|
+
last-reviewed: "2026-10-17"
|
|
7
7
|
guide-id: python
|
|
8
8
|
requires-gates:
|
|
9
9
|
- threat-boundary
|
|
@@ -22,6 +22,12 @@ actual project from owned `.py` files and its packaging/build metadata, such as
|
|
|
22
22
|
Do not infer Python project identity from documentation, editor settings,
|
|
23
23
|
Jupyter output, a Python executable used only by CI, or a transitive package.
|
|
24
24
|
|
|
25
|
+
This is reference guidance in ForgeLoop's catalog. The current structural
|
|
26
|
+
project-evidence schema and router do not automatically detect Python or
|
|
27
|
+
select this specialist from Python manifests. Load it explicitly when Python
|
|
28
|
+
work is in scope, and inspect the canonical route for the selected guides;
|
|
29
|
+
the presence of this document is not automatic-routing support.
|
|
30
|
+
|
|
25
31
|
This guide is based on the official Python 3.15.0 documentation. Python 3.15.0
|
|
26
32
|
was released as a stable release on 2026-10-09. Its release highlights include
|
|
27
33
|
the `sentinel` and `frozendict` built-ins, UTF-8 as the default encoding,
|