Restore fresh install, harden CI, fix doc drift and audit findings

.github/workflows/tests.yml

@@ -5,6 +5,9 @@ on:
     branches: [1.x]
   pull_request:
     branches: [1.x]
+  schedule:
+    - cron: '0 3 * * 1'
+  workflow_dispatch:
 
 jobs:
   tests:

.gitignore

@@ -1,3 +1,4 @@
 vendor/
 .phpunit.cache/
 composer.lock
+demos/*/var/log/semantic-dev-*.json

CLAUDE.md

@@ -84,22 +84,26 @@ will not run under Ray.Di or will break framework expectations.
 5. **Moments**: implement `MomentInterface`; create the Potential object in
    the constructor; commit it in `be()`. Do NOT call `be()` from the
    constructor. The owning Final calls `be()` on its Moments during self-
-   completion.
+   completion. Exception: a **pure-data Moment** (a part of the whole that
+   carries no Potential and performs no side effect) MAY omit
+   `MomentInterface` and `be()` entirely — state this explicitly in the
+   class docblock (see `demos/insurance-claim/src/Moment/FraudCleared.php`).
 6. **Finals that converge Moments**: take each Moment via `#[Inject]` and call
    `$this->foo->be()` in the constructor body, then derive the actualized
    fields. See `demos/order-processing/src/Final/OrderConfirmed.php` for the
    canonical shape.
 7. **Semantic validators**: one class per concept, one `#[Validate]` method,
    throw a domain exception from `src/Exception/`. Link to schema.org in the
    docblock when a standard term exists (`@link https://schema.org/…`).
-8. **Reason services**: Reasons sitting at an **external I/O boundary**
-   (HTTP, DB, payment gateway, third-party API, filesystem, clock, randomness)
+8. **Reason services**: Reasons that model an **external system**
+   (HTTP, DB, payment gateway, credit bureau, third-party API, filesystem)
    MUST define an `…Interface`; consumers depend on the interface and Ray.Di
    binds the implementation — so tests can swap in a Fake. Reasons that are
-   **pure in-process policies or calculators** (rule-book classes with no
-   I/O) MAY be injected as concrete classes; no interface is required.
-   Examples: `PaymentGatewayInterface` and `CreditBureauInterface` (boundary);
-   `IncomePolicy` and `JTASProtocol` (pure policy).
+   **in-process policies, calculators, or generators** (rule-book classes,
+   ID/token/timestamp generators with no out-of-process dependency) MAY be
+   injected as concrete classes; no interface is required.
+   Examples: `PaymentGatewayInterface` and `CreditBureauInterface` (external
+   system); `IncomePolicy`, `JTASProtocol`, and `UserIdGenerator` (in-process).
 9. **Namespaces**: follow the existing per-demo pattern
    `Be\Pattern\<Name>\<Layer>\…`. Never invent a new root namespace.
 10. **No side effects in Beings.** A Being transforms data; external I/O
@@ -133,9 +137,15 @@ a real demo (replace `Template` with the actual demo name).
 
 ## 6. Running tests
 
+Each demo is a standalone Composer project — there is no root `composer.json`.
+Install dependencies and run PHPUnit inside the demo directory:
+
 ```bash
-composer test                                     # all demos
-./demos/vendor/bin/phpunit demos/medical-triage/tests/   # one demo
+# one demo
+cd demos/medical-triage && composer install && ./vendor/bin/phpunit
+
+# all demos
+for d in demos/*/; do (cd "$d" && composer install -q && ./vendor/bin/phpunit); done
 ```
 
 If you modify a demo, always run its tests before concluding the task.

README.ja.md

@@ -152,7 +152,7 @@ flowchart LR
     M3([Moment]) -.-> F1 & F2
 ```
 
-保険請求処理デモ。`ClaimInput` と `PolicyInput` はどちらも `#[Be([ClaimSettled, ClaimEscalated])]` を宣言しており、`$being` の型マッチングによって各 Input がちょうど1つの Final に解決されます。`DamageValued`、`AdjustmentReviewed`、`FraudCleared` などの Moment は両方の Final に注入されるため、どちらの分岐を辿っても同じ自己完結ロジックが共有されます。
+保険請求処理デモ。`ClaimInput` と `PolicyInput` はどちらも `#[Be([ClaimSettled, ClaimEscalated])]` を宣言しており、2つの Final を可能な帰結として名指しします。`DamageValued`、`AdjustmentReviewed`、`FraudCleared` などの Moment は両方の Final に注入されるため、どちらの分岐を辿っても同じ自己完結ロジックが共有されます。
 
 > 具体: `ClaimInput` + `PolicyInput` → `ClaimSettled` または `ClaimEscalated`（各 Final に共有 Moment を注入）
 
@@ -179,11 +179,11 @@ flowchart LR
 cd demos/hello-world && composer install && vendor/bin/phpunit
 ```
 
-各デモには正常系統合テスト、Semantic検証単体テスト、Reasonレイヤーロジックテスト、そして該当する場合はPotential冪等性テストが含まれます。
+各デモには正常系テストとSemantic検証単体テストが含まれます。上級デモにはさらにReasonレイヤーロジックテスト、該当する場合はPotential冪等性テストが含まれます。
 
 ## 要件
 
-- PHP 8.2+
+- PHP 8.3+
 - [Ray.Di](https://ray-di.github.io/)（依存性注入）
 
 ## 背景

README.md

@@ -152,7 +152,7 @@ flowchart LR
     M3([Moment]) -.-> F1 & F2
 ```
 
-Insurance claim processing. `ClaimInput` and `PolicyInput` both declare `#[Be([ClaimSettled, ClaimEscalated])]`, so each Input resolves to exactly one of the two Finals by `$being` type matching. Moments such as `DamageValued`, `AdjustmentReviewed` and `FraudCleared` are injected into both Finals, so the same self-completion logic is shared regardless of which branch is taken.
+Insurance claim processing. `ClaimInput` and `PolicyInput` both declare `#[Be([ClaimSettled, ClaimEscalated])]`, naming the two Finals as possible outcomes. Moments such as `DamageValued`, `AdjustmentReviewed` and `FraudCleared` are injected into both Finals, so the same self-completion logic is shared regardless of which branch is taken.
 
 > Concrete: `ClaimInput` + `PolicyInput` → `ClaimSettled` | `ClaimEscalated`, with shared Moments injected into each Final.
 
@@ -179,11 +179,11 @@ See [Semantic Logging](https://be-framework.github.io/manuals/1.0/en/10-semantic
 cd demos/hello-world && composer install && vendor/bin/phpunit
 ```
 
-Every demo ships with happy-path integration tests, Semantic validation unit tests, Reason layer logic tests, and (where applicable) Potential idempotency tests.
+Every demo ships with happy-path tests and Semantic validation unit tests; the advanced demos add Reason layer logic tests and (where applicable) Potential idempotency tests.
 
 ## Requirements
 
-- PHP 8.2+
+- PHP 8.3+
 - [Ray.Di](https://ray-di.github.io/) (dependency injection)
 
 ## Background

demos/blog-publishing/composer.json

@@ -1,6 +1,7 @@
 {
     "name": "be-framework/demo-blog-publishing",
-    "description": "Be Framework Blog Publishing Demo - Moment without Potential (pure data Moment) and mini-diamond merge",
+    "description": "Be Framework Blog Publishing Demo - Multi-Reason Being orchestrating several Reason services",
+    "license": "MIT",
     "type": "project",
     "autoload": {
         "psr-4": {
@@ -19,7 +20,8 @@
     },
     "require-dev": {
         "be-framework/psalm-plugin": "1.x-dev",
-        "phpunit/phpunit": "^12"
+        "phpunit/phpunit": "^12",
+        "vimeo/psalm": "^7.0@beta"
     },
     "scripts": {
         "psalm": "psalm --show-info=false",

demos/blog-publishing/src/Moment/MetadataResolved.php

@@ -26,9 +26,9 @@
     public string $slug;
 
     public function __construct(
-        #[Inject] SlugGenerated $slugGenerated,
         #[Input] public string $authorId,
         #[Input] public array $tags,
+        #[Inject] SlugGenerated $slugGenerated,
         #[Inject] AuthorResolverInterface $resolver,
     ) {
         $this->slug = $slugGenerated->slug;

demos/blog-publishing/tests/BlogPublishingTest.php

@@ -11,10 +11,10 @@
 use Be\Pattern\BlogPublishing\Final\ArticlePublished;
 use Be\Pattern\BlogPublishing\Input\ArticleInput;
 use Be\Pattern\BlogPublishing\Module\AppModule;
-use Be\Pattern\BlogPublishing\Semantic\ArticleTitle;
 use Be\Pattern\BlogPublishing\Semantic\AuthorId;
 use Be\Pattern\BlogPublishing\Semantic\MarkdownBody;
-use Be\Pattern\BlogPublishing\Semantic\Tag;
+use Be\Pattern\BlogPublishing\Semantic\Tags;
+use Be\Pattern\BlogPublishing\Semantic\Title;
 use Be\Framework\Becoming;
 use PHPUnit\Framework\TestCase;
 use Ray\Di\Injector;
@@ -102,24 +102,24 @@ public function testExcerptIsTruncated(): void
     // Semantic Validation Tests
     // ──────────────────────────────────────────────
 
-    public function testValidArticleTitle(): void
+    public function testValidTitle(): void
     {
-        $semantic = new ArticleTitle();
+        $semantic = new Title();
         $semantic->validate('Understanding the BE Framework');
         $this->addToAssertionCount(1);
     }
 
     public function testEmptyTitleThrowsException(): void
     {
         $this->expectException(InvalidTitleException::class);
-        $semantic = new ArticleTitle();
+        $semantic = new Title();
         $semantic->validate('');
     }
 
     public function testTitleTooLongThrowsException(): void
     {
         $this->expectException(InvalidTitleException::class);
-        $semantic = new ArticleTitle();
+        $semantic = new Title();
         $semantic->validate(str_repeat('a', 201));
     }
 
@@ -158,24 +158,31 @@ public function testInvalidAuthorIdThrowsException(): void
         $semantic->validate('not-a-valid-uuid');
     }
 
-    public function testValidTag(): void
+    public function testValidTags(): void
     {
-        $semantic = new Tag();
-        $semantic->validate('philosophy');
+        $semantic = new Tags();
+        $semantic->validate(['philosophy', 'framework', 'php']);
         $this->addToAssertionCount(1);
     }
 
+    public function testEmptyTagsThrowsException(): void
+    {
+        $this->expectException(InvalidTagException::class);
+        $semantic = new Tags();
+        $semantic->validate([]);
+    }
+
     public function testInvalidTagFormatThrowsException(): void
     {
         $this->expectException(InvalidTagException::class);
-        $semantic = new Tag();
-        $semantic->validate('INVALID_TAG');
+        $semantic = new Tags();
+        $semantic->validate(['INVALID_TAG']);
     }
 
     public function testTagTooLongThrowsException(): void
     {
         $this->expectException(InvalidTagException::class);
-        $semantic = new Tag();
-        $semantic->validate(str_repeat('a', 31));
+        $semantic = new Tags();
+        $semantic->validate([str_repeat('a', 31)]);
     }
 }

demos/contact-form/composer.json

@@ -1,6 +1,7 @@
 {
     "name": "be-framework/demo-contact-form",
     "description": "Be Framework Contact Form Demo - Semantic validation and Being transformation",
+    "license": "MIT",
     "type": "project",
     "autoload": {
         "psr-4": {
@@ -19,7 +20,8 @@
     },
     "require-dev": {
         "be-framework/psalm-plugin": "1.x-dev",
-        "phpunit/phpunit": "^12"
+        "phpunit/phpunit": "^12",
+        "vimeo/psalm": "^7.0@beta"
     },
     "scripts": {
         "psalm": "psalm --show-info=false",

demos/hello-world/composer.json

@@ -1,6 +1,7 @@
 {
     "name": "be-framework/demo-hello-world",
     "description": "Be Framework Hello World Demo - The simplest transformation",
+    "license": "MIT",
     "type": "project",
     "autoload": {
         "psr-4": {
@@ -19,7 +20,8 @@
     },
     "require-dev": {
         "be-framework/psalm-plugin": "1.x-dev",
-        "phpunit/phpunit": "^12"
+        "phpunit/phpunit": "^12",
+        "vimeo/psalm": "^7.0@beta"
     },
     "scripts": {
         "dev": "php bin/be.php 'hello?name=World'",

demos/hello-world/tests/HelloTest.php

@@ -4,10 +4,13 @@
 
 namespace Be\Pattern\Hello\Tests;
 
+use Be\Pattern\Hello\Exception\InvalidNameException;
 use Be\Pattern\Hello\Final\Hello;
 use Be\Pattern\Hello\Input\HelloInput;
 use Be\Pattern\Hello\Module\AppModule;
+use Be\Pattern\Hello\Semantic\Name;
 use Be\Framework\Becoming;
+use Be\Framework\Exception\SemanticVariableException;
 use PHPUnit\Framework\TestCase;
 use Ray\Di\Injector;
 
@@ -41,4 +44,25 @@ public function testHelloWithDifferentName(): void
 
         $this->assertSame('Hello Be Framework', $final->greeting);
     }
+
+    public function testBecomingFlowRejectsEmptyName(): void
+    {
+        $this->expectException(SemanticVariableException::class);
+
+        ($this->becoming)(new HelloInput(name: '   '));
+    }
+
+    public function testValidName(): void
+    {
+        $semantic = new Name();
+        $semantic->validate('World');
+        $this->addToAssertionCount(1);
+    }
+
+    public function testEmptyNameThrowsException(): void
+    {
+        $this->expectException(InvalidNameException::class);
+        $semantic = new Name();
+        $semantic->validate('');
+    }
 }

demos/insurance-claim/README.md

@@ -73,7 +73,7 @@ the order-processing demo.
 | **Moment** | `DamageValued`, `AdjustmentReviewed`, `FraudCleared`, `PaymentDispatched`, `EscalationQueued` |
 | **Potential** | `DamageValuation`, `PaymentExecution` |
 | **Final**  | `ClaimSettled`, `ClaimEscalated` |
-| **Semantic** | `PolicyNumber`, `IncidentDate`, `IncidentType`, `ClaimAmount`, `CoverageType`, `ClaimantId` |
+| **Semantic** | `PolicyNumber`, `IncidentDate`, `IncidentType`, `EstimatedAmount`, `CoverageType`, `ClaimantId` |
 | **Reason** | `ClaimRegistrar`, `PolicyRegistry`, `CoverageValidator`, `DamageAppraiser`, `AdjusterAllocator`, `FraudDetector`, `PaymentProcessor`, `SettlementPolicy` |
 | **Exception** | `InvalidPolicyNumberException`, `InvalidIncidentDateException`, `InvalidIncidentTypeException`, `InvalidClaimAmountException`, `InvalidCoverageTypeException`, `InvalidClaimantIdException` |
 

demos/insurance-claim/composer.json

@@ -1,5 +1,7 @@
 {
     "name": "be-framework/demo-insurance-claim",
+    "description": "Be Framework Insurance Claim Demo - Complex convergence with shared Moments across branching Finals",
+    "license": "MIT",
     "type": "project",
     "autoload": {
         "psr-4": {
@@ -18,7 +20,8 @@
     },
     "require-dev": {
         "be-framework/psalm-plugin": "1.x-dev",
-        "phpunit/phpunit": "^12"
+        "phpunit/phpunit": "^12",
+        "vimeo/psalm": "^7.0@beta"
     },
     "scripts": {
         "psalm": "psalm --show-info=false",