# Source-Grounded Assistant Prototype Contract

## Decision

Issue #78 should be implemented as a non-runtime prototype contract over the approved AI Capability Playbook package.

```text
We are not building a chatbot.
We are building a governed interpretation layer over an approved AI capability knowledge package.
```

The reader site remains for humans. The corpus remains the grounding authority. The assistant path is for interpretation. The model is not the source of truth.

This prototype is static-safe by design. It does not implement runtime assistant behavior, chat UI, API calls, provider or model execution, backend services, vector search, graph storage, connector ingestion, durable memory, private-data workflow, Cloudflare deployment, Supabase integration, Copilot Studio configuration, or enterprise workflow integration.

## Prototype Purpose

The prototype defines the smallest useful assistant contract that future implementation tickets can test without weakening the package boundary.

The prototype should prove these product questions before runtime work starts:

| Question | Prototype answer |
|---|---|
| What can ground an answer? | Approved package files, context-pack files, manifests, source maps, grounding rules, glossary, reader targets, and validation receipts where approved. |
| What modes exist? | Find, Explain, and Assess. |
| What must every grounded answer include? | A cited source basis or an explicit refusal. |
| What happens when the package is silent? | The assistant refuses instead of using model memory. |
| What approval meaning can the answer carry? | None beyond the cited field guidance. |
| What is generated output? | A derivative interpretation, not source evidence or approval record. |

## Product Principle

```text
The site is for readers.
The corpus is for grounding.
The assistant is for interpretation.
The model is not the source of truth.
```

Reader orientation must remain useful without the assistant. Assistant responses may link readers back to stable targets, but reader links do not replace source citations.

## Approved Corpus Input Contract

The assistant path may use only approved package material.

Minimum corpus inputs:

| Input | Role | Boundary |
|---|---|---|
| `docs/artifact-manifest.json` | Artifact identity, public paths, source paths, portable export posture, and package metadata. | Manifest metadata supports traceability. It does not approve tools, data classes, workflows, or production use. |
| `context-pack/manifest.json` | AI-consumable package inventory and package posture. | Root `context-pack/` remains canonical. |
| `docs/context-pack/manifest.json` | Published mirror of context-pack manifest for controlled-sharing access. | Published mirror is not canonical source. |
| `context-pack/source_map.json` | Artifact, source path, context, and reader target mapping. | Missing source-map entries must be treated as gaps. |
| `context-pack/sections.jsonl` | Section-level lookup surface where available. | Section IDs support citation, not truth certification. |
| `context-pack/claims.jsonl` | Claim posture and source-boundary metadata where available. | Claim metadata must preserve confidence and limitation fields. |
| `context-pack/glossary.json` | Package terms and controlled meaning. | Glossary terms do not create universal industry authority. |
| `context-pack/grounding_rules.md` | Grounding, source-quality, claim, approval, and interpretation boundaries. | Grounding rules constrain answers. They are not runtime enforcement by themselves. |
| Product-architecture notes | Approved architecture boundaries for #150, #153, #155, #156, #158, #159, #88, #79, and #151. | Architecture notes guide future work. They do not implement runtime behavior. |
| Validation receipts | Evidence for checks, provenance, and package generation where relevant and approved. | Receipts are evidence of checks, not semantic approval or policy approval. |

Rendered HTML pages and Start Here reader paths may be used as reader targets. They should not be the only grounding substrate when canonical source paths or context-pack references are available.

## Request Contract

A future assistant call or prompt export should carry a provider-neutral request shape.

```json
{
  "mode": "Find | Explain | Assess",
  "user_input": "question or proposal text",
  "approved_corpus_refs": [
    {
      "artifact_id": "ai-capability-discipline",
      "artifact_title": "AI Capability Discipline",
      "section_id": "optional-section-id",
      "section_title": "optional section title",
      "source_path": "source/AI_Capability_Discipline_v0.9.md",
      "context_pack_path": "context-pack/sections.jsonl",
      "reader_target": "docs/html/03_ai_capability_discipline_v0.9.html"
    }
  ],
  "grounding_rules_path": "context-pack/grounding_rules.md",
  "refusal_patterns": [
    "Not found in the approved playbook package.",
    "The playbook provides guidance, but it does not approve this tool, data class, workflow, production use, or company policy.",
    "The submitted proposal lacks enough evidence to assess this criterion."
  ],
  "routing_hint": "deterministic | small-model | mid-tier | premium-escalation",
  "output_format": "citation-first-json-or-markdown"
}
```

The request must not include provider credentials, hidden browser-side secrets, private company material, arbitrary URLs, unrestricted documents, durable memory, connector payloads, or production workflow actions.

## Prompt Contract

Any future prompt or prompt export should preserve these instructions:

```text
Use only the approved corpus references supplied with this request.
Do not use model memory as source authority.
If the supplied package material does not support the answer, refuse.
Cite artifact ID, artifact title, section ID or section title when available, source path, context-pack path, and reader target where available.
Treat generated answers as derivative interpretation, not source evidence.
Do not imply company policy approval, tool approval, data-class approval, workflow approval, production approval, supplier approval, security approval, legal approval, regulatory approval, or GxP readiness.
Keep Find, Explain, and Assess behavior distinct.
```

The prompt contract is portable across OpenAI, Z.ai or GLM-class, Gemini, local or open-weight, and Microsoft-native paths. It must not hardcode a premium model as the default.

## Mode Contract

### Find

Use Find when a reader asks where the package covers a topic.

Minimum output:

| Field | Requirement |
|---|---|
| Query restatement | Restate the topic neutrally. |
| Matches | List artifact ID, artifact title, section ID or section title where available, source path, context-pack path, and reader target where available. |
| Why it matters | Explain why each match is relevant using only approved package material. |
| Related package areas | Include only when source maps, section metadata, or package text support the relation. |
| Refusal | Use `Not found in the approved playbook package.` when no approved source supports the topic. |

Find should be retrieval-heavy and deterministic-first. A future implementation should prefer manifest, source-map, section, and glossary lookup before model reasoning.

### Explain

Use Explain when a reader asks what a package concept means, why it matters, or how two package concepts differ.

Minimum output:

| Field | Requirement |
|---|---|
| Direct explanation | Explain in plain language without turning field guidance into final policy. |
| Source basis | Cite package sources and context-pack paths. |
| Boundary | State what the explanation does not approve when approval meaning could be confused. |
| Package silence | Refuse when the approved package does not support the answer. |

Explain may use a cheaper or mid-tier model in a future runtime only when source citations are strong, data is approved for that route, and review expectations match consequence.

### Assess

Use Assess when a user supplies an AI use case, architecture submission, assistant concept, workflow, or capability proposal.

Minimum output:

| Field | Requirement |
|---|---|
| Submitted evidence used | Quote or summarize only the proposal evidence needed for the finding. |
| Assessment dimension | Map to the proposal assessment path dimensions. |
| Finding class | Use `pass`, `concern`, `blocker`, `missing evidence`, or `not covered`. |
| Finding | State the assessment result in review-ready language. |
| Package criterion | Name the playbook concept or criterion used. |
| Citation | Cite artifact ID, section ID or title, source path, context-pack path, and reader target where available. |
| Missing evidence | Identify what the proposal failed to provide. |
| Reviewer action | Recommend human review action without granting approval. |
| Derivative label | State that the assessment output is generated derivative review assistance. |

Assess may require premium reasoning only when ambiguity, novelty, consequence, conflicting evidence, or governance risk requires escalation. Premium reasoning is an escalation choice, not the default.

## Assessment Output Classes

| Class | Meaning | Required behavior |
|---|---|---|
| `pass` | The proposal provides enough evidence for the criterion at the requested review depth. | Cite the package criterion and proposal evidence. Do not grant approval. |
| `concern` | The proposal partially addresses the criterion but leaves material uncertainty, weakness, or follow-up. | Name the uncertainty and reviewer action. |
| `blocker` | The proposal conflicts with package guidance, source boundary, approval boundary, or safe operating posture. | Cite the conflict and name the stop condition. |
| `missing evidence` | The proposal lacks enough evidence to assess the criterion. | Use the required missing-evidence refusal pattern where applicable. |
| `not covered` | The approved package does not contain enough guidance for the criterion. | Use the package-silence refusal pattern and do not answer from model memory. |

Assessment output can support review memos, missing-information checklists, approval-condition drafts, email drafts, or review packets in later work. Those outputs remain generated derivatives and do not replace source records, approval records, validation receipts, or human review.

## Response Schema

A future assistant response should normalize answers into this provider-neutral shape.

```json
{
  "mode": "Find | Explain | Assess",
  "status": "answered | refused | partially_answered",
  "answer": "source-grounded answer text or refusal text",
  "source_boundary": "Answer uses only approved package references supplied to this request.",
  "citations": [
    {
      "artifact_id": "ai-capability-discipline",
      "artifact_title": "AI Capability Discipline",
      "section_id": "optional-section-id",
      "section_title": "optional section title",
      "source_path": "source/AI_Capability_Discipline_v0.9.md",
      "context_pack_path": "context-pack/sections.jsonl",
      "claim_id": "optional-claim-id",
      "reader_target": "docs/html/03_ai_capability_discipline_v0.9.html",
      "citation_limit": "reader target supports navigation but does not replace source citation"
    }
  ],
  "refusal_reason": "not_found | approval_boundary | missing_proposal_evidence | private_or_external_source_boundary | none",
  "assessment_findings": [
    {
      "class": "pass | concern | blocker | missing evidence | not covered",
      "dimension": "Source authority",
      "finding": "review-ready finding text",
      "proposal_evidence_used": "submitted proposal evidence",
      "missing_evidence": "required evidence not supplied",
      "recommended_reviewer_action": "human review action",
      "approval_boundary_note": "does not approve tool, data, workflow, production use, or policy"
    }
  ],
  "derivative_output_label": "Generated derivative interpretation. Not source evidence, policy approval, or production approval.",
  "routing_metadata": {
    "model_tier": "not executed | deterministic | small-model | mid-tier | premium-escalation",
    "provider": "not executed",
    "token_cost_latency": "not available for static prototype"
  }
}
```

If a field cannot be supported by approved package metadata, the response should say so rather than inventing the missing value.

## Refusal Behavior Examples

### Package Silence

```text
Not found in the approved playbook package.

Source boundary: The supplied approved package references do not contain enough support to answer this question. I will not use model memory as source authority.
```

### Approval Boundary

```text
The playbook provides guidance, but it does not approve this tool, data class, workflow, production use, or company policy.

Source boundary: The cited package material can support review questions and operating discipline, but approval must come from the appropriate owner, policy, security, data, workflow, or production governance path.
```

### Missing Proposal Evidence

```text
The submitted proposal lacks enough evidence to assess this criterion.

Missing evidence: source authority, data classes, evaluation approach, human review model, sustainment owner, or approval status must be supplied before this criterion can be assessed.
```

### External Or Private Source Request

```text
Not found in the approved playbook package.

Source boundary: This Playbook-grounded mode does not use external web sources, private company material, connector data, or model memory. External pulse-check or private-corpus modes require separate approved scope.
```

## Reader Target Contract

Assistant responses should link to stable reader targets when available.

Preferred citation order:

1. artifact ID and artifact title
2. section ID and section title where available
3. source path
4. context-pack path or source-map reference
5. claim ID or source-boundary note when relevant
6. reader target link when stable

Reader target links help humans inspect the package. They do not replace source citations, source maps, grounding rules, or validation receipts.

The Start Here reader paths should remain the first human orientation layer. Future assistant answers should use those paths to route people back to package reading surfaces, especially for executive, architecture, governance, platform-owner, builder, practitioner, and assistant/context-package user questions.

## Static Prototype Notes

This issue stops at the contract layer because the existing architecture work keeps runtime behavior out of scope.

Static-safe prototype outputs may include:

- this behavior contract
- provider-neutral request and response shapes
- prompt export rules
- citation and refusal examples
- assessment output classes
- corpus input contract
- reader target linkage rules

Static-safe prototype outputs do not include:

- live model calls
- browser chat UI
- static-site chat shell
- server-side proxy
- provider adapters
- provider credentials
- deployment configuration
- data ingestion
- persistent conversations
- private proposal uploads

Static-only package browsing and prompt export remain possible future no-proxy behavior. Any real provider API call remains behind a future server-side boundary.

## Model Routing Posture

The prototype is provider-agnostic and model-agnostic.

Future implementations should preserve this routing posture:

- do not use a model when deterministic lookup, schema validation, hashing, or package inspection is sufficient
- use the weakest sufficient model for low-risk Find and Explain cases with strong citations
- escalate only when ambiguity, novelty, consequence, conflicting source evidence, or governance risk justifies stronger reasoning
- keep retrieval, reasoning, drafting, and approval separate
- keep approval outside the model
- record model tier, provider, cost, token, latency, and fallback metadata only when a future runtime implementation approves collection

This prototype does not endorse OpenAI, Z.ai, Gemini, Microsoft-native models, local models, open-weight models, or any other provider for enterprise use.

## Relationship To Recent Architecture Work

| Issue | Relationship |
|---|---|
| #150 | Implements the source-grounded assistant boundary as an interrogation layer over the governed knowledge package, not a standalone product. |
| #153 | Reuses Find, Explain, Assess behavior, citations, refusals, generated-derivative labels, and field-guidance-not-policy boundaries. |
| #155 | Preserves the separation between reader site, approved grounding corpus, and Microsoft-native interpretation surface. |
| #156 | Keeps one portable assistant behavior contract that can map to external API, local, open-weight, or Microsoft-native paths later. |
| #158 | Keeps model routing provider-agnostic and avoids a default premium-model assumption. |
| #159 | Aligns with the static/proxy boundary by keeping real provider calls behind future server-side compute. |
| #88 | Links assistant behavior back to stable reader paths while keeping human reader orientation useful without the assistant. |
| #79 | Keeps backend, graph, vector, hosted retrieval, connector ingestion, and durable-memory evaluation deferred. |
| #151 | Does not supersede DOCX rebuild idempotence, which remains a separate deterministic artifact-generation hygiene issue. |

## Non-Goals

This prototype does not add:

- runtime chatbot behavior
- chat UI
- static-site chat shell
- API calls
- OpenAI integration
- Z.ai or GLM-class integration
- Gemini integration
- credentials
- model invocation
- provider configuration
- Cloudflare deployment
- Cloudflare Worker or Function code
- Supabase integration
- Copilot Studio configuration
- vector database
- graph database
- hosted retrieval service
- connector ingestion
- durable memory
- private or company-sensitive data workflow
- SourceMesh or ArtifactPlane repository changes
- enterprise workflow integration
- tool approval
- data-class approval
- workflow approval
- production approval
- company policy approval
- supplier approval

## Acceptance Boundary

This issue is accepted when the repository contains a source-grounded assistant prototype contract that:

- is package-bound and static-safe
- defines Find, Explain, and Assess behavior
- defines approved corpus inputs
- defines prompt, request, response, citation, and refusal contracts
- defines assessment output classes
- connects back to #150, #153, #155, #156, #158, #159, #88, #79, and #151
- documents that generated answers are derivative interpretation, not source evidence
- adds no runtime, UI, provider, deployment, backend, database, retrieval, connector, durable-memory, private-data, or enterprise-integration behavior