icore 1.0.4 → 1.0.5

package/docs/git-flow.md

@@ -1,188 +0,0 @@
-# Git Flow
-
-This project uses a classic Git Flow branching model.
-
-## Long-Lived Branches
-
-### `master`
-
-`master` is the production and package provenance branch.
-
-- Contains only released code.
-- Receives completed releases from `release/*` branches.
-- Receives urgent production fixes from `hotfix/*` branches.
-- Each release commit on `master` must have a semver tag, for example `v1.1.5`.
-
-Do not commit feature work directly to `master`.
-
-### `legacy/v1`
-
-`legacy/v1` preserves the historical `icore@0.1.38` codebase.
-
-- Points to the final legacy package state.
-- Must remain available for provenance and historical reference.
-- Must not receive new development work.
-- Must be pushed before any cleanup or replacement of legacy files.
-
-### `develop`
-
-`develop` is the integration branch for active development.
-
-- New feature branches start from `develop`.
-- Completed feature branches are merged back into `develop`.
-- Release branches start from `develop`.
-- Hotfix branches are merged back into `develop` after they are released from `master`.
-
-Do not release directly from `develop`.
-
-## Short-Lived Branches
-
-### `feature/*`
-
-Use `feature/*` branches for regular development work.
-
-Naming:
-
-```bash
-feature/<short-description>
-```
-
-Example:
-
-```bash
-feature/restore-public-api
-```
-
-Flow:
-
-```bash
-git switch develop
-git switch -c feature/restore-public-api
-
-# make changes, run checks
-git add .
-git commit -m "fix: restore public API"
-
-git switch develop
-git merge --no-ff feature/restore-public-api
-git branch -d feature/restore-public-api
-git push origin develop
-```
-
-### `release/*`
-
-Use `release/*` branches to prepare a version for release.
-
-Naming:
-
-```bash
-release/v<major>.<minor>.<patch>
-```
-
-Example:
-
-```bash
-release/v1.1.5
-```
-
-Allowed changes on a release branch:
-
-- Version bump.
-- Changelog or release notes.
-- Release-only documentation.
-- Small release blockers found during validation.
-
-Do not add unrelated feature work to a release branch.
-
-Flow:
-
-```bash
-git switch develop
-git switch -c release/v1.1.5
-
-# version/changelog/release fixes, run checks
-git add .
-git commit -m "chore: prepare release v1.1.5"
-
-git switch master
-git merge --no-ff release/v1.1.5
-git tag -a v1.1.5 -m "Release v1.1.5"
-
-git switch develop
-git merge --no-ff release/v1.1.5
-
-git branch -d release/v1.1.5
-git push origin master develop --tags
-```
-
-### `hotfix/*`
-
-Use `hotfix/*` branches only for urgent fixes to released code.
-
-Naming:
-
-```bash
-hotfix/v<major>.<minor>.<patch>
-```
-
-Example:
-
-```bash
-hotfix/v1.1.6
-```
-
-Flow:
-
-```bash
-git switch master
-git switch -c hotfix/v1.1.6
-
-# make fix, run checks
-git add .
-git commit -m "fix: correct production issue"
-
-git switch master
-git merge --no-ff hotfix/v1.1.6
-git tag -a v1.1.6 -m "Release v1.1.6"
-
-git switch develop
-git merge --no-ff hotfix/v1.1.6
-
-git branch -d hotfix/v1.1.6
-git push origin master develop --tags
-```
-
-## Tags
-
-Every released version must be tagged from `master`.
-
-Use annotated tags:
-
-```bash
-git tag -a v1.1.5 -m "Release v1.1.5"
-git push origin --tags
-```
-
-Do not move release tags after they have been pushed.
-
-## Merge Policy
-
-Use merge commits for branch completion:
-
-```bash
-git merge --no-ff <branch>
-```
-
-This preserves the historical branch structure and matches the existing repository history.
-
-## Current Historical Baseline
-
-The repository preserves the old npm package history before new development:
-
-- `master` points to the final legacy release commit `3048f15`.
-- `legacy/v1` points to the same final legacy release commit `3048f15`.
-- npm `icore@0.1.38` was published from commit `3048f15`.
-- New alpha development starts from `develop`, not from `master`.
-
-Do not delete or rewrite `legacy/v1`. If a future `main` branch is introduced,
-decide that as a separate repository migration and keep `legacy/v1` intact.

package/docs/policy/abstraction-policy.md

@@ -1,198 +0,0 @@
-# Abstraction Policy
-
-> Type: Policy. This document defines rules for introducing interfaces, factories, registries, helpers, adapters, and shared modules.
-
-## Purpose
-
-This policy protects the project from premature generalization.
-
-A typical agent mistake is to create an interface, factory, registry, helper, or adapter before real repetition or an architectural boundary appears in the code.
-
-## Basic Rule
-
-An abstraction appears after repetition or an explicit boundary.
-
-Allowed reasons:
-
-- the logic is actually repeated;
-- there are two or more implementations;
-- there is an explicit boundary between business logic and infrastructure;
-- the code must be tested separately;
-- the inline solution has become more complex than a named abstraction;
-- the new abstraction reduces coupling between existing parts.
-
-Not allowed reasons:
-
-- "this is architecturally prettier";
-- "it may be useful later";
-- "other projects do it this way";
-- "a second implementation will appear someday";
-- "I want to hide the details";
-- "the file became visually long".
-
-## One Implementation
-
-One implementation usually does not require an interface.
-
-An interface is allowed with one implementation only if:
-
-- it is a public contract;
-- it is a boundary for an infrastructure adapter;
-- it is a test seam without which behavior cannot be checked reliably;
-- it is an external API requirement;
-- there is an owner decision for an extension point.
-
-Creating an interface only so that a class "depends on an abstraction" is forbidden.
-
-## Helpers
-
-A helper is introduced only if it reduces complexity.
-
-Allowed:
-
-- extract a repeated non-trivial calculation;
-- name a complex condition when the name exposes business meaning;
-- hide an integration detail inside an infrastructure boundary;
-- remove duplication that has already appeared in the current task.
-
-Not allowed:
-
-- wrap one standard function without a new responsibility;
-- hide an important branch behind a too-generic name;
-- create `utils` for one line;
-- extract two similar lines when the similarity is accidental;
-- create a helper that forces readers to open more files to understand simple behavior.
-
-A good helper makes the calling code clearer. A bad helper hides meaning and increases navigation.
-
-## Factories
-
-A factory is needed when object creation itself has become a separate responsibility.
-
-Allowed:
-
-- creation logic contains branching;
-- several dependencies must be assembled;
-- there is lifecycle or resource ownership;
-- there are several supported creation modes;
-- the factory is public API.
-
-Not allowed:
-
-- create `createX()` only instead of `new X()`;
-- extract a constructor call for consistency;
-- create a factory before lifecycle/branching/dependency assembly appears.
-
-## Registries
-
-A registry is needed only for dynamic selection from a set of known implementations.
-
-Allowed:
-
-- there are several registered handlers/adapters;
-- selection happens by runtime key;
-- the set of entries is part of the contract;
-- duplicate switch/lookup logic has already appeared.
-
-Not allowed:
-
-- a registry with one item;
-- a registry "for the future";
-- a registry instead of a simple import;
-- a registry that hides the dependency graph.
-
-## Adapters
-
-An adapter is needed at a boundary with an external system, library, filesystem, network, framework, or process API.
-
-Allowed:
-
-- separate an external type from an internal/public contract;
-- isolate library-specific behavior;
-- normalize external errors;
-- hide environment-specific IO.
-
-Not allowed:
-
-- create an adapter for an internal function without an external boundary;
-- introduce an adapter only for naming symmetry;
-- leak an adapter type into public API without an owner decision.
-
-## Shared / Common / Utils
-
-A shared module is allowed only when it has a clear responsibility.
-
-Forbidden:
-
-- create `utils`, `common`, `shared`, or `helpers` as a dumping ground;
-- move code there without naming the responsibility;
-- mix unrelated helpers;
-- use a shared module as a bypass around an architectural boundary.
-
-If shared code is needed, the name must describe the role:
-
-```text
-config/
-filesystem/
-diagnostics/
-formatting/
-runtime/
-```
-
-If the role cannot be named more precisely, the abstraction is not ready yet.
-
-## Local Simplicity
-
-Local simplicity is more important than "beautiful architecture".
-
-Preferred:
-
-- keep a simple condition inline;
-- keep one implementation without an interface;
-- keep a direct call without a factory;
-- keep an explicit import without a registry;
-- keep local code next to its only usage.
-
-Architectural form is justified only when it reduces current complexity, not when it demonstrates future design.
-
-## Frequency Rule
-
-Practical rule:
-
-```text
-1 use  -> inline
-2 uses -> consider whether this is the same responsibility
-3+ uses -> consider an abstraction
-```
-
-The number of repetitions is not enough by itself. The repetition must have the same reason to change.
-
-## Check Before Extracting
-
-Before adding an abstraction, answer:
-
-1. What current problem is being solved?
-2. Is there repetition or an explicit boundary?
-3. Will the code be easier to read at the call site?
-4. Is important behavior being hidden?
-5. Is a public/internal contract being created for the future?
-6. Can the task be solved locally in a simpler way?
-
-If the answers are unconvincing, the abstraction is not added.
-
-## Examples
-
-Allowed:
-
-- extract repeated config parsing when it is used in several modules with the same reason to change;
-- create an adapter for filesystem access when business logic must not know about IO;
-- create a factory when runtime object creation requires lifecycle and several dependencies;
-- create a registry when there are several handlers and runtime dispatch.
-
-Not allowed:
-
-- create `utils.ts` for one function;
-- create an interface for a single class without a boundary;
-- create a registry with one handler;
-- create a factory that only calls a constructor;
-- extract a helper so that the calling code loses important context.

package/docs/policy/change-policy.md

@@ -1,86 +0,0 @@
-# Change Policy
-
-> Type: Policy. This document defines the minimum acceptable change rule.
-
-## Minimality Of Changes
-
-A change must be the minimum necessary change required to solve the task.
-
-Forbidden:
-
-- large refactoring without a request
-- cleanup without justification
-- style changes outside the affected area
-- architecture changes
-- pipeline changes
-- scripts changes
-- behavior changes
-
-Existing code is considered intentional.
-
-If a change is not required, it must not be made.
-
-## Local Improvements
-
-Small improvements are allowed when they are directly related to the current task.
-
-Allowed:
-
-- remove local duplication
-- improve naming
-- simplify readability
-- fix a nearby obvious defect
-- improve local tests
-
-Conditions:
-
-- behavior does not change
-- the change remains local
-- the improvement helps solve the current task
-
-If an improvement is outside the task scope, it should be proposed separately.
-
-## Examples
-
-Allowed:
-
-- fix a specific defect in one module without rewriting neighboring code
-- add a focused test for a new requirement without changing the existing test pipeline
-- extend an existing `if` branch when this is directly required by the task
-
-Not allowed:
-
-- mass-rename entities for consistency
-- perform unrelated renames in other modules
-- rewrite an entire module instead of fixing one branch
-- change file structure only because it seems more convenient
-
-## Module Boundaries
-
-Bad structure should not be preserved only because it already exists.
-
-Allowed:
-
-- fix poor local naming
-- clarify a module responsibility
-- move a small amount of code to improve readability
-
-Not allowed:
-
-- redesign a subsystem
-- move files in bulk
-- change architectural boundaries without a request
-
-## Good Practices
-
-- before making a change, state which exact task requirement the change covers
-- limit the diff to files that actually participate in the task
-- check whether the change affects behavior outside the required scenario
-
-## Environment Issues
-
-Environment issues are not a reason to change project code.
-
-If validation cannot run because of missing tools, permissions, cache, shell utilities, or container limitations, stop, describe the problem, and ask for a decision.
-
-Using a local temporary cache/workdir is allowed only if it does not change the project and does not expand the task scope.

package/docs/policy/comment-policy.md

@@ -1,253 +0,0 @@
-# Comment Policy
-
-> Type: Policy. This document defines rules for writing comments in production code.
-
-## Purpose
-
-Comments must explain a module role, responsibility boundaries, invariants, and reasons for non-obvious decisions.
-
-A comment must not duplicate code, retell obvious mechanics, or replace clear names for functions, types, and variables.
-
-The main question a comment must answer is:
-
-> Why does this decision exist in this form?
-
-Not:
-
-> What does this line do?
-
-## Basic Rules
-
-1. In each production module that participates in runtime, defines a layer contract, or contains non-trivial responsibility, one top architectural block is allowed.
-2. The top architectural block must describe the file role, allowed responsibility, module boundaries, and foreign responsibility that must not be moved into this file.
-3. Local comments are allowed only where the reason for a decision, invariant, or constraint would be lost without them.
-4. Obvious code actions do not need comments.
-5. JSDoc for public contracts must be short and specific.
-6. Within one file, comment style and language must be consistent.
-7. A comment must explain "why" or "for what purpose", not retell "what the line does".
-8. A comment must not expand the code contract. If a comment mentions a guarantee, invariant, execution order, safety, or constraint, it must be backed by code, types, or tests.
-9. Refactoring history must not be stored in comments. Git, ADRs, and design notes exist for that.
-
-## Top Architectural Block
-
-The top block describes the whole module, not individual functions.
-
-Template:
-
-```ts
-/**
- * Module <role of the file in the system>.
- *
- * Allowed here:
- * - <responsibility 1>;
- * - <responsibility 2>;
- * - <responsibility 3>;
- *
- * This file must not contain <foreign responsibility>.
- */
-```
-
-Good example:
-
-```ts
-/**
- * The runtime config resolver module transforms external input
- * into normalized launch settings.
- *
- * Allowed here:
- * - reading supported config sources;
- * - validating required fields;
- * - forming diagnostics for invalid config;
- *
- * This file must not contain CLI rendering or network calls.
- */
-```
-
-Bad example:
-
-```ts
-/**
- * Config file.
- */
-```
-
-This comment does not explain the module role, boundaries, or allowed responsibility.
-
-## Exceptions
-
-A top architectural block is not required for:
-
-- barrel export files;
-- build output;
-- test fixtures;
-- trivial files with one obvious type or constant;
-- temporary local helper files that do not define a production contract.
-
-If a file participates in production runtime, defines a layer contract, or contains non-trivial responsibility, a top block is allowed and must be meaningful.
-
-## Public Contract JSDoc
-
-JSDoc for public functions, classes, and interfaces must describe only contract-level details:
-
-- input constraints;
-- side effects;
-- errors;
-- lifecycle;
-- important guarantees;
-- external API constraints.
-
-JSDoc is not needed if the meaning is fully clear from the name, types, and code.
-
-Bad:
-
-```ts
-/**
- * Creates a client.
- */
-createClient(options);
-```
-
-Better:
-
-```ts
-/**
- * Creates a runtime client from already validated options.
- *
- * The function does not read environment and does not change global state.
- */
-createClient(options);
-```
-
-But if this is already obvious from the interface and tests, it is better not to add the comment.
-
-## When A Comment Is Needed
-
-A comment is needed if it explains:
-
-- module role;
-- layer boundary;
-- non-obvious invariant;
-- workaround;
-- external API constraint;
-- reason for an unusual branch;
-- reason for cleanup logic;
-- preservation of compatibility with an old contract;
-- an intentionally empty branch when absence of action is part of the logic;
-- placeholder / TODO with an explanation of why implementation is absent for now;
-- reason why a dependency is allowed exactly here.
-
-Good:
-
-```ts
-// CLI config has priority over file config:
-// this is an observable command contract, not a merge order detail.
-const options = mergeConfig(fileConfig, cliConfig);
-```
-
-Good:
-
-```ts
-// The first request is not delayed:
-// the rate limit constrains the interval between subsequent calls.
-if (lastRequestTime === undefined) {
-  lastRequestTime = now;
-  return;
-}
-```
-
-## When A Comment Is Not Needed
-
-A comment is not needed if:
-
-- the meaning is already clear from the function name, type, and code;
-- the comment repeats the line literally;
-- the comment describes trivial mechanics;
-- the comment explains language syntax;
-- the comment becomes outdated faster than the code itself;
-- the comment stores change history instead of the current reason for the decision.
-
-Bad:
-
-```ts
-// Create options
-const options = resolveOptions(input);
-```
-
-Bad:
-
-```ts
-// Check if path exists
-if (fs.existsSync(file)) {
-  return file;
-}
-```
-
-## TODO And Placeholder
-
-A TODO is allowed only if it explains:
-
-- why implementation is deferred;
-- which constraint is currently in effect;
-- under which condition this place must be revisited.
-
-Good:
-
-```ts
-// TODO: streaming mode requires an owner decision on public API shape.
-// Revisit after supported options are approved.
-```
-
-Bad:
-
-```ts
-// TODO: fix later
-```
-
-If a module or branch is intentionally empty, this must be stated explicitly.
-
-## Workaround Comments
-
-A workaround must explain the external constraint, not just describe the workaround.
-
-Good:
-
-```ts
-// External API returns an empty string instead of a missing value:
-// normalize it here so the domain layer works only with undefined.
-const value = rawValue === '' ? undefined : rawValue;
-```
-
-Bad:
-
-```ts
-// Normalize value
-const value = rawValue === '' ? undefined : rawValue;
-```
-
-## Comments And Architectural Boundaries
-
-A comment is useful when it protects a layer boundary.
-
-Good:
-
-```ts
-/**
- * CLI entrypoint only transforms argv into command input.
- *
- * This file must not contain domain behavior, persistence, or network orchestration.
- */
-```
-
-This block helps avoid mixing bootstrap and runtime behavior.
-
-## Good Comment Criterion
-
-A good comment helps understand:
-
-- why the module exists;
-- where its boundaries are;
-- which invariant must not be violated;
-- which external constraint affected the code;
-- why an obviously strange decision is actually intentional.
-
-If a comment can be deleted without losing meaning, it should be deleted.