From 2ab576a731640842811dcd4a3c9faed17e108925 Mon Sep 17 00:00:00 2001 From: Agent IX Date: Tue, 23 Jun 2026 08:13:16 -0700 Subject: [PATCH] feat(archetype): add Feedback archetype for cockpit review threads MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A transient review-thread artifact the filament-ide cockpit writes under ~/.ix and an agent reads to refine — the first-class home for what was previously an unspecified feedback format. - frontmatter schema: status (open/addressed/resolved), kind (comment/triage), optional decision (Fix/Dismiss/Defer), and an anchor with text-primary / block-fallback resolution (W3C-style quote+prefix/suffix, falling back to a structural requirementId/headingPath+blockIndex; reader orphans on total miss) - manifest artifact_type + feedback doc_kind; references/found_in links - ## Comment body (required), ## Resolution (optional); skeleton + example Worktree-only; not deployed to ~/.ix and no release. Module tests pass. Co-Authored-By: Claude Opus 4.8 (1M context) --- spec_artifacts_process/examples/feedback.md | 33 +++++++ spec_artifacts_process/manifest.yaml | 19 ++++ .../schemas/feedback-frontmatter.schema.json | 99 +++++++++++++++++++ spec_artifacts_process/skeletons/Feedback.md | 46 +++++++++ 4 files changed, 197 insertions(+) create mode 100644 spec_artifacts_process/examples/feedback.md create mode 100644 spec_artifacts_process/schemas/feedback-frontmatter.schema.json create mode 100644 spec_artifacts_process/skeletons/Feedback.md diff --git a/spec_artifacts_process/examples/feedback.md b/spec_artifacts_process/examples/feedback.md new file mode 100644 index 0000000..17ac48b --- /dev/null +++ b/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. diff --git a/spec_artifacts_process/manifest.yaml b/spec_artifacts_process/manifest.yaml index 97bb913..f7fdfda 100644 --- a/spec_artifacts_process/manifest.yaml +++ b/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: diff --git a/spec_artifacts_process/schemas/feedback-frontmatter.schema.json b/spec_artifacts_process/schemas/feedback-frontmatter.schema.json new file mode 100644 index 0000000..f8639a9 --- /dev/null +++ b/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" } + } + } + } + } +} diff --git a/spec_artifacts_process/skeletons/Feedback.md b/spec_artifacts_process/skeletons/Feedback.md new file mode 100644 index 0000000..7ce8150 --- /dev/null +++ b/spec_artifacts_process/skeletons/Feedback.md @@ -0,0 +1,46 @@ +--- +id: FB-001 +title: "" +type: Feedback +status: open +kind: comment +anchor: + artifact: "spec/functional/FR-003-validate-spec-in-renderer.md" + text: + quote: "" + prefix: "" + suffix: "" + block: + requirementId: "FR-003-AC-2" + headingPath: ["FR-003", "Acceptance Criteria"] + blockIndex: 0 +relationships: + - target: ix://agent-ix/example/FR-003 + type: references +--- + +# [FB-001] + +## Comment + + + +## Resolution + +