@cassiomc1/forgeloop 1.12.0 → 1.13.0

package/ENG/swift-development-eng.md

@@ -0,0 +1,111 @@
+---
+name: swift-development-eng
+language: en
+description: "Specialist guidance for production Swift applications, packages, services, and Apple-platform components."
+version: "2026.09"
+last-reviewed: "2026-09-12"
+guide-id: swift
+requires-gates:
+  - threat-boundary
+completion-evidence:
+  - swift-validation
+---
+
+# Swift Development Engineering Guide
+
+## Mission and activation
+
+Use this guide for Swift applications, packages, services, workers, Apple
+platform components, and command-line tools. A valid `Package.swift` is
+SwiftPM topology; it does not by itself prove that a Swift target exists. The
+specialist is confirmed by owned `.swift` source, explicit Swift in CMake or
+Meson, bounded Xcode Swift markers, or a direct claim to Swift source. A direct
+claim to `Package.swift` selects Swift guidance because the manifest itself is
+Swift/PackageDescription code, including a native-only package. A C-only or
+C++-only package remains native-only for unrelated source claims.
+
+`Package.resolved`, package names, an Xcode image, Docker/CI setup, generated
+or vendored source, and package-manager metadata alone are not Swift runtime
+identity. Detection reads bounded text and never runs SwiftPM, Xcode, macros,
+plugins, build scripts, tests, or network resolution.
+
+## Authority and precedence
+
+Repository package manifest, toolchain, deployment target, SDK, target triple,
+entitlements, signing policy, ABI, and platform support win over generic
+advice. Use version-matched Swift language, SwiftPM, Apple SDK, and Xcode
+documentation after repository evidence. Swift 6.3 is the stable reference in
+the 2026-09 plan snapshot; the online language book's 6.4 beta material is not
+an automatic target.
+
+Keep Swift language mode, compiler/toolchain, SDK, deployment target, runtime
+OS, architecture, signing, entitlements, and package/platform compatibility
+separate. Do not migrate an existing target because a newer toolchain is
+available.
+
+## Package, project, and target discovery
+
+`Package.swift` must have a tools-version header and conservative
+`PackageDescription`/`Package(` structure. The manifest is executable code, so
+dynamic target declarations may remain unresolved. Use default SwiftPM source
+conventions and already discovered files without evaluating the manifest.
+Invalid `Package.swift` contributes no SwiftPM-derived Swift/C/C++ evidence;
+independently confirmed native build roots remain eligible. Swift `mobile-ui`
+work is executable language work for routing purposes.
+`project.pbxproj` and CMake/Meson declarations are static context; an
+`.xcworkspace` or package resolution file is aggregation/dependency context.
+
+SwiftPM may contain separate Swift, C, and C++ targets. Preserve same-root
+composition and nested package ownership; do not make languages mutually
+exclusive or claim a native target as Swift without evidence.
+
+## Architecture and language semantics
+
+Keep UI, domain, persistence, networking, platform services, and package
+targets separate where the repository does. Review value/reference semantics,
+optionals, protocols, generics, associated types, error enums, `Codable`,
+actors, structured concurrency, isolation, `Sendable`, ownership/lifetime,
+ARC, retain cycles, unsafe pointers, existentials, and ABI/public API
+compatibility.
+
+Make async cancellation, task ownership, actor boundaries, executor use,
+timeouts, back pressure, and shutdown observable. Do not hide mutable shared
+state behind global actors or introduce `@unchecked Sendable` without a
+proven invariant.
+
+## I/O, security, and performance
+
+Validate URL, file, IPC, decoded, keychain, network, and platform-service data
+before use. Bound downloads, image/data decoding, queues, retries, tasks,
+database resources, and logging. Protect credentials, entitlements, signing
+material, user data, deep links, and IPC boundaries. Measure startup, memory,
+allocation, rendering, battery, network, and concurrency behavior before
+optimizing.
+
+## Build, interop, and portability
+
+Keep SwiftPM/Xcode build settings, SDKs, generated sources, macros, package
+versions, platform deployment targets, and reproducible archives under review.
+At C/C++/Objective-C/FFI boundaries specify layout, ownership, nullability,
+error translation, thread/actor rules, and lifetime. Keep Apple-platform
+conditional code and cross-platform abstractions explicit.
+
+## Verification and Definition of Done
+
+Run focused SwiftPM/Xcode compilation, unit/UI/integration tests, concurrency
+checks, static analysis, package resolution/lockfile checks, signing and
+entitlement checks, and platform matrix validation for the exact SDK and
+target. Record command, toolchain, platform, and unavailable tools as
+`NOT_VERIFIED`. Completion requires tested cancellation, failure, resource,
+security, compatibility, and packaging behavior. ForgeLoop performs bounded
+structural Swift package/project analysis, not full SwiftPM resolution, build
+setting evaluation, macro execution, or Xcode build execution.
+
+## Official sources
+
+- [The Swift Programming Language](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/)
+- [Swift.org documentation](https://www.swift.org/documentation/)
+- [Swift Package Manager](https://github.com/swiftlang/swift-package-manager)
+- [Swift Package Manager package description](https://docs.swift.org/package-manager/PackageDescription/PackageDescription.html)
+- [CMake project languages](https://cmake.org/cmake/help/latest/command/project.html)
+- [Apple developer documentation](https://developer.apple.com/documentation/)

package/ENG/typescript-development-eng.md

@@ -0,0 +1,108 @@
+---
+name: typescript-development-eng
+language: en
+description: "Specialist guidance for TypeScript applications, libraries, build configurations, and typed JavaScript boundaries."
+version: "2026.09"
+last-reviewed: "2026-09-12"
+guide-id: typescript
+requires-gates:
+  - threat-boundary
+completion-evidence:
+  - typescript-validation
+---
+
+# TypeScript Development Engineering Guide
+
+## Mission and activation
+
+Use this runtime-neutral guide for TypeScript applications, libraries, tools,
+and typed JavaScript boundaries. A valid bounded `tsconfig.json` is primary
+evidence. A custom `tsconfig.*.json` is primary only when directly claimed or
+referenced by a confirmed local config. `jsconfig.json`, `.ts` snippets,
+`.d.ts` declarations, a TypeScript dependency, CI compiler setup, generated
+declarations, and build/test configuration alone do not establish a TypeScript
+project. A TypeScript config may coexist with Node.js at the same root; the
+two specialists describe different concerns.
+
+The detector uses a small JSONC recognizer for comments and trailing commas,
+keeps references bounded to discovered configs, and never executes a config,
+compiler, package script, or project code.
+
+## Authority and precedence
+
+Repository compiler/configuration, emitted module contract, runtime support,
+public type compatibility, and build policy win over generic advice. Use the
+matching repository TypeScript version/config first, then official TypeScript
+documentation and release notes, then runtime/framework documentation. The
+2026-09 plan snapshot records TypeScript 7.0 as the current reference. TS 7.0
+uses the native Go-based toolset and does not provide a stable programmatic
+compiler API; TS 6 compatibility can remain necessary for tooling. Do not
+auto-migrate TS 6 projects or compiler integrations to TS 7.
+
+## Configuration and project discovery
+
+Treat a confirmed application `tsconfig.json` as a project root even when it
+has no source. Preserve solution configs with `files: []` and local
+`references`; a reference may name a directory containing `tsconfig.json` or a
+specific discovered config. Local `extends` is shared configuration context,
+not permission to execute or walk arbitrary packages. External package
+resolution and cyclic/unbounded config graphs fail closed or remain
+unresolved. `extends` may be a string or an array. A claimed shared base,
+including one literally named `tsconfig.json`, maps to its own confirmed
+project (when independently evidenced) plus discovered direct and transitive
+consumers; a shared config is not promoted to an independent project solely by
+its basename.
+
+Keep `include`/`exclude`, project references, `composite`, incremental state,
+path mapping, module resolution, `module`/`target`, `lib`, JSX, decorators,
+declaration emit, source maps, and `noEmit` as separate decisions. Build,
+test, Vite, Webpack, and Node configuration is not backend identity.
+
+## Architecture and type semantics
+
+Keep runtime contracts distinct from type-level intent. Review inference and
+narrowing, `unknown` versus `any`, `never`, unions/intersections,
+discriminated unions, generics, conditional/mapped/template-literal types,
+variance where relevant, assertions, `satisfies`, declaration merging, and
+public declaration compatibility. Do not enable `strict`,
+`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, or a module-mode
+migration as incidental cleanup.
+
+Type erasure means TypeScript type correctness is not runtime input
+validation. Validate JSON, network, environment, database, IPC, and persisted
+data at runtime with an intentional boundary contract.
+
+## Modules, async behavior, and security
+
+Preserve the repository's ESM/CJS, package `exports`/`imports`, interop,
+source-map, and loader behavior. Make promises, cancellation, timeouts,
+back-pressure, worker ownership, and shutdown observable. Treat DOM/runtime
+values, serialized data, file paths, environment variables, dynamic imports,
+templates, and credentials as untrusted. Avoid leaking source maps, secrets,
+or internal errors across public boundaries.
+
+## Performance, build, and portability
+
+Measure compiler graph size, incremental performance, emitted bundle size,
+startup, memory, and runtime latency before optimizing. Keep generated output,
+declaration emit, package manager lockfiles, platform APIs, browser/Node
+globals, and target compatibility explicit. Do not infer runtime support from
+the compiler target or from a build tool's Node process.
+
+## Verification and Definition of Done
+
+Run the affected config's type-check, project-reference build, tests, lint,
+runtime validation, bundle/package checks, and security checks, then the
+repository suite. Record compiler version, config path, module mode, target,
+runtime, generated artifacts, and exact commands. Verify public library types
+and clean-install behavior. Missing tooling is `NOT_VERIFIED`. ForgeLoop
+performs bounded structural TypeScript analysis; it does not implement the
+compiler, module resolver, path mapper, or build graph.
+
+## Official sources
+
+- [TypeScript handbook](https://www.typescriptlang.org/docs/)
+- [What is a tsconfig.json?](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html)
+- [TypeScript TSConfig reference](https://www.typescriptlang.org/tsconfig/)
+- [TypeScript 7.0 release announcement](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/)
+- [TypeScript GitHub repository](https://github.com/microsoft/TypeScript)