@moon791017/neo-skills 1.0.32 → 1.0.33

package/README.md

@@ -63,7 +63,10 @@
 ### 10. 需求釐清助手
 *   **需求釐清**：系統化引導用戶釐清模糊需求，並將其轉化為結構化的規格文件（背景、功能、約束、驗收標準）。
 
-### 11. 安全守衛 (Security Guard)
+### 11. AI 開發流程健檢
+*   **AI 助手開發治理 (`skills/neo-agent-harness`)**：檢查專案規則、測試、CI、審查流程與安全防護是否足夠清楚，協助 AI 助手更穩定、更安全地參與開發。
+
+### 12. 安全守衛 (Security Guard)
 *   **主動防護 (`secret-guard.ts`)**：作為 CLI 的中介軟體 (Hook)，自動攔截並掃描所有工具執行的參數。若偵測到敏感資訊（如環境設定檔、私鑰、雲端憑證等）將強制阻擋執行，防止機密外洩。
 
 ## 📂 系統架構
@@ -215,6 +218,7 @@ npx -p @moon791017/neo-skills install-system-instructions \
 | **全方位程式碼審查** | `幫我 code review 剛才的修改` |
 | **生成 C# Interface** | `幫我針對這個 class 產生介面` |
 | **技術解析與架構洞察** | `分析這個專案的架構` |
+| **AI 開發流程健檢** | `幫我檢查這個專案怎麼讓 AI 助手開發得更穩、更安全` |
 
 ## 🛠 開發指南
 

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "name": "neo-skills",
   "description": "A universal capability extension for Gemini CLI",
-  "version": "0.56.2",
+  "version": "0.57.1",
   "mcpServers": {
     "neo-skills": {
       "command": "node",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.0.32",
+  "version": "1.0.33",
   "type": "module",
   "description": "Neo Skills: A Universal Expert Agent Extension",
   "homepage": "https://neo-blog-iota.vercel.app/",
@@ -20,7 +20,6 @@
     "dist",
     "bin",
     "skills",
-    "commands",
     "gemini-extension.json",
     "GEMINI.md"
   ],

package/skills/neo-agent-harness/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: neo-agent-harness
+description: 分析專案的 AI agent harnessability，設計 feedforward guides、feedback sensors、驗證流程與人類決策點，用於提升 agent 輔助開發品質。
+---
+
+# Agent Harness Architect Skill
+
+## Trigger On
+- The user asks to design or improve an AI agent development workflow.
+- The user wants coding agents to be more reliable, safer, or easier to supervise.
+- The user asks for AGENTS.md, skills, tests, CI, hooks, review loops, or project rules to be planned together.
+- The task is about harness engineering, agent harnessability, feedback loops, or "humans on the loop".
+
+## Core Principle
+Treat agent-assisted development as a controlled engineering system. Do not only improve prompts; design the guides, sensors, verification steps, and human decision points that let agents work with higher confidence.
+
+Use this skill for planning first. Do not modify files unless the user explicitly asks for implementation after the harness plan is clear.
+
+## Perceive
+1. Inspect the repository before asking questions:
+   - Project instructions: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`.
+   - Skill or prompt assets: `skills/`, `.codex/skills/`, `.claude/skills/`, `.github/skills/`.
+   - Validation commands: `package.json`, `pyproject.toml`, `Makefile`, CI workflow files, build scripts.
+   - Safety and governance: hooks, linters, formatters, secret scanners, dependency scanners.
+   - Existing documentation: README, architecture docs, ADRs, testing docs, contribution docs.
+2. Identify the project type, primary languages, current test surface, CI status, and release/deploy path.
+3. Separate discoverable repository facts from product or team preferences that require user confirmation.
+
+## Reason
+Analyze the project through these dimensions:
+
+1. **Feedforward guides**
+   - What should the agent know before editing?
+   - Examples: project rules, coding style, architecture boundaries, task decomposition, testing strategy, domain vocabulary, safe file ownership.
+2. **Feedback sensors**
+   - What can check the agent's work after each change?
+   - Examples: typecheck, tests, lint, build, static analysis, security checks, architecture tests, review agents, smoke tests.
+3. **Control type**
+   - Prefer computational controls for fast deterministic checks.
+   - Use inferential controls for semantic review, architecture judgment, test-quality review, and risk assessment.
+4. **Regulation category**
+   - Maintainability: readability, duplication, complexity, style, testability.
+   - Architecture fitness: module boundaries, performance, observability, security, deployability.
+   - Behaviour: requirements, acceptance criteria, user journeys, fixtures, manual test points.
+5. **Human role**
+   - Move human effort from repeated low-level correction to high-value decisions: scope, product fit, risk acceptance, architectural tradeoffs, and harness evolution.
+
+For detailed patterns and examples, read [reference/harness-patterns.md](reference/harness-patterns.md) when the task needs a full harness design, maturity model, or improvement roadmap. For the complete source article synthesis behind this skill, read [reference/agent-harness-engineering.md](reference/agent-harness-engineering.md) only when deeper conceptual background is needed.
+
+## Act
+Output in Traditional Chinese (Taiwan). Use this structure:
+
+### 1. 現況盤點
+- Summarize the repository facts discovered.
+- Mention the current guides, sensors, and missing signals.
+
+### 2. Harnessability 評估
+- Rate the current harnessability as `低`, `中`, or `高`.
+- Explain the rating with concrete evidence from the repository.
+
+### 3. Feedforward Guides 設計
+- List the rules, docs, skills, templates, or examples agents should receive before work starts.
+- Mark each item as existing, needs update, or missing.
+
+### 4. Feedback Sensors 設計
+- List fast local checks, CI checks, security checks, semantic reviews, and manual checks.
+- Distinguish computational from inferential checks.
+
+### 5. 開發前改善清單
+- Prioritize improvements as P0, P1, and P2.
+- P0 must focus on changes that reduce repeated agent mistakes or prevent high-risk failures.
+
+### 6. 人類決策點
+- State where humans should stay on the loop.
+- Identify decisions that should not be delegated fully to agents.
+
+### 7. 驗證方式
+- Provide exact commands or review steps when discoverable.
+- If a command is unknown, state the missing fact instead of inventing one.
+
+## Constraints
+- Do not treat AI-generated tests as sufficient proof of behaviour correctness.
+- Do not replace deterministic tooling with LLM judgment when a fast tool can check the same thing.
+- Do not recommend broad automation before the project has reliable local validation commands.
+- Do not propose fully autonomous changes for security, compliance, production deploys, or product-scope decisions.
+- Keep the output actionable and tied to repository evidence.

package/skills/neo-agent-harness/reference/agent-harness-engineering.md

@@ -0,0 +1,343 @@
+# Agent Harness Engineering and the Role of Humans in the Software Engineering Loop
+
+> This document is a summary and integration of two articles from Martin Fowler's website, focusing on practical explanations rather than word-for-word translation.
+
+## Original Sources
+
+- [Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)  
+  Author: Birgitta Boeckeler, Published: 2026-04-02
+- [Humans and Agents in Software Engineering Loops](https://martinfowler.com/articles/exploring-gen-ai/humans-and-agents.html)  
+  Author: Kief Morris, Published: 2026-03-04
+
+## One-sentence Summary
+
+The focus of AI coding agents is not just "letting the model write code," but establishing a working system (harness) for the agent to guide, check, correct, and continuously improve. Humans should not just review line-by-line at the lowest level, nor should they exit completely; instead, they should stand above the loop, designing and maintaining the agent's harness to ensure reliable software output in a controlled environment.
+
+## Core Background
+
+LLM coding agents can generate code quickly, but they have several inherent limitations:
+
+- Output is not entirely predictable.
+- They may not understand the full business context.
+- They have limited grasp of existing code, team conventions, architectural constraints, and product trade-offs.
+- They are prone to iterating in the wrong direction, wasting tokens, time, and review costs.
+
+Therefore, the key to improving agent performance is not just switching to a stronger model, but designing the environment in which it works. This environment includes specifications, documentation, templates, tests, linting, architectural checks, review agents, CI pipelines, observability data, and human decision-making processes. This entire external control system is the "harness" discussed in the articles.
+
+## What is a Harness?
+
+In a broad sense, an agent can be understood as:
+
+```text
+Agent = Model + Harness
+```
+
+In the context of coding agents, the model is the LLM responsible for reasoning and generation; the harness is the working system wrapped around the model. It may include:
+
+- System prompts, project rules, AGENTS.md, skills, and how-to guides.
+- Code retrieval, language servers, CLI tools, and MCP servers.
+- Tests, type checks, linting, static analysis, and architectural rules.
+- AI code reviews, LLM judges, and semantic checks.
+- CI/CD pipelines, production telemetry, and user journey data.
+
+A good harness has two goals:
+
+- Increase the probability of the agent getting it right the first time.
+- Enable the agent to self-correct more issues based on feedback before reaching humans.
+
+In other words, the value of a harness is to reduce the human review burden while improving system quality.
+
+## Feedforward and Feedback
+
+Harness controls can be divided into two categories.
+
+### Feedforward: Guidance Before Action
+
+Feedforward controls provide direction before the agent starts working, aiming to prevent errors. Examples include:
+
+- Coding convention documents.
+- Architectural principles.
+- Task breakdown methods.
+- Project bootstrap guides.
+- API usage specifications.
+- Technical decision records (ADRs).
+- Templates and scaffolds.
+- Codemods or fixed refactoring tools.
+
+The effect of feedforward is to increase the probability that the agent produces correct results from the start.
+
+### Feedback: Sensing and Correction After Action
+
+Feedback controls provide signals after the agent performs an action, allowing it to check and self-correct. Examples include:
+
+- Unit and integration tests.
+- Type checkers.
+- Linters.
+- Architecture fitness tests.
+- Coverage or mutation testing.
+- Semgrep or security scans.
+- AI review agents.
+- Browser smoke tests.
+- Production logs, SLOs, error rates, and latency.
+
+The effect of feedback is to ensure the agent is not just "constrained by rules" but knows whether its output is actually effective.
+
+Without feedback, the agent might repeat the same mistakes; without feedforward, the team won't know if the rules are actually having an effect. A good harness requires both.
+
+## Computational and Inferential
+
+The articles also divide guides and sensors into two execution types.
+
+### Computational Controls
+
+Computational controls are deterministic, fast, and cheap machine checks, usually executed by the CPU. Examples include:
+
+- Type checks.
+- Unit tests.
+- Linting.
+- Static analysis.
+- Structural tests.
+- Codemods.
+- Dependency checks.
+
+The advantages of these controls are stability, low cost, and repeatability, making them suitable for execution before every change, commit, or in the CI pipeline.
+
+### Inferential Controls
+
+Inferential controls are AI or LLM-based checks that require semantic judgment. Examples include:
+
+- AI code reviews.
+- LLM-as-a-judge.
+- Commentary on architectural soundness.
+- Commentary on test quality.
+- Detection of duplicate logic or over-engineering.
+- Inferring potential issues from logs.
+
+These controls can handle problems that traditional tools find difficult, but they are more expensive, slower, and less stable. They are suitable for high-value, high-risk, or late-stage checks, rather than replacing all deterministic checks.
+
+## Three Types of Harnesses
+
+### 1. Maintainability Harness
+
+The maintainability harness is used to maintain internal code quality. This is currently the easiest type to implement because existing tools are very mature.
+
+Issues covered include:
+
+- Duplicate code.
+- Excessive complexity.
+- Missing tests.
+- Inconsistent naming or formatting.
+- Violated architectural boundaries.
+- Style guide violations.
+
+Computational sensors are very effective for these issues. Inferential sensors can complement them at the semantic level, such as detecting "logic that looks different but is actually duplicate," "tests that exist but don't verify the core point," or "fixes that are too brute-force or over-engineered."
+
+However, a maintainability harness cannot fully solve requirement misunderstandings, incorrect diagnoses, or scope creep. These still require clearer specifications and human judgment.
+
+### 2. Architecture Fitness Harness
+
+The architecture fitness harness is used to maintain architectural characteristics and system quality attributes. Examples include:
+
+- Module boundaries.
+- Consistency in API design.
+- Performance requirements.
+- Observability standards.
+- Security and compliance requirements.
+- Deployment and operational constraints.
+
+Its feedforward might be architectural documents, ADRs, logging standards, or performance budgets; feedback might be architecture tests, performance tests, contract tests, observability reviews, or deployment checks.
+
+The focus of this harness is to translate "what our system looks like" into rules that an agent can read, follow, and be checked against by tools.
+
+### 3. Behaviour Harness
+
+The behavior harness is used to confirm that software functional behavior meets requirements. This is currently the most difficult type.
+
+Common practices include:
+
+- Feedforward: Providing the agent with functional specifications, user stories, and acceptance criteria.
+- Feedback: Letting the agent generate and execute tests, supplemented by coverage, mutation testing, or manual testing.
+
+The problem is that AI-generated tests themselves are not necessarily trustworthy. Tests might only verify implementation details rather than actual requirements. The articles mention "approved fixtures" as a pattern that can improve test quality in some scenarios, but it's not a universal solution for all systems.
+
+Therefore, functional correctness remains the area that most needs human product judgment and high-quality specifications.
+
+## Harnessability: Not All Systems Are Equally Easy to Harness
+
+Whether a codebase can be stably operated by an agent depends on whether it possesses enough structural clues.
+
+Systems that are easier to harness usually have:
+
+- Strongly typed languages and strict type checking.
+- Clear module boundaries.
+- Consistent frameworks and directory structures.
+- Automatable tests.
+- Clear coding conventions.
+- Architectural rules checkable by tools.
+
+Systems that are harder to harness usually have:
+
+- High technical debt.
+- Too many implicit rules.
+- Vague architectural boundaries.
+- Insufficient tests.
+- A requirement for significant tribal knowledge.
+- Highly mixed frameworks and styles.
+
+This means greenfield projects can be designed for harnessability from day one, while legacy projects need to add structure, tests, and rules before safely increasing agent autonomy.
+
+## Harness Templates
+
+Large organizations often have several common types of services, such as:
+
+- CRUD business services.
+- Event processors.
+- Data dashboards.
+- API gateways.
+- Batch jobs.
+
+If these types already have service templates, they can evolve into harness templates. That is, each service type comes built-in with:
+
+- Standard directory structure.
+- Tech stack and dependencies.
+- Generation and modification guides.
+- Test templates.
+- Architectural rules.
+- CI pipelines.
+- Security and observability checks.
+- Agent review guides.
+
+This narrows the space in which the agent can arbitrarily generate, making control more feasible. The downside is that the template itself requires version management, synchronization, and governance; otherwise, projects will gradually diverge from the upstream standard.
+
+## Three Human Positions in the Loop
+
+The second article provides another important model: where should humans stand in the loop?
+
+### Humans Outside the Loop
+
+This leaves humans in the "why loop" and lets the agent handle the "how loop." Humans only describe the desired result, and the agent decides how to construct the software.
+
+This approach is close to what's often called "vibe coding." Its appeal lies in speed and minimal intervention, but the risk is that internal quality, maintainability, cost, security, and compliance may spiral out of control.
+
+The articles remind us: we care about internal quality not because code is sacred, but because internal quality affects external outcomes. A chaotic codebase makes agents slower, more likely to get lost, and harder to modify reliably.
+
+### Humans In the Loop
+
+This keeps humans in the lowest-level coding loop, reviewing the agent's code line-by-line.
+
+This approach leverages human experience and judgment, especially when the agent gets stuck, misunderstands, or repeatedly fixes things incorrectly. The problem is that humans become the bottleneck. Agents generate code much faster than humans can review it line-by-line. If all quality assurance relies on manual review, the efficiency gains of AI are neutralized.
+
+### Humans On the Loop
+
+The articles advocate for "humans on the loop": humans do not control the agent line-by-line, nor do they exit completely; instead, they design, manage, and improve the agent's work loop.
+
+The difference can be understood as:
+
+- In the loop: Seeing an incorrect agent output and fixing it directly, or telling the agent to fix that specific output.
+- On the loop: Seeing an incorrect agent output and going back to modify the harness so that future similar outputs are more likely to be correct.
+
+This turns every error into an opportunity to improve the system, rather than just fixing a one-off problem.
+
+## Agentic Flywheel
+
+A more advanced state is the "agentic flywheel": humans not only ask the agent to build features but also ask it to analyze the harness's effectiveness and propose improvements.
+
+Implementation can start simply:
+
+1. Let the agent read tests, CI results, and review findings.
+2. Ask the agent to identify failure patterns and recurring issues.
+3. Have the agent suggest adding or modifying rules, tests, documentation, linting, or pipelines.
+4. Humans review these suggestions before assigning the agent to implement them.
+5. As trust increases, let the agent flag risks, costs, and benefits for its suggestions.
+6. Gradually automate low-risk, high-confidence improvements.
+
+Such a flywheel doesn't aim for a one-time "it mostly works," but rather makes the system progressively more capable of self-checking, self-correcting, and self-improving.
+
+## Practical Implications for Engineering Teams
+
+### 1. Don't Understand AI Engineering Only as Prompting Skills
+
+Prompts are important, but long-term reliability comes from the entire work system. Teams should view AGENTS.md, skills, specification documents, tests, linting, CI, review processes, and production feedback as a single harness rather than fragmented tools.
+
+### 2. Prioritize Moving Cheap, Stable, and Deterministic Checks Upstream
+
+Problems that can be solved with deterministic tooling should not be prioritized for LLM judgment. Type checks, linting, unit tests, formatting, and architectural rules should run as early as possible, ideally during the agent's self-correction phase.
+
+### 3. Focus Human Attention on High-Value Judgments
+
+The most valuable place for humans is not reading every line of code, but judging:
+
+- Whether requirements are clear.
+- Whether the product direction is correct.
+- Whether architectural trade-offs are reasonable.
+- Whether risks are acceptable.
+- Which technical debts are intentional and which are out of control.
+- How the harness should evolve.
+
+### 4. Turn Recurring Errors into Harness Improvements
+
+If an agent makes the same mistake multiple times, it shouldn't just be fixed each time it happens. Instead, ask:
+
+- Is a feedforward document missing?
+- Do tests need to be added?
+- Can a lint rule or static analysis be added?
+- Does AGENTS.md or a skill need to be updated?
+- Does a project-specific review checklist need to be created?
+- Can manual knowledge be turned into an automated check?
+
+### 5. Be Cautious About Functional Behavior
+
+Functional correctness is the hardest to automate fully. AI-generated tests cannot be equated directly with trustworthy acceptance. Important features still need clear specifications, acceptance criteria, manual exploratory testing, and, when necessary, domain expert reviews.
+
+## Checklist for Building a Coding Agent Harness
+
+### Phase 1: Establishing Basic Controllability
+
+- Create or update AGENTS.md, explaining project rules, workflows, testing methods, and security limits.
+- Ensure the project has one-click commands for install, test, and build.
+- Set up type checking, linting, formatting, and unit tests.
+- Document common task workflows in how-to guides or skills.
+- Ensure the agent clearly knows which files can be modified and which should not be changed manually.
+
+### Phase 2: Strengthening the Feedback Loop
+
+- Automatically execute fast tests and type checks after agent modifications.
+- Provide clear correction guidance for common failure messages.
+- Add architectural boundary checks or dependency rules.
+- Add contract tests or approval tests for important modules.
+- Feed CI results back into the agent's correction process.
+
+### Phase 3: Adding Semantic-Level Checks
+
+- Establish a code review skill or checklist.
+- Create specialized review processes for architecture, security, performance, and test quality.
+- Let AI reviews find high-risk issues first, rather than replacing all manual reviews.
+- Periodically review false positives and false negatives from AI reviews.
+
+### Phase 4: Establishing the Harness Improvement Loop
+
+- Collect common error patterns from the agent.
+- Turn recurring errors into rules, tests, documentation, or tools.
+- Periodically check that AGENTS.md, skills, CI, and linting are consistent with each other.
+- Have the agent suggest harness improvements based on CI, reviews, and production data.
+- Flag risks, costs, benefits, and automation levels for improvement suggestions.
+
+## Observations Applicable to This Project
+
+This repository itself is a collection of skills and agent work rules, making it highly suitable for management from a harness engineering perspective.
+
+Consider the following directions:
+
+- Treat each skill as a feedforward guide: it tells the agent how to act in a specific task.
+- Treat `test/*.test.js`, `bun run typecheck`, and `bun run build` as computational feedback sensors.
+- Treat `src/hooks/secret-guard.ts` and `hooks/hooks.json` as part of the security and governance harness.
+- In the future, add specialized checks for skill quality, such as SKILL.md structure, required sections, valid reference paths, and template consistency.
+- Establish a "skill review checklist" to assist in checking if instructions are clear, too broad, or in conflict with other skills using inferential review.
+
+## Most Important Conclusion
+
+The reliability of an AI agent is not produced naturally by model capability alone; it is formed by the combination of the model, context, tools, checks, feedback, and human governance.
+
+The human role should not be simplified into two extremes: either exiting completely or guarding every line. A more sustainable approach is to stand above the loop, continuously designing and improving the system in which the agent works.
+
+For teams actually delivering products, harness engineering will become a core engineering capability: gradually transforming human experience, team conventions, architectural judgment, and quality standards into a work environment that an agent can follow, execute, check, and continuously improve.

package/skills/neo-agent-harness/reference/harness-patterns.md

@@ -0,0 +1,180 @@
+# Agent Harness Patterns
+
+Use this reference when designing a complete agent harness plan or roadmap.
+
+## Core Model
+
+An agent harness is the system around the model that guides, checks, and improves agent work.
+
+```text
+Agent = Model + Harness
+```
+
+For coding agents, the useful outer harness includes:
+
+- Project instructions and task workflows.
+- Skills, templates, examples, and architectural rules.
+- Local verification commands and CI stages.
+- Hooks, linters, static analysis, and security checks.
+- AI review, architecture review, test-quality review, and human decision points.
+- Production feedback such as logs, SLOs, user journeys, and support signals.
+
+The goal is not full human removal. The goal is to reduce repeated review toil and direct human attention to product, risk, architecture, and tradeoff decisions.
+
+## Feedforward Guides
+
+Feedforward guides shape agent output before it acts.
+
+Common examples:
+
+- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot instructions.
+- Coding standards and style references.
+- Architecture docs, ADRs, dependency rules, module maps.
+- Task-specific skills and how-to guides.
+- Service templates, scaffolds, fixtures, and examples.
+- API docs, domain vocabulary, data contracts, and non-functional requirements.
+
+Good feedforward guides are:
+
+- Specific enough to prevent repeated mistakes.
+- Short enough to be loaded often.
+- Close to the code they govern.
+- Kept in sync with tests, CI, and review expectations.
+
+## Feedback Sensors
+
+Feedback sensors observe work after the agent acts and provide correction signals.
+
+Fast computational sensors:
+
+- Typecheck.
+- Unit tests and focused integration tests.
+- Lint and format checks.
+- Build checks.
+- Static analysis.
+- Dependency and secret scanning.
+- Architecture boundary tests.
+
+Slower or inferential sensors:
+
+- AI code review.
+- Architecture review.
+- Test-quality review.
+- Security reasoning review.
+- Log and incident analysis.
+- Behaviour or UX review against user journeys.
+
+Prefer fast deterministic sensors during local development. Reserve inferential sensors for semantic judgment, riskier changes, and later review stages.
+
+## Regulation Categories
+
+### Maintainability Harness
+
+Purpose: keep the codebase easy for humans and agents to understand and change.
+
+Signals:
+
+- Duplicate code.
+- Excessive complexity.
+- Naming or style drift.
+- Missing or weak tests.
+- Hard-to-review diffs.
+- Over-engineered or brute-force fixes.
+
+Useful controls:
+
+- Format, lint, typecheck, tests.
+- Complexity and dependency analysis.
+- Code review skill.
+- Refactoring guides and examples.
+
+### Architecture Fitness Harness
+
+Purpose: keep the system aligned with its intended structure and quality attributes.
+
+Signals:
+
+- Module boundary violations.
+- API inconsistency.
+- Performance regression.
+- Observability gaps.
+- Security or compliance drift.
+- Deployment fragility.
+
+Useful controls:
+
+- Architecture docs and ADRs.
+- Fitness functions and structural tests.
+- Contract tests.
+- Performance budgets.
+- Logging and tracing standards.
+- CI gates for risky paths.
+
+### Behaviour Harness
+
+Purpose: verify that the product does what stakeholders need.
+
+Signals:
+
+- Ambiguous requirements.
+- Tests that only mirror implementation.
+- Missing acceptance criteria.
+- Broken user journeys.
+- Manual test steps that are not captured.
+
+Useful controls:
+
+- User stories with acceptance criteria.
+- Approved fixtures or golden examples where appropriate.
+- End-to-end smoke tests for critical flows.
+- Domain expert review for high-impact behaviour.
+- Manual exploration checklist when automation is weak.
+
+Do not assume AI-generated tests prove behaviour correctness. Behaviour harnesses need clear human intent and high-quality examples.
+
+## Harnessability Assessment
+
+Rate harnessability by evidence:
+
+- **High**: clear structure, strong typing, reliable tests, CI, documented rules, repeatable build, clear ownership.
+- **Medium**: some tests and rules exist, but coverage, architecture docs, or validation commands are incomplete.
+- **Low**: weak tests, unclear structure, hidden conventions, inconsistent frameworks, no reliable local checks, or high technical debt.
+
+Common improvement sequence:
+
+1. Make setup, test, typecheck, and build commands explicit.
+2. Document project rules in the agent instruction file.
+3. Add fast computational checks before adding AI review.
+4. Add architecture or domain-specific sensors for repeated failures.
+5. Add inferential review for semantic quality and risk.
+6. Feed recurring failures back into guides, tests, hooks, or skills.
+
+## Maturity Roadmap
+
+### Level 1: Basic Control
+
+- Agent can find project rules.
+- Local validation commands are documented.
+- Secret and destructive-action rules are clear.
+- Human reviews all significant changes.
+
+### Level 2: Fast Self-Correction
+
+- Agent runs focused tests, typecheck, lint, and build after changes.
+- Failure messages are actionable.
+- Repeated mistakes become guides or checks.
+- CI repeats the local quality gates.
+
+### Level 3: Architecture-Aware Development
+
+- Agent understands module boundaries and service topology.
+- Architecture fitness checks catch drift.
+- Review process checks performance, observability, and deployability.
+- Templates encode common project shapes.
+
+### Level 4: Harness Improvement Loop
+
+- Agent reviews CI, review comments, and incidents to propose harness improvements.
+- Humans prioritize and approve harness changes.
+- Low-risk improvements can be automated after repeated success.
+- Harness quality itself is reviewed regularly.