ai-spector 0.9.21 → 0.9.25

package/contracts/bootstrap/templates/srs/7-quality-attributes.md

@@ -0,0 +1,74 @@
+## 7. Non-Functional Requirements (Quality Attributes)
+
+> This section specifies the non-functional requirements that define the quality attributes, constraints, and performance characteristics of the system. These requirements describe how the system should behave rather than what functions it should perform.
+
+### 7.1 Usability
+
+> Specify any requirements regarding characteristics that will make the software appear to be "user-friendly."
+
+**Requirements:**
+- **Ease of Use:** <Requirement>
+- **Ease of Learning:** <Requirement>
+- **Accessibility:** <Requirement>
+- **Error Handling:** <Requirement>
+
+**UI Design Standards:**
+- <Standard 1>
+- <Standard 2>
+
+### 7.2 Performance
+
+> State specific performance requirements for various system operations.
+
+| Operation | Response Time Requirement |
+|-----------|---------------------------|
+| <Operation 1> | <Time requirement> |
+| <Operation 2> | <Time requirement> |
+
+**Throughput Requirements:**
+- <Requirement 1>
+- <Requirement 2>
+
+### 7.3 Security
+
+> Specify any requirements regarding security or privacy issues.
+
+**Requirements:**
+- **Access Control:** <Requirement>
+- **Authentication:** <Requirement>
+- **Authorization:** <Requirement>
+- **Data Security:** <Requirement>
+- **Privacy:** <Requirement>
+
+**Compliance:**
+- <Compliance requirement 1>
+- <Compliance requirement 2>
+
+### 7.4 Safety
+
+> Specify requirements that are concerned with possible loss, damage, or harm.
+
+**Requirements:**
+- <Requirement 1>
+- <Requirement 2>
+
+**Safeguards:**
+- <Safeguard 1>
+- <Safeguard 2>
+
+### 7.5 Others as relevant
+
+> Create a separate section for each additional product quality attribute.
+
+**Availability:**
+- <Requirement 1>
+- <Requirement 2>
+
+**Reliability:**
+- <Requirement 1>
+- <Requirement 2>
+
+**Maintainability:**
+- <Requirement 1>
+- <Requirement 2>
+

package/contracts/bootstrap/templates/srs/8-internationalization.md

@@ -0,0 +1,36 @@
+## 8. Internationalization and Localization Requirements
+
+> Internationalization and localization requirements ensure that the product will be suitable for use in nations, cultures, and geographic locations other than those in which it was created.
+
+**Supported Languages:**
+
+- <Language 1>
+- <Language 2>
+
+**Supported Locales:**
+
+- <Locale 1>
+- <Locale 2>
+
+**Formatting Requirements:**
+
+- **Currency:** 
+- **Date/Time:** 
+- **Numbers:** 
+- **Addresses:** 
+
+**Character Sets:**
+
+- <Requirement 1>
+- <Requirement 2>
+
+**Cultural Considerations:**
+
+- <Consideration 1>
+- <Consideration 2>
+
+**Regulatory Compliance:**
+
+- <Regulation 1>
+- <Regulation 2>
+

package/contracts/bootstrap/templates/srs/9-other-requirements.md

@@ -0,0 +1,46 @@
+## 9. Other Requirements
+
+> Examples are: legal, regulatory or financial compliance, and standards requirements; requirements for product installation, configuration, startup, and shutdown; and logging, monitoring and audit trail requirements.
+
+### 9.1 Legal and Regulatory Compliance
+
+**Legal Requirements:**
+- <Requirement 1>
+- <Requirement 2>
+
+**Regulatory Compliance:**
+- <Compliance requirement 1>
+- <Compliance requirement 2>
+
+**Standards Compliance:**
+- <Standard 1>
+- <Standard 2>
+
+### 9.2 Installation and Configuration
+
+**Installation Requirements:**
+- <Requirement 1>
+- <Requirement 2>
+
+**Configuration Requirements:**
+- <Requirement 1>
+- <Requirement 2>
+
+**Startup/Shutdown Requirements:**
+- <Requirement 1>
+- <Requirement 2>
+
+### 9.3 Logging and Monitoring
+
+**Logging Requirements:**
+- <Requirement 1>
+- <Requirement 2>
+
+**Monitoring Requirements:**
+- <Requirement 1>
+- <Requirement 2>
+
+**Audit Trail Requirements:**
+- <Requirement 1>
+- <Requirement 2>
+

package/contracts/examples/full-docops.config.json

@@ -0,0 +1,54 @@
+{
+  "schemaVersion": "1.0",
+  "layout": "docops",
+  "docsRoot": "docs",
+  "languages": [
+    { "code": "en", "label": "English", "path": "en" },
+    { "code": "vi", "label": "Vietnamese", "path": "vi" },
+    { "code": "jp", "label": "Japanese", "path": "jp" }
+  ],
+  "primaryLanguage": "en",
+  "internalLanguage": "vi",
+  "clientLanguage": "jp",
+  "docTypes": {
+    "srs": {
+      "enabled": true,
+      "path": "docs/srs",
+      "label": "SRS",
+      "templatesPath": ".docops/templates/srs"
+    },
+    "basicDesign": {
+      "enabled": true,
+      "path": "docs/basic-design",
+      "label": "Basic Design",
+      "templatesPath": ".docops/templates/basic-design"
+    },
+    "detailDesign": {
+      "enabled": false,
+      "path": "docs/detail-design",
+      "label": "Detail Design",
+      "templatesPath": ".docops/templates/detail-design"
+    },
+    "otherDocument": {
+      "enabled": false,
+      "path": "docs/other",
+      "label": "Other Document"
+    }
+  },
+  "paths": {
+    "registry": ".docops/registry",
+    "comments": ".docops/comments",
+    "reviewConfig": ".docops/review.config.json",
+    "reviewQueue": ".docops/review-queue",
+    "prototypeConfig": ".docops/prototype/config.json",
+    "prototypeScreenMap": ".docops/prototype/screen-map.json"
+  },
+  "capabilities": {
+    "review": true,
+    "comments": true,
+    "prototype": true,
+    "graph": false,
+    "generate": false,
+    "translate": false
+  }
+}

package/contracts/examples/migrate-lifecycle.json

@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "intent": "migrate",
+  "adapter": "ai-spector",
+  "updatedAt": "2026-06-29T10:00:00Z",
+  "updatedBy": "kari-writer",
+  "steps": [
+    { "id": "project-created", "status": "done", "completedAt": "2026-06-29T10:00:00Z" },
+    { "id": "git-connected", "status": "done", "completedAt": "2026-06-29T10:00:00Z" },
+    { "id": "docops-init", "status": "done", "completedAt": "2026-06-29T10:00:00Z" },
+    { "id": "legacy-aligned", "status": "in_progress", "helpRef": "guide/MIGRATION.md" },
+    { "id": "registry-synced", "status": "pending", "helpRef": "guide/ENTITY_REGISTRY_MIGRATION.md" },
+    { "id": "local-adapter-ready", "status": "pending" },
+    { "id": "first-docs-generated", "status": "pending" },
+    { "id": "review-queue-synced", "status": "pending", "helpRef": "guide/modules/review.md" },
+    { "id": "first-push-synced", "status": "pending" }
+  ]
+}

package/contracts/examples/minimal-comment-thread/comment-root.json

@@ -0,0 +1,10 @@
+{
+  "commentId": "comment-root",
+  "threadId": "thread-001",
+  "body": "Please clarify the login flow requirements.",
+  "authorId": 42,
+  "createdAt": "2026-06-15T10:00:00.000Z",
+  "parentCommentId": null,
+  "editedAt": null,
+  "deletedAt": null
+}

package/contracts/examples/minimal-comment-thread/meta_data.json

@@ -0,0 +1,22 @@
+{
+  "threadId": "thread-001",
+  "filePath": "srs/01-overview.md",
+  "originBranch": "main",
+  "commentType": "document",
+  "status": "open",
+  "version": 1,
+  "createdAt": "2026-06-15T10:00:00.000Z",
+  "updatedAt": "2026-06-15T10:00:00.000Z",
+  "createdBy": 42,
+  "resolvedAt": null,
+  "resolvedBy": null,
+  "resolvedInCommitSha": null,
+  "anchor": {
+    "branchName": "main",
+    "filePath": "srs/01-overview.md",
+    "anchorState": "active",
+    "startLine": 10,
+    "endLine": 12,
+    "baseCommitSha": "abc123"
+  }
+}

package/contracts/examples/minimal-docops.config.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": "1.0",
+  "layout": "docops",
+  "docsRoot": "docs",
+  "languages": [
+    { "code": "en", "label": "English", "path": "en" }
+  ],
+  "primaryLanguage": "en",
+  "docTypes": {
+    "srs": {
+      "enabled": true,
+      "path": "docs/srs",
+      "label": "SRS",
+      "templatesPath": ".docops/templates/srs"
+    }
+  },
+  "paths": {
+    "registry": ".docops/registry",
+    "comments": ".docops/comments",
+    "reviewConfig": ".docops/review.config.json",
+    "reviewQueue": ".docops/review-queue",
+    "prototypeConfig": ".docops/prototype/config.json",
+    "prototypeScreenMap": ".docops/prototype/screen-map.json"
+  },
+  "capabilities": {
+    "review": false,
+    "comments": true,
+    "prototype": true,
+    "graph": false,
+    "generate": false,
+    "translate": false
+  }
+}

package/contracts/examples/minimal-lifecycle.json

@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "intent": "greenfield",
+  "adapter": "ai-spector",
+  "updatedAt": "2026-06-29T10:00:00Z",
+  "updatedBy": "kari-writer",
+  "steps": [
+    { "id": "project-created", "status": "done", "completedAt": "2026-06-29T10:00:00Z" },
+    { "id": "git-connected", "status": "done", "completedAt": "2026-06-29T10:00:00Z" },
+    { "id": "docops-init", "status": "in_progress", "helpRef": "guide/modules/generate.md" },
+    { "id": "local-adapter-ready", "status": "pending", "helpRef": "course/en/02-get-started/01-setup-via-chat" },
+    { "id": "data-source-added", "status": "pending" },
+    { "id": "first-docs-generated", "status": "pending" },
+    { "id": "review-queue-synced", "status": "pending", "helpRef": "guide/modules/review.md" },
+    { "id": "first-push-synced", "status": "pending" }
+  ]
+}

package/contracts/examples/minimal-prototype.config.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": 1,
+  "version": 1,
+  "buildMode": "static",
+  "techStack": "html",
+  "prototypeDir": "prototype",
+  "srcDir": "prototype/src",
+  "defaultTheme": "vercel",
+  "htpasswdFile": "prototype/.htpasswd",
+  "basicAuth": {
+    "username": "reviewer",
+    "password": "change-me",
+    "setAt": "2026-06-15T10:00:00.000Z"
+  },
+  "reviewHost": "https://preview.example.com",
+  "projectId": "my-project",
+  "deployVersion": "1.0.0"
+}

package/contracts/examples/minimal-screen-map.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": 1,
+  "buildMode": "static",
+  "defaultScreenId": "SCR-001",
+  "defaultScreen": {
+    "screenId": "SCR-001",
+    "displayName": "Login",
+    "screenDocPath": "basic-design/screens/login.md",
+    "prototypePath": "",
+    "route_exists": false
+  },
+  "screens": [
+    {
+      "screenId": "SCR-001",
+      "displayName": "Login",
+      "screenDocPath": "basic-design/screens/login.md",
+      "screenDocs": {
+        "en": "docs/basic-design/en/screens/login.md"
+      },
+      "prototypePath": "",
+      "route_exists": false,
+      "reviewUrl": null
+    }
+  ]
+}

package/contracts/examples/registry/minimal-document.entity.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "entityId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "kind": "document",
+  "docType": "SRS",
+  "logicalPath": "srs/01-overview.md",
+  "repoDocs": {
+    "en": "docs/srs/en/01-overview.md",
+    "vi": "docs/srs/vi/01-overview.md"
+  },
+  "displayName": "01-overview",
+  "aliases": [],
+  "createdAt": "2026-06-01T00:00:00.000Z",
+  "updatedAt": "2026-06-26T12:00:00.000Z"
+}

package/contracts/examples/registry/minimal-manifest.json

@@ -0,0 +1,7 @@
+{
+  "schemaVersion": 1,
+  "buildMode": "static",
+  "defaultScreenId": "SCR-001",
+  "themeName": "default",
+  "directReviewUrl": false
+}

package/contracts/examples/registry/minimal-screen.entity.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "screenId": "SCR-001",
+  "kind": "prototype_screen",
+  "displayName": "Login",
+  "documentEntityId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
+  "prototypePath": "src/login.html",
+  "route_exists": true,
+  "reviewUrl": null,
+  "updatedAt": "2026-06-26T12:00:00.000Z"
+}

package/contracts/examples/review/minimal-pending.json

@@ -0,0 +1,14 @@
+{
+  "version": 2,
+  "jobs": [
+    {
+      "id": "srs/01-overview:internal",
+      "logicalPath": "srs/01-overview",
+      "track": "internal",
+      "reason": "first_review",
+      "queuedAt": "2026-06-15T10:00:00.000Z",
+      "baselineHash": null,
+      "currentHash": "abc123def456ef78"
+    }
+  ]
+}

package/contracts/examples/review/minimal-registry.json

@@ -0,0 +1,31 @@
+{
+  "version": 3,
+  "documents": {
+    "srs/01-overview": {
+      "logicalPath": "srs/01-overview",
+      "docPath": "docs/srs/en/01-overview.md",
+      "contentHash": "abc123def456ef78",
+      "overallStatus": "pending_internal",
+      "internal": {
+        "status": "pending",
+        "votes": [],
+        "quorumMetAt": null,
+        "closedAt": null,
+        "closedBy": null,
+        "closeReason": null,
+        "reopenedAt": null,
+        "invalidatedAt": null
+      },
+      "client": {
+        "status": "pending",
+        "votes": [],
+        "quorumMetAt": null,
+        "closedAt": null,
+        "closedBy": null,
+        "closeReason": null,
+        "reopenedAt": null
+      },
+      "lastEventAt": "2026-06-15T10:00:00.000Z"
+    }
+  }
+}

package/contracts/examples/review/minimal-review.config.json

@@ -0,0 +1,7 @@
+{
+  "schemaVersion": "1.0",
+  "extends": "kaopiz-default",
+  "meta": {
+    "source": "agent"
+  }
+}

package/contracts/schemas/comments/comment_body.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://kari-writer.local/contracts/schemas/comments/comment_body.schema.json",
+  "title": "CommentBody",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["commentId", "threadId", "body", "authorId", "createdAt"],
+  "properties": {
+    "commentId": { "type": "string", "minLength": 1 },
+    "threadId": { "type": "string", "minLength": 1 },
+    "body": { "type": "string" },
+    "authorId": { "type": "integer" },
+    "createdAt": { "type": "string" },
+    "parentCommentId": { "type": ["string", "null"] },
+    "editedAt": { "type": ["string", "null"] },
+    "deletedAt": { "type": ["string", "null"] },
+    "anchor": { "type": "object", "additionalProperties": true }
+  }
+}

package/contracts/schemas/comments/meta_data.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://kari-writer.local/contracts/schemas/comments/meta_data.schema.json",
+  "title": "CommentThreadMeta",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "threadId",
+    "commentType",
+    "status",
+    "version",
+    "createdAt",
+    "anchor"
+  ],
+  "properties": {
+    "threadId": { "type": "string", "minLength": 1 },
+    "targetId": { "type": "string", "minLength": 1 },
+    "filePath": { "type": "string", "minLength": 1 },
+    "originBranch": { "type": "string" },
+    "commentType": {
+      "type": "string",
+      "enum": ["document", "prototype"]
+    },
+    "status": {
+      "type": "string",
+      "enum": ["open", "resolved"]
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Concurrency token — bump on each thread mutation"
+    },
+    "createdAt": { "type": "string" },
+    "updatedAt": { "type": "string" },
+    "createdBy": { "type": "integer" },
+    "resolvedAt": { "type": ["string", "null"] },
+    "resolvedBy": { "type": ["integer", "null"] },
+    "resolvedInCommitSha": { "type": ["string", "null"] },
+    "anchor": { "$ref": "#/$defs/anchor" }
+  },
+  "$defs": {
+    "anchor": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["filePath"],
+      "properties": {
+        "branchName": { "type": "string" },
+        "filePath": { "type": "string", "minLength": 1 },
+        "anchorState": {
+          "type": "string",
+          "enum": ["active", "stale", "orphaned"]
+        },
+        "startLine": { "type": "integer", "minimum": 1 },
+        "endLine": { "type": "integer", "minimum": 1 },
+        "baseCommitSha": { "type": "string" }
+      }
+    }
+  }
+}

package/contracts/schemas/docops.config.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://kari-writer.local/contracts/schemas/docops.config.schema.json",
+  "title": "DocopsConfig",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schemaVersion"],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "layout": {
+      "type": "string",
+      "enum": ["docops"],
+      "description": "When set to docops, Writer reads comments/review/prototype from .docops/ paths only. Omit for legacy ai-spector layout."
+    },
+    "docsRoot": {
+      "type": "string",
+      "default": "docs",
+      "minLength": 1
+    },
+    "languages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["code", "label"],
+        "properties": {
+          "code": { "type": "string", "minLength": 1 },
+          "label": { "type": "string", "minLength": 1 },
+          "path": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "primaryLanguage": { "type": "string", "minLength": 1 },
+    "internalLanguage": { "type": "string", "minLength": 1 },
+    "clientLanguage": { "type": "string", "minLength": 1 },
+    "docTypes": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["enabled", "path"],
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "path": { "type": "string", "minLength": 1 },
+          "label": { "type": "string" },
+          "templatesPath": { "type": "string", "minLength": 1 }
+        }
+      },
+      "properties": {
+        "srs": { "$ref": "#/$defs/docType" },
+        "basicDesign": { "$ref": "#/$defs/docType" },
+        "detailDesign": { "$ref": "#/$defs/docType" },
+        "otherDocument": { "$ref": "#/$defs/docType" }
+      }
+    },
+    "paths": {
+      "type": "object",
+      "additionalProperties": { "type": "string", "minLength": 1 },
+      "properties": {
+        "comments": { "type": "string", "minLength": 1 },
+        "reviewConfig": { "type": "string", "minLength": 1 },
+        "reviewQueue": { "type": "string", "minLength": 1 },
+        "registry": { "type": "string", "minLength": 1 },
+        "prototypeConfig": { "type": "string", "minLength": 1 },
+        "prototypeScreenMap": { "type": "string", "minLength": 1 }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": { "type": "boolean" },
+      "properties": {
+        "review": { "type": "boolean" },
+        "comments": { "type": "boolean" },
+        "prototype": { "type": "boolean" },
+        "graph": { "type": "boolean" },
+        "generate": { "type": "boolean" },
+        "translate": { "type": "boolean" }
+      }
+    }
+  },
+  "$defs": {
+    "docType": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["enabled", "path"],
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "path": { "type": "string", "minLength": 1 },
+        "label": { "type": "string" },
+        "templatesPath": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}