docs(ci): documenter la regle fail-fast et le pilotage BCASL

Author: raidos23

docs/ci_cd_ark_cli.md

@@ -24,6 +24,15 @@ python3 /path/to/PyCompiler_ARK/pycompiler_ark.py
 
 ## Minimal Pipeline (copy/paste)
 
+If you use the project wrapper script, prefer CLI flags over environment variables:
+
+```bash
+./ci_cd_ark.sh --workspace /path/to/workspace --engine pyinstaller --no-bcasl
+./ci_cd_ark.sh --workspace /path/to/workspace --engine pyinstaller --with-bcasl --bcasl-timeout 120
+```
+
+Direct ARK CLI flow:
+
 ```bash
 ARK_BIN="python3 /path/to/PyCompiler_ARK/pycompiler_ark.py"
 WORKSPACE_DIR="/path/to/workspace"
@@ -48,6 +57,9 @@ PY
 )"
 ENTRYPOINT_FILE="$WORKSPACE_DIR/$ENTRYPOINT_REL"
 
+# Optional BCASL stage (enable explicitly when required)
+# $ARK_BIN bcasl run "$WORKSPACE_DIR" --timeout 120 > "$WORKSPACE_DIR/.ark_bcasl_run.log"
+
 $ARK_BIN engine info "$ENGINE_ID" --workspace "$WORKSPACE_DIR" --json > "$WORKSPACE_DIR/.ark_engine_info.json"
 if ! $ARK_BIN engine compile "$ENGINE_ID" "$ENTRYPOINT_FILE" --workspace "$WORKSPACE_DIR" --json > "$WORKSPACE_DIR/.ark_build_result.json"; then
   WORKSPACE_DIR="$WORKSPACE_DIR" python3 - <<'PY'
@@ -83,6 +95,10 @@ $ARK_BIN workspace entrypoint-clear "$WORKSPACE_DIR" --json
   - CI/CD gate
   - exits non-zero when precheck fails
 
+- `bcasl run` (optional)
+  - include BCASL plugin execution in pipeline when needed
+  - recommended through wrapper flags: `--with-bcasl` / `--no-bcasl`
+
 - `engine compile`
   - compiles the resolved entrypoint with the selected engine
   - returns non-zero on build failure, even in `--json` mode (pipeline-friendly)
@@ -91,6 +107,14 @@ $ARK_BIN workspace entrypoint-clear "$WORKSPACE_DIR" --json
 - `venv status/use-system/use-venv/install-req`
   - lets CI enforce workspace Python mode and requirements installation policy
 
+## Fail-fast Rule
+
+CI/CD flow should be fail-fast:
+
+- if one stage fails, stop the pipeline immediately
+- do not continue to later stages (for example, do not compile after a BCASL failure)
+- mark non-executed stages as skipped in the final summary
+
 ## System Tool Auto-install Policy (CI Security)
 
 When `ARK_AUTO_INSTALL_SYSTEM_TOOLS=1` is set, ARK can attempt to install missing
@@ -243,6 +267,8 @@ from pathlib import Path
 ws = Path(os.environ["WORKSPACE_DIR"])
 reports = [
     ("workspace-apply", ws / ".ark_workspace_apply.json", lambda d: bool(d.get("ok"))),
+    # Optional BCASL report generated by your wrapper script when enabled
+    ("bcasl-run", ws / ".ark_bcasl_run.json", lambda d: bool(d.get("ok"))),
     ("check", ws / ".ark_check.json", lambda d: bool(d.get("ok"))),
     ("engine-info", ws / ".ark_engine_info.json", lambda d: bool(d.get("found", True))),
     ("compile", ws / ".ark_build_result.json", lambda d: bool(d.get("success"))),