# Feedback Layer Model

This document defines how `project-scaffold-skill` should think about
constraints, feedback, and business-flow verification when building a
project-specific autonomous development harness.

Use this document together with `INTENT.md`.

## Why This Exists

The harness is not complete when it has produced a few planning documents.
It is complete only when the target project gives the agent enough feedback to:

- know which layer it is changing
- know which boundaries it must not violate
- know what commands or tools prove the change is valid
- know what evidence to inspect when the change fails
- know how to recover without guessing

The feedback layer is therefore part of the environment, not just part of the
documentation.

## Canonical Machine-Readable Contracts

The skill should produce two complementary machine-readable contracts:

- `docs/harness-manifest.json`
  This answers: what artifacts were intentionally generated, which scripts and
  sub-skills exist, and what is the repo's execution contract?
- `docs/feedback-profile.json`
  This answers: which feedback surfaces exist, how strong are they, which
  business flows are covered, where does evidence live, and which gaps still
  need human confirmation or future work?

Do not overload one file with both responsibilities. Artifact inventory and
feedback-layer state evolve together, but they are not the same thing.

## Reading The Architecture Diagram

The diagram discussed in design review implies a layered system, for example:

- `Providers`
- `Service`
- `Runtime`
- `UI`
- `Types`
- `Config`
- `Repo`
- `Utils`
- `App Wiring + UI`

The exact layer names vary by project. The important point is that the harness
must understand:

1. Which layers exist
2. Which directions of dependency are allowed
3. Which user or business flows cross those layers
4. Which feedback surface should catch failure at each point

The goal is not only "the app runs." The goal is "the agent can tell which
layer is wrong, which contract was broken, and which evidence proves it."

## The Feedback Layer Is Multi-Surface

The feedback layer is not one script and not one document. It is a set of
surfaces around the codebase.

### 1. Static Constraint Feedback

This catches illegal structure before runtime.

Examples:

- dependency direction rules
- forbidden imports
- directory ownership rules
- architecture boundary checks
- schema drift checks

Typical mechanisms:

- lint rules
- import/dependency graph tooling
- architecture tests
- manifest or structure validation

### 2. Contract Feedback

This catches mismatches between layers.

Examples:

- wrong request or response shape
- broken repo or provider contract
- incompatible domain types
- invalid config shape

Typical mechanisms:

- typecheck
- schema validation
- API contract tests
- integration tests between layers

### 3. Runtime Feedback

This catches failures that only appear while the program is running.

Examples:

- runtime exceptions
- browser console errors
- failed network calls
- bad state transitions
- missing environment configuration

Typical mechanisms:

- structured logs
- local traces
- screenshots
- browser automation traces
- smoke tests

### 4. Business-Flow Feedback

This catches "the code passes, but the product behavior is still wrong."

Examples:

- a primary user path appears to succeed but violates an access rule
- a multi-step workflow completes but leaves downstream state inconsistent
- a successful response is returned but the intended side effect does not happen
- a command exits successfully but the observable result is still wrong

Typical mechanisms:

- scenario tests
- acceptance tests
- end-to-end tests
- fixture-based integration flows
- golden output tests

## Constraint Encoding Model

Constraints should be encoded in three layers:

### 1. Explanation Layer

Used so the agent understands intent and priorities.

Typical artifacts:

- `AGENTS.md`
- `docs/project_spec.md`
- `docs/prompt.md`

### 2. Contract Layer

Used so the repo has machine-readable or mechanically checkable agreements.

Typical artifacts:

- `docs/harness-manifest.json`
- `docs/feedback-profile.json`
- schemas
- API contracts
- directory or layer dependency declarations
- explicit command contracts

### 3. Enforcement Layer

Used so the environment can reject bad changes.

Typical artifacts:

- `scripts/quality-gates.*`
- `scripts/validate-docs.*`
- lint
- typecheck
- unit tests
- integration tests
- scenario smoke tests
- end-to-end tests

The skill should prefer turning important constraints into enforcement. If a
constraint exists only in prose, the harness is weak.

## Business Flow Verification Is The Hard Part

Business-flow validation is usually the least inferable part of the harness.
Static structure can often be discovered from code. Business truth often cannot.

Because of that, the skill should separate business-flow inputs into three
classes:

### 1. Repo-Confirmed

Safe to trust because it already exists in the repository.

Examples:

- requirements documents
- product specs
- API contracts
- existing user flows in tests
- design files linked from the repo

### 2. Inferred

Reasonable to propose, but not safe to treat as final truth.

Examples:

- likely primary route based on router structure
- likely layer boundaries based on imports
- likely core workflow shape based on file and endpoint naming

These should be tagged as inferred until confirmed.

### 3. Human-Confirmed

Must be explicitly asked when getting it wrong would distort the harness.

Examples:

- the top 1 to 3 user-critical flows
- failure modes that are unacceptable in production
- the real milestone acceptance criteria
- external systems that must not be assumed
- role, permission, billing, compliance, or approval rules

## When The Skill Should Ask The Human

The skill should ask during harness setup when business truth is needed to
design the feedback layer well. It should not keep asking during routine
implementation if that truth could have been captured once and written into the
repo.

Good setup-time questions:

- What are the most critical user or operator flows?
- Which failure is most expensive or unacceptable?
- What makes milestone one genuinely done?
- Which systems, permissions, or environments must not be assumed?

Bad routine questions:

- Should I run tests again?
- Is this error probably important?
- Should I check the logs?

Those should be answered by the harness itself.

## Empty Project With Requirements Docs

An empty repo with requirements docs can still get a strong feedback layer.
The skill should:

1. Read the requirements docs from the repo
2. Extract likely system shape, primary users, and key flows
3. Identify which parts are confirmed vs inferred vs unknown
4. Ask the human only for the business truths that cannot be safely inferred
5. Scaffold the minimum runnable and verifiable environment
6. Encode the accepted flows and constraints back into repo artifacts

For an empty project, this means the feedback layer is often bootstrapped from
the intended behavior, not from existing code.

Examples:

- web app: minimal route, lint, typecheck, browser smoke, trace path
- API service: minimal endpoint, request smoke, schema checks, logs
- CLI tool: minimal command, golden output test, exit-code checks
- library: public API example, unit tests, integration sample

## What "Done" Looks Like

The harness is strong enough when a downstream agent can answer:

- Which layer am I editing?
- Which boundaries must not be crossed?
- Which command or test proves this change is valid?
- Where do I look when this fails?
- Which business flow does this change affect?
- Which acceptance rule determines whether the milestone is actually complete?

If the agent still has to guess these answers, the feedback layer is incomplete.
