updates

Author: KSemenenko

.github/workflows/jekyll-gh-pages.yml

@@ -30,15 +30,15 @@ jobs:
         id: changes
         run: |
           git fetch origin main --depth=2
-          # Get files changed, excluding github-pages/ and .github/
-          CONTENT_CHANGES=$(git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -vE '^(github-pages/|\.github/|$)' || true)
-          # Release only if there are content changes
+          # Only these files trigger a release (actual documentation)
+          CONTENT_CHANGES=$(git diff --name-only HEAD~1 HEAD 2>/dev/null | grep -E '^(README\.md|TUTORIAL\.md|CREDITS\.md|docs/)' || true)
+          # Release only if there are documentation changes
           if [ -n "$CONTENT_CHANGES" ]; then
-            echo "Content changes detected:"
+            echo "Documentation changes detected:"
             echo "$CONTENT_CHANGES"
             echo "release=true" >> $GITHUB_OUTPUT
           else
-            echo "No content changes, skipping release"
+            echo "No documentation changes, skipping release"
             echo "release=false" >> $GITHUB_OUTPUT
           fi
 

CREDITS.md

@@ -1,16 +1,16 @@
 # Credits
 
-MCAF is an open framework built by developers who believe AI coding agents need structure, not just prompts. 
+MCAF is an open framework built by developers who believe AI coding agents need structure, not just prompts.
 This page recognizes the people who made it happen.
 
 ## Contributors
 
-- [Managed Code](https://www.managed-code.com) — Framework design and development
+- <a href="https://www.managed-code.com" target="_blank">Managed Code</a> — Framework design and development
 
 ## Special Thanks
 
-- **[Roger Johansson](https://www.linkedin.com/in/roger-johansson-4a4bb61/)** — His post about self-learning code agents inspired the self-learning logic that became the core of MCAF
+- **<a href="https://www.linkedin.com/in/roger-johansson-4a4bb61/" target="_blank">Roger Johansson</a>** — His post about self-learning code agents inspired the self-learning logic that became the core of MCAF
 
 ---
 
-*Want to contribute? Open a PR or issue on [GitHub](https://github.com/managedcode/MCAF).*
+*Want to contribute? Open a PR or issue on <a href="https://github.com/managedcode/MCAF" target="_blank">GitHub</a>.*

README.md

@@ -146,10 +146,26 @@ MCAF uses several levels of tests:
 
 Coverage expectations:
 
-- Each significant feature or functional behaviour has at least one integration-level test for its core flow.  
-- If behaviour is exposed via API, there is at least one API test for it.  
-- If behaviour is visible to users through UI, there is at least one UI/E2E test for it.  
-- Unit tests are added when internal logic is complex, critical, or performance-sensitive.  
+- Each significant feature or functional behaviour has sufficient tests to cover its possible cases; at minimum, one integration-level test for the core flow.
+- If behaviour is exposed via API, each public endpoint has at least one API test; complex endpoints have tests for different input variations and error conditions.
+- API and integration tests must exercise real flows end-to-end, not just call endpoints in isolation; tests verify that components work together correctly.
+- If behaviour is visible to users through UI, there is at least one UI/E2E test for it; critical user flows have tests for main and alternative paths.
+- Unit tests are added when internal logic is complex, critical, or performance-sensitive.
+- The goal is not "one test per feature" but "enough tests to have confidence in the behaviour"; one is the minimum, not the target.
+
+Code coverage:
+
+- Code coverage is measured and tracked to see which functionality is actually tested.
+- Coverage reports show which functions, branches, and flows are exercised by tests — and which are not.
+- Coverage reports are generated as part of CI or on demand.
+- Low coverage in critical modules triggers review and test planning.
+- Coverage is a tool for finding gaps, not a target to game; 100% coverage with weak assertions is worse than 70% coverage with meaningful tests.
+
+Test quality:
+
+- Each test verifies a real flow or scenario, not just that a function can be called.
+- Tests without meaningful assertions are forbidden; a test that only calls code without verifying outcomes is not a valid test.
+- Tests check behaviour and outcomes, not implementation details.  
 
 Tests cover:
 
@@ -283,12 +299,30 @@ In large repositories, directories may have their own `AGENTS.md` files. They:
 - add stricter requirements without contradicting MCAF principles  
 - apply to files in that directory and its subdirectories  
 
-### 4.6 Hard rules for Instructions
+### 4.6 AGENTS.md governance
+
+`AGENTS.md` is a critical document that shapes how AI agents work in the repository. Changes to it affect all future AI-assisted development.
+
+Change approval:
+
+- Changes to the root `AGENTS.md` require review and approval by a designated owner or lead maintainer.
+- The owner of `AGENTS.md` is defined in the document itself or in `CODEOWNERS`.
+- AI agents may propose changes to `AGENTS.md`, but humans approve and merge them.
+- Significant rule changes are discussed with the team before merging.
+
+Review criteria for `AGENTS.md` changes:
+
+- The change aligns with MCAF principles.
+- The rule is clear and actionable.
+- The rule does not contradict existing rules without explicit replacement.
+- The rule reflects a stable pattern, not a one-time preference.
 
-- Every repository that uses MCAF has a root `AGENTS.md`.  
-- Root `AGENTS.md` is in English and aligned with this Guide.  
-- Agents read `AGENTS.md` and relevant docs before editing code.  
-- Stable patterns and lessons are recorded in `AGENTS.md` or docs; chat alone is not memory.  
+### 4.7 Hard rules for Instructions
+
+- Every repository that uses MCAF has a root `AGENTS.md`.
+- Root `AGENTS.md` is in English and aligned with this Guide.
+- Agents read `AGENTS.md` and relevant docs before editing code.
+- Stable patterns and lessons are recorded in `AGENTS.md` or docs; chat alone is not memory.
 - Automation and agent instructions rely only on documented `build`, `test`, `format`, and `analyze` commands.
 
 ---
@@ -573,4 +607,23 @@ To adopt MCAF in a repository:
    - updated docs and `AGENTS.md`  
    - human review and merge  
 
-MCAF is considered active only when these practices are followed in day-to-day work, not just written down.
+MCAF is considered active only when these practices are followed in day-to-day work, not just written down.
+
+---
+
+## 10. Ownership and Process
+
+### 10.1 Ownership
+
+Every significant feature, document, and decision has an accountable owner:
+
+- Feature docs — owned by the feature owner (Product perspective).
+- ADRs — owned by the person who made the decision.
+- Test docs — owned by QA or the feature owner.
+- `AGENTS.md` — see governance rules in section 4.6.
+
+### 10.2 Process
+
+- **Onboarding**: New team members read this Guide, the root `AGENTS.md`, and key docs before making changes.
+- **Regular review**: The team periodically reviews `AGENTS.md` and docs to ensure they reflect current practices.
+- **Feedback loops**: Issues with AI agent behaviour are tracked and lead to `AGENTS.md` or doc updates, not repeated chat corrections.

docs/templates/AGENTS.md

@@ -11,6 +11,13 @@ Follows [MCAF](https://mcaf.managed-code.com/)
 
 Learn the user's habits, preferences, and working style. Extract rules from conversations, save to "## Rules to follow", and generate code according to the user's personal rules.
 
+**Update requirement (core mechanism):**
+
+Before doing ANY task, evaluate the latest user message.  
+If you detect a new rule, correction, preference, or change → update `agents.md` first.  
+Only after updating the file you may produce the task output.  
+If no new rule is detected → do not update the file.
+
 **When to extract rules:**
 
 - prohibition words (never, don't, stop, avoid) or similar → add NEVER rule
@@ -73,6 +80,7 @@ Learn the user's habits, preferences, and working style. Extract rules from conv
 - Run tests in layers: new → related suite → broader regressions
 - After all tests pass: run format, then build
 - Summarize changes and test results before marking complete
+- Always run required builds and tests yourself; do not ask the user to execute them (explicit user directive).
 
 ### Documentation (ALL TASKS)
 
@@ -87,11 +95,15 @@ Learn the user's habits, preferences, and working style. Extract rules from conv
 
 <!-- CUSTOMIZE (remove after): your test structure -->
 
-- Every behaviour change needs automated tests
+- Every behaviour change needs sufficient automated tests to cover its cases; one is the minimum, not the target
+- Each public API endpoint has at least one test; complex endpoints have tests for different inputs and errors
+- Integration tests must exercise real flows end-to-end, not just call endpoints in isolation
 - Prefer integration/API/UI tests over unit tests
 - No mocks for internal systems (DB, queues, caches) — use containers
 - Mocks only for external third-party systems
 - Never delete or weaken a test to make it pass
+- Each test verifies a real flow or scenario, not just calls a function — tests without meaningful assertions are forbidden
+- Check code coverage to see which functionality is actually tested; coverage is for finding gaps, not a number to chase
 
 ### Autonomy