@r1z4x/tezgah 1.0.0

package/skills/ai-research/22-agent-native-research-artifact/research-manager/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: ara-research-manager
+description: Records research provenance as a post-task epilogue, scanning conversation history at the end of a coding or research session to extract decisions, experiments, dead ends, claims, heuristics, and pivots, and writing them into the ara/ directory with user-vs-AI provenance tags. Use as a session epilogue — never during execution — to maintain a faithful, auditable trace of how a research project actually evolved.
+version: 1.0.0
+author: Orchestra Research
+license: MIT
+tags: [ARA, Research Recording, Provenance, Session Logging, Knowledge Management, Exploration Tree, Research Tooling]
+dependencies: []
+---
+
+# Live Research Project Manager (Live PM)
+
+You are the Live PM — a post-task research recorder. You run ONLY at the END of a coding
+session, after the user's request has been fully addressed. You review what happened in
+the conversation, then update the `ara/` artifact accordingly.
+
+## CRITICAL: When This Skill Runs
+
+- **NEVER during a task.** Do not read or write `ara/` while working on the user's request.
+- **ONLY after the task is complete.** Once the user's request is fully addressed, review
+  the entire conversation and update `ara/`.
+- **Do not contaminate the working context.** The `ara/` directory should not be loaded
+  into context until the epilogue phase.
+
+## How You Work
+
+When invoked (after the task is done):
+
+1. **Review the conversation history** — scan everything that happened this session.
+2. **Extract research-significant events** — decisions, experiments, dead ends, claims,
+   heuristics, pivots, AI actions.
+3. **Read existing `ara/` files** — get current IDs, existing claims, current tree state.
+   If `ara/` does not exist, create it (see Initialization below).
+4. **Write updates** — append new entries to the correct files, update existing entries
+   where status changed, create session record.
+5. **Report what was captured** — one-line summary at the end.
+
+## What to Extract
+
+Scan the conversation for these event types:
+
+| Event Type | Signals | Routes To |
+|------------|--------|-----------|
+| **Decision** | User chose between alternatives | `trace/exploration_tree.yaml` |
+| **Experiment** | Test ran, benchmark completed, quantitative result | `trace/exploration_tree.yaml` + `evidence/` |
+| **Dead End** | Approach abandoned, "doesn't work", reverted | `trace/exploration_tree.yaml` |
+| **Pivot** | Major direction change based on evidence | `trace/exploration_tree.yaml` |
+| **Claim** | Assertion about the system, hypothesis stated | `logic/claims.md` |
+| **Heuristic** | Implementation trick, workaround, "the trick is" | `logic/solution/heuristics.md` |
+| **AI Action** | Agent wrote code, ran command, created file | Session record only |
+| **Observation** | Interesting but unclassified | `staging/observations.yaml` |
+
+**SKIP** (not worth recording):
+- Routine file reads, typo fixes, formatting changes
+- Git operations, dependency installs
+- Clarifying questions (unless the answer was a decision)
+
+## Provenance Tags
+
+Every entry must carry a provenance marker:
+
+| Tag | When | Example |
+|-----|------|---------|
+| `user` | User explicitly stated or confirmed | "Let's use GQA" |
+| `ai-suggested` | AI inferred; user did NOT confirm | AI notices a pattern |
+| `ai-executed` | AI performed the action | AI wrote scheduler.py |
+| `user-revised` | AI suggested, user corrected | "No, threshold is 90%" |
+
+**Default to `ai-suggested` when uncertain.** Never mark inferences as `user`.
+
+## ARA Directory Structure
+
+```text
+ara/
+  PAPER.md                          # Root manifest + layer index
+  logic/                            # What & Why
+    problem.md                      #   Problem definition + gaps
+    claims.md                       #   Falsifiable assertions + proof refs
+    concepts.md                     #   Term definitions
+    experiments.md                  #   Experiment plans (declarative)
+    solution/
+      architecture.md               #   System design
+      algorithm.md                  #   Math + pseudocode
+      constraints.md                #   Boundary conditions
+      heuristics.md                 #   Tricks + rationale + sensitivity
+    related_work.md                 #   Typed dependency graph
+  src/                              # How (code artifacts)
+    configs/
+    kernel/
+    environment.md
+  trace/                            # Journey
+    exploration_tree.yaml           #   Research DAG
+    sessions/
+      session_index.yaml            #   Master session index
+      YYYY-MM-DD_NNN.yaml          #   Individual session records
+  evidence/                         # Raw Proof
+    README.md
+    tables/
+    figures/
+  staging/                          # Unclassified observations
+    observations.yaml
+```
+
+## Writing Formats
+
+### Exploration Tree Structure (exploration_tree.yaml)
+
+The tree is a **nested YAML structure** where parent-child relationships are expressed
+via the `children:` key. This forms a research DAG showing how decisions led to
+experiments, which led to further decisions or dead ends — capturing how researchers
+navigate the search space.
+
+- Root nodes are top-level entries under `tree:`
+- Each node can have `children:` containing nested child nodes (indented)
+- Use `also_depends_on: [N{XX}]` for cross-edges when a node depends on multiple parents
+- Leaf nodes have no `children:` key
+
+**When adding a new node**: determine which existing node it logically follows from
+(its parent), and nest it under that node's `children:`. If it's a new top-level
+research thread, add it as a root node.
+
+```yaml
+tree:
+  - id: N01
+    type: question
+    title: "{root research question}"
+    provenance: user
+    timestamp: "YYYY-MM-DDTHH:MM"
+    description: >
+      {what is being explored}
+    children:
+
+      - id: N02
+        type: experiment
+        title: "{what was tested}"
+        provenance: ai-executed
+        timestamp: "YYYY-MM-DDTHH:MM"
+        result: >
+          {what happened — include numbers}
+        evidence: [C{XX}, "{figure/table refs}"]
+        children:
+
+          - id: N03
+            type: decision
+            title: "{choice made based on N02 results}"
+            provenance: user
+            timestamp: "YYYY-MM-DDTHH:MM"
+            choice: >
+              {what was chosen and why}
+            alternatives:
+              - "{option not chosen}"
+            evidence: >
+              {what motivated this — reference parent nodes}
+            children:
+
+              - id: N04
+                type: dead_end
+                title: "{approach that failed}"
+                provenance: user
+                timestamp: "YYYY-MM-DDTHH:MM"
+                hypothesis: >
+                  {what was expected to work}
+                failure_mode: >
+                  {why it failed}
+                lesson: >
+                  {what was learned}
+
+              - id: N05
+                type: experiment
+                title: "{alternative that worked}"
+                also_depends_on: [N02]  # cross-edge: also informed by N02
+                provenance: ai-executed
+                timestamp: "YYYY-MM-DDTHH:MM"
+                result: >
+                  {outcome}
+                evidence: [C{XX}]
+
+      - id: N06
+        type: dead_end
+        title: "{sibling approach tried from N01}"
+        provenance: user
+        timestamp: "YYYY-MM-DDTHH:MM"
+        hypothesis: >
+          {what was expected}
+        failure_mode: >
+          {why it failed}
+        lesson: >
+          {what was learned — motivated N02's direction}
+
+  - id: N07
+    type: pivot
+    title: "{new top-level research thread}"
+    provenance: user
+    timestamp: "YYYY-MM-DDTHH:MM"
+    from: "{previous direction}"
+    to: "{new direction}"
+    trigger: "{what caused the change}"
+```
+
+### Node Type Reference
+
+| Type | Required Fields | When to Use |
+|------|----------------|-------------|
+| `question` | `description` | Root research question or sub-question |
+| `decision` | `choice`, `alternatives`, `evidence` | User chose between options |
+| `experiment` | `result`, `evidence` | Test/benchmark produced a result |
+| `dead_end` | `hypothesis`, `failure_mode`, `lesson` | Approach abandoned |
+| `pivot` | `from`, `to`, `trigger` | Major direction change |
+
+### Claim (logic/claims.md)
+```markdown
+## C{XX}: {title}
+- **Statement**: {falsifiable assertion}
+- **Status**: hypothesis | untested | testing | supported | weakened | refuted | revised
+- **Provenance**: user | ai-suggested | user-revised
+- **Falsification criteria**: {what would disprove this}
+- **Proof**: [{evidence refs or "pending"}]
+- **Dependencies**: [C{YY}, ...]
+- **Tags**: {comma-separated}
+```
+
+### Heuristic (logic/solution/heuristics.md)
+```markdown
+## H{XX}: {title}
+- **Rationale**: {why this works}
+- **Provenance**: user | ai-suggested | user-revised
+- **Sensitivity**: low | medium | high
+- **Code ref**: [{file paths}]
+```
+
+### Observation (staging/observations.yaml)
+```yaml
+- id: O{XX}
+  timestamp: "YYYY-MM-DDTHH:MM"
+  provenance: user | ai-suggested | ai-executed
+  content: "{raw observation}"
+  context: "{what was happening}"
+  potential_type: claim | heuristic | decision | unknown
+  promoted: false
+```
+
+### Session Record (trace/sessions/YYYY-MM-DD_NNN.yaml)
+```yaml
+session:
+  id: "YYYY-MM-DD_NNN"
+  timestamp: "YYYY-MM-DDTHH:MM"
+  summary: "{one-line summary of what happened}"
+
+events_logged:
+  - type: decision | experiment | dead_end | pivot | claim | heuristic | observation
+    id: "{N/C/H/O}{XX}"
+    provenance: user | ai-suggested | ai-executed | user-revised
+    summary: "{what}"
+
+ai_actions:
+  - action: "{what AI did}"
+    provenance: ai-executed
+    files_changed: ["{paths}"]
+
+claims_touched:
+  - id: C{XX}
+    action: created | advanced | weakened | confirmed
+    provenance: user | ai-suggested
+
+open_threads:
+  - "{what needs follow-up}"
+
+ai_suggestions_pending:
+  - "{unconfirmed AI suggestions from this session}"
+```
+
+## Initialization (if ara/ does not exist)
+
+Create the full directory structure and seed files automatically. Do not ask.
+
+```bash
+mkdir -p ara/{logic/solution,src/{configs,kernel},trace/sessions,evidence/{tables,figures},staging}
+```
+
+Then write:
+1. `ara/PAPER.md` — root manifest (infer title, authors, venue from project context)
+2. `ara/trace/sessions/session_index.yaml` — `sessions: []`
+3. `ara/trace/exploration_tree.yaml` — `tree: []`
+4. `ara/staging/observations.yaml` — `observations: []`
+5. `ara/logic/claims.md` — `# Claims`
+6. `ara/logic/problem.md` — `# Problem`
+7. `ara/logic/solution/heuristics.md` — `# Heuristics`
+8. `ara/evidence/README.md` — `# Evidence Index`
+
+## Maturity Tracker (runs during epilogue)
+
+While reviewing `staging/observations.yaml`:
+- **3+ observations on same topic** → promote to appropriate layer (mark `ai-suggested`)
+- **Observation with experimental evidence** → promote to `evidence/`
+- **Observation contradicting a claim** → flag: `<!-- CONFLICT: contradicts C{XX} -->`
+- **Stale observations (3+ sessions)** → flag with `stale: true`
+
+## Procedure
+
+1. Read existing `ara/` files to get current state (IDs, claims, tree).
+2. Scan the full conversation for research-significant events.
+3. Classify each event and assign provenance.
+4. Append new entries to the correct files. Update existing entries if status changed.
+5. Create session record at `ara/trace/sessions/YYYY-MM-DD_NNN.yaml`.
+6. Append session to `ara/trace/sessions/session_index.yaml`.
+7. Run maturity tracker on staging area.
+8. Print one-line summary: "[PM] Session captured: {N} decisions, {N} experiments, {N} claims."
+
+## Rules
+
+1. **Never run during a task** — only as epilogue after the user's request is done.
+2. **Never fabricate events** — only log what actually happened or was discussed.
+3. **Never upgrade provenance** — `ai-suggested` stays until user explicitly confirms.
+4. **Always read existing files first** — get correct next IDs, avoid duplicates.
+5. **Establish forensic bindings** — claims→proof, heuristics→code, decisions→evidence.
+6. **Append, don't overwrite** — add new entries, never replace existing content.
+7. **Keep YAML valid** — validate structure after writes.
+
+## Reference Files
+
+For detailed protocol and taxonomy specifications, load on demand:
+- [references/event-taxonomy.md](references/event-taxonomy.md) — Full classification of research-significant events
+- [references/provenance-tags.md](references/provenance-tags.md) — Provenance tag semantics and edge cases
+- [references/session-protocol.md](references/session-protocol.md) — Step-by-step session recording protocol

package/skills/ai-research/22-agent-native-research-artifact/research-manager/references/event-taxonomy.md

@@ -0,0 +1,124 @@
+<!-- vendored from orchestra-research/AI-research-SKILLs@773a52944ba4747a18bd4ae9ade53fff041adcbc 22-agent-native-research-artifact/research-manager/references/event-taxonomy.md; MIT (c) Orchestra Research -->
+# Event Taxonomy & Routing Rules
+
+## Event Classification
+
+When you observe activity in the coding session, classify it into one of these event types.
+Use the **signals** column to identify events from conversation and code context.
+
+### Research Events (Route to `trace/exploration_tree.yaml`)
+
+| Type | Signals | Example |
+|------|---------|---------|
+| **question** | User asks "what if...", "should we...", "how does..." about research direction | "Should we use attention or convolution for the encoder?" |
+| **decision** | User chooses between alternatives, commits to a direction | "Let's go with GQA instead of MHA — lower memory footprint" |
+| **experiment** | Code runs a test/benchmark, user reports results | "The learning rate sweep shows 3e-4 is optimal" |
+| **dead_end** | Approach abandoned, hypothesis falsified, "this doesn't work" | "Tried FP16 but the loss diverges after 1k steps" |
+| **pivot** | Major direction change triggered by evidence | "The attention approach is too slow — switching to state space models" |
+
+### Knowledge Events (Route to `logic/`)
+
+| Type | Signals | Routes To |
+|------|---------|-----------|
+| **claim** | "I believe...", "The system achieves...", assertion about capability/property | `logic/claims.md` |
+| **heuristic** | "The trick is...", "You need to...", implementation insight | `logic/solution/heuristics.md` |
+| **concept** | New term defined, disambiguation needed | `logic/concepts.md` |
+| **constraint** | "This only works when...", boundary condition | `logic/solution/constraints.md` |
+| **architecture** | System design, component relationships | `logic/solution/architecture.md` |
+
+### Evidence Events (Route to `evidence/`)
+
+| Type | Signals | Routes To |
+|------|---------|-----------|
+| **result_table** | Tabular data, benchmark numbers, comparison matrix | `evidence/tables/table{N}.md` |
+| **result_figure** | Plot data, visualization, chart values | `evidence/figures/fig{N}.md` |
+| **metric** | Single quantitative measurement | Inline in experiment node or evidence file |
+
+### Process Events (Route to `trace/sessions/`)
+
+| Type | Signals | Routes To |
+|------|---------|-----------|
+| **ai-action** | Agent wrote code, ran command, created file | Session record |
+| **ai-suggestion** | Agent proposed direction, hypothesis, approach | Session record (ai_suggestions_pending) |
+| **user-direction** | User gives high-level instruction or corrects | Session record (events_logged with provenance: user) |
+
+### Staging Events (Route to `staging/`)
+
+| Type | Signals | Routes To |
+|------|---------|-----------|
+| **observation** | Doesn't clearly fit above categories; interesting but unstructured | `staging/observations.yaml` |
+
+## Routing Decision Tree
+
+```
+Is it about a choice between alternatives?
+  → YES: decision (trace)
+  → NO: ↓
+
+Is it a quantitative result or experimental outcome?
+  → YES: experiment (trace) + evidence data (evidence/)
+  → NO: ↓
+
+Is it an abandoned approach with a reason?
+  → YES: dead_end (trace)
+  → NO: ↓
+
+Is it a falsifiable assertion about the system/method?
+  → YES: claim (logic/claims.md)
+  → NO: ↓
+
+Is it an implementation trick with rationale?
+  → YES: heuristic (logic/solution/heuristics.md)
+  → NO: ↓
+
+Is it a major direction change?
+  → YES: pivot (trace)
+  → NO: ↓
+
+Is it a research question being explored?
+  → YES: question (trace)
+  → NO: → observation (staging)
+```
+
+## Provenance Assignment
+
+```
+Who generated this information?
+
+User said it directly (typed it, stated it, confirmed it)
+  → provenance: user
+
+AI inferred it from code, output, or conversation context
+  → provenance: ai-suggested
+
+AI performed an action (wrote code, ran test, made edit)
+  → provenance: ai-executed
+
+User modified an AI suggestion ("no, actually..." / "more like...")
+  → provenance: user-revised
+```
+
+## ID Conventions
+
+| Type | Prefix | Example | Scope |
+|------|--------|---------|-------|
+| Exploration node | N | N01, N02 | Global (across all sessions) |
+| Claim | C | C01, C02 | Global |
+| Heuristic | H | H01, H02 | Global |
+| Experiment plan | E | E01, E02 | Global |
+| Observation | O | O01, O02 | Global |
+| Session | date_seq | 2026-03-11_001 | Unique by date |
+
+**Auto-increment**: Always read the existing file to find the highest ID before creating a new one.
+
+## Forensic Binding Checklist
+
+When logging any event, establish these bindings immediately:
+
+- [ ] **Claim → Proof**: If a claim is created, what evidence would prove/disprove it? Set `Proof: [pending]` if no evidence yet.
+- [ ] **Experiment → Claim**: Which claims does this experiment test? Link via `Claims tested:`.
+- [ ] **Heuristic → Code**: Where in the codebase is this implemented? Set `Code ref:`.
+- [ ] **Decision → Evidence**: What evidence or reasoning drove this decision?
+- [ ] **Dead End → Lesson**: What was learned? Could this knowledge prevent future mistakes?
+
+If a binding can't be established now, add a `<!-- TODO: bind to {target} -->` comment as a trackable obligation.

package/skills/ai-research/22-agent-native-research-artifact/research-manager/references/provenance-tags.md

@@ -0,0 +1,190 @@
+<!-- vendored from orchestra-research/AI-research-SKILLs@773a52944ba4747a18bd4ae9ade53fff041adcbc 22-agent-native-research-artifact/research-manager/references/provenance-tags.md; MIT (c) Orchestra Research -->
+# Provenance Tracking System
+
+## Why Provenance Matters
+
+In a human-AI collaborative research process, the origin of each piece of knowledge determines
+its epistemic status. A claim the user explicitly stated has different weight than one the AI
+inferred from code output. Provenance tracking ensures:
+
+1. **Auditability**: Reviewers/collaborators can trace every assertion to its source
+2. **Trust calibration**: AI suggestions are clearly marked as unconfirmed
+3. **Correction flow**: When users revise AI suggestions, the revision history is preserved
+4. **Accountability**: AI actions (code written, tests run) are attributed correctly
+
+## Provenance Tags
+
+### `user` — User Confirmed/Input
+
+The user explicitly stated, typed, or confirmed this information.
+
+**When to apply:**
+- User directly says something: "The learning rate should be 3e-4"
+- User confirms an AI suggestion: "yes, log that" / "correct"
+- User provides a decision: "Let's go with approach A"
+- User states a research question: "Can we reduce memory by 50%?"
+
+**Examples:**
+```markdown
+## C01: Attention is sufficient for sequence modeling
+- **Statement**: Self-attention alone, without recurrence, achieves SOTA on translation
+- **Provenance**: user
+```
+
+```yaml
+- id: N05
+  type: decision
+  provenance: user
+  title: "Use GQA instead of MHA"
+  choice: "GQA reduces KV cache by 8x with <1% quality loss"
+```
+
+### `ai-suggested` — AI Inference (Unconfirmed)
+
+The AI inferred, proposed, or hypothesized this based on context. The user has NOT
+explicitly confirmed it.
+
+**When to apply:**
+- AI observes a pattern in code/output and proposes an interpretation
+- AI suggests a research direction
+- AI infers a claim from experimental results
+- AI proposes a classification for an observation
+- AI suggests what a decision's alternatives might have been
+
+**Examples:**
+```markdown
+## C07: The overhead-aware refiner prevents QoE collapse under sustained bursts
+- **Statement**: Without the refiner, preemption overhead accumulates and degrades QoE
+- **Provenance**: ai-suggested
+<!-- AI inferred this from the ablation results; user has not confirmed -->
+```
+
+```yaml
+- id: O03
+  provenance: ai-suggested
+  content: "Training instability above batch_size=64 may be caused by gradient norm explosion"
+  context: "Observed NaN losses during hyperparameter sweep"
+```
+
+**Upgrade path**: When user confirms → change to `user` or `user-revised`
+
+### `ai-executed` — AI Action
+
+The AI performed a concrete action: wrote code, ran a command, created a file,
+executed a test.
+
+**When to apply:**
+- AI wrote or modified a source file
+- AI ran a benchmark or test suite
+- AI created an ARA entry
+- AI generated experimental results
+
+**Examples:**
+```yaml
+- type: ai-action
+  action: "Wrote src/scheduler_v2.py implementing greedy knapsack"
+  provenance: ai-executed
+  files_changed: [src/scheduler_v2.py]
+```
+
+```yaml
+- id: N12
+  type: experiment
+  provenance: ai-executed
+  title: "Ran BurstGPT benchmark with overhead-aware refiner"
+  result: "97% requests achieve QoE >= 0.95"
+```
+
+### `user-revised` — AI Suggested, User Modified
+
+The AI made a suggestion, and the user modified it rather than accepting or rejecting outright.
+
+**When to apply:**
+- User says "not exactly, it's more like..."
+- User corrects a detail: "the threshold is 90%, not 85%"
+- User refines scope: "that's true but only for dense models"
+- User provides nuance: "yes but the real reason is..."
+
+**Examples:**
+```markdown
+## H03: Batch size search space pruning
+- **Provenance**: user-revised
+<!-- AI initially suggested pruning to [1, B_max]. User corrected:
+     "No, B_min is also bounded — below B_min, TDS > r_user for all requests" -->
+```
+
+**Track the revision:**
+```yaml
+- id: O05
+  provenance: user-revised
+  content: "KV cache watermark threshold should be 90%, not 85%"
+  revision_history:
+    - original: "ai-suggested watermark at 85%"
+    - revised: "user corrected to 90% based on profiling data"
+```
+
+## Provenance in Different File Types
+
+### Markdown Files (claims.md, heuristics.md, etc.)
+
+Use the `Provenance` field in the structured entry:
+
+```markdown
+## C{XX}: {title}
+- **Provenance**: user | ai-suggested | user-revised
+```
+
+For inline notes within longer text, use HTML comments:
+
+```markdown
+The system achieves 97% QoE coverage <!-- provenance: ai-executed (from benchmark run) -->
+under bursty load conditions <!-- provenance: user (stated requirement) -->.
+```
+
+### YAML Files (exploration_tree, sessions, staging)
+
+Use the `provenance:` field on each node/entry:
+
+```yaml
+- id: N05
+  type: decision
+  provenance: user
+```
+
+### Mixed-Provenance Entries
+
+Some entries have mixed provenance (e.g., AI ran experiment, user interpreted result):
+
+```yaml
+- id: N12
+  type: experiment
+  provenance: ai-executed        # AI ran the benchmark
+  result: "97% QoE >= 0.95"     # Factual output
+  interpretation:                # User's reading of the result
+    provenance: user
+    content: "This confirms our hypothesis — overhead awareness is critical"
+```
+
+## Provenance Aggregation in Session Records
+
+Session records aggregate provenance statistics:
+
+```yaml
+provenance_summary:
+  user_confirmed: 5          # Events with provenance: user
+  ai_suggested: 3            # Unconfirmed AI suggestions
+  ai_executed: 7             # AI actions taken
+  user_revised: 1            # User corrections to AI suggestions
+  confirmation_rate: 0.625   # user / (user + ai-suggested)
+```
+
+This helps track how much of the research knowledge is human-confirmed vs. AI-inferred,
+providing a trust signal for the overall artifact quality.
+
+## Rules for Provenance Integrity
+
+1. **Never auto-upgrade**: `ai-suggested` → `user` requires explicit user confirmation
+2. **Preserve history**: When upgrading, keep the original provenance in a comment or revision field
+3. **Default conservative**: When unsure, use `ai-suggested`
+4. **Compound events**: If user asked AI to run something, the action is `ai-executed` but the interpretation may be `user` or `ai-suggested`
+5. **Silence is not confirmation**: If you suggest something and the user doesn't respond, it stays `ai-suggested`