diff --git a/.gitignore b/.gitignore index 87f1d925e..7f99d35f3 100644 --- a/.gitignore +++ b/.gitignore @@ -40,6 +40,7 @@ docs/copilot_histories/ # Temporary/private paper draft workspaces docs/papers/ +docs/von_compendium_design_and_go_forward_review.md # Generated replay-suite validation artefacts docs/generated/validation_reports/replay_suite_* diff --git a/AGENTS.md b/AGENTS.md index a54c393de..0ee2b8ffd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,8 @@ This file is the concise operating constitution for AI agents working on Von. -All AI agents must read this file and `docs/engineering/security_considerations.md` before starting any work. +All AI agents must read this file, `docs/engineering/security_considerations.md`, +and `docs/design_index.md` before starting any work. ## 1. Purpose @@ -16,6 +17,12 @@ This file is intentionally shorter and sharper than a catch-all agent handbook. - `AGENTS.md` - `docs/engineering/security_considerations.md` +- `docs/design_index.md` (document map, authority, and freshness status) + +The design index distinguishes current guidance, target design, dated evidence, +proposals, and historical material. Consult it before treating any other +engineering note as current authority. The direct mandatory-document links in +this file remain authoritative if the index ever drifts. ### 2.2 Read before finalising the plan for any substantial implementation task @@ -63,7 +70,7 @@ debugging work, see: - `docs/engineering/operational_engineering_guide.md` - `docs/engineering/maintaining_global_design_constraints_and_authority_alignment_with_coding_agents.md` -Use that document for environment handling, shell and host behaviour, +Use those documents for environment handling, shell and host behaviour, credential-path issues, access/tooling defaults, pytest execution practice, and similar operational lessons that do not belong in this constitutional guide. For frontend/browser user-view validation practice, also see diff --git a/docs/AINotes.md b/docs/AINotes.md index 435b6fc73..86dc0b64c 100644 --- a/docs/AINotes.md +++ b/docs/AINotes.md @@ -1,21 +1,22 @@ -"AINotes" is a living scratchpad for agents. +# AI Notes — Frozen Operational Snapshot -Goal: help a fresh agent get oriented in <2 minutes. +> **Document status: Frozen tactical snapshot from 23 April 2026; not current +> task, branch, tool, or repository status.** Start with [`AGENTS.md`](../AGENTS.md), +> the [design and engineering document index](design_index.md), live `git` +> state, and live Jira. Revalidate any operational advice below before using it. -Rules of thumb: -- Keep this file short and current. -- Prefer pointers over prose. -- When something is no longer relevant, delete it (or move it to the archive). - -Last updated: 2026-04-23 +- **Kind:** Tactical notes snapshot +- **Lifecycle:** Frozen +- **Authority:** Historical only +- **State as of:** 2026-04-23 --- -## Now (current focus) +## Focus recorded on 23 April 2026 - Fix/verify: interaction-session UX issues (see current branch name in git). - Run focused tests after UI changes: `npm run test:frontend`. -## Next (likely follow-ups) +## Follow-ups recorded on 23 April 2026 - Add a short regression note here when a bug is fixed (1–2 bullets), then move details to Jira/PR. - Keep Phase/initiative tracking in Jira rather than in this file. @@ -53,7 +54,7 @@ Push the feature branch before merging so the remote tracking ref exists; otherw - Engineering notes: `docs/engineering/` - Archive (historical details): `docs/AINotes_archive.md` -## Recent decisions / changes worth remembering +## Decisions and changes recorded in this snapshot - Presenter “spoken vs screen” behaviour is documented in Jira (JVNAUTOSCI-894); avoid duplicating the write-up here. - 2026-04-20: Atlassian MCP transport verification/migration follow-through - Repo workspace config now ships an Atlassian MCP entry in `.vscode/mcp.json` on `https://mcp.atlassian.com/v1/mcp`. @@ -157,5 +158,3 @@ Push the feature branch before merging so the remote tracking ref exists; otherw - Write-tool guardrail: moved write permissioning into a workflow-driven policy (`write_tool_policy`) instead of hard-coded orchestrator logic; added regression test (JVNAUTOSCI-956). - 2026-01-09 diary - Chat prompts: treat legacy `#V#von_llm_prompt` as a behaviour prompt so user-specific prompts load in chat and MCP introspection; updated tests; closed JVNAUTOSCI-974. - - diff --git a/docs/design_index.md b/docs/design_index.md new file mode 100644 index 000000000..bef6e680d --- /dev/null +++ b/docs/design_index.md @@ -0,0 +1,202 @@ +# Von Design and Engineering Document Index + +- **Kind:** Documentation-governance index +- **Lifecycle:** Active +- **Authority:** Canonical navigation and classification only; it does not + override current user direction, `AGENTS.md`, live represented authority, or + live evidence +- **Owner:** Von maintainers +- **Last reviewed:** 12 July 2026 +- **Review trigger:** Any change to `AGENTS.md` reading routes, canonical + document selection, or document supersession +- **Scope:** Tracked design, engineering, operational, review, and generated + documentation in this repository + +## 1. Why this index exists + +Von's documentation records several years of design, implementation, incidents, +Jira milestones, and research thinking. Those records are useful, but they do +not all describe the same system or carry the same authority. A confident old +status report is not a current implementation guide, and a live defect is not a +new design principle. + +Coding agents must therefore use this index before treating an engineering note +as current authority. In particular: + +- read [`AGENTS.md`](../AGENTS.md) and the documents it selects; +- determine what kind of claim the document is making; +- check its lifecycle, authority scope, and evidence date separately; +- verify present behaviour on the live authority and evidence surfaces; and +- treat an unlisted engineering note as supporting material, not as current + project-wide authority. + +The directory remains mostly flat for now so existing links and external +bookmarks continue to work. Status banners and this virtual organisation are +the first migration step; files can move into archival folders later, with +compatibility stubs, when that produces more value than link churn. + +## 2. Do not compress document status into one label + +Interpret these four dimensions independently: + +| Dimension | Question | Typical values | +|---|---|---| +| **Kind** | What is this document? | constitution, principle, specification, manual, protocol, runbook, programme design, proposal, snapshot, audit, implementation record | +| **Lifecycle** | Is the document itself active? | draft, active, frozen, superseded, retired | +| **Authority** | What, if anything, may it prescribe? | governing, normative in scope, canonical reference, advisory, evidence only, historical only | +| **Evidence basis** | How well does it establish a factual claim? | live validated, observed, reported, inferred, proposed, aspirational, contradicted, unknown | + +Words such as “complete”, “secure”, “implemented”, and “production ready” are +claims about a system or a bounded milestone, not document lifecycle values. +They require a scope, evidence locator, and date. + +## 3. Authority and evidence order + +The right precedence depends on the question. + +| Question | Use this order | +|---|---| +| What is Von intended to become? | Current explicit user direction → `AGENTS.md` → applicable active guidance selected by `AGENTS.md` → accepted decision records → advisory programme designs and proposals | +| What policy, prompt, workflow, or knowledge is operationally represented? | Live canonical Vontology artefact → named published release/export → repository seed or fixture only when explicitly designated | +| What does Von actually do now? | Exact user-visible path and world-state read-back → persisted telemetry and receipts → live artefact inspection → current code and targeted tests → dated reports → prose assertions | +| What work is planned or complete? | Current user decision and live Jira → current git/CI evidence → dated programme notes and milestone reports | +| Why was a design decision made? | Accepted decision record → linked Jira decision → active design proposal → historical discussion | + +A security or correctness failure is evidence that the implementation violates a +requirement; it does not supersede the requirement. Conversely, a document's +desired architecture does not prove the implementation currently behaves that +way. + +## 4. Start here + +The direct links in `AGENTS.md` remain authoritative if this index ever drifts. + +| Work | Required or primary documents | +|---|---| +| Every task | [`AGENTS.md`](../AGENTS.md), [security considerations](engineering/security_considerations.md), and this index | +| Substantial implementation | [modern agentic AI primer](engineering/intro_to_modern_agentic_ai_for_coding_agents.md) | +| Workflow or orchestration | [VWL manual](engineering/von_workflow_language_manual.md) | +| Prompts, models, routing, optimisation, or fine-tuning | [prompt programmes and model routing](engineering/prompt_programs_and_model_routing_playbook.md) | +| Retrieval, memory, RAG, KB growth, or long-horizon state | [agent memory and enduring knowledge](engineering/agent_memory_and_enduring_knowledge.md) | +| Evaluation, benchmarks, or research-sensitive architecture | [agent evaluation and research uptake](engineering/agent_evaluation_and_research_uptake.md) | +| Minimal imposition, elicitation, or write policy | [minimal-imposition principle](engineering/minimal_imposition_design_principle.md) | +| Frontend or authenticated browser acceptance | [frontend browser validation](engineering/frontend_browser_user_view_validation.md) | +| Live user-visible behaviour or telemetry diagnosis | [real-path replay and telemetry loop](engineering/real_path_server_replay_and_telemetry_loop.md) | +| Practical repository operation | [operational engineering guide](engineering/operational_engineering_guide.md), [authority-alignment scan](engineering/maintaining_global_design_constraints_and_authority_alignment_with_coding_agents.md) | + +## 5. Current governing and mandatory guidance + +These documents are current because `AGENTS.md` selects them, not merely because +their own headers say so. + +| Document | Kind and lifecycle | Authority and freshness boundary | +|---|---|---| +| [`AGENTS.md`](../AGENTS.md) | Active constitution | Governing repository instructions, subordinate to current explicit user direction and higher-level safety rules | +| [Security considerations](engineering/security_considerations.md) | Active security guide with dated posture observations | Always mandatory; verify deployment-profile and implementation claims live | +| [Modern agentic AI primer](engineering/intro_to_modern_agentic_ai_for_coding_agents.md) | Active principle/background guide | Mandatory before substantial implementation planning; not a current-status report | +| [VWL manual](engineering/von_workflow_language_manual.md) | Active manual | Canonical reference for VWL vocabulary, authoring, and runtime interfaces; live Vontology and current runtime evidence govern actual artefacts and behaviour | +| [Prompt programmes and model routing](engineering/prompt_programs_and_model_routing_playbook.md) | Active playbook | Normative in the scope selected by `AGENTS.md` | +| [Agent memory and enduring knowledge](engineering/agent_memory_and_enduring_knowledge.md) | Active design guide | Normative in the scope selected by `AGENTS.md` | +| [Agent evaluation and research uptake](engineering/agent_evaluation_and_research_uptake.md) | Active protocol/design guide | Normative in the scope selected by `AGENTS.md` | +| [Minimal-imposition principle](engineering/minimal_imposition_design_principle.md) | Active principle | Normative in the scope selected by `AGENTS.md`, subject to the precedence stated there | +| [Frontend browser validation](engineering/frontend_browser_user_view_validation.md) | Active practical guide | Required for its named acceptance scope; browser evidence still needs a dated locator | +| [Real-path replay and telemetry loop](engineering/real_path_server_replay_and_telemetry_loop.md) | Active practical guide | Required for its named validation scope; exact-path evidence outranks prose | +| [Operational engineering guide](engineering/operational_engineering_guide.md) | Active companion runbook | Canonical practical guidance; revalidate environment- and tool-specific details | +| [Authority-alignment scan](engineering/maintaining_global_design_constraints_and_authority_alignment_with_coding_agents.md) | Active companion guide | Advisory structural review procedure under `AGENTS.md` | + +## 6. Programme direction and current synthesis + +No formal Architecture Decision Record corpus existed at this review. Do not +mistake a design proposal or Jira implementation summary for an accepted ADR. +Until an ADR process is established, acceptance must be grounded in current +human direction, `AGENTS.md`, and the relevant live Jira decision record. + +| Document | Classification | Correct use | +|---|---|---| +| [Von for Agentic AI](engineering/Von_for_AgenticAI.md) | Advisory long-horizon programme design with an April 2026 state snapshot | Use the durable target direction; revalidate every present-state, file-size, gap, and priority claim | +| Private research syntheses | Advisory material retained outside the public repository | Public coding agents must not depend on private notes; promote approved decisions into the applicable public canonical guide | +| [Automated policy learning](engineering/automated_policy_learning_design.md) | Design with partial substrate | Use as a proposed learning architecture, not proof of a closed operational loop | +| [Testing workflows and ephemeral theories](engineering/testing_workflows_ephemeral_theories_design.md) | Research/design proposal with partial substrate | Use for design intent and explicit hypotheses; verify implemented surfaces | +| [Multi-agent coordination](engineering/multi_agent_coordination_design.md) | Early design proposal | Use as a direction to evaluate, not implemented architecture | +| [Vontology tooling from KA/KR literature](engineering/vontology_tooling_from_ka_kcap_kr_literature.md) | Research-backed advisory roadmap | Use for alternatives and research uptake, not present capability claims | + +## 7. Dated snapshots, diagnostics, and proposals + +These files retain evidence and rationale, but must not drive current task +ordering or implementation without live revalidation: + +- [Agentic architecture status — 23 April 2026](engineering/agentic_architecture_status_2026-04-23.md) +- [Recent architecture progress — 21 April 2026](engineering/recent_architecture_progress_2026-04-20.md) +- [Enduring-memory architecture — 23 April 2026](engineering/jvnautosci_1962_enduring_memory_architecture_2026-04-23.md) +- [Self-improvement worlds architecture — 23 April 2026](engineering/jvnautosci_1963_self_improvement_worlds_architecture_2026-04-23.md) +- [Evaluator architecture — 23 April 2026](engineering/jvnautosci_1964_evaluator_architecture_2026-04-23.md) +- [Role-learning review — 24 April 2026](engineering/jvnautosci_2011_role_learning_review_2026-04-24.md) +- [Workflow execution analysis — 7 April 2026](engineering/workflow_execution_architecture_analysis.md) +- [Chat-turn control-plane analysis — 7 April 2026](engineering/chat_turn_workflow_control_plane_analysis.md) +- [Comparative arXiv workflow analysis — 7 April 2026](engineering/arxiv_paper_workflow_analysis.md) +- [Workflow self-authoring gap analysis — 5 April 2026](engineering/workflow_self_authoring_gap_analysis.md) +- [Workflow system audit — 7 February 2026](engineering/workflow_audit_2026-02-07.md) +- [VWL implementation audit — 24 March 2026](engineering/vwl_implementation_audit_2026-03-24.md) +- [MCP reliability incident reflection](engineering/mcp_reliability_analysis.md) +- dated `jvnautosci_*` reviews, audits, designs, and implementation summaries, + unless a current guide above explicitly adopts their conclusions. + +## 8. Historical and generated material + +- [`intro_to_modern_agentic_ai_for_coding_agents.suggested.md`](engineering/intro_to_modern_agentic_ai_for_coding_agents.suggested.md) + is a superseded, unselected proposal. It is not the guide required by + `AGENTS.md`. +- [`AINotes.md`](AINotes.md) is a frozen tactical snapshot, not current task or + repository status. Use live git and Jira instead. +- [Historical agent guidance](engineering/historical_agent_guidance_notes.md) + is an archive and already labels itself accordingly. +- The `JVNAUTOSCI-799` document family records a bounded 2025 milestone. Its + completion, coverage, and readiness claims are not current system-level + evidence. +- Files under [`docs/generated/`](generated/) are generated evidence snapshots. + Read their timestamps and inputs; never treat a generated report as standing + design authority. +- A date in a filename is an evidence boundary, not a freshness guarantee. + +## 9. Metadata for new and substantially revised documents + +Use this compact header, adapting fields to the document: + +```markdown +**Kind:** manual | runbook | design | proposal | snapshot | audit | record +**Lifecycle:** draft | active | frozen | superseded | retired +**Authority:** governing | normative in scope | canonical reference | advisory | +evidence only | historical only +**Authority scope:** ... +**Owner:** named person or team | unassigned +**Last reviewed:** YYYY-MM-DD +**Review due or trigger:** YYYY-MM-DD or named change trigger +**State or evidence as of:** YYYY-MM-DD or not applicable +**Supersedes / superseded by:** ... +**Live authority or implementation evidence:** ... +**Open questions:** ... +``` + +Maintenance rules: + +1. Only current human direction, `AGENTS.md`, or an explicitly authorised + decision may elevate a document to governing or normative status. +2. Keep one active canonical document per subject. Update it instead of adding + a near-duplicate “suggested”, “final”, or “new” guide. +3. Separate target-state design from current-state evidence. Date the latter. +4. Freeze audits and snapshots. Publish a new observation rather than silently + rewriting the old evidence base. +5. Supersession is two-way: banner and replacement link on the old document, + backlink from the replacement where useful, and an index update. +6. Do not use unqualified “current”, “complete”, “secure”, “canonical”, or + “production ready”. State the scope, date, and evidence. +7. Repository descriptions of Vontology-governed workflows, prompts, policies, + or knowledge must say whether they are manuals, exports, seeds, fixtures, or + live authority. +8. Re-check links, code anchors, live Jira, and represented artefacts whenever a + substantial task relies on an older document. + +This first pass classifies the authority-bearing and highest-risk material. It +does not pretend that all 104 pre-existing engineering files have already +received complete metadata. Until they do, unlisted documents remain supporting +material whose claims require independent verification. diff --git a/docs/engineering/Arxiv_WF_purity.md b/docs/engineering/Arxiv_WF_purity.md index d5de8b443..b88d87f3d 100644 --- a/docs/engineering/Arxiv_WF_purity.md +++ b/docs/engineering/Arxiv_WF_purity.md @@ -1,4 +1,13 @@ -Code Review: JVNAUTOSCI-1763 Branch vs Jira Requirements & No-Thin-Shim Rule +# Historical JVNAUTOSCI-1763 Branch Review Transcript + +> **Document status: Historical, unnormalised branch-review transcript.** These +> findings refer to the JVNAUTOSCI-1763 branch and runtime state inspected at +> the time. They are incident provenance, not current architecture or Jira +> status. Re-check every finding against current code, Vontology, telemetry, and +> Jira before acting on it. + +## Code Review: JVNAUTOSCI-1763 Branch vs Jira Requirements and No-Thin-Shim Rule + Critical Concerns (architectural/rule violations) 1. von_routes.py still owns the arXiv dispatch decision — violates 1766 @@ -77,5 +86,3 @@ I would not consider JVNAUTOSCI-1763 or subtasks 1764-1767 genuinely done in the I didn’t change code. I checked the working tree, the Jira task texts/comments, the authoritative workflow registry, and a couple of targeted runtime validations; I did not run a full /von/generate end-to-end because the import/registration failures and unchanged authoritative workflows already show the path is not in a closable state. - - diff --git a/docs/engineering/OPTION1_SECURITY_IMPLEMENTATION.md b/docs/engineering/OPTION1_SECURITY_IMPLEMENTATION.md index 786be50a2..878002fe2 100644 --- a/docs/engineering/OPTION1_SECURITY_IMPLEMENTATION.md +++ b/docs/engineering/OPTION1_SECURITY_IMPLEMENTATION.md @@ -1,12 +1,21 @@ -# Option 1 Security Implementation - Completed +# Historical Option 1 Security Mitigation Record + +> **Document status: Historical mitigation record from 2 December 2024; not a +> statement of Von's current security posture.** “Secure” below referred only +> to removal of the client-provided `user_id` fallback on the named path. It did +> not establish complete caller authentication, authorisation, namespace +> isolation, or deployment security. Use +> [`security_considerations.md`](security_considerations.md) for current +> requirements and limitations. **Date**: December 2, 2024 **Issue**: JVNAUTOSCI-760 (RAG namespace filtering) -**Security Level**: ✅ **SECURE** +**Bounded milestone result**: Client-provided `user_id` fallback removed on the +named path ## Summary -Successfully implemented **Option 1 (Secure)** authentication approach: +At the time, this implemented the bounded “Option 1” authentication mitigation: - ❌ **Removed** insecure client-provided user_id fallback - ✅ **Require** proper authentication via session or validated headers - ✅ **Inform** agent about authentication status and tool availability diff --git a/docs/engineering/README.md b/docs/engineering/README.md new file mode 100644 index 000000000..4db6a84e2 --- /dev/null +++ b/docs/engineering/README.md @@ -0,0 +1,27 @@ +# Engineering Documentation + +This directory deliberately contains both current engineering guidance and the +historical design, audit, incident, and Jira records that explain how Von +evolved. Proximity in this directory does not imply equal authority or +freshness. + +Use the canonical [Von design and engineering document +index](../design_index.md) to determine a document's kind, lifecycle, authority, +and evidence boundary before relying on it. The mandatory reading paths remain +in [`AGENTS.md`](../../AGENTS.md). + +Quick rules: + +- current explicit user direction and `AGENTS.md` govern intended direction; +- live Vontology artefacts govern represented prompts, workflows, policies, and + enduring knowledge; +- exact-path behaviour, state read-back, telemetry, current code, and targeted + tests establish what the system presently does; +- dated audits and Jira implementation reports are evidence snapshots, not + standing implementation instructions; and +- an unlisted note is supporting material until its authority and freshness are + established. + +Do not infer authority from words such as “current”, “complete”, “secure”, or +“canonical” inside an older document. Check its banner and the canonical index, +then revalidate factual claims on the appropriate live surface. diff --git a/docs/engineering/Von_for_AgenticAI.md b/docs/engineering/Von_for_AgenticAI.md index 618d6dd6b..73f328626 100644 --- a/docs/engineering/Von_for_AgenticAI.md +++ b/docs/engineering/Von_for_AgenticAI.md @@ -1,8 +1,15 @@ # Von for Agentic AI -**Status:** working architecture note -**Updated:** 24 April 2026 -**Scope:** current Von architectural direction, recent progress, remaining gaps, and the path from a capable neuro-symbolic assistant toward minimal-imposition agentic AI in the stronger Von sense +- **Kind:** Long-horizon programme and target-architecture design +- **Lifecycle:** Active as advisory design; implementation snapshot frozen +- **Authority:** Advisory; `AGENTS.md` and current explicit user direction govern +- **State evidence as of:** 24 April 2026 +- **Freshness boundary:** Durable target-direction arguments may remain useful; + all “current”, “already”, “still”, code-size, gap, and priority claims require + live revalidation +- **Scope:** Von's architectural direction and the path from a capable + neuro-symbolic assistant toward minimal-imposition agentic AI in the stronger + Von sense ## 1. Purpose diff --git a/docs/engineering/agentic_architecture_status_2026-04-23.md b/docs/engineering/agentic_architecture_status_2026-04-23.md index 32022c864..a3ab8615f 100644 --- a/docs/engineering/agentic_architecture_status_2026-04-23.md +++ b/docs/engineering/agentic_architecture_status_2026-04-23.md @@ -1,5 +1,15 @@ # Agentic Architecture Status - 23 April 2026 +> **Document status: Frozen architecture and task-ordering snapshot.** This +> records evidence and conclusions from 23 April 2026. It is not current +> programme status. Revalidate code, Vontology, telemetry, and live Jira before +> using any “current”, “remaining”, or “next” claim. + +- **Kind:** Status snapshot +- **Lifecycle:** Frozen +- **Authority:** Evidence only +- **State as of:** 2026-04-23 + ## Purpose This note records the current engineering status of the Von codebase against the @@ -81,41 +91,41 @@ The remaining umbrellas should now be interpreted against the following live surfaces rather than against older pre-`1988` or pre-`1993` wording: - Memory substrate and turn-context integration: - [conversation_turn_memory_context_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/conversation_turn_memory_context_service.py:547), - [context_bundle_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/context_bundle_service.py:630), - [context_bundle_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/context_bundle_service.py:1296), - [orchestrator.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/integrations/internal_mcp/orchestrator.py:28847), - [orchestrator.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/integrations/internal_mcp/orchestrator.py:29840), - [von_routes.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/server/routes/von_routes.py:7717) + [conversation_turn_memory_context_service.py](../../src/backend/services/conversation_turn_memory_context_service.py), + [context_bundle_service.py](../../src/backend/services/context_bundle_service.py), + [context_bundle_service.py](../../src/backend/services/context_bundle_service.py), + [orchestrator.py](../../src/backend/integrations/internal_mcp/orchestrator.py), + [orchestrator.py](../../src/backend/integrations/internal_mcp/orchestrator.py), + [von_routes.py](../../src/backend/server/routes/von_routes.py) - Episode self-improvement and proposal/promotion loop: - [episode_evaluation_workflow.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/workflows/durable/episode_evaluation_workflow.py:318), - [episode_self_improvement_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/episode_self_improvement_service.py:310), - [episode_self_improvement_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/episode_self_improvement_service.py:638), - [episode_self_improvement_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/episode_self_improvement_service.py:706), - [episode_self_improvement_workflow.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/workflows/durable/episode_self_improvement_workflow.py:239), - [workflow_studio_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/workflows/workflow_studio_service.py:869) + [episode_evaluation_workflow.py](../../src/backend/workflows/durable/episode_evaluation_workflow.py), + [episode_self_improvement_service.py](../../src/backend/services/episode_self_improvement_service.py), + [episode_self_improvement_service.py](../../src/backend/services/episode_self_improvement_service.py), + [episode_self_improvement_service.py](../../src/backend/services/episode_self_improvement_service.py), + [episode_self_improvement_workflow.py](../../src/backend/workflows/durable/episode_self_improvement_workflow.py), + [workflow_studio_service.py](../../src/backend/workflows/workflow_studio_service.py) - Experiment worlds, testing theories, and publication rollback support: - [experiment_run_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/experiment_run_service.py:1046), - [experiment_run_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/experiment_run_service.py:1181), - [experiment_run_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/experiment_run_service.py:1688), - [testing_theory_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/testing_theory_service.py:363), - [testing_theory_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/testing_theory_service.py:573), - [testing_theory_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/testing_theory_service.py:625), - [workflow_studio_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/workflows/workflow_studio_service.py:1684), - [workflow_studio_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/workflows/workflow_studio_service.py:2251) + [experiment_run_service.py](../../src/backend/services/experiment_run_service.py), + [experiment_run_service.py](../../src/backend/services/experiment_run_service.py), + [experiment_run_service.py](../../src/backend/services/experiment_run_service.py), + [testing_theory_service.py](../../src/backend/services/testing_theory_service.py), + [testing_theory_service.py](../../src/backend/services/testing_theory_service.py), + [testing_theory_service.py](../../src/backend/services/testing_theory_service.py), + [workflow_studio_service.py](../../src/backend/workflows/workflow_studio_service.py), + [workflow_studio_service.py](../../src/backend/workflows/workflow_studio_service.py) - Current critic/evaluator surfaces: - [episode_evaluator_contract_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/episode_evaluator_contract_service.py:1), - [turn_execution_record_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/turn_execution_record_service.py:1300), - [turn_execution_record_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/turn_execution_record_service.py:6399), - [episode_critic_evidence_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/episode_critic_evidence_service.py:1395), - [episode_evaluation_workflow.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/workflows/durable/episode_evaluation_workflow.py:228), - [episode_critique_memory_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/episode_critique_memory_service.py:716), - [episode_critique_memory_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/episode_critique_memory_service.py:1723), - [episode_critique_benchmark_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/episode_critique_benchmark_service.py:1393), - [episode_evaluation_workflow_vontology_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/episode_evaluation_workflow_vontology_service.py:79) + [episode_evaluator_contract_service.py](../../src/backend/services/episode_evaluator_contract_service.py), + [turn_execution_record_service.py](../../src/backend/services/turn_execution_record_service.py), + [turn_execution_record_service.py](../../src/backend/services/turn_execution_record_service.py), + [episode_critic_evidence_service.py](../../src/backend/services/episode_critic_evidence_service.py), + [episode_evaluation_workflow.py](../../src/backend/workflows/durable/episode_evaluation_workflow.py), + [episode_critique_memory_service.py](../../src/backend/services/episode_critique_memory_service.py), + [episode_critique_memory_service.py](../../src/backend/services/episode_critique_memory_service.py), + [episode_critique_benchmark_service.py](../../src/backend/services/episode_critique_benchmark_service.py), + [episode_evaluation_workflow_vontology_service.py](../../src/backend/services/episode_evaluation_workflow_vontology_service.py) These anchors matter because the remaining gaps are no longer mostly "missing live-path repair" tasks. They are broader substrate-shaping tasks that should diff --git a/docs/engineering/arxiv_paper_workflow_analysis.md b/docs/engineering/arxiv_paper_workflow_analysis.md index 8f3ed47ab..45a798532 100644 --- a/docs/engineering/arxiv_paper_workflow_analysis.md +++ b/docs/engineering/arxiv_paper_workflow_analysis.md @@ -1,12 +1,21 @@ # Arxiv Paper Workflow: Comparative Architectural Analysis -**Status**: Comparative Analysis -**Date**: 2026-04-07 -**Subject**: Analysis of `#V#arxiv_paper_representation_workflow` and the Von Control Plane -**Sources**: -- [Doc A: Chat-Turn Workflow Control Plane Analysis](docs/engineering/chat_turn_workflow_control_plane_analysis.md) -- [Doc B: Workflow Execution Architecture Analysis](docs/engineering/workflow_execution_architecture_analysis.md) -- [Reference: Von Workflow Language Manual](docs/engineering/von_workflow_language_manual.md) +> **Document status: Dated comparative diagnostic; not a current +> implementation guide.** Workflow inventories, Vontology counts, line anchors, +> and Jira conclusions describe the 7 April 2026 evidence base and require live +> revalidation. + +- **Kind:** Comparative diagnostic analysis +- **Lifecycle:** Frozen +- **Authority:** Evidence only +- **State as of:** 2026-04-07 +- **Subject:** Analysis of `#V#arxiv_paper_representation_workflow` and the Von + control plane + +**Sources:** +- [Doc A: Chat-Turn Workflow Control Plane Analysis](chat_turn_workflow_control_plane_analysis.md) +- [Doc B: Workflow Execution Architecture Analysis](workflow_execution_architecture_analysis.md) +- [Reference: Von Workflow Language Manual](von_workflow_language_manual.md) --- diff --git a/docs/engineering/catalyst_cloud_swift_setup.md b/docs/engineering/catalyst_cloud_swift_setup.md index 9447a5e43..7d82665a4 100644 --- a/docs/engineering/catalyst_cloud_swift_setup.md +++ b/docs/engineering/catalyst_cloud_swift_setup.md @@ -283,5 +283,5 @@ for the step-by-step restore procedure when restoring from Catalyst Cloud. ## Related documents - If you’re configuring arXiv MCP usage as well, see the arXiv MCP integration notes in `AGENTS.md`. -- For Terraform-based OpenStack infrastructure provisioning, see [docs/engineering/catalyst_cloud_terraform_iac.md](docs/engineering/catalyst_cloud_terraform_iac.md). -- For general guidance on MCP tool design and reliability, see [docs/engineering/mcp_tools_best_practices.md](docs/engineering/mcp_tools_best_practices.md). +- For Terraform-based OpenStack infrastructure provisioning, see [catalyst_cloud_terraform_iac.md](catalyst_cloud_terraform_iac.md). +- For general guidance on MCP tool design and reliability, see [mcp_tools_best_practices.md](mcp_tools_best_practices.md). diff --git a/docs/engineering/chat_turn_workflow_control_plane_analysis.md b/docs/engineering/chat_turn_workflow_control_plane_analysis.md index 51968d662..261e5493c 100644 --- a/docs/engineering/chat_turn_workflow_control_plane_analysis.md +++ b/docs/engineering/chat_turn_workflow_control_plane_analysis.md @@ -1,9 +1,17 @@ # Chat-Turn Workflow Control Plane Analysis -**Status**: Analytical paper - not a specification -**Date**: 2026-04-07 -**Author**: Analysis prepared for Michael Witbrock -**Scope**: Intended chat-turn and workflow hierarchy versus the current implementation reality +> **Document status: Dated diagnostic snapshot; not a current implementation +> guide.** Present-tense implementation claims and source line numbers describe +> evidence available on 7 April 2026. Revalidate them against current code, +> live Vontology, telemetry, and Jira before acting. + +- **Kind:** Diagnostic analysis +- **Lifecycle:** Frozen +- **Authority:** Evidence only; not a specification +- **State as of:** 2026-04-07 +- **Author:** Analysis prepared for Michael Witbrock +- **Scope:** Intended chat-turn and workflow hierarchy versus the implementation + observed at that date --- diff --git a/docs/engineering/durable_workflow_system_design.md b/docs/engineering/durable_workflow_system_design.md index e6693255a..a559b0dfc 100644 --- a/docs/engineering/durable_workflow_system_design.md +++ b/docs/engineering/durable_workflow_system_design.md @@ -1,6 +1,12 @@ # Durable Workflow System Design -**Status**: Draft +> **Document status: Historical design precursor; non-normative.** Current-state +> and gap descriptions reflect February 2026 and have been overtaken by later +> durable-workflow implementation. Use the current VWL manual and live +> code/Vontology state for workflow planning. + +**Lifecycle**: Superseded design precursor +**Authority**: Historical only **Version**: 1.0 **Date**: 2026-02-03 **Parent JIRA**: [JVNAUTOSCI-803](https://naoinstitute.atlassian.net/browse/JVNAUTOSCI-803) (LLM Workflows) diff --git a/docs/engineering/frontend_browser_user_view_validation.md b/docs/engineering/frontend_browser_user_view_validation.md index e38c4b900..f9ad37d98 100644 --- a/docs/engineering/frontend_browser_user_view_validation.md +++ b/docs/engineering/frontend_browser_user_view_validation.md @@ -1,7 +1,13 @@ # Frontend Browser User-View Validation Guide -**Status**: Living practical guidance -**Date**: 2026-04-06 +- **Kind:** Browser-acceptance protocol and practical guidance +- **Lifecycle:** Active +- **Authority:** Required by `AGENTS.md` for frontend, browser acceptance, and + authenticated user-view testing +- **Created:** 2026-04-06 +- **Last substantive content update before this metadata review:** 2026-06-08 +- **Evidence boundary:** Each acceptance claim still requires its own dated + user-view evidence ## 1. Purpose diff --git a/docs/engineering/intro_to_modern_agentic_ai_for_coding_agents.md b/docs/engineering/intro_to_modern_agentic_ai_for_coding_agents.md index add7551fc..96e2446b2 100644 --- a/docs/engineering/intro_to_modern_agentic_ai_for_coding_agents.md +++ b/docs/engineering/intro_to_modern_agentic_ai_for_coding_agents.md @@ -1,7 +1,13 @@ # Intro to Modern Agentic AI for Coding Agents -**Status**: Draft design/background guidance -**Date**: 2026-04-04 +- **Kind:** Principle and engineering-background guide +- **Lifecycle:** Active +- **Authority:** Required for substantial implementation planning because it is + selected by [`AGENTS.md`](../../AGENTS.md); subordinate to that constitution + and current explicit user direction +- **Created:** 2026-04-04 +- **Freshness boundary:** Design guidance, not a report of current + implementation state; verify factual claims against live evidence ## 1. Purpose diff --git a/docs/engineering/intro_to_modern_agentic_ai_for_coding_agents.suggested.md b/docs/engineering/intro_to_modern_agentic_ai_for_coding_agents.suggested.md index 2c291bada..0bfaf64d7 100644 --- a/docs/engineering/intro_to_modern_agentic_ai_for_coding_agents.suggested.md +++ b/docs/engineering/intro_to_modern_agentic_ai_for_coding_agents.suggested.md @@ -1,11 +1,21 @@ -# Von Agentic AI Architecture Constitution +# Superseded proposal: Von Agentic AI Architecture Constitution -**Status**: Normative design guidance -**Date**: 2026-04-04 +> **Document status: Superseded proposal; non-authoritative.** This file was +> never the guide selected by `AGENTS.md`. Do not treat its “normative”, “main +> architecture guide”, or “mandatory” wording as current authority. Use +> [`intro_to_modern_agentic_ai_for_coding_agents.md`](intro_to_modern_agentic_ai_for_coding_agents.md) +> together with [`AGENTS.md`](../../AGENTS.md). This copy is retained only for +> design provenance. + +- **Kind:** Unselected architecture proposal +- **Lifecycle:** Superseded +- **Authority:** Historical only +- **Original date:** 2026-04-04 ## 1. Purpose -This document is the main architecture guide for coding agents working on Von. +This document was proposed as the main architecture guide for coding agents +working on Von. It was not selected as the canonical guide. It exists to prevent a recurring failure mode: treating modern agentic behaviour as if it were mainly ordinary application logic that should be hand-coded in Python, with prompts, workflows, knowledge representations, model portfolios, and learning loops treated as secondary decoration. @@ -24,7 +34,9 @@ To drive progress towards the vision of Von as an advanced neuro-symbolic assist ## 2. When to read it -Per `AGENTS.md`, this document is mandatory before finalising the plan for any substantial implementation task. +This document is not required by `AGENTS.md`. Read it only when investigating +design provenance or material that may merit deliberate promotion into a +current guide. It is especially important when the task touches: diff --git a/docs/engineering/jvnautosci_1962_enduring_memory_architecture_2026-04-23.md b/docs/engineering/jvnautosci_1962_enduring_memory_architecture_2026-04-23.md index 4fd61b7ae..5f06458b8 100644 --- a/docs/engineering/jvnautosci_1962_enduring_memory_architecture_2026-04-23.md +++ b/docs/engineering/jvnautosci_1962_enduring_memory_architecture_2026-04-23.md @@ -1,5 +1,10 @@ # JVNAUTOSCI-1962 Enduring Memory Architecture - 23 April 2026 +> **Document status: Long-horizon design with a dated implementation snapshot.** +> The design may remain useful. Claims using “current”, “already”, “still”, +> source anchors, and task priority describe the April 2026 evidence base and +> require live revalidation. This is not release-status authority. + ## Purpose This note records the concrete enduring-memory architecture for Von after the diff --git a/docs/engineering/jvnautosci_1963_self_improvement_worlds_architecture_2026-04-23.md b/docs/engineering/jvnautosci_1963_self_improvement_worlds_architecture_2026-04-23.md index ad7f319cb..4b0970423 100644 --- a/docs/engineering/jvnautosci_1963_self_improvement_worlds_architecture_2026-04-23.md +++ b/docs/engineering/jvnautosci_1963_self_improvement_worlds_architecture_2026-04-23.md @@ -1,5 +1,10 @@ # JVNAUTOSCI-1963 Isolated Self-Improvement Worlds Architecture - 23 April 2026 +> **Document status: Long-horizon design with a dated implementation snapshot.** +> The design may remain useful. Claims using “current”, “already”, “still”, +> source anchors, and task priority describe the April 2026 evidence base and +> require live revalidation. This is not release-status authority. + ## Purpose This note records the concrete self-improvement-world architecture for Von after diff --git a/docs/engineering/jvnautosci_1964_evaluator_architecture_2026-04-23.md b/docs/engineering/jvnautosci_1964_evaluator_architecture_2026-04-23.md index a06554c88..2f0aee7e1 100644 --- a/docs/engineering/jvnautosci_1964_evaluator_architecture_2026-04-23.md +++ b/docs/engineering/jvnautosci_1964_evaluator_architecture_2026-04-23.md @@ -1,5 +1,10 @@ # JVNAUTOSCI-1964 Evaluator Architecture - 23 April 2026 +> **Document status: Long-horizon design with a dated implementation snapshot.** +> The design may remain useful. Claims using “current”, “already”, “still”, +> source anchors, and task priority describe the April 2026 evidence base and +> require live revalidation. This is not release-status authority. + ## Purpose This note records the concrete evaluator architecture for Von after the diff --git a/docs/engineering/jvnautosci_2011_role_learning_review_2026-04-24.md b/docs/engineering/jvnautosci_2011_role_learning_review_2026-04-24.md index eb554fa39..a75184f73 100644 --- a/docs/engineering/jvnautosci_2011_role_learning_review_2026-04-24.md +++ b/docs/engineering/jvnautosci_2011_role_learning_review_2026-04-24.md @@ -1,5 +1,10 @@ # JVNAUTOSCI-2011 Role-Learning Design Review - 24 April 2026 +> **Document status: Long-horizon design with a dated implementation snapshot.** +> The role-learning framing may remain useful. Claims about the current +> substrate, gaps, source anchors, or task ordering describe the 24 April 2026 +> evidence base and require live revalidation. + ## Purpose This note records the design review that led to `JVNAUTOSCI-2011`, the epic diff --git a/docs/engineering/jvnautosci_799_documentation_index.md b/docs/engineering/jvnautosci_799_documentation_index.md index 75d7c6f45..d2a0edacd 100644 --- a/docs/engineering/jvnautosci_799_documentation_index.md +++ b/docs/engineering/jvnautosci_799_documentation_index.md @@ -1,5 +1,11 @@ # JVNAUTOSCI-799 Documentation Index +> **Document status: Historical, task-local documentation index for the 2025 +> JVNAUTOSCI-799 milestone.** This is not the Von-wide document index. “Current +> status”, “complete”, and readiness wording below is bounded to evidence at +> that milestone. Use [`../design_index.md`](../design_index.md) for current +> documentation authority and navigation. + **Structured Tool Calling for Internal MCP - Complete Documentation** This index organizes all documentation for JVNAUTOSCI-799 (Phases 0-2 Complete). diff --git a/docs/engineering/jvnautosci_799_final_status.md b/docs/engineering/jvnautosci_799_final_status.md index 6d87123cf..129c1a242 100644 --- a/docs/engineering/jvnautosci_799_final_status.md +++ b/docs/engineering/jvnautosci_799_final_status.md @@ -1,5 +1,12 @@ # JVNAUTOSCI-799 Phases 0-2: Final Status Report +> **Document status: Historical JVNAUTOSCI-799 implementation record +> (November–December 2025).** “Complete”, “validated”, “current”, coverage, and +> readiness claims below refer only to the named phase and evidence available +> then. They are not claims about current Von behaviour, broader reliability, +> present test coverage, or production readiness. Revalidate the current code +> path, targeted tests, and live authority surfaces before relying on details. + **Date**: 2025-11-15 **Status**: ✅ COMPLETE AND VALIDATED **Tests**: 23/23 Passing (100%) diff --git a/docs/engineering/jvnautosci_799_implementation_roadmap.md b/docs/engineering/jvnautosci_799_implementation_roadmap.md index debe1600f..4268c7a72 100644 --- a/docs/engineering/jvnautosci_799_implementation_roadmap.md +++ b/docs/engineering/jvnautosci_799_implementation_roadmap.md @@ -1,5 +1,11 @@ # JVNAUTOSCI-799: Structured Tool Calling - Implementation Roadmap +> **Document status: Historical JVNAUTOSCI-799 implementation record +> (November–December 2025).** Phase status, “current state”, completion, and +> next-step language below records that milestone, not current work sequencing +> or system behaviour. Revalidate against live Jira, code, tests, and authority +> surfaces before acting. + **Issue**: JVNAUTOSCI-799 (Structured tool calling for internal MCP) **Epic**: JVNAUTOSCI-640 (Von Agent Foundations) **Related**: JVNAUTOSCI-803 (LLM Workflows) - **DEPENDS ON THIS** @@ -492,8 +498,8 @@ If structured calling fails in Phase 3: ### Documentation - [Phase 0 Audit](jvnautosci_799_phase0_audit.md) - [Usage Guide](structured_tool_calling_guide.md) -- [CONTRIBUTING.md](/CONTRIBUTING.md) -- [Code Style Guide](/docs/engineering/software_engineering.md) +- [CONTRIBUTING.md](../../CONTRIBUTING.md) +- [AI Agent Guide](../../AGENTS.md) ### External References - OpenAI Function Calling: https://platform.openai.com/docs/guides/function-calling diff --git a/docs/engineering/jvnautosci_799_lessons_learned.md b/docs/engineering/jvnautosci_799_lessons_learned.md index b03a3c757..598e738ac 100644 --- a/docs/engineering/jvnautosci_799_lessons_learned.md +++ b/docs/engineering/jvnautosci_799_lessons_learned.md @@ -1,5 +1,10 @@ # Lessons Learned - JVNAUTOSCI-799 +> **Document status: Historical JVNAUTOSCI-799 implementation record from +> December 2025.** The design lessons may remain useful, but coverage, +> implementation-time, compatibility, and code-path claims are bounded to that +> milestone and require current verification. + **Project:** Structured Tool Calling for Internal MCP **Date:** December 2025 **Implementation Time:** ~4 hours across all phases diff --git a/docs/engineering/jvnautosci_799_phase0_audit.md b/docs/engineering/jvnautosci_799_phase0_audit.md index dcc812ad8..5e72b3bb4 100644 --- a/docs/engineering/jvnautosci_799_phase0_audit.md +++ b/docs/engineering/jvnautosci_799_phase0_audit.md @@ -1,10 +1,12 @@ -"""Documentation of current tool-call patterns and audit findings. +# PHASE 0 AUDIT: Current Tool-Call Patterns -This document captures the current state of tool invocation across Von, -providing the baseline for Phase 0 (JVNAUTOSCI-799). -""" +> **Document status: Historical JVNAUTOSCI-799 implementation record from +> November 2025.** “Current” below means current at that audit date. Line +> numbers, invocation paths, gaps, and baseline findings are not guaranteed to +> describe present Von. Revalidate the current code path, targeted tests, and +> live authority surfaces before relying on them. -# PHASE 0 AUDIT: Current Tool-Call Patterns +This document captured the tool-invocation baseline for JVNAUTOSCI-799 Phase 0. ## 1. Current Invocation Paths @@ -281,11 +283,10 @@ three categories of current problems: The implementation prioritises OpenAI first (highest reliability requirement), then adds Gemini and Ollama support for breadth of coverage. -""" # Summary Table: Current Patterns vs Proposed -""" +```text Current State (JSON-in-Text): ┌─────────────────────┬─────────────────────────────┐ │ Aspect │ Current Implementation │ @@ -313,4 +314,4 @@ Proposed State (JVNAUTOSCI-799): │ Async Support │ async/sync both available │ │ Retry Logic │ At adapter layer │ └─────────────────────┴─────────────────────────────┘ -""" +``` diff --git a/docs/engineering/jvnautosci_799_phases_1-2_summary.md b/docs/engineering/jvnautosci_799_phases_1-2_summary.md index 628c37d4b..1706739ee 100644 --- a/docs/engineering/jvnautosci_799_phases_1-2_summary.md +++ b/docs/engineering/jvnautosci_799_phases_1-2_summary.md @@ -1,5 +1,10 @@ # JVNAUTOSCI-799 Phases 1-2: Implementation Summary +> **Document status: Historical JVNAUTOSCI-799 implementation record +> (November–December 2025).** Completion, coverage, code-size, and replacement +> claims below are bounded to that milestone and are not current system-level +> evidence. Revalidate the current implementation and targeted tests. + **Status**: ✅ Phases 0-2 Complete **Date Completed**: 2025-11-15 **Lines of Code**: ~2000 (core + tests + documentation) diff --git a/docs/engineering/jvnautosci_799_quick_reference.md b/docs/engineering/jvnautosci_799_quick_reference.md index e9444e9b2..b42b260ba 100644 --- a/docs/engineering/jvnautosci_799_quick_reference.md +++ b/docs/engineering/jvnautosci_799_quick_reference.md @@ -1,9 +1,12 @@ -""" -JVNAUTOSCI-799: Structured Tool Calling - Quick Reference +# JVNAUTOSCI-799 Structured Tool Calling Quick Reference -Short reference for using the structured tool calling module. -For detailed docs, see: structured_tool_calling_guide.md -""" +> **Document status: Legacy component reference; last evidenced during +> JVNAUTOSCI-799 in 2025.** The component still exists, but API names, provider +> examples, fallbacks, and integration behaviour below are not guaranteed +> current. Inspect the current package and targeted tests before copying code. + +For the associated historical guide, see +[`structured_tool_calling_guide.md`](structured_tool_calling_guide.md). ## Import Everything You Need diff --git a/docs/engineering/llm_workflows_design.md b/docs/engineering/llm_workflows_design.md index e14a6762f..9eb0ad9e1 100644 --- a/docs/engineering/llm_workflows_design.md +++ b/docs/engineering/llm_workflows_design.md @@ -1,6 +1,12 @@ # LLM Workflows: Design Document -**Status**: Draft +> **Document status: Historical design precursor; non-normative.** Current-state +> and gap descriptions reflect December 2025 and have been overtaken by later +> implementation. Preserve this as design rationale, but use the current VWL +> manual and live code/Vontology state for workflow planning. + +**Lifecycle**: Superseded design precursor +**Authority**: Historical only **Version**: 1.0 **Date**: 2025-12-21 **JIRA**: [JVNAUTOSCI-803](https://naoinstitute.atlassian.net/browse/JVNAUTOSCI-803) diff --git a/docs/engineering/mcp_reliability_analysis.md b/docs/engineering/mcp_reliability_analysis.md index c82631e60..ad747cf67 100644 --- a/docs/engineering/mcp_reliability_analysis.md +++ b/docs/engineering/mcp_reliability_analysis.md @@ -1,5 +1,11 @@ # Analysis: Why MCP Service Wasn't Used & How to Fix It +> **Document status: Historical incident reflection; evidence date not recorded.** +> It explains one mistaken implementation approach and may retain a useful MCP +> invariant, but its tool inventory and proposed fixes are not current MCP +> documentation. Re-discover the live MCP surface and use current operational +> guidance before acting. + ## What I Did (Wrong Approach) I performed critical Vontology operations by writing manual Python scripts: 1. Used `text_value_service.upsert_text_for_concept()` to add detector prompt text diff --git a/docs/engineering/minimal_imposition_design_principle.md b/docs/engineering/minimal_imposition_design_principle.md index 774e6ff51..02c2a96e3 100644 --- a/docs/engineering/minimal_imposition_design_principle.md +++ b/docs/engineering/minimal_imposition_design_principle.md @@ -1,7 +1,12 @@ # Minimal Imposition as a Design Principle for Von -**Status**: Draft design guidance -**Date**: 2026-04-03 +- **Kind:** Design principle +- **Lifecycle:** Active +- **Authority:** Normative within the minimal-imposition, elicitation, and + write-policy scope selected by `AGENTS.md`, subject to the precedence stated + below +- **Created:** 2026-04-03 +- **Freshness boundary:** Principle, not current implementation evidence ## 1. Purpose diff --git a/docs/engineering/operational_engineering_guide.md b/docs/engineering/operational_engineering_guide.md index 4d82be831..0a4309329 100644 --- a/docs/engineering/operational_engineering_guide.md +++ b/docs/engineering/operational_engineering_guide.md @@ -1,7 +1,11 @@ # Operational Engineering Guide for Coding Agents -**Status**: Living practical guidance -**Date**: 2026-04-04 +- **Kind:** Operational runbook and practical guidance +- **Lifecycle:** Active +- **Authority:** Canonical operational companion selected by `AGENTS.md` +- **Created:** 2026-04-04 +- **Last substantive content update before this metadata review:** 2026-07-11 +- **Freshness boundary:** Revalidate environment-, host-, and tool-specific facts ## 1. Purpose diff --git a/docs/engineering/phase3_orchestrator_integration_summary.md b/docs/engineering/phase3_orchestrator_integration_summary.md index c72eba3d6..2c449768d 100644 --- a/docs/engineering/phase3_orchestrator_integration_summary.md +++ b/docs/engineering/phase3_orchestrator_integration_summary.md @@ -1,5 +1,11 @@ # Phase 3: Orchestrator Integration - Completion Summary +> **Document status: Historical JVNAUTOSCI-799 implementation record from +> December 2025.** “Complete”, replacement, validation, and “ready for +> deployment” claims below are phase-local historical claims, not evidence of +> current architecture, reliability, or production readiness. Revalidate the +> present orchestrator path and tests before relying on them. + **JIRA Issue**: JVNAUTOSCI-799 **Status**: ✅ Complete **Date**: December 2025 diff --git a/docs/engineering/real_path_server_replay_and_telemetry_loop.md b/docs/engineering/real_path_server_replay_and_telemetry_loop.md index 686d6a56d..3c7d68569 100644 --- a/docs/engineering/real_path_server_replay_and_telemetry_loop.md +++ b/docs/engineering/real_path_server_replay_and_telemetry_loop.md @@ -1,7 +1,13 @@ # Real-Path Server Replay and Telemetry Loop -**Status**: Living practical guidance -**Date**: 2026-04-17 +- **Kind:** Validation protocol and practical guidance +- **Lifecycle:** Active +- **Authority:** Required by `AGENTS.md` for live user-visible behaviour, + real-path replay, and telemetry-based diagnosis +- **Created:** 2026-04-17 +- **Last substantive content update before this metadata review:** 2026-07-11 +- **Evidence boundary:** Each acceptance claim still requires its own dated + exact-path evidence ## 1. Purpose diff --git a/docs/engineering/recent_architecture_progress_2026-04-20.md b/docs/engineering/recent_architecture_progress_2026-04-20.md index 0a182fe58..bcc0731bb 100644 --- a/docs/engineering/recent_architecture_progress_2026-04-20.md +++ b/docs/engineering/recent_architecture_progress_2026-04-20.md @@ -174,7 +174,7 @@ The remaining work is now more concentrated. The biggest live problems are no lo ### 1. Buttonify’s residual heuristic helper slab has now been removed -**Location:** [buttonify_service.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/services/buttonify_service.py:152) +**Location:** [buttonify_service.py](../../src/backend/services/buttonify_service.py) The live route/workflow path was already structured-output-first through `#V#chat_buttonify_workflow` and `buttonify_options_json`, but `buttonify_service.py` still carried residual heuristic/prose-recovery helpers and stale tests/docs that obscured the intended authority boundary. @@ -182,7 +182,7 @@ That residual slab is now gone. Buttonify options are validated from structured ### 2. The orchestrator remains the biggest structural risk -**Location:** [orchestrator.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/integrations/internal_mcp/orchestrator.py:28634) +**Location:** [orchestrator.py](../../src/backend/integrations/internal_mcp/orchestrator.py) Even after the recent cleanups, `InternalMCPChatOrchestrator` is still an oversized integration monolith. The most egregious surviving semantic slab from the previous draft, the structured tool-family prompt-keyword heuristic block, is gone, and `1954`/`1955` repaired two important grounded-answer failure families. But the class still combines too many concerns: @@ -196,19 +196,19 @@ This is the main structural reason new hacks tend to accumulate here first. ### 3. Backend route layers improved materially, but the monolith is still too large -**Location:** [von_routes.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/server/routes/von_routes.py) +**Location:** [von_routes.py](../../src/backend/server/routes/von_routes.py) `JVNAUTOSCI-1121` is now done, and it made a real structural dent: the `/von/generate` durable-turn lifecycle, chat-history persistence, and success/error payload shaping helpers were extracted into `generate_route_support.py`, taking several hundred lines out of `von_routes.py` and giving later route work clearer seams. But the backend route layer is still large and mixed in responsibility, so this remains an ongoing structural concern rather than a solved problem. ### 4. Flask app-factory sprawl is no longer the main route-layer blocker -**Location:** [utils_flask.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/server/utils_flask.py) +**Location:** [utils_flask.py](../../src/backend/server/utils_flask.py) `JVNAUTOSCI-1825` is now done. The old `create_flask_app(...)` slab has been cut down materially by extracting request timing/configuration, startup bootstrap, chat-history admin context resolution, diagnostics helpers, and prewarm wiring into explicit support surfaces. The file is still large, but the structural risk has shifted away from one huge all-purpose app-factory function and toward the remaining large route modules themselves. ### 5. Catalogue size is still large, but the risk has shifted -**Location:** [catalogue.py](/C:/Users/mwit860/Programming/Strong-AI-Lab/Von/src/backend/integrations/internal_mcp/catalogue.py:29952) +**Location:** [catalogue.py](../../src/backend/integrations/internal_mcp/catalogue.py) `JVNAUTOSCI-1827` already removed the worst inline assembly slab by turning `build_default_catalogue()` into a composition layer over builder helpers. The file is still very large, but the remaining risk is now more about size, merge pressure, and further per-family decomposition than about one egregious remaining semantic-hack block. diff --git a/docs/engineering/security_considerations.md b/docs/engineering/security_considerations.md index 8dfe8a479..152c9ee43 100644 --- a/docs/engineering/security_considerations.md +++ b/docs/engineering/security_considerations.md @@ -1,5 +1,13 @@ # Security Considerations for Von +- **Kind:** Security guidance with dated deployment-posture observations +- **Lifecycle:** Active +- **Authority:** Always mandatory under [`AGENTS.md`](../../AGENTS.md) +- **Evidence boundary:** Statements about current users, deployments, and + implemented controls are dated observations and must be revalidated; the + security requirements do not expire merely because implementation evidence + changes + ## Critical Security Context **Von is currently a research prototype. As far as we know on 2026-04-24, the @@ -54,11 +62,13 @@ Use different controls for different data and capability classes. ## Known Security Limitations -### 1. Authentication Required (SECURE - Implemented December 2024) +### 1. Narrow authentication safeguard implemented in December 2024 **Location**: `src/backend/server/routes/von_routes.py` - `/generate` endpoint -**Status**: ✅ **SECURE** - Client-provided user IDs are now **rejected** +**Bounded result**: Client-provided user IDs are rejected on the named path. +This is not a claim that Von's authentication or deployment posture is secure +as a whole. **Implementation**: The system requires proper authentication for private user/org-scoped operations via: diff --git a/docs/engineering/structured_tool_calling_guide.md b/docs/engineering/structured_tool_calling_guide.md index 4f3b14477..de5f7c6cb 100644 --- a/docs/engineering/structured_tool_calling_guide.md +++ b/docs/engineering/structured_tool_calling_guide.md @@ -1,4 +1,9 @@ -"""Structured Tool Calling Module - Documentation & Usage Guide +# Structured Tool Calling Module — Historical Usage Guide + +> **Document status: Legacy component reference; last evidenced during +> JVNAUTOSCI-799 in 2025.** The component still exists, but API names, provider +> examples, fallbacks, and integration behaviour below are not guaranteed +> current. Inspect the current package and targeted tests before copying code. ## Overview @@ -465,4 +470,3 @@ docs/engineering/ - Michael Witbrock (Von Lab, University of Auckland) See JIRA task JVNAUTOSCI-799 for detailed design and acceptance criteria. -""" diff --git a/docs/engineering/testing_workflows_ephemeral_theories_design.md b/docs/engineering/testing_workflows_ephemeral_theories_design.md index f1ee9686d..f501d4415 100644 --- a/docs/engineering/testing_workflows_ephemeral_theories_design.md +++ b/docs/engineering/testing_workflows_ephemeral_theories_design.md @@ -64,10 +64,10 @@ The literature scan in this task found adjacent work, but not an exact match for Von already has the core workflow runtime and durable execution model: -1. [von_workflow_language_manual.md](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/docs/engineering/von_workflow_language_manual.md) -2. [durable_workflow_system_design.md](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/docs/engineering/durable_workflow_system_design.md) -3. [models.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/workflows/durable/models.py) -4. [plan_state_runtime.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/workflows/plan_state_runtime.py) +1. [von_workflow_language_manual.md](von_workflow_language_manual.md) +2. [durable_workflow_system_design.md](durable_workflow_system_design.md) +3. [models.py](../../src/backend/workflows/durable/models.py) +4. [plan_state_runtime.py](../../src/backend/workflows/plan_state_runtime.py) Relevant consequences: @@ -80,9 +80,9 @@ Relevant consequences: There is already a notion of `transient_microtheory`, but only as a payload shape for renderer applicability: -1. [renderer_applicability_service.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/services/renderer_applicability_service.py) -2. [orchestrator.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/integrations/internal_mcp/orchestrator.py) -3. [renderer_applicability_vontology_service.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/services/renderer_applicability_vontology_service.py) +1. [renderer_applicability_service.py](../../src/backend/services/renderer_applicability_service.py) +2. [orchestrator.py](../../src/backend/integrations/internal_mcp/orchestrator.py) +3. [renderer_applicability_vontology_service.py](../../src/backend/services/renderer_applicability_vontology_service.py) This is important because it shows the system already accepts an object kind that is neither a canonical concept nor a free-text blob. It is a strong seed for a more general ephemeral-theory design. @@ -90,9 +90,9 @@ This is important because it shows the system already accepts an object kind tha Von already records structured execution evidence and benchmarkable failure signals: -1. [turn_execution_completion_schema_proposal.md](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/docs/engineering/turn_execution_completion_schema_proposal.md) -2. [turn_execution_record_service.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/services/turn_execution_record_service.py) -3. `turn_execution_*` MCP tools in [catalogue.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/integrations/internal_mcp/catalogue.py) +1. [turn_execution_completion_schema_proposal.md](turn_execution_completion_schema_proposal.md) +2. [turn_execution_record_service.py](../../src/backend/services/turn_execution_record_service.py) +3. `turn_execution_*` MCP tools in [catalogue.py](../../src/backend/integrations/internal_mcp/catalogue.py) This means Testing Workflows do not need to invent result evidence from scratch. They should extend this discipline to theory experiments. @@ -100,8 +100,8 @@ This means Testing Workflows do not need to invent result evidence from scratch. Von already has a guarded end-to-end benchmark harness: -1. [kb_clone_benchmark_harness.md](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/docs/engineering/kb_clone_benchmark_harness.md) -2. [kb_clone_benchmark_service.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/services/kb_clone_benchmark_service.py) +1. [kb_clone_benchmark_harness.md](kb_clone_benchmark_harness.md) +2. [kb_clone_benchmark_service.py](../../src/backend/services/kb_clone_benchmark_service.py) This is already suitable for destructive integration tests and system-wide experiments. It is too heavy for rapid internal experimentation, but it should become Tier 2 of the Testing Workflows design rather than a parallel subsystem. @@ -109,9 +109,9 @@ This is already suitable for destructive integration tests and system-wide exper Von already has the pattern "identify a workflow gap, create a candidate, optionally test it, then decide whether to use it": -1. [workflow_gap_recovery_workflow.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/workflows/durable/workflow_gap_recovery_workflow.py) -2. [workflow_gap_workflow_contracts.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/workflows/workflow_gap_workflow_contracts.py) -3. [workflow_creation_contracts.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/workflows/workflow_creation_contracts.py) +1. [workflow_gap_recovery_workflow.py](../../src/backend/workflows/durable/workflow_gap_recovery_workflow.py) +2. [workflow_gap_workflow_contracts.py](../../src/backend/workflows/workflow_gap_workflow_contracts.py) +3. [workflow_creation_contracts.py](../../src/backend/workflows/workflow_creation_contracts.py) That is already very close in spirit to Testing Workflows. @@ -119,9 +119,9 @@ That is already very close in spirit to Testing Workflows. Von already has learning-oriented workflow selection and episode history machinery: -1. [workflow_selection_experience.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/services/workflow_selection_experience.py) -2. [workflow_selection_policy_service.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/services/workflow_selection_policy_service.py) -3. [workflow_episode_service.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/services/workflow_episode_service.py) +1. [workflow_selection_experience.py](../../src/backend/services/workflow_selection_experience.py) +2. [workflow_selection_policy_service.py](../../src/backend/services/workflow_selection_policy_service.py) +3. [workflow_episode_service.py](../../src/backend/services/workflow_episode_service.py) Testing Workflows should consume and emit signals compatible with those services. @@ -157,8 +157,8 @@ The safety model is not complete enough yet for theory inclusion and self-experi Relevant evidence: -1. [security_considerations.md](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/docs/engineering/security_considerations.md) explicitly says namespace is intended to interact with future microtheory and theory-inclusion work. -2. [effective_namespace_contract.md](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/docs/engineering/effective_namespace_contract.md) already defines one authoritative namespace-resolution path, but not theory inclusion semantics. +1. [security_considerations.md](security_considerations.md) explicitly says namespace is intended to interact with future microtheory and theory-inclusion work. +2. [effective_namespace_contract.md](effective_namespace_contract.md) already defines one authoritative namespace-resolution path, but not theory inclusion semantics. Missing capabilities: @@ -369,8 +369,8 @@ Current recommendation: Relevant existing substrates: -1. [uncertain_relationship_service.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/services/uncertain_relationship_service.py) -2. [relation_elicitation_service.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/services/relation_elicitation_service.py) +1. [uncertain_relationship_service.py](../../src/backend/services/uncertain_relationship_service.py) +2. [relation_elicitation_service.py](../../src/backend/services/relation_elicitation_service.py) ## 9. Workflow Architecture @@ -425,7 +425,7 @@ Canonical ontology writes should occur only in a separate promotion workflow. ## 10.2 Namespace and theory inclusion -Namespace must become the main access-safety primitive for theory inclusion and promotion. This is already anticipated in [security_considerations.md](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/docs/engineering/security_considerations.md). +Namespace must become the main access-safety primitive for theory inclusion and promotion. This is already anticipated in [security_considerations.md](security_considerations.md). Required policy: diff --git a/docs/engineering/testing_workflows_framework_plan.md b/docs/engineering/testing_workflows_framework_plan.md index 99fd5ae3a..b0fb39173 100644 --- a/docs/engineering/testing_workflows_framework_plan.md +++ b/docs/engineering/testing_workflows_framework_plan.md @@ -163,10 +163,10 @@ This matters because Testing Workflows can now rely on an authoritative workflow Relevant existing bases: -1. [von_workflow_language_manual.md](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/docs/engineering/von_workflow_language_manual.md) -2. [durable_workflow_system_design.md](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/docs/engineering/durable_workflow_system_design.md) -3. [models.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/workflows/durable/models.py) -4. [plan_state_runtime.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/workflows/plan_state_runtime.py) +1. [von_workflow_language_manual.md](von_workflow_language_manual.md) +2. [durable_workflow_system_design.md](durable_workflow_system_design.md) +3. [models.py](../../src/backend/workflows/durable/models.py) +4. [plan_state_runtime.py](../../src/backend/workflows/plan_state_runtime.py) What these already give us: @@ -180,8 +180,8 @@ What these already give us: Relevant existing bases: -1. [turn_execution_completion_schema_proposal.md](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/docs/engineering/turn_execution_completion_schema_proposal.md) -2. [turn_execution_record_service.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/services/turn_execution_record_service.py) +1. [turn_execution_completion_schema_proposal.md](turn_execution_completion_schema_proposal.md) +2. [turn_execution_record_service.py](../../src/backend/services/turn_execution_record_service.py) 3. `turn_execution_*` internal MCP tools. This gives Testing Workflows a model for: @@ -194,8 +194,8 @@ This gives Testing Workflows a model for: Relevant existing bases: -1. [kb_clone_benchmark_harness.md](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/docs/engineering/kb_clone_benchmark_harness.md) -2. [kb_clone_benchmark_service.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/services/kb_clone_benchmark_service.py) +1. [kb_clone_benchmark_harness.md](kb_clone_benchmark_harness.md) +2. [kb_clone_benchmark_service.py](../../src/backend/services/kb_clone_benchmark_service.py) This is already a good Tier 2 runner. It should be treated as the heavyweight backend of the testing framework, not a separate evaluation universe. @@ -203,10 +203,10 @@ This is already a good Tier 2 runner. It should be treated as the heavyweight ba Relevant existing bases: -1. [workflow_gap_recovery_workflow.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/workflows/durable/workflow_gap_recovery_workflow.py) -2. [workflow_selection_experience.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/services/workflow_selection_experience.py) -3. [workflow_selection_policy_service.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/services/workflow_selection_policy_service.py) -4. [workflow_episode_service.py](/c:/Users/witbr/Documents/Programming/Strong-AI-Lab/Von/src/backend/services/workflow_episode_service.py) +1. [workflow_gap_recovery_workflow.py](../../src/backend/workflows/durable/workflow_gap_recovery_workflow.py) +2. [workflow_selection_experience.py](../../src/backend/services/workflow_selection_experience.py) +3. [workflow_selection_policy_service.py](../../src/backend/services/workflow_selection_policy_service.py) +4. [workflow_episode_service.py](../../src/backend/services/workflow_episode_service.py) These already suggest the right shape: diff --git a/docs/engineering/von_workflow_language_manual.md b/docs/engineering/von_workflow_language_manual.md index be424316d..f3cce738b 100644 --- a/docs/engineering/von_workflow_language_manual.md +++ b/docs/engineering/von_workflow_language_manual.md @@ -1,8 +1,15 @@ # Von Workflow Language (VWL) Manual -Status: Draft (current implementation-aligned) -Last updated: 2026-05-03 (Pacific/Auckland) -Audience: Human engineers and AI agents +- **Kind:** Workflow-language manual +- **Lifecycle:** Active +- **Authority:** Canonical reference for VWL vocabulary, authoring rules, and + runtime interfaces; required by `AGENTS.md` for workflow/orchestration work +- **Live-authority boundary:** Live Vontology artefacts govern individual + workflow definitions; current code, tests, and telemetry govern observed + runtime behaviour +- **Created:** 2026-05-03 +- **Last substantive content update before this metadata review:** 2026-07-11 +- **Audience:** Human engineers and AI agents ## 1. Purpose and Scope diff --git a/docs/engineering/vwl_implementation_audit_2026-03-24.md b/docs/engineering/vwl_implementation_audit_2026-03-24.md index fbd9a6326..5f8ba595f 100644 --- a/docs/engineering/vwl_implementation_audit_2026-03-24.md +++ b/docs/engineering/vwl_implementation_audit_2026-03-24.md @@ -1,5 +1,10 @@ # VWL Implementation Audit 2026-03-24 +> **Document status: Frozen audit and correction record from March 2026.** Its +> authority lessons may remain relevant, but completion state, code anchors, +> fallback paths, and Jira sequencing require current verification. Use the VWL +> manual and live Vontology/runtime evidence as the implementation reference. + Task: `JVNAUTOSCI-1575` Date: 2026-03-24 diff --git a/docs/engineering/workflow_audit_2026-02-07.md b/docs/engineering/workflow_audit_2026-02-07.md index a3c1a1824..ce964638a 100644 --- a/docs/engineering/workflow_audit_2026-02-07.md +++ b/docs/engineering/workflow_audit_2026-02-07.md @@ -1,5 +1,10 @@ # Workflow System Audit — 2026-02-07 +> **Document status: Frozen audit snapshot from 7 February 2026.** The fixes, +> gaps, Jira states, and implementation anchors below describe that session, +> not current workflow behaviour. Use the VWL manual and live +> Vontology/code/telemetry evidence for new work. + ## Summary This audit reviews the recent workflow system changes in the context of Jira tasks diff --git a/docs/engineering/workflow_authoritative_publication_process.md b/docs/engineering/workflow_authoritative_publication_process.md index 1db32ef3e..2699f1194 100644 --- a/docs/engineering/workflow_authoritative_publication_process.md +++ b/docs/engineering/workflow_authoritative_publication_process.md @@ -1,5 +1,16 @@ # Workflow Authoritative Publication Process +> **Document status: Dated implementation note from 20 February 2026.** The +> Vontology-authority invariant remains applicable. The named bootstrap and +> publication functions below are historical implementation anchors, not the +> exclusive current authoring procedure. Follow the current VWL manual, live +> Vontology tooling, and authority read-back for new work. + +- **Kind:** Implementation note with a retained authority invariant +- **Lifecycle:** Frozen +- **Authority:** Advisory implementation detail; the authority invariant is + governed by `AGENTS.md` + Date: 2026-02-20 Related: `JVNAUTOSCI-803`, `JVNAUTOSCI-1217` diff --git a/docs/engineering/workflow_execution_architecture_analysis.md b/docs/engineering/workflow_execution_architecture_analysis.md index d59d94e2e..be4c45c30 100644 --- a/docs/engineering/workflow_execution_architecture_analysis.md +++ b/docs/engineering/workflow_execution_architecture_analysis.md @@ -1,9 +1,19 @@ # Von Workflow Execution Architecture: Intended Design vs Current Reality -**Status**: Analytical paper — not a specification -**Date**: 2026-04-07 -**Author**: Analysis prepared for Michael Witbrock -**Trigger**: Observed failure-to-communicate in a live arXiv paper ingestion turn (session `d57ab88b`, request `51a65483`), where the system silently created a file copy and a paper concept without telling the user +> **Document status: Dated diagnostic snapshot; not a current implementation +> guide.** Present-tense claims, source line numbers, workflow inventories, and +> Jira conclusions describe evidence available on 7 April 2026. Architectural +> questions may remain useful, but revalidate every factual claim against +> current code, live Vontology, telemetry, and Jira before implementation. + +- **Kind:** Diagnostic analysis +- **Lifecycle:** Frozen +- **Authority:** Evidence only; not a specification +- **State as of:** 2026-04-07 +- **Author:** Analysis prepared for Michael Witbrock +- **Trigger:** Observed failure-to-communicate in a live arXiv paper ingestion + turn (session `d57ab88b`, request `51a65483`), where the system silently + created a file copy and a paper concept without telling the user --- diff --git a/docs/engineering/workflow_first_conversion_sweep_jvnautosci_1210.md b/docs/engineering/workflow_first_conversion_sweep_jvnautosci_1210.md index b438739ad..3e55f87f2 100644 --- a/docs/engineering/workflow_first_conversion_sweep_jvnautosci_1210.md +++ b/docs/engineering/workflow_first_conversion_sweep_jvnautosci_1210.md @@ -81,4 +81,9 @@ These are workflow-first migration candidates for follow-on work: `JVNAUTOSCI-1217` adds strict publication/runnability gates and deterministic definition identity/hash telemetry for workflow monitor/introspection surfaces. -See `docs/engineering/workflow_authoritative_publication_process.md` for the authoritative publication procedure and validation expectations. +The dated +[`workflow_authoritative_publication_process.md`](workflow_authoritative_publication_process.md) +records the February 2026 implementation provenance. For current authoring and +validation procedure, use the +[`von_workflow_language_manual.md`](von_workflow_language_manual.md), live +Vontology tooling, and authority read-back. diff --git a/docs/engineering/workflow_self_authoring_gap_analysis.md b/docs/engineering/workflow_self_authoring_gap_analysis.md index 320fb6a87..e73f9d69a 100644 --- a/docs/engineering/workflow_self_authoring_gap_analysis.md +++ b/docs/engineering/workflow_self_authoring_gap_analysis.md @@ -1,9 +1,16 @@ # Workflow Self-Authoring and Intent Generation: Gap Analysis & Plan -**Status**: Draft -**Date**: 2026-04-05 -**Related Epics**: `JVNAUTOSCI-833`, `JVNAUTOSCI-964`, `JVNAUTOSCI-1586` -**Related Tasks**: `JVNAUTOSCI-1531`, `JVNAUTOSCI-1654`, `JVNAUTOSCI-1574` +> **Document status: Dated gap analysis and proposed plan; not current programme +> authority.** “Current”, “exists”, “missing”, and task-ordering claims reflect +> the 5–6 April 2026 audit. Re-read live Jira, code, Vontology materialisation, +> and current VWL authority rules before planning. + +- **Kind:** Gap analysis and design proposal +- **Lifecycle:** Frozen proposal +- **Authority:** Advisory only +- **State as of:** 2026-04-06 +- **Related Epics:** `JVNAUTOSCI-833`, `JVNAUTOSCI-964`, `JVNAUTOSCI-1586` +- **Related Tasks:** `JVNAUTOSCI-1531`, `JVNAUTOSCI-1654`, `JVNAUTOSCI-1574` ## 1. Purpose This document examines the extent to which Von meets its goal of driving user interaction behaviours primarily through workflows that are self-authored following collaborative problem-solving sessions. It outlines the met goals, identifies the architectural gaps, and provides a concrete implementation plan.