feat(archetype): add Feedback archetype for cockpit review threads

spec_artifacts_process/examples/feedback.md

@@ -0,0 +1,33 @@
+---
+id: FB-001
+title: "Bound the project root the main process may open"
+type: Feedback
+status: open
+kind: triage
+decision: Fix
+anchor:
+  artifact: "spec/functional/FR-001-open-project-enumerate-artifacts.md"
+  text:
+    quote: "the system SHALL enumerate the Quoin artifacts beneath it"
+    prefix: "When the user selects a local project root, "
+    suffix: " — spec artifacts"
+  block:
+    requirementId: "FR-001"
+    headingPath: ["FR-001", "Description"]
+    blockIndex: 0
+relationships:
+  - target: ix://agent-ix/filament-ide/FR-001
+    type: references
+---
+# [FB-001] Bound the project root the main process may open
+
+## Comment
+
+Add a constraint that the main process rejects a project root that resolves —
+after symlink expansion — outside an allowed base directory, closing the
+path-traversal gap raised in the scope-boundary review. The enumeration itself is
+fine; the missing piece is bounding which roots may be opened in the first place.
+
+## Resolution
+
+Pending — to be filled when the FR is updated with the bounding constraint.

spec_artifacts_process/manifest.yaml

@@ -58,6 +58,7 @@ grammars:
   - test-matrix
   - standard
   - finding
+  - feedback
 artifact_types:
 - name: ADR
   grammar_ref: process-artifacts
@@ -143,6 +144,23 @@ artifact_types:
   - references
   examples: []
   lint_rules_ref: []
+- name: Feedback
+  grammar_ref: process-artifacts
+  frontmatter_schema_ref: schemas/feedback-frontmatter.schema.json
+  defaults:
+    id_pattern: FB-{next:03d}
+  allowed_links:
+  - references
+  - found_in
+  examples: []
+  lint_rules_ref: []
+  body_extraction:
+    yield_pattern:
+      match:
+        comment:
+          from: section_body
+          after_heading: Comment
+          required: true
 - name: TestMatrix
   grammar_ref: process-artifacts
   frontmatter_schema_ref: schemas/testmatrix-frontmatter.schema.json
@@ -170,6 +188,7 @@ doc_kinds:
 - test-matrix
 - standard
 - finding
+- feedback
 object_types:
 - name: standard
   data_schema:

spec_artifacts_process/schemas/feedback-frontmatter.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": [
+    "id",
+    "title",
+    "type",
+    "status",
+    "kind",
+    "anchor"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Z]{2,4}-[0-9]+$"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "type": {
+      "const": "Feedback"
+    },
+    "status": {
+      "description": "Human review-thread lifecycle. Anchor resolution (anchored/drifted/orphaned) is computed at load time and not stored here.",
+      "enum": ["open", "addressed", "resolved"]
+    },
+    "kind": {
+      "description": "A free-form passage comment, or a decision on a review finding.",
+      "enum": ["comment", "triage"]
+    },
+    "decision": {
+      "description": "Required meaning only when kind is 'triage'.",
+      "enum": ["Fix", "Dismiss", "Defer"]
+    },
+    "anchor": {
+      "description": "Where this feedback attaches. Resolution is text-primary, block-fallback: prefer the exact text selector; if the quote is gone, fall back to the structural block; if the block is gone, the app marks the thread orphaned (never silently re-points).",
+      "type": "object",
+      "required": ["artifact"],
+      "additionalProperties": true,
+      "properties": {
+        "artifact": {
+          "description": "The artifact this feedback is anchored in — a repo-relative path or an ix:// reference.",
+          "type": "string",
+          "minLength": 1
+        },
+        "text": {
+          "description": "PRIMARY selector — the exact selected text plus a little surrounding context for disambiguation (W3C TextQuoteSelector style).",
+          "type": "object",
+          "required": ["quote"],
+          "additionalProperties": true,
+          "properties": {
+            "quote": { "type": "string", "minLength": 1 },
+            "prefix": { "type": "string" },
+            "suffix": { "type": "string" }
+          }
+        },
+        "block": {
+          "description": "FALLBACK selector — a structural locator that survives prose rewrites. At least one of its fields should be present.",
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "requirementId": {
+              "description": "The owning requirement or acceptance-criterion id, e.g. FR-003 or FR-003-AC-2.",
+              "type": "string"
+            },
+            "headingPath": {
+              "description": "Ordered heading trail to the block, e.g. [\"FR-003\", \"Description\"].",
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "blockIndex": {
+              "description": "Zero-based index of the block within its section.",
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        }
+      }
+    },
+    "object": {
+      "type": "string"
+    },
+    "relationships": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["target", "type"],
+        "additionalProperties": false,
+        "properties": {
+          "target": { "type": "string", "pattern": "^ix://" },
+          "type": { "type": "string" },
+          "cardinality": { "type": "string" }
+        }
+      }
+    }
+  }
+}

spec_artifacts_process/skeletons/Feedback.md

@@ -0,0 +1,46 @@
+---
+id: FB-001
+title: "<short summary of the feedback>"
+type: Feedback
+status: open
+kind: comment
+anchor:
+  artifact: "spec/functional/FR-003-validate-spec-in-renderer.md"
+  text:
+    quote: "<the exact selected text>"
+    prefix: "<a few characters before the selection>"
+    suffix: "<a few characters after the selection>"
+  block:
+    requirementId: "FR-003-AC-2"
+    headingPath: ["FR-003", "Acceptance Criteria"]
+    blockIndex: 0
+relationships:
+  - target: ix://agent-ix/example/FR-003
+    type: references
+---
+<!-- Feedback authoring skeleton (spec-artifacts-process). A transient review
+     thread the cockpit writes under ~/.ix and an agent reads to refine.
+     Contract (validated by `quire validate`):
+     - Frontmatter: type: Feedback; id matches ^[A-Z]{2,4}-[0-9]+$ (e.g. FB-001);
+       status ∈ open|addressed|resolved; kind ∈ comment|triage;
+       decision ∈ Fix|Dismiss|Defer (meaningful only when kind: triage);
+       anchor.artifact required.
+     - Anchor resolution is text-primary, block-fallback: prefer anchor.text.quote
+       (with prefix/suffix for disambiguation); if the quote is gone, fall back to
+       anchor.block (requirementId / headingPath+blockIndex); if the block is gone
+       too, the reader marks the thread orphaned — it never silently re-points.
+     - REQUIRED body (level 2): ## Comment — the reviewer's comment, or for a triage
+       decision the "how to fix" guidance.
+     - OPTIONAL body (level 2): ## Resolution — what changed, or why dismissed/deferred.
+     - relationships: a `references` edge to the requirement/finding this targets. -->
+# [FB-001] <short summary of the feedback>
+
+## Comment
+
+<The reviewer's comment. For a triage decision (kind: triage) this is the
+"how to fix" guidance that tells the agent exactly what to do.>
+
+## Resolution
+
+<Optional — filled when the thread is addressed or resolved: what changed in the
+artifact, or why the finding was dismissed or deferred.>