ai-forge-cli 2.1.12__tar.gz → 2.1.13__tar.gz

{ai_forge_cli-2.1.12/src/ai_forge_cli.egg-info → ai_forge_cli-2.1.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-forge-cli
-Version: 2.1.12
+Version: 2.1.13
 Summary: Forge V3 context CLI
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{ai_forge_cli-2.1.12 → ai_forge_cli-2.1.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-forge-cli"
-version = "2.1.12"
+version = "2.1.13"
 description = "Forge V3 context CLI"
 readme = "README.md"
 requires-python = ">=3.11"

{ai_forge_cli-2.1.12 → ai_forge_cli-2.1.13/src/ai_forge_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-forge-cli
-Version: 2.1.12
+Version: 2.1.13
 Summary: Forge V3 context CLI
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{ai_forge_cli-2.1.12 → ai_forge_cli-2.1.13}/src/cli/commands/audit.py

@@ -832,7 +832,7 @@ def _flow_panel(
         branches = step.get("branches", [])
         branch_html = ""
         if branches:
-            branch_html = _branch_list(branches)
+            branch_html = _branch_list(branches, expand_outgoing=not include_component)
         subject = ""
         if include_container and step.get("container"):
             subject = (
@@ -843,7 +843,7 @@ def _flow_panel(
             subject = f"<p class='flow-step-meta'>Component: {escape(step['component'])}</p>"
         description = _flow_description(step.get("description", ""))
         outgoing = str(step.get("outgoing", "")).strip()
-        outgoing_html = _outgoing_html(outgoing)
+        outgoing_html = _outgoing_html(outgoing, expand=not include_component)
         steps_html.append(
             f"<div class='flow-step'><h4>Step {step.get('id')}</h4>{subject}{description}"
             f"{outgoing_html}{branch_html}</div>"
@@ -874,13 +874,13 @@ def _flow_description(value: object) -> str:
     return f"<p>{escape(str(value))}</p>"
 
 
-def _branch_list(branches: object) -> str:
+def _branch_list(branches: object, *, expand_outgoing: bool = True) -> str:
     branch_items = []
     for branch in branches:
         if not isinstance(branch, dict):
             continue
         outgoing = str(branch.get("outgoing", "")).strip()
-        outgoing_html = _outgoing_html(outgoing)
+        outgoing_html = _outgoing_html(outgoing, expand=expand_outgoing)
         branch_items.append(
             f"<li><strong>{escape(str(branch.get('condition', 'Condition')))}</strong>"
             f"{outgoing_html}</li>"
@@ -888,9 +888,14 @@ def _branch_list(branches: object) -> str:
     return "<ul class='branch-list'>" + "".join(branch_items) + "</ul>"
 
 
-def _outgoing_html(value: str) -> str:
+def _outgoing_html(value: str, *, expand: bool = True) -> str:
     if not value:
         return ""
+    if not expand and _is_shape_like_text(value):
+        return (
+            "<div class='footer-note'>Outgoing</div>"
+            f'<div class="schema-viewer"><pre>{escape(_format_shape_like_text(value))}</pre></div>'
+        )
     if _is_shape_like_text(value):
         return _payload_details("Outgoing Payload", value)
     return f"<div class='footer-note'>Outgoing: {escape(value)}</div>"

{ai_forge_cli-2.1.12 → ai_forge_cli-2.1.13}/src/cli/resources/FRAMEWORK_V3.md

@@ -21,6 +21,17 @@ The framework should move from broad truth to narrow implementation:
 7. review and secure that vertical before implementation starts
 8. build and validate that vertical end to end
 
+## LLM Work Discipline
+
+When an LLM is authoring, reviewing, or building with Forge:
+
+- State assumptions and tradeoffs before making material changes.
+- Prefer the minimum artifact, field, or code change that solves the problem.
+- Touch only the files and lines required by the current goal.
+- Do not add speculative flexibility, abstractions, or cleanup.
+- Define how success will be verified before executing multi-step work.
+- If the request or schema intent is ambiguous, stop and name the ambiguity.
+
 ## Recommended Authoring Order
 
 ### 1. System

{ai_forge_cli-2.1.12 → ai_forge_cli-2.1.13}/src/cli/resources/SCHEMA_REFERENCE_V3.md

@@ -1,5 +1,16 @@
 # Forge V2 Schema Reference
 
+## Authoring Discipline
+
+Forge schema artifacts should be minimal, explicit, and verifiable:
+
+- State assumptions instead of hiding uncertainty in invented structure.
+- Add only fields, artifacts, and flows that serve the current architectural or build goal.
+- Do not add speculative flexibility, optionality, or future-facing artifacts.
+- Keep one-off payloads inline until reuse, persistence, or system significance justifies promotion.
+- Touch the narrowest schema scope needed; do not refactor unrelated artifacts.
+- Define review or validation criteria for every non-trivial schema change.
+
 ## System
 
 Defines the highest-level truth about the system: what it is, why it exists, what is inside its boundary, who interacts with it, and which external systems it depends on.
@@ -200,6 +211,7 @@ Additional rule:
 - A step with `branches` is a decision step.
 - A step with neither is a terminal step.
 - A step with both is invalid.
+- `next` and branch targets may point to earlier steps when the flow intentionally loops.
 
 ### Example
 
@@ -575,6 +587,7 @@ Additional rule:
 - A step with `branches` is a decision step.
 - A step with neither is a terminal step.
 - A step with both is invalid.
+- `next` and branch targets may point to earlier steps when the flow intentionally loops.
 
 ### Example
 
@@ -1228,20 +1241,21 @@ container:
 
 `container.component_flows[].steps[].next`
 - Numeric id of the normal next step.
-- A step may define `next` and `outgoing`, or `branches`, but never both.
+- A step may define `next` with optional `outgoing`, or `branches`, but never both.
 - Terminal steps should omit this field.
 
 `container.component_flows[].steps[].outgoing`
-- Exact payload definition sent from this step to the next step.
+- Exact payload definition emitted by this step.
+- For a step with `next`, this is the payload sent to the next component step.
+- For a terminal step without `next` or `branches`, this is the payload emitted back to the runtime/container boundary.
 - This may include field names, nested structure, required data, and data types.
 - When the payload has been promoted into a `data_shape`, use `ref[data_shape_id]` instead of repeating the full structure inline.
-- A step may define `next` and `outgoing`, or `branches`, but never both.
-- A terminal step should omit this field.
+- A step may define `next` with optional `outgoing`, `branches`, or terminal `outgoing`, but never mix linear and branch fields.
 
 `container.component_flows[].steps[].branches`
 - Optional list of decision branches from the current step.
 - Use this when the step can lead to multiple different next steps.
-- A step may define `branches`, or `next` and `outgoing`, but never both.
+- A step may define `branches`, or `next` with optional `outgoing`, but never both.
 
 `container.component_flows[].steps[].branches[].condition`
 - Plain-language description of the condition that causes the branch.
@@ -1255,10 +1269,11 @@ container:
 - When the payload has been promoted into a `data_shape`, use `ref[data_shape_id]` instead of repeating the full structure inline.
 
 Additional rule:
-- A step with `next` and `outgoing` is a linear step.
+- A step with `next` is a linear step and may include `outgoing`.
 - A step with `branches` is a decision step.
-- A step with neither is a terminal step.
+- A step with neither `next` nor `branches` is a terminal step and may include `outgoing`.
 - A step with both linear and branch fields is invalid.
+- `next` and branch targets may point to earlier steps when the component flow intentionally loops.
 
 ### Example
 
@@ -1323,15 +1338,15 @@ container:
             },
             payment_method_token: string
           }
-        steps:
-          - id: 1
-            component: order_request_controller
-            description:
-              - Accept the order request from the storefront.
-              - Perform request-level validation checks.
-              - Pass the normalized request into the validation service.
-            next: 2
-            outgoing: >
+      steps:
+        - id: 1
+          component: order_request_controller
+          description:
+            - Accept the order request from the storefront.
+            - Perform request-level validation checks.
+            - Pass the normalized request into the validation service.
+          next: 2
+          outgoing: >
               {
                 customer_id: string,
                 line_items: [
@@ -1353,16 +1368,16 @@ container:
                 },
                 payment_method_token: string
               }
-          - id: 2
-            component: order_validation_service
-            description:
-              - Validate the business correctness of the request.
-              - Normalize order content for persistence.
-              - Decide whether the order can proceed.
-            branches:
-              - condition: Order request is valid and can be persisted.
-                next: 3
-                outgoing: >
+        - id: 2
+          component: order_validation_service
+          description:
+            - Validate the business correctness of the request.
+            - Normalize order content for persistence.
+            - Decide whether the order can proceed.
+          branches:
+            - condition: Order request is valid and can be persisted.
+              next: 3
+              outgoing: >
                   {
                     customer_id: string,
                     line_items: [
@@ -1385,31 +1400,31 @@ container:
                     payment_method_token: string,
                     order_status: pending_payment
                   }
-              - condition: Order request is invalid and cannot proceed.
-                next: 5
-                outgoing: ref[order_rejection_response]
-          - id: 3
-            component: order_repository
-            description: Persist the order and return the stored record for payment processing.
-            next: 4
-            outgoing: ref[order_record]
-          - id: 4
-            component: payment_service
-            description:
-              - Request payment authorization for the persisted order.
-              - Determine whether the order can be confirmed.
-            branches:
-              - condition: Payment is authorized successfully.
-                next: 5
-                outgoing: ref[order_confirmation_response]
-              - condition: Payment authorization fails.
-                next: 5
-                outgoing: ref[order_rejection_response]
-          - id: 5
-            component: order_response_mapper
-            description:
-              - Build the customer-facing response payload.
-              - Return the final result to the calling container boundary.
+            - condition: Order request is invalid and cannot proceed.
+              next: 5
+              outgoing: ref[order_rejection_response]
+        - id: 3
+          component: order_repository
+          description: Persist the order and return the stored record for payment processing.
+          next: 4
+          outgoing: ref[order_record]
+        - id: 4
+          component: payment_service
+          description:
+            - Request payment authorization for the persisted order.
+            - Determine whether the order can be confirmed.
+          branches:
+            - condition: Payment is authorized successfully.
+              next: 5
+              outgoing: ref[order_confirmation_response]
+            - condition: Payment authorization fails.
+              next: 5
+              outgoing: ref[order_rejection_response]
+        - id: 5
+          component: order_response_mapper
+          description:
+            - Build the customer-facing response payload.
+            - Return the final result to the calling container boundary.
 ```
 
 ## Deployment

{ai_forge_cli-2.1.12 → ai_forge_cli-2.1.13}/src/cli/resources/skills/forge-build/SKILL.md

@@ -111,6 +111,19 @@ The plan should identify:
 
 Build mode should execute the approved plan incrementally.
 
+### LLM Build Guardrails
+
+Apply these safeguards before and during implementation:
+
+1. State the current increment goal and how it will be verified.
+2. Implement the minimum code needed for that increment; do not add speculative features or abstractions.
+3. Keep edits surgical and aligned with the approved schema, plan, and local code style.
+4. Do not clean up unrelated code; mention unrelated issues separately.
+5. Write or update focused tests before declaring behavior complete.
+6. If the schema, plan, and code disagree, stop and resolve the mismatch instead of coding around it.
+7. State assumptions or ambiguity before implementing when the approved plan does not fully determine behavior.
+8. Remove only dead code, imports, or variables created by the current change unless explicitly asked otherwise.
+
 ### Build Workflow
 
 For each increment:

{ai_forge_cli-2.1.12 → ai_forge_cli-2.1.13}/src/cli/resources/skills/forge-review/SKILL.md

@@ -91,6 +91,18 @@ Review only one artifact class when the user asks for a narrower pass.
 
 If a fix would require inventing new architecture rather than correcting drift, route back to `forge-schema` instead of improvising in review.
 
+## LLM Review Guardrails
+
+Apply these safeguards during every review:
+
+1. Findings must be grounded in a schema rule, artifact line, broken reference, or concrete behavioral risk.
+2. Do not invent fixes that require new architecture; identify the smallest correction direction.
+3. Do not flag personal style preferences as findings.
+4. Do not broaden review scope unless the current artifact cannot be evaluated without it.
+5. If evidence is ambiguous, state the assumption or ask for clarification instead of declaring a defect.
+6. Do not propose speculative flexibility or future-facing artifacts as review fixes.
+7. Every recommendation should be verifiable by a schema edit, review pass, or test.
+
 ## Review Passes
 
 Run these passes in order.
@@ -129,14 +141,15 @@ Check:
    - decision step: `branches`
    - terminal step: neither
 2. A runtime-aware or component flow uses only:
-   - linear step: `next` plus `outgoing`
+   - linear step: `next` with optional `outgoing`
    - decision step: `branches`
-   - terminal step: neither
+   - terminal step: neither, or terminal `outgoing` for component-flow boundary output
 3. No flow step mixes linear and branch forms.
 4. Runtime-aware steps represent one container participation each.
 5. Component-flow steps represent one component participation each.
-6. A container may retain in-flight workflow-scoped state across its own runtime steps when it is clearly the orchestrator of the slice.
-7. Do not assume that a later step only knows the immediately preceding boundary payload when the same container is plausibly coordinating the broader workflow.
+6. `next` or branch targets may point to earlier steps when the loop is intentional.
+7. A container may retain in-flight workflow-scoped state across its own runtime steps when it is clearly the orchestrator of the slice.
+8. Do not assume that a later step only knows the immediately preceding boundary payload when the same container is plausibly coordinating the broader workflow.
 
 For orchestrated runtime flows:
 

{ai_forge_cli-2.1.12 → ai_forge_cli-2.1.13}/src/cli/resources/skills/forge-schema/SKILL.md

@@ -49,6 +49,17 @@ Follow these rules throughout:
 8. Ask follow-up questions only when ambiguity blocks the next drafting step.
 9. Log every meaningful decision as soon as it is made.
 
+## LLM Guardrails
+
+Apply these safeguards before changing schema artifacts:
+
+1. State assumptions and unresolved ambiguity before drafting.
+2. Choose the simplest valid schema representation; do not add optional fields, artifacts, or promotion just for neatness.
+3. Make surgical edits to the current stage or vertical only.
+4. Every changed line should trace to a user decision, a schema rule, or a validation finding.
+5. For non-trivial changes, define the review check that will prove the schema is better.
+6. If two schema interpretations are plausible, present the tradeoff instead of silently choosing.
+
 ## Decision Notes Rule
 
 Maintain a markdown file named:
@@ -364,10 +375,11 @@ Run these checks before leaving each stage and again at the end of the skill.
 2. `runtime_flow` uses container-level steps only.
 3. `container` uses component-level steps only.
 4. A flow step is either:
-   - linear: `next` plus `outgoing`
+   - linear: `next` with optional `outgoing`
    - decision: `branches`
-   - terminal: neither
+   - terminal: neither, or terminal `outgoing` for component-flow boundary output
 5. Reject steps that mix linear and branch forms.
+6. Allow `next` or branch targets to point to earlier steps when the loop is intentional.
 
 ### Promotion Checks
 

{ai_forge_cli-2.1.12 → ai_forge_cli-2.1.13}/src/cli/resources/skills/forge-security/SKILL.md

@@ -34,6 +34,16 @@ Security in Forge V2 is expressed in four places:
 
 Keep the distinction clean.
 
+## LLM Security Guardrails
+
+Apply these safeguards when adding or reviewing security content:
+
+1. State security assumptions explicitly; do not hide uncertainty behind generic language.
+2. Add only security obligations that change architecture, implementation, or verification.
+3. Keep controls at the right level: system, container, persisted shape, or deployment boundary.
+4. Avoid speculative provider detail unless the schema already commits to that provider.
+5. If a security issue needs deeper analysis, route to the relevant security reference instead of bloating Forge artifacts.
+
 ### `system.security`
 
 Use for:

{ai_forge_cli-2.1.12 → ai_forge_cli-2.1.13}/src/cli/schema.py

@@ -129,6 +129,7 @@ def _validate_schema(schema: ForgeSchema) -> None:
     _check_unique_ids(schema, errors)
     _check_cross_references(schema, errors)
     _check_container_components(schema, errors)
+    _check_component_flow_step_shapes(schema, errors)
     if errors:
         joined = "\n".join(f"- {error}" for error in errors)
         raise ValueError(f"Schema validation failed for {schema.root}:\n{joined}")
@@ -314,3 +315,22 @@ def _check_container_components(schema: ForgeSchema, errors: list[str]) -> None:
                         f"container `{container_id}` component flow `{flow_id}` step "
                         f"`{step.get('id', '?')}` references unknown component `{component_id}`."
                     )
+
+
+def _check_component_flow_step_shapes(schema: ForgeSchema, errors: list[str]) -> None:
+    for container in schema.containers:
+        container_id = container.get("id", "<unknown container>")
+        for component_flow in container.get("component_flows", []):
+            if not isinstance(component_flow, dict):
+                continue
+            flow_id = component_flow.get("id", "?")
+            for step in component_flow.get("steps", []):
+                if not isinstance(step, dict):
+                    continue
+                has_next = step.get("next") is not None
+                has_branches = bool(step.get("branches"))
+                if has_next and has_branches:
+                    errors.append(
+                        f"container `{container_id}` component flow `{flow_id}` step "
+                        f"`{step.get('id', '?')}` must not define both `next` and `branches`."
+                    )

{ai_forge_cli-2.1.12 → ai_forge_cli-2.1.13}/tests/test_context.py

@@ -250,6 +250,20 @@ def test_schema_validation_reports_broken_references(tmp_path: Path, capsys) ->
     assert "vertical `place_order` runtime_containers references unknown id `missing_orders_db`." in output
 
 
+def test_component_flow_terminal_outgoing_is_valid_and_rendered(tmp_path: Path) -> None:
+    copied_root = tmp_path / "terminal-outgoing-example"
+    shutil.copytree(EXAMPLE_ROOT, copied_root)
+
+    container_path = copied_root / "containers" / "ordering_api.yaml"
+    container_payload = yaml.safe_load(container_path.read_text(encoding="utf-8"))
+    terminal_step = container_payload["container"]["component_flows"][0]["steps"][-1]
+    terminal_step["outgoing"] = "ref[order_confirmation_response]"
+    container_path.write_text(yaml.safe_dump(container_payload, sort_keys=False), encoding="utf-8")
+
+    html = render_live_audit_html(copied_root)
+    assert "Outgoing: ref[order_confirmation_response]" in html
+
+
 def test_live_audit_rerenders_from_current_schema(tmp_path: Path) -> None:
     copied_root = tmp_path / "example"
     shutil.copytree(EXAMPLE_ROOT, copied_root)