@popoverai/dotrequirements 0.21.0 → 0.21.1

package/dist/commands/mcp-setup.js

@@ -5,7 +5,7 @@ import { join } from 'path';
 import prompts from 'prompts';
 import { loadTemplate } from '../utils/templates.js';
 import { brand } from '../utils/brand.js';
-import { getContextFileName, getContextFilePath, findDotrequirementsSection, appendOrUpdateSection, } from '../utils/context-file.js';
+import { getContextFileName, findGitRoot, findDotrequirementsSection, appendOrUpdateSection, buildNoGitRepoMessage, } from '../utils/context-file.js';
 /**
  * Load the context file section template
  */
@@ -16,12 +16,17 @@ function loadContextFileSection() {
  * Install workflow guidance to the appropriate context file for a platform
  */
 async function installContextFileSection(platform) {
-    const contextFilePath = await getContextFilePath(platform);
-    if (!contextFilePath) {
-        console.error(`\n❌ Could not determine context file path for ${platform}`);
+    const fileName = getContextFileName(platform);
+    if (!fileName) {
+        console.error(`\n❌ Unknown platform: ${platform}`);
         return;
     }
-    const fileName = getContextFileName(platform);
+    const gitRoot = await findGitRoot();
+    if (!gitRoot) {
+        console.log('\n' + buildNoGitRepoMessage(fileName) + '\n');
+        return;
+    }
+    const contextFilePath = join(gitRoot, fileName);
     const sectionContent = loadContextFileSection();
     // Check if file exists and has existing section
     let existingSection = null;

package/dist/templates/context-file-section.md

@@ -21,7 +21,7 @@ requirements, so your plan should too.
 ### Requirements Syntax
 
 ```dotrequirements
-REQ-ID: Short description of expected behavior
+DOMAIN-1: Short description of expected behavior
   0. -> First criterion or condition
   1. -> Second criterion
     1.0. -> Nested detail under second criterion
@@ -31,6 +31,7 @@ REQ-ID: Short description of expected behavior
 - Criteria: `position. -> content` (optional label before the arrow)
 - Nesting: Indent with 2 spaces, use `x.y` position paths
 - Delimiter: `->` or `→`
+- **Key style**: Use sequential keys with a short domain prefix (`ORCHESTRATOR-1`, `ORCHESTRATOR-2`, ...) rather than semantic keys (`AUTONOMOUS-ADVANCE`). Sequential keys stay stable when a requirement gets reworded, so test references don't break. Call `create_requirement_document` for full key-naming guidance.
 
 ### Test Usage
 

package/dist/templates/example-requirements.js

@@ -18,15 +18,15 @@ document:
 
 This file demonstrates the dotrequirements format. Feel free to edit or delete it.
 
-## HOW-TO: How to use dotrequirements
+## HOWTO-1: How to use dotrequirements
 
 \`\`\`dotrequirements
-HOW-TO: How to use dotrequirements
-  0. → Requirements live here and are referenced by index, like requirement('HOW-TO.0')
-  1. Labels → Anything before the arrow is a label. You can reference a requirement by its index or its label: requirement('HOW-TO.1') == requirement('HOW-TO.labels')
-  2. Labels → Repeated labels can be referenced sequentially: requirement('HOW-TO.labels#2')
-    2.0. Nesting → You can keep nesting. Label references don't need to be nested: requirement('HOW-TO.nesting').
-    2.1. Several words → Reference multi-word labels using kebab-case. Label references are never case sensitive: requirement('HOW-TO.several-words')
+HOWTO-1: How to use dotrequirements
+  0. → Requirements live here and are referenced by index, like requirement('HOWTO-1.0')
+  1. Labels → Anything before the arrow is a label. You can reference a requirement by its index or its label: requirement('HOWTO-1.1') == requirement('HOWTO-1.labels')
+  2. Labels → Repeated labels can be referenced sequentially: requirement('HOWTO-1.labels#2')
+    2.0. Nesting → You can keep nesting. Label references don't need to be nested: requirement('HOWTO-1.nesting').
+    2.1. Several words → Reference multi-word labels using kebab-case. Label references are never case sensitive: requirement('HOWTO-1.several-words')
   3. → While you _can_ write your requirements longhand in this format, there are a number of better ways.
     3.0. MCP → The dotrequirements MCP equips an AI assistant to develop requirements with you
     3.1. Your current tools → Dotrequirements has a composer for Jira, Confluence, and Notion
@@ -36,12 +36,12 @@ HOW-TO: How to use dotrequirements
 
 ---
 
-## USER-AUTH: User authentication flow
+## AUTH-1: User authentication flow
 
 **Implementation notes:** Use bcrypt for password hashing with work factor >= 12.
 
 \`\`\`dotrequirements
-USER-AUTH: User authentication flow
+AUTH-1: User authentication flow
   0. AC → Login form accepts email and password
   1. AC → Invalid credentials show error message
   2. Edge-case → Rate limiting after 5 failed attempts
@@ -71,11 +71,11 @@ import { requirement } from '@popoverai/dotrequirements/test';
 
 test('login with valid credentials', () => {
   // Reference by numeric path
-  const ac = requirement('USER-AUTH.0');
+  const ac = requirement('AUTH-1.0');
   // Returns: "AC: Login form accepts email and password"
 
   // Reference by label
-  const edgeCase = requirement('USER-AUTH.edge-case');
+  const edgeCase = requirement('AUTH-1.edge-case');
   // Returns: "Edge-case: Rate limiting after 5 failed attempts"
 
   // Your test implementation...

package/dist/templates/example-requirements.ts

@@ -19,15 +19,15 @@ document:
 
 This file demonstrates the dotrequirements format. Feel free to edit or delete it.
 
-## HOW-TO: How to use dotrequirements
+## HOWTO-1: How to use dotrequirements
 
 \`\`\`dotrequirements
-HOW-TO: How to use dotrequirements
-  0. → Requirements live here and are referenced by index, like requirement('HOW-TO.0')
-  1. Labels → Anything before the arrow is a label. You can reference a requirement by its index or its label: requirement('HOW-TO.1') == requirement('HOW-TO.labels')
-  2. Labels → Repeated labels can be referenced sequentially: requirement('HOW-TO.labels#2')
-    2.0. Nesting → You can keep nesting. Label references don't need to be nested: requirement('HOW-TO.nesting').
-    2.1. Several words → Reference multi-word labels using kebab-case. Label references are never case sensitive: requirement('HOW-TO.several-words')
+HOWTO-1: How to use dotrequirements
+  0. → Requirements live here and are referenced by index, like requirement('HOWTO-1.0')
+  1. Labels → Anything before the arrow is a label. You can reference a requirement by its index or its label: requirement('HOWTO-1.1') == requirement('HOWTO-1.labels')
+  2. Labels → Repeated labels can be referenced sequentially: requirement('HOWTO-1.labels#2')
+    2.0. Nesting → You can keep nesting. Label references don't need to be nested: requirement('HOWTO-1.nesting').
+    2.1. Several words → Reference multi-word labels using kebab-case. Label references are never case sensitive: requirement('HOWTO-1.several-words')
   3. → While you _can_ write your requirements longhand in this format, there are a number of better ways.
     3.0. MCP → The dotrequirements MCP equips an AI assistant to develop requirements with you
     3.1. Your current tools → Dotrequirements has a composer for Jira, Confluence, and Notion
@@ -37,12 +37,12 @@ HOW-TO: How to use dotrequirements
 
 ---
 
-## USER-AUTH: User authentication flow
+## AUTH-1: User authentication flow
 
 **Implementation notes:** Use bcrypt for password hashing with work factor >= 12.
 
 \`\`\`dotrequirements
-USER-AUTH: User authentication flow
+AUTH-1: User authentication flow
   0. AC → Login form accepts email and password
   1. AC → Invalid credentials show error message
   2. Edge-case → Rate limiting after 5 failed attempts
@@ -72,11 +72,11 @@ import { requirement } from '@popoverai/dotrequirements/test';
 
 test('login with valid credentials', () => {
   // Reference by numeric path
-  const ac = requirement('USER-AUTH.0');
+  const ac = requirement('AUTH-1.0');
   // Returns: "AC: Login form accepts email and password"
 
   // Reference by label
-  const edgeCase = requirement('USER-AUTH.edge-case');
+  const edgeCase = requirement('AUTH-1.edge-case');
   // Returns: "Edge-case: Rate limiting after 5 failed attempts"
 
   // Your test implementation...

package/dist/utils/context-file.d.ts

@@ -35,4 +35,12 @@ export declare function appendOrUpdateSection(filePath: string, sectionContent:
  * Get the full path to the context file for a platform
  */
 export declare function getContextFilePath(platform: string): Promise<string | null>;
+/**
+ * Build a user-facing message explaining that context file installation
+ * was skipped because the current directory is not inside a git repository.
+ *
+ * The MCP server itself is configured separately, so this message is only
+ * about the second step (writing the platform's context file).
+ */
+export declare function buildNoGitRepoMessage(fileName: string): string;
 //# sourceMappingURL=context-file.d.ts.map

package/dist/utils/context-file.js

@@ -91,4 +91,23 @@ export async function getContextFilePath(platform) {
         return null;
     return join(gitRoot, fileName);
 }
+/**
+ * Build a user-facing message explaining that context file installation
+ * was skipped because the current directory is not inside a git repository.
+ *
+ * The MCP server itself is configured separately, so this message is only
+ * about the second step (writing the platform's context file).
+ */
+export function buildNoGitRepoMessage(fileName) {
+    return [
+        `⚠️  Skipped writing ${fileName}: not inside a git repository.`,
+        `   ${fileName} would have been created at the git repo root, but no .git directory was found.`,
+        '',
+        '   To finish setup, either:',
+        '     • run `git init` here, then re-run `dotreq mcp-setup`, or',
+        '     • `cd` into an existing project directory and run `dotreq mcp-setup` there.',
+        '',
+        '   Note: the MCP server itself was configured successfully — only the context file step was skipped.',
+    ].join('\n');
+}
 //# sourceMappingURL=context-file.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "description": "Requirements tracking CLI, test harness, and MCP server",
   "type": "module",
   "bin": {