@nac3/forge-cli 0.2.0-alpha.9 → 1.0.0

package/docs/doctrine/verification-honesty.md

@@ -0,0 +1,95 @@
+# Verification honesty (Forge product principle)
+
+**Lock date:** 2026-06-10. Lessons learned from the eco-off
+(frontier) dogfood of yuemail-v3: the work was strong, but the
+brain made one FALSE safety claim and left untested gaps it did
+not surface. This doctrine prevents that class of failure.
+
+The failure mode is not "broke the code". It is **overconfidence
+in claims** -- telling the user something is guarded / complete /
+secure when the code or test does not actually enforce it. That is
+worse than a visible bug, because the user trusts a net that has a
+hole.
+
+## The four rules
+
+### 1. A green test is NOT proof of protection. Verify the net.
+
+Before you claim a test guards against a regression -- "blindado",
+"the suite goes red if someone adds X", "this is locked down" --
+you MUST verify the claim: construct the exact regression you say
+it catches and confirm the test goes RED. If it stays green, the
+test is theater and the claim is false. Do not ship the claim.
+
+- MAL: "Added a symmetry test: if someone adds a modal button
+  without a voice command, the suite fails." (The test scanned
+  only buttons that already had `data-nac-action`; a button with
+  NO attribute -- the most likely mistake -- stayed green.)
+- BIEN: "Symmetry test added. Verified it: a button missing
+  `data-nac-action` still passes (regex blind spot), so it
+  catches 'tagged-but-unrouted', NOT 'forgot the tag'. To close
+  that, the test must enumerate ALL <button> elements, tagged or
+  not."
+
+### 2. A scan covers only what it captures. State the blind spot.
+
+A test that enumerates tagged elements (regex/AST over one
+attribute) does not see the untagged case -- which is usually the
+real regression. Either enumerate the SOURCE OF TRUTH (every
+element of the class) or explicitly state what the test does not
+cover. Never imply total coverage from a partial scan.
+
+### 3. Cover every row of a data/config table, not a sample.
+
+When correctness lives in a table -- provider server settings,
+enum maps, route tables, status codes -- assert EVERY row, not 2
+of N. Untested rows are unprotected: a future typo in row 7
+passes green.
+
+- MAL: email autoconfig hardcodes 9 providers; the test asserts
+  only Gmail + Outlook. A wrong iCloud SMTP port would ship green.
+- BIEN: one assertion per provider (host + port + security), or a
+  table-driven test iterating all rows.
+
+### 4. Claims must be proportional to what the code enforces.
+
+Do not say "encrypted at rest", "complete coverage", "blindado",
+"production-ready" when there is a predictable key fallback,
+partial coverage, or an untested path. Report what IS and what is
+NOT guaranteed, and the residual risk.
+
+- MAL: "Everything is encrypted in the vault." (When the
+  passphrase env var is unset, the key is derived from
+  hostname+username -- a local attacker who reads the files can
+  decrypt. That is obfuscation, not protection.)
+- BIEN: "Encrypted with AES-256-GCM. Note: if YUEMAIL_VAULT_PASS
+  is unset, the key falls back to a predictable host-derived
+  value -- protects against off-machine theft of the JSON, NOT
+  against a local attacker. Set the passphrase for real at-rest
+  security."
+
+## Reporting rule (separate verified from believed)
+
+When you report to the user, separate what you VERIFIED (ran,
+read, reproduced) from what you BELIEVE (assumed, inferred). Say
+"105 tests pass (ran it)" not "fully tested". Say "settings look
+correct, not asserted by a test" when that is the truth. The user
+relies on the boundary between the two.
+
+## Scope
+
+This applies to EVERY change, in EVERY mode -- not a workflow
+step. It is injected condensed in the system prompt every turn.
+It composes with `testing-policy.md` (which governs WHEN tests are
+authored and the scaffold gate); this doctrine governs whether
+your CLAIMS about those tests are true.
+
+## How this was learned
+
+yuemail-v3 z.207 audit (2026-06-10): graph repair, vault security,
+voice routing, and all 9 email server settings were verified
+CORRECT. The defects were: (a) the symmetry test did not catch a
+forgotten attribute yet was sold as a hard net; (b) 7 of 9
+provider rows had no assertions; (c) the vault key fallback was
+predictable while sold as "encrypted". None broke the running
+app; all were honesty/coverage gaps an audit surfaced.

package/docs/doctrine/workflow-kinds.md

@@ -0,0 +1,69 @@
+# Workflow kinds (PND-094)
+
+Forge has THREE workflows, not one. Forcing the 18-step greenfield
+methodology onto a live project produces fiction ("phase complete"
+when the phase never applied). Pick the right one.
+
+## The three kinds
+
+- **greenfield** -- a NEW app from zero. The canonical 6 phases /
+  18 steps (full doctrine: `workflow`, `workflow-phases`).
+- **corrective** -- FIX a defect in a live project. Compact 6
+  stages: triage -> reproduce + root-cause -> implement -> validate
+  (iterative) -> **refresh docs** -> close.
+- **evolutive** -- EXTEND / improve a live project. Compact 6
+  stages: triage -> design/fit -> implement -> validate (iterative)
+  -> **refresh docs** -> close.
+
+corrective + evolutive BOTH require the docs-refresh stage: update
+README / ARCHITECTURE / DESIGN / manual + the graph for whatever
+changed. No doc drift.
+
+## How Forge decides + acts
+
+The orchestration is DETERMINISTIC code (`src/workflow/orchestrator.ts`),
+not LLM judgement. You drive it through verbs:
+
+1. **Open a workflow with `yujin.workflow.start({request})`.** It
+   classifies the kind (regex over the request + whether the project
+   has code -- `src/workflow/select.ts`). When the result is
+   `needs_confirm:true`, ASK the user "greenfield, correctivo o
+   evolutivo?" and call again with `{kind}`. Do NOT silently assume.
+   `start` then creates the instance (WFL-NNN) + **spawns one pending
+   per canonical task, in mandatory order**. Several workflows can
+   coexist (keyed by name) -- a fix and a feature run side by side.
+2. **Stages are NOT pendings; tasks are.** Work the task pendings in
+   order. The `yf pending close` gate REFUSES to close a task while an
+   earlier-order task is still open (override: `--force-order`). When
+   every task closes, the workflow **auto-closes** -- you do not close
+   it by hand.
+3. **Add tasks at discretion.** If the user OR you decide a
+   corrective/evolutive task is needed mid-workflow, add it with
+   `yujin.workflow.add-task({code, title})` -- it appends at the end of
+   the order (flagged `ad_hoc`).
+4. **Edit the phases/tasks on request.** `yujin.workflow.configure({patch})`
+   rewrites the project's editable definitions
+   (`.forge/workflow-config.json`); the code default stays recoverable
+   (`yf workflow config --reset`).
+5. **Log the evolution.** As you cross stage/step boundaries, call
+   `yujin.workflow.log-step(...)` -- it writes `docs/WORKFLOW_LOG.md` +
+   `workflow.evolution[]` so the project records its own workflow
+   history. Greenfield detail = the 18-step flow (`workflow`,
+   `workflow-phases`); never force it on a live project.
+
+## Relation to the request lifecycle
+
+The pending request-lifecycle (add -> note -> close with history) is
+the MICRO level (per task). The workflow is the MACRO level (per
+project, with stages). They are now the SAME store: a workflow task IS
+a pending item (with a `workflow` link). The instance names the stages;
+its tasks are pendings closed in mandatory order.
+
+## Canonical steps source
+
+The canonical step definitions live in `src/workflow/definitions.ts`
+(the immutable DEFAULT + disaster-recovery source). A project may
+override them in `.forge/workflow-config.json` (edited via
+`yujin.workflow.configure`); a `.default.json` snapshot keeps the
+default recoverable. The worker-canonical layer plugs in later, same
+pattern as doctrines + lessons.

package/docs/doctrine/workflow-phases.md

@@ -0,0 +1,108 @@
+# Workflow phases -- full reference
+
+Fetch when the user asks: "que pasa en la fase X?", "como salgo
+de clarificacion?", "que necesito para arrancar build?",
+"cuales son los specs?".
+
+The Forge build workflow has 6 phases. Each phase has a
+distinctive intent + an exit condition. The cost router uses
+the current phase to pick eco / frontier per turn, and several
+SQ rules pre-empt phase transitions.
+
+## Phase I -- Intake
+
+**Intent:** capture the raw user request + flag whether the
+project already exists.
+**Steps:** triage (auto), tier election (user picks
+starter/standard/advanced/enterprise), workspace bootstrap.
+**Eco-friendly:** yes. Default tier. Cheap.
+**Exit:** tier locked + workspace ready.
+**Gates:** G1 (tier required), G2 (vault has >= 2 BYOK keys).
+
+## Phase II -- Clarification
+
+**Intent:** narrow the request into something a spec can be
+written against. Disambiguation rounds with the user.
+**Steps:** clarifying-questions iterations (`iterations[]`
+schema, see lessons-workflow doctrine for capture model).
+**Eco-friendly:** yes. Default eco; escalate to frontier on
+SQ rule-violation text.
+**Exit:** user signs off the clarification summary.
+**Gates:** none.
+
+## Phase III -- Specification
+
+**Intent:** produce the three core specs: RFP, ARCH, DESIGN.
+**Steps:** spec-extract (auto), spec-plan (auto), spec-validate
+(auto + user approval).
+**Eco-friendly:** mixed -- text-generation pieces escalate to
+frontier; tooling steps stay eco.
+**Exit:** each spec has `done_at` + `approved_at` non-empty in
+workflow_state.specs.
+**Gates:** G3 (no phase-skip), G-DOC (each step ends with a
+commit ASCII-only).
+
+## Phase IV -- Approval
+
+**Intent:** human sign-off on the spec set + block plan.
+**Steps:** review board (async), block-plan, ship-target
+selection.
+**Eco-friendly:** no -- approvals always frontier so the brain
+catches edge cases.
+**Exit:** all `approvals.*.approved_at` non-empty + block_plan
+exists.
+**Gates:** G4 (block-plan OK), G5 (fase V sin OK explicito de
+los 3 spec docs).
+
+## Phase V -- Build
+
+**Intent:** execute the block plan. Code + tests + integrations.
+**Steps:** per-block dev iterations, smoke tests, integration
+gates.
+**Eco-friendly:** no by default; frontier for the meat of the
+work, eco for status queries.
+**Exit:** every block in block_plan has status='done' +
+smoke tests green.
+**Gates:** G6 (block tests rojos = bloqueo), G7 (creds
+faltantes = bloqueo).
+
+## Phase VI -- Ship
+
+**Intent:** deploy + post-launch monitoring.
+**Steps:** ship-target deploy, smoke test prod, launch
+announcement (when asked).
+**Eco-friendly:** mixed.
+**Exit:** smoke-prod green + announcement composed.
+**Gates:** G8 (launch sin smoke verde).
+
+## What the brain MUST do per phase
+
+1. **Read workflow_state from the injected block** -- never
+   re-fetch via yujin.workflow.state for fields already
+   present.
+2. **Acknowledge the current phase/step** before proposing
+   any action that touches it.
+3. **Refuse phase skips > 1 forward** -- G3 hard rule.
+4. **Cite the gate** when refusing -- "no puedo avanzar
+   porque G2-vault-min-keys exige 2 keys, tenes 1".
+5. **Suggest the cheap fix** -- always offer the user the
+   shortest path to clear a gate (e.g. `yf keys setup`).
+
+## How to read iterations[]
+
+When `workflow_state.iterations[]` is non-empty, the brain
+MUST acknowledge the prior iterations (slug + summary) before
+proposing a new one. Stale-iteration replies are a known
+failure mode caught by the
+`iterations_query_history` scenario.
+
+## Forbidden during a phase
+
+- Phase I-III: NEVER write production code. Specs only.
+- Phase IV: NEVER mutate specs that already have
+  approved_at -- propose a new iteration with a different
+  slug.
+- Phase V: NEVER bypass smoke tests. If they fail, the
+  brain MUST surface the failure, not paper it over.
+- Phase VI: NEVER announce a launch before smoke-prod is
+  green.

package/docs/doctrine/workflow.md

@@ -0,0 +1,66 @@
+# Workflow doctrine -- 6 phases / 18 steps (GREENFIELD)
+
+SCOPE: this 6-phase / 18-step methodology is the GREENFIELD workflow --
+building a new app from zero. A LIVE project uses the compact
+corrective / evolutive flow instead (see `workflow-kinds`). Never force
+these 18 steps on an existing project. Open any workflow with
+`yujin.workflow.start` (it classifies the kind + spawns the task
+pendings in order); this doc is the detail for the greenfield case.
+
+Yujin Forge guides greenfield delivery through 6 phases / 18 steps
+(PRODUCT_WORKFLOW.md). The LLM picks the right phase based on what the
+user is asking; if the user jumps mid-phase the LLM respects that but
+flags the risk.
+
+PHASE I -- INTAKE (steps 1-3.5)
+  1.   Complexity triage           Simple / Medium / Full tier
+  2.   Vault keys validation       13 credential families, BYOK
+  3.   Discover intent             migrate / new / modify; desktop / mobile /
+                                   both; chat / voice / document-paste
+  3.5  Audit existing artifacts    if migrating legacy
+
+PHASE II -- CLARIFICATION (steps 4-9)
+  4.   Functional                  user stories, MVP, personas
+  5.   NFR quantitative            volumetry, parallelism, process complexity
+  6.   NFR structural              persistence, middleware, object lifecycle,
+                                   workers
+  7.   NFR governance              compliance (GDPR/HIPAA/PCI/SOC2), audit,
+                                   retention, RBAC, DR
+  8.   NFR operational             i18n, a11y, cost budget, monitoring, SLA
+  9.   Block prioritisation        decompose + dep graph + MVP
+
+PHASE III -- SPECIFICATION (steps 10-12)
+  10.  RFP / PRD                   consolidates Phase I + II
+  11.  Architecture doc            stack + layering + async + topology +
+                                   observability + security, driven by NFRs
+  12.  Solution Design             per-block: data model, APIs, screens,
+                                   state machines
+
+PHASE IV -- APPROVAL GATE (step 13)
+  13.  Explicit OK on the 3 docs   You REFUSE to advance to Phase V without
+                                   explicit "si" on RFP + architecture +
+                                   design.
+
+PHASE V -- BUILD ITERATIVE (steps 14-15)
+  14.  Bootstrap                   NAC-3 baseline + CI gates + test
+                                   scaffolding all layers + observability
+  15.  Iterative cycle per block   implement -> e2e tests with 100%
+                                   structural coverage -> a11y check ->
+                                   green-gate before next block
+
+PHASE VI -- SHIP & OPERATE (steps 16-18)
+  16.  Deploy automation + execute creds + pipeline + secrets + monitoring +
+                                   smoke + rollback
+  17.  Post-launch                 user manual auto-gen, dashboards,
+                                   feedback collect
+  18.  Iteration re-entry          route new requirements back to the right
+                                   phase, keep docs in sync
+
+CROSS-CUTTING: documentation sync, cost tracking, translation of
+user-facing artifacts, versioning + changelog, handoff, backup + DR.
+
+COMPLEXITY TIER MAPPING:
+  Simple  = landing / blog / demo POC                 -> steps 1-3, 9, 14-16
+  Medium  = CRUD app with auth, low-traffic SaaS      -> + 4-7, 10-13
+  Full    = regulated SaaS, multi-tenant, workflows   -> ALL 18 steps + hard
+                                                       gates

package/docs/doctrine/yf-commands.md

@@ -0,0 +1,49 @@
+# yf CLI command catalog
+
+When the user asks "how do I X?", recommend the matching `yf X`
+command (it teaches them the surface). When the user wants the
+result right now ("install Stripe webhook for me"), invoke the
+relevant NAC3 verb directly instead.
+
+PROJECT LIFECYCLE
+  yf new <slug>                  scaffold a new NAC-3 React project
+  yf migrate <repo> --audit      scan existing project for NAC-3 readiness
+  yf migrate <repo> --apply      execute the AST migration (paid seat)
+  yf ship                        deploy gate: validate + license + tests + build
+
+DEV LOOP
+  yf chat                        this panel (you are inside it)
+  yf doctor                      verify environment + license + deps
+  yf gen-tests <dir>             emit e2e tests from manifest
+  yf scenarios:emit              emit Playwright + Maestro from yaml scenarios
+  yf review-screens              visual regression review UI
+  yf review-status               CI gate: 0 iff every screenshot is OK
+
+CONFIG + LICENSE
+  yf keys setup                  interactive BYOK (brain + voice)
+  yf vault                       manage encrypted credentials
+  yf license activate --user-handle <email>   bind to Polar subscription
+  yf license status / cancel / resubscribe    subscription ops
+  yf voice                       voice + wake-word config
+
+SHIP + DEPLOY
+  yf publish --npm               npm publish using vaulted token
+  yf publish --docker            docker push using vaulted token
+  yf deploy                      cloud deploy (AWS built-in, others chat-guided)
+  yf repo                        init repo + GitHub remote pairing
+
+OBSERVABILITY
+  yf log                         per-scope log levels + redaction (SQ.K)
+  yf projects                    cross-device project registry
+
+QA HARNESSES
+  yf qa brain-matrix             E2E test invariants against LLM brains
+  yf graph                       semantic graph CRUD (alpha.59p)
+  yf mcp                         MCP bridge config (alpha.60 stubs)
+  yf limits                      runtime caps (max tool rounds, timeouts)
+
+INTROSPECTION (z.67)
+  yf doctrine list               list available doctrines (md files)
+  yf doctrine show <slug>        print one doctrine
+  yf manifest verbs              enumerate NAC-3 verbs + policies
+  yf manifest verbs --ns office. filter by namespace prefix

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nac3/forge-cli",
-  "version": "0.2.0-alpha.9",
+  "version": "1.0.0",
   "description": "Yujin Forge -- voice-first NAC-3 React development framework. CLI + chat panel + spec ingest + 10-format document reader + voice loop.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Pablo Kuschnirof <pablo@rpaforce.com>",
@@ -16,19 +16,29 @@
     ".": "./dist/index.js"
   },
   "scripts": {
-    "build": "tsc",
+    "version": "node scripts/sync_version.mjs && git add src/version.ts",
+    "build": "tsc && node scripts/copy_qa_assets.mjs",
     "dev": "tsx watch src/bin/yf.ts",
     "typecheck": "tsc --noEmit",
+    "typecheck:all": "pnpm typecheck && pnpm --filter @yujin/hito4-server typecheck && pnpm --filter @yujin/forge-mobile typecheck",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "tsc --noEmit",
     "yf": "tsx src/bin/yf.ts",
     "catalog:lint": "node scripts/catalog_lint.mjs",
-    "prepublishOnly": "pnpm run build && pnpm run typecheck && pnpm run catalog:lint && pnpm run test"
+    "pairing:check": "node scripts/check_pairing_sync.mjs",
+    "brain-matrix:gate": "node scripts/brain_matrix_gate.mjs",
+    "hito4:lint": "node scripts/hito4_lint_bundle.mjs",
+    "publish-alpha-emergency": "node scripts/publish_alpha_emergency.mjs",
+    "prepublishOnly": "pnpm run build && pnpm run typecheck && pnpm run catalog:lint && pnpm run test && pnpm run brain-matrix:gate && pnpm run hito4:lint"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.32.1",
     "@aws-sdk/client-ecs": "^3.1053.0",
+    "@noble/ciphers": "^2.2.0",
+    "@noble/hashes": "^2.2.0",
+    "@scure/base": "^2.2.0",
+    "better-sqlite3": "^12.10.0",
     "commander": "12.1.0",
     "dotenv": "^17.4.2",
     "kleur": "4.1.5",
@@ -36,13 +46,17 @@
     "node-html-parser": "6.1.13",
     "pdfjs-dist": "^4.10.38",
     "prompts": "2.4.2",
+    "qrcode": "^1.5.4",
     "typescript": "5.7.2",
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "22.10.2",
     "@types/prompts": "2.4.9",
+    "@types/qrcode": "^1.5.6",
+    "acorn": "^8.16.0",
     "pixelmatch": "^7.2.0",
     "pngjs": "^7.0.0",
     "tsx": "4.19.2",
@@ -57,6 +71,9 @@
     "dist",
     "templates",
     "docs/manuals",
+    "docs/SQ.md",
+    "docs/SQ_BY_STEP.yaml",
+    "docs/doctrine",
     "src/i18n/catalogs",
     "README.md",
     "LICENSE"